dsphinx.addnodesdocument)}( rawsourcechildren]( translations LanguagesNode)}(hhh](h pending_xref)}(hhh]docutils.nodesTextChinese (Simplified)}parenthsba attributes}(ids]classes]names]dupnames]backrefs] refdomainstdreftypedoc reftarget&/translations/zh_CN/filesystems/autofsmodnameN classnameN refexplicitutagnamehhh ubh)}(hhh]hChinese (Traditional)}hh2sbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/zh_TW/filesystems/autofsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hItalian}hhFsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/it_IT/filesystems/autofsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hJapanese}hhZsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/ja_JP/filesystems/autofsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hKorean}hhnsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/ko_KR/filesystems/autofsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hPortuguese (Brazilian)}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/pt_BR/filesystems/autofsmodnameN classnameN refexplicituh1hhh ubh)}(hhh]hSpanish}hhsbah}(h]h ]h"]h$]h&] refdomainh)reftypeh+ reftarget&/translations/sp_SP/filesystems/autofsmodnameN classnameN refexplicituh1hhh ubeh}(h]h ]h"]h$]h&]current_languageEnglishuh1h hh _documenthsourceNlineNubhsection)}(hhh](htitle)}(hautofs - how it worksh]hautofs - how it works}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhh@/var/lib/git/docbuild/linux/Documentation/filesystems/autofs.rsthKubh)}(hhh](h)}(hPurposeh]hPurpose}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhhhhhKubh paragraph)}(hThe goal of autofs is to provide on-demand mounting and race free automatic unmounting of various other filesystems. This provides two key advantages:h]hThe goal of autofs is to provide on-demand mounting and race free automatic unmounting of various other filesystems. This provides two key advantages:}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhhhhubhenumerated_list)}(hhh](h list_item)}(hXEThere is no need to delay boot until all filesystems that might be needed are mounted. Processes that try to access those slow filesystems might be delayed but other processes can continue freely. This is particularly important for network filesystems (e.g. NFS) or filesystems stored on media with a media-changing robot. h]h)}(hXDThere is no need to delay boot until all filesystems that might be needed are mounted. Processes that try to access those slow filesystems might be delayed but other processes can continue freely. This is particularly important for network filesystems (e.g. NFS) or filesystems stored on media with a media-changing robot.h]hXDThere is no need to delay boot until all filesystems that might be needed are mounted. Processes that try to access those slow filesystems might be delayed but other processes can continue freely. This is particularly important for network filesystems (e.g. NFS) or filesystems stored on media with a media-changing robot.}(hhhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK hhubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubh)}(hXThe names and locations of filesystems can be stored in a remote database and can change at any time. The content in that database at the time of access will be used to provide a target for the access. The interpretation of names in the filesystem can even be programmatic rather than database-backed, allowing wildcards for example, and can vary based on the user who first accessed a name. h]h)}(hXThe names and locations of filesystems can be stored in a remote database and can change at any time. The content in that database at the time of access will be used to provide a target for the access. The interpretation of names in the filesystem can even be programmatic rather than database-backed, allowing wildcards for example, and can vary based on the user who first accessed a name.h]hXThe names and locations of filesystems can be stored in a remote database and can change at any time. The content in that database at the time of access will be used to provide a target for the access. The interpretation of names in the filesystem can even be programmatic rather than database-backed, allowing wildcards for example, and can vary based on the user who first accessed a name.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj ubah}(h]h ]h"]h$]h&]uh1hhhhhhhhNubeh}(h]h ]h"]h$]h&]enumtypearabicprefixhsuffix.uh1hhhhhhhhK ubeh}(h]purposeah ]h"]purposeah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hContexth]hContext}(hj9hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj6hhhhhKubh)}(hXThe "autofs" filesystem module is only one part of an autofs system. There also needs to be a user-space program which looks up names and mounts filesystems. This will often be the "automount" program, though other tools including "systemd" can make use of "autofs". This document describes only the kernel module and the interactions required with any user-space program. Subsequent text refers to this as the "automount daemon" or simply "the daemon".h]hXThe “autofs” filesystem module is only one part of an autofs system. There also needs to be a user-space program which looks up names and mounts filesystems. This will often be the “automount” program, though other tools including “systemd” can make use of “autofs”. This document describes only the kernel module and the interactions required with any user-space program. Subsequent text refers to this as the “automount daemon” or simply “the daemon”.}(hjGhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj6hhubh)}(h"autofs" is a Linux kernel module which provides the "autofs" filesystem type. Several "autofs" filesystems can be mounted and they can each be managed separately, or all managed by the same daemon.h]h“autofs” is a Linux kernel module which provides the “autofs” filesystem type. Several “autofs” filesystems can be mounted and they can each be managed separately, or all managed by the same daemon.}(hjUhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK&hj6hhubeh}(h]contextah ]h"]contextah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(hContenth]hContent}(hjnhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjkhhhhhK+ubh)}(hAn autofs filesystem can contain 3 sorts of objects: directories, symbolic links and mount traps. Mount traps are directories with extra properties as described in the next section.h]hAn autofs filesystem can contain 3 sorts of objects: directories, symbolic links and mount traps. Mount traps are directories with extra properties as described in the next section.}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK-hjkhhubh)}(hXObjects can only be created by the automount daemon: symlinks are created with a regular `symlink` system call, while directories and mount traps are created with `mkdir`. The determination of whether a directory should be a mount trap is based on a master map. This master map is consulted by autofs to determine which directories are mount points. Mount points can be *direct*/*indirect*/*offset*. On most systems, the default master map is located at */etc/auto.master*.h](hYObjects can only be created by the automount daemon: symlinks are created with a regular }(hjhhhNhNubhtitle_reference)}(h `symlink`h]hsymlink}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhA system call, while directories and mount traps are created with }(hjhhhNhNubj)}(h`mkdir`h]hmkdir}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh. The determination of whether a directory should be a mount trap is based on a master map. This master map is consulted by autofs to determine which directories are mount points. Mount points can be }(hjhhhNhNubhemphasis)}(h*direct*h]hdirect}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh/}(hjhhhNhNubj)}(h *indirect*h]hindirect}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh/}hjsbj)}(h*offset*h]hoffset}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh8. On most systems, the default master map is located at }(hjhhhNhNubj)}(h*/etc/auto.master*h]h/etc/auto.master}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK1hjkhhubh)}(hXIf neither the *direct* or *offset* mount options are given (so the mount is considered to be *indirect*), then the root directory is always a regular directory, otherwise it is a mount trap when it is empty and a regular directory when not empty. Note that *direct* and *offset* are treated identically so a concise summary is that the root directory is a mount trap only if the filesystem is mounted *direct* and the root is empty.h](hIf neither the }(hjhhhNhNubj)}(h*direct*h]hdirect}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh or }(hjhhhNhNubj)}(h*offset*h]hoffset}(hj"hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh; mount options are given (so the mount is considered to be }(hjhhhNhNubj)}(h *indirect*h]hindirect}(hj4hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh), then the root directory is always a regular directory, otherwise it is a mount trap when it is empty and a regular directory when not empty. Note that }(hjhhhNhNubj)}(h*direct*h]hdirect}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh and }(hjhhhNhNubj)}(h*offset*h]hoffset}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh{ are treated identically so a concise summary is that the root directory is a mount trap only if the filesystem is mounted }(hjhhhNhNubj)}(h*direct*h]hdirect}(hjjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh and the root is empty.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhK9hjkhhubh)}(hzDirectories created in the root directory are mount traps only if the filesystem is mounted *indirect* and they are empty.h](h\Directories created in the root directory are mount traps only if the filesystem is mounted }(hjhhhNhNubj)}(h *indirect*h]hindirect}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh and they are empty.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKAhjkhhubh)}(hX`Directories further down the tree depend on the *maxproto* mount option and particularly whether it is less than five or not. When *maxproto* is five, no directories further down the tree are ever mount traps, they are always regular directories. When the *maxproto* is four (or three), these directories are mount traps precisely when they are empty.h](h0Directories further down the tree depend on the }(hjhhhNhNubj)}(h *maxproto*h]hmaxproto}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhI mount option and particularly whether it is less than five or not. When }(hjhhhNhNubj)}(h *maxproto*h]hmaxproto}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubht is five, no directories further down the tree are ever mount traps, they are always regular directories. When the }(hjhhhNhNubj)}(h *maxproto*h]hmaxproto}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhU is four (or three), these directories are mount traps precisely when they are empty.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKDhjkhhubh)}(hXSo: non-empty (i.e. non-leaf) directories are never mount traps. Empty directories are sometimes mount traps, and sometimes not depending on where in the tree they are (root, top level, or lower), the *maxproto*, and whether the mount was *indirect* or not.h](hSo: non-empty (i.e. non-leaf) directories are never mount traps. Empty directories are sometimes mount traps, and sometimes not depending on where in the tree they are (root, top level, or lower), the }(hjhhhNhNubj)}(h *maxproto*h]hmaxproto}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh, and whether the mount was }(hjhhhNhNubj)}(h *indirect*h]hindirect}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh or not.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKKhjkhhubeh}(h]contentah ]h"]contentah$]h&]uh1hhhhhhhhK+ubh)}(hhh](h)}(h Mount Trapsh]h Mount Traps}(hj#hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj hhhhhKQubh)}(hXA core element of the implementation of autofs is the Mount Traps which are provided by the Linux VFS. Any directory provided by a filesystem can be designated as a trap. This involves two separate features that work together to allow autofs to do its job.h]hXA core element of the implementation of autofs is the Mount Traps which are provided by the Linux VFS. Any directory provided by a filesystem can be designated as a trap. This involves two separate features that work together to allow autofs to do its job.}(hj1hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKShj hhubh)}(h**DCACHE_NEED_AUTOMOUNT**h]hstrong)}(hjAh]hDCACHE_NEED_AUTOMOUNT}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1jChj?ubah}(h]h ]h"]h$]h&]uh1hhhhKXhj hhubh)}(hXIf a dentry has the DCACHE_NEED_AUTOMOUNT flag set (which gets set if the inode has S_AUTOMOUNT set, or can be set directly) then it is (potentially) a mount trap. Any access to this directory beyond a "`stat`" will (normally) cause the `d_op->d_automount()` dentry operation to be called. The task of this method is to find the filesystem that should be mounted on the directory and to return it. The VFS is responsible for actually mounting the root of this filesystem on the directory.h](hIf a dentry has the DCACHE_NEED_AUTOMOUNT flag set (which gets set if the inode has S_AUTOMOUNT set, or can be set directly) then it is (potentially) a mount trap. Any access to this directory beyond a “}(hjXhhhNhNubj)}(h`stat`h]hstat}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjXubh” will (normally) cause the }(hjXhhhNhNubj)}(h`d_op->d_automount()`h]hd_op->d_automount()}(hjrhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjXubh dentry operation to be called. The task of this method is to find the filesystem that should be mounted on the directory and to return it. The VFS is responsible for actually mounting the root of this filesystem on the directory.}(hjXhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKZhj hhubh)}(hXautofs doesn't find the filesystem itself but sends a message to the automount daemon asking it to find and mount the filesystem. The autofs `d_automount` method then waits for the daemon to report that everything is ready. It will then return "`NULL`" indicating that the mount has already happened. The VFS doesn't try to mount anything but follows down the mount that is already there.h](hautofs doesn’t find the filesystem itself but sends a message to the automount daemon asking it to find and mount the filesystem. The autofs }(hjhhhNhNubj)}(h `d_automount`h]h d_automount}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh^ method then waits for the daemon to report that everything is ready. It will then return “}(hjhhhNhNubj)}(h`NULL`h]hNULL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh” indicating that the mount has already happened. The VFS doesn’t try to mount anything but follows down the mount that is already there.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKchj hhubh)}(hXThis functionality is sufficient for some users of mount traps such as NFS which creates traps so that mountpoints on the server can be reflected on the client. However it is not sufficient for autofs. As mounting onto a directory is considered to be "beyond a `stat`", the automount daemon would not be able to mount a filesystem on the 'trap' directory without some way to avoid getting caught in the trap. For that purpose there is another flag.h](hX This functionality is sufficient for some users of mount traps such as NFS which creates traps so that mountpoints on the server can be reflected on the client. However it is not sufficient for autofs. As mounting onto a directory is considered to be “beyond a }(hjhhhNhNubj)}(h`stat`h]hstat}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh”, the automount daemon would not be able to mount a filesystem on the ‘trap’ directory without some way to avoid getting caught in the trap. For that purpose there is another flag.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKjhj hhubh)}(h**DCACHE_MANAGE_TRANSIT**h]jD)}(hjh]hDCACHE_MANAGE_TRANSIT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubah}(h]h ]h"]h$]h&]uh1hhhhKrhj hhubh)}(hIf a dentry has DCACHE_MANAGE_TRANSIT set then two very different but related behaviours are invoked, both using the `d_op->d_manage()` dentry operation.h](huIf a dentry has DCACHE_MANAGE_TRANSIT set then two very different but related behaviours are invoked, both using the }(hjhhhNhNubj)}(h`d_op->d_manage()`h]hd_op->d_manage()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh dentry operation.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKthj hhubh)}(hFirstly, before checking to see if any filesystem is mounted on the directory, d_manage() will be called with the `rcu_walk` parameter set to `false`. It may return one of three things:h](hrFirstly, before checking to see if any filesystem is mounted on the directory, d_manage() will be called with the }(hjhhhNhNubj)}(h `rcu_walk`h]hrcu_walk}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh parameter set to }(hjhhhNhNubj)}(h`false`h]hfalse}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh%. It may return one of three things:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKxhj hhubh bullet_list)}(hhh](h)}(hXA return value of zero indicates that there is nothing special about this dentry and normal checks for mounts and automounts should proceed. autofs normally returns zero, but first waits for any expiry (automatic unmounting of the mounted filesystem) to complete. This avoids races. h](h)}(hA return value of zero indicates that there is nothing special about this dentry and normal checks for mounts and automounts should proceed.h]hA return value of zero indicates that there is nothing special about this dentry and normal checks for mounts and automounts should proceed.}(hjNhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhK|hjJubh)}(hautofs normally returns zero, but first waits for any expiry (automatic unmounting of the mounted filesystem) to complete. This avoids races.h]hautofs normally returns zero, but first waits for any expiry (automatic unmounting of the mounted filesystem) to complete. This avoids races.}(hj\hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjJubeh}(h]h ]h"]h$]h&]uh1hhjGhhhhhNubh)}(hXGA return value of `-EISDIR` tells the VFS to ignore any mounts on the directory and to not consider calling `->d_automount()`. This effectively disables the **DCACHE_NEED_AUTOMOUNT** flag causing the directory not be a mount trap after all. autofs returns this if it detects that the process performing the lookup is the automount daemon and that the mount has been requested but has not yet completed. How it determines this is discussed later. This allows the automount daemon not to get caught in the mount trap. There is a subtlety here. It is possible that a second autofs filesystem can be mounted below the first and for both of them to be managed by the same daemon. For the daemon to be able to mount something on the second it must be able to "walk" down past the first. This means that d_manage cannot *always* return -EISDIR for the automount daemon. It must only return it when a mount has been requested, but has not yet completed. `d_manage` also returns `-EISDIR` if the dentry shouldn't be a mount trap, either because it is a symbolic link or because it is not empty. h](h)}(hA return value of `-EISDIR` tells the VFS to ignore any mounts on the directory and to not consider calling `->d_automount()`. This effectively disables the **DCACHE_NEED_AUTOMOUNT** flag causing the directory not be a mount trap after all.h](hA return value of }(hjthhhNhNubj)}(h `-EISDIR`h]h-EISDIR}(hj|hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjtubhQ tells the VFS to ignore any mounts on the directory and to not consider calling }(hjthhhNhNubj)}(h`->d_automount()`h]h->d_automount()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjtubh . This effectively disables the }(hjthhhNhNubjD)}(h**DCACHE_NEED_AUTOMOUNT**h]hDCACHE_NEED_AUTOMOUNT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjtubh: flag causing the directory not be a mount trap after all.}(hjthhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjpubh)}(hXautofs returns this if it detects that the process performing the lookup is the automount daemon and that the mount has been requested but has not yet completed. How it determines this is discussed later. This allows the automount daemon not to get caught in the mount trap.h]hXautofs returns this if it detects that the process performing the lookup is the automount daemon and that the mount has been requested but has not yet completed. How it determines this is discussed later. This allows the automount daemon not to get caught in the mount trap.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjpubh)}(hXThere is a subtlety here. It is possible that a second autofs filesystem can be mounted below the first and for both of them to be managed by the same daemon. For the daemon to be able to mount something on the second it must be able to "walk" down past the first. This means that d_manage cannot *always* return -EISDIR for the automount daemon. It must only return it when a mount has been requested, but has not yet completed.h](hX0There is a subtlety here. It is possible that a second autofs filesystem can be mounted below the first and for both of them to be managed by the same daemon. For the daemon to be able to mount something on the second it must be able to “walk” down past the first. This means that d_manage cannot }(hjhhhNhNubj)}(h*always*h]halways}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh} return -EISDIR for the automount daemon. It must only return it when a mount has been requested, but has not yet completed.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjpubh)}(h`d_manage` also returns `-EISDIR` if the dentry shouldn't be a mount trap, either because it is a symbolic link or because it is not empty.h](j)}(h `d_manage`h]hd_manage}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh also returns }(hjhhhNhNubj)}(h `-EISDIR`h]h-EISDIR}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhl if the dentry shouldn’t be a mount trap, either because it is a symbolic link or because it is not empty.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhjpubeh}(h]h ]h"]h$]h&]uh1hhjGhhhhhNubh)}(hX<Any other negative value is treated as an error and returned to the caller. autofs can return - -ENOENT if the automount daemon failed to mount anything, - -ENOMEM if it ran out of memory, - -EINTR if a signal arrived while waiting for expiry to complete - or any other error sent down by the automount daemon. h](h)}(hKAny other negative value is treated as an error and returned to the caller.h]hKAny other negative value is treated as an error and returned to the caller.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubh)}(hautofs can returnh]hautofs can return}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubjF)}(hhh](h)}(h9-ENOENT if the automount daemon failed to mount anything,h]h)}(hj?h]h9-ENOENT if the automount daemon failed to mount anything,}(hjAhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj=ubah}(h]h ]h"]h$]h&]uh1hhj:ubh)}(h -ENOMEM if it ran out of memory,h]h)}(hjVh]h -ENOMEM if it ran out of memory,}(hjXhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjTubah}(h]h ]h"]h$]h&]uh1hhj:ubh)}(h?-EINTR if a signal arrived while waiting for expiry to completeh]h)}(h?-EINTR if a signal arrived while waiting for expiry to completeh]h?-EINTR if a signal arrived while waiting for expiry to complete}(hjohhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjkubah}(h]h ]h"]h$]h&]uh1hhj:ubh)}(h7or any other error sent down by the automount daemon. h]h)}(h5or any other error sent down by the automount daemon.h]h5or any other error sent down by the automount daemon.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhjubah}(h]h ]h"]h$]h&]uh1hhj:ubeh}(h]h ]h"]h$]h&]bullet-uh1jEhhhKhjubeh}(h]h ]h"]h$]h&]uh1hhjGhhhNhNubeh}(h]h ]h"]h$]h&]jjuh1jEhhhK|hj hhubh)}(hSThe second use case only occurs during an "RCU-walk" and so `rcu_walk` will be set.h](h@The second use case only occurs during an “RCU-walk” and so }(hjhhhNhNubj)}(h `rcu_walk`h]hrcu_walk}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh will be set.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hAn RCU-walk is a fast and lightweight process for walking down a filename path (i.e. it is like running on tip-toes). RCU-walk cannot cope with all situations so when it finds a difficulty it falls back to "REF-walk", which is slower but more robust.h]hAn RCU-walk is a fast and lightweight process for walking down a filename path (i.e. it is like running on tip-toes). RCU-walk cannot cope with all situations so when it finds a difficulty it falls back to “REF-walk”, which is slower but more robust.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hRCU-walk will never call `->d_automount`; the filesystems must already be mounted or RCU-walk cannot handle the path. To determine if a mount-trap is safe for RCU-walk mode it calls `->d_manage()` with `rcu_walk` set to `true`.h](hRCU-walk will never call }(hjhhhNhNubj)}(h`->d_automount`h]h ->d_automount}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh; the filesystems must already be mounted or RCU-walk cannot handle the path. To determine if a mount-trap is safe for RCU-walk mode it calls }(hjhhhNhNubj)}(h`->d_manage()`h]h ->d_manage()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh with }(hjhhhNhNubj)}(h `rcu_walk`h]hrcu_walk}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh set to }(hjhhhNhNubj)}(h`true`h]htrue}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hXIn this case `d_manage()` must avoid blocking and should avoid taking spinlocks if at all possible. Its sole purpose is to determine if it would be safe to follow down into any mounted directory and the only reason that it might not be is if an expiry of the mount is underway.h](h In this case }(hj3hhhNhNubj)}(h `d_manage()`h]h d_manage()}(hj;hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj3ubh must avoid blocking and should avoid taking spinlocks if at all possible. Its sole purpose is to determine if it would be safe to follow down into any mounted directory and the only reason that it might not be is if an expiry of the mount is underway.}(hj3hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hX{In the `rcu_walk` case, `d_manage()` cannot return -EISDIR to tell the VFS that this is a directory that doesn't require d_automount. If `rcu_walk` sees a dentry with DCACHE_NEED_AUTOMOUNT set but nothing mounted, it *will* fall back to REF-walk. `d_manage()` cannot make the VFS remain in RCU-walk mode, but can only tell it to get out of RCU-walk mode by returning `-ECHILD`.h](hIn the }(hjShhhNhNubj)}(h `rcu_walk`h]hrcu_walk}(hj[hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjSubh case, }(hjShhhNhNubj)}(h `d_manage()`h]h d_manage()}(hjmhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjSubhh cannot return -EISDIR to tell the VFS that this is a directory that doesn’t require d_automount. If }(hjShhhNhNubj)}(h `rcu_walk`h]hrcu_walk}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjSubhF sees a dentry with DCACHE_NEED_AUTOMOUNT set but nothing mounted, it }(hjShhhNhNubj)}(h*will*h]hwill}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjSubh fall back to REF-walk. }(hjShhhNhNubj)}(h `d_manage()`h]h d_manage()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjSubhl cannot make the VFS remain in RCU-walk mode, but can only tell it to get out of RCU-walk mode by returning }(hjShhhNhNubj)}(h `-ECHILD`h]h-ECHILD}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjSubh.}(hjShhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(hSo `d_manage()`, when called with `rcu_walk` set, should either return -ECHILD if there is any reason to believe it is unsafe to enter the mounted filesystem, otherwise it should return 0.h](hSo }(hjhhhNhNubj)}(h `d_manage()`h]h d_manage()}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh, when called with }(hjhhhNhNubj)}(h `rcu_walk`h]hrcu_walk}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh set, should either return -ECHILD if there is any reason to believe it is unsafe to enter the mounted filesystem, otherwise it should return 0.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubh)}(h~autofs will return `-ECHILD` if an expiry of the filesystem has been initiated or is being considered, otherwise it returns 0.h](hautofs will return }(hjhhhNhNubj)}(h `-ECHILD`h]h-ECHILD}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhb if an expiry of the filesystem has been initiated or is being considered, otherwise it returns 0.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj hhubeh}(h] mount-trapsah ]h"] mount trapsah$]h&]uh1hhhhhhhhKQubh)}(hhh](h)}(hMountpoint expiryh]hMountpoint expiry}(hj*hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj'hhhhhKubh)}(hXThe VFS has a mechanism for automatically expiring unused mounts, much as it can expire any unused dentry information from the dcache. This is guided by the MNT_SHRINKABLE flag. This only applies to mounts that were created by `d_automount()` returning a filesystem to be mounted. As autofs doesn't return such a filesystem but leaves the mounting to the automount daemon, it must involve the automount daemon in unmounting as well. This also means that autofs has more control over expiry.h](hThe VFS has a mechanism for automatically expiring unused mounts, much as it can expire any unused dentry information from the dcache. This is guided by the MNT_SHRINKABLE flag. This only applies to mounts that were created by }(hj8hhhNhNubj)}(h`d_automount()`h]h d_automount()}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj8ubh returning a filesystem to be mounted. As autofs doesn’t return such a filesystem but leaves the mounting to the automount daemon, it must involve the automount daemon in unmounting as well. This also means that autofs has more control over expiry.}(hj8hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj'hhubh)}(hXThe VFS also supports "expiry" of mounts using the MNT_EXPIRE flag to the `umount` system call. Unmounting with MNT_EXPIRE will fail unless a previous attempt had been made, and the filesystem has been inactive and untouched since that previous attempt. autofs does not depend on this but has its own internal tracking of whether filesystems were recently used. This allows individual names in the autofs directory to expire separately.h](hNThe VFS also supports “expiry” of mounts using the MNT_EXPIRE flag to the }(hjXhhhNhNubj)}(h`umount`h]humount}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjXubhXe system call. Unmounting with MNT_EXPIRE will fail unless a previous attempt had been made, and the filesystem has been inactive and untouched since that previous attempt. autofs does not depend on this but has its own internal tracking of whether filesystems were recently used. This allows individual names in the autofs directory to expire separately.}(hjXhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj'hhubh)}(hXEWith version 4 of the protocol, the automount daemon can try to unmount any filesystems mounted on the autofs filesystem or remove any symbolic links or empty directories any time it likes. If the unmount or removal is successful the filesystem will be returned to the state it was before the mount or creation, so that any access of the name will trigger normal auto-mount processing. In particular, `rmdir` and `unlink` do not leave negative entries in the dcache as a normal filesystem would, so an attempt to access a recently-removed object is passed to autofs for handling.h](hXWith version 4 of the protocol, the automount daemon can try to unmount any filesystems mounted on the autofs filesystem or remove any symbolic links or empty directories any time it likes. If the unmount or removal is successful the filesystem will be returned to the state it was before the mount or creation, so that any access of the name will trigger normal auto-mount processing. In particular, }(hjxhhhNhNubj)}(h`rmdir`h]hrmdir}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjxubh and }(hjxhhhNhNubj)}(h`unlink`h]hunlink}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjxubh do not leave negative entries in the dcache as a normal filesystem would, so an attempt to access a recently-removed object is passed to autofs for handling.}(hjxhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj'hhubh)}(hX'With version 5, this is not safe except for unmounting from top-level directories. As lower-level directories are never mount traps, other processes will see an empty directory as soon as the filesystem is unmounted. So it is generally safest to use the autofs expiry protocol described below.h]hX'With version 5, this is not safe except for unmounting from top-level directories. As lower-level directories are never mount traps, other processes will see an empty directory as soon as the filesystem is unmounted. So it is generally safest to use the autofs expiry protocol described below.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhKhj'hhubh)}(hXNormally the daemon only wants to remove entries which haven't been used for a while. For this purpose autofs maintains a "`last_used`" time stamp on each directory or symlink. For symlinks it genuinely does record the last time the symlink was "used" or followed to find out where it points to. For directories the field is used slightly differently. The field is updated at mount time and during expire checks if it is found to be in use (ie. open file descriptor or process working directory) and during path walks. The update done during path walks prevents frequent expire and immediate mount of frequently accessed automounts. But in the case where a GUI continually access or an application frequently scans an autofs directory tree there can be an accumulation of mounts that aren't actually being used. To cater for this case the "`strictexpire`" autofs mount option can be used to avoid the "`last_used`" update on path walk thereby preventing this apparent inability to expire mounts that aren't really in use.h](hNormally the daemon only wants to remove entries which haven’t been used for a while. For this purpose autofs maintains a “}(hjhhhNhNubj)}(h `last_used`h]h last_used}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhX” time stamp on each directory or symlink. For symlinks it genuinely does record the last time the symlink was “used” or followed to find out where it points to. For directories the field is used slightly differently. The field is updated at mount time and during expire checks if it is found to be in use (ie. open file descriptor or process working directory) and during path walks. The update done during path walks prevents frequent expire and immediate mount of frequently accessed automounts. But in the case where a GUI continually access or an application frequently scans an autofs directory tree there can be an accumulation of mounts that aren’t actually being used. To cater for this case the “}(hjhhhNhNubj)}(h`strictexpire`h]h strictexpire}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh4” autofs mount option can be used to avoid the “}(hjhhhNhNubj)}(h `last_used`h]h last_used}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhp” update on path walk thereby preventing this apparent inability to expire mounts that aren’t really in use.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj'hhubh)}(hXWThe daemon is able to ask autofs if anything is due to be expired, using an `ioctl` as discussed later. For a *direct* mount, autofs considers if the entire mount-tree can be unmounted or not. For an *indirect* mount, autofs considers each of the names in the top level directory to determine if any of those can be unmounted and cleaned up.h](hLThe daemon is able to ask autofs if anything is due to be expired, using an }(hjhhhNhNubj)}(h`ioctl`h]hioctl}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh as discussed later. For a }(hjhhhNhNubj)}(h*direct*h]hdirect}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhS mount, autofs considers if the entire mount-tree can be unmounted or not. For an }(hjhhhNhNubj)}(h *indirect*h]hindirect}(hj(hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh mount, autofs considers each of the names in the top level directory to determine if any of those can be unmounted and cleaned up.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhKhj'hhubh)}(hXThere is an option with indirect mounts to consider each of the leaves that has been mounted on instead of considering the top-level names. This was originally intended for compatibility with version 4 of autofs and should be considered as deprecated for Sun Format automount maps. However, it may be used again for amd format mount maps (which are generally indirect maps) because the amd automounter allows for the setting of an expire timeout for individual mounts. But there are some difficulties in making the needed changes for this.h]hXThere is an option with indirect mounts to consider each of the leaves that has been mounted on instead of considering the top-level names. This was originally intended for compatibility with version 4 of autofs and should be considered as deprecated for Sun Format automount maps. However, it may be used again for amd format mount maps (which are generally indirect maps) because the amd automounter allows for the setting of an expire timeout for individual mounts. But there are some difficulties in making the needed changes for this.}(hj@hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj'hhubh)}(hX=When autofs considers a directory it checks the `last_used` time and compares it with the "timeout" value set when the filesystem was mounted, though this check is ignored in some cases. It also checks if the directory or anything below it is in use. For symbolic links, only the `last_used` time is ever considered.h](h0When autofs considers a directory it checks the }(hjNhhhNhNubj)}(h `last_used`h]h last_used}(hjVhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjNubh time and compares it with the “timeout” value set when the filesystem was mounted, though this check is ignored in some cases. It also checks if the directory or anything below it is in use. For symbolic links, only the }(hjNhhhNhNubj)}(h `last_used`h]h last_used}(hjhhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjNubh time is ever considered.}(hjNhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj'hhubh)}(hPIf both appear to support expiring the directory or symlink, an action is taken.h]hPIf both appear to support expiring the directory or symlink, an action is taken.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhj'hhubh)}(hXThere are two ways to ask autofs to consider expiry. The first is to use the **AUTOFS_IOC_EXPIRE** ioctl. This only works for indirect mounts. If it finds something in the root directory to expire it will return the name of that thing. Once a name has been returned the automount daemon needs to unmount any filesystems mounted below the name normally. As described above, this is unsafe for non-toplevel mounts in a version-5 autofs. For this reason the current `automount(8)` does not use this ioctl.h](hNThere are two ways to ask autofs to consider expiry. The first is to use the }(hjhhhNhNubjD)}(h**AUTOFS_IOC_EXPIRE**h]hAUTOFS_IOC_EXPIRE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubhXr ioctl. This only works for indirect mounts. If it finds something in the root directory to expire it will return the name of that thing. Once a name has been returned the automount daemon needs to unmount any filesystems mounted below the name normally. As described above, this is unsafe for non-toplevel mounts in a version-5 autofs. For this reason the current }(hjhhhNhNubj)}(h`automount(8)`h]h automount(8)}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh does not use this ioctl.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhj'hhubh)}(hXThe second mechanism uses either the **AUTOFS_DEV_IOCTL_EXPIRE_CMD** or the **AUTOFS_IOC_EXPIRE_MULTI** ioctl. This will work for both direct and indirect mounts. If it selects an object to expire, it will notify the daemon using the notification mechanism described below. This will block until the daemon acknowledges the expiry notification. This implies that the "`EXPIRE`" ioctl must be sent from a different thread than the one which handles notification.h](h%The second mechanism uses either the }(hjhhhNhNubjD)}(h**AUTOFS_DEV_IOCTL_EXPIRE_CMD**h]hAUTOFS_DEV_IOCTL_EXPIRE_CMD}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubh or the }(hjhhhNhNubjD)}(h**AUTOFS_IOC_EXPIRE_MULTI**h]hAUTOFS_IOC_EXPIRE_MULTI}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubhX ioctl. This will work for both direct and indirect mounts. If it selects an object to expire, it will notify the daemon using the notification mechanism described below. This will block until the daemon acknowledges the expiry notification. This implies that the “}(hjhhhNhNubj)}(h`EXPIRE`h]hEXPIRE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhW” ioctl must be sent from a different thread than the one which handles notification.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM hj'hhubh)}(hWhile the ioctl is blocking, the entry is marked as "expiring" and `d_manage` will block until the daemon affirms that the unmount has completed (together with removing any directories that might have been necessary), or has been aborted.h](hGWhile the ioctl is blocking, the entry is marked as “expiring” and }(hj hhhNhNubj)}(h `d_manage`h]hd_manage}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh will block until the daemon affirms that the unmount has completed (together with removing any directories that might have been necessary), or has been aborted.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM(hj'hhubeh}(h]mountpoint-expiryah ]h"]mountpoint expiryah$]h&]uh1hhhhhhhhKubh)}(hhh](h)}(h/Communicating with autofs: detecting the daemonh]h/Communicating with autofs: detecting the daemon}(hj/ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj, hhhhhM.ubh)}(hXVThere are several forms of communication between the automount daemon and the filesystem. As we have already seen, the daemon can create and remove directories and symlinks using normal filesystem operations. autofs knows whether a process requesting some operation is the daemon or not based on its process-group id number (see getpgid(1)).h]hXVThere are several forms of communication between the automount daemon and the filesystem. As we have already seen, the daemon can create and remove directories and symlinks using normal filesystem operations. autofs knows whether a process requesting some operation is the daemon or not based on its process-group id number (see getpgid(1)).}(hj= hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM0hj, hhubh)}(hXWhen an autofs filesystem is mounted the pgid of the mounting processes is recorded unless the "pgrp=" option is given, in which case that number is recorded instead. Any request arriving from a process in that process group is considered to come from the daemon. If the daemon ever has to be stopped and restarted a new pgid can be provided through an ioctl as will be described below.h]hXWhen an autofs filesystem is mounted the pgid of the mounting processes is recorded unless the “pgrp=” option is given, in which case that number is recorded instead. Any request arriving from a process in that process group is considered to come from the daemon. If the daemon ever has to be stopped and restarted a new pgid can be provided through an ioctl as will be described below.}(hjK hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM6hj, hhubeh}(h].communicating-with-autofs-detecting-the-daemonah ]h"]/communicating with autofs: detecting the daemonah$]h&]uh1hhhhhhhhM.ubh)}(hhh](h)}(h)Communicating with autofs: the event pipeh]h)Communicating with autofs: the event pipe}(hjd hhhNhNubah}(h]h ]h"]h$]h&]uh1hhja hhhhhM>ubh)}(hWhen an autofs filesystem is mounted, the 'write' end of a pipe must be passed using the 'fd=' mount option. autofs will write notification messages to this pipe for the daemon to respond to. For version 5, the format of the message is::h]hWhen an autofs filesystem is mounted, the ‘write’ end of a pipe must be passed using the ‘fd=’ mount option. autofs will write notification messages to this pipe for the daemon to respond to. For version 5, the format of the message is:}(hjr hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM@hja hhubh literal_block)}(hXstruct autofs_v5_packet { struct autofs_packet_hdr hdr; autofs_wqt_t wait_queue_token; __u32 dev; __u64 ino; __u32 uid; __u32 gid; __u32 pid; __u32 tgid; __u32 len; char name[NAME_MAX+1]; };h]hXstruct autofs_v5_packet { struct autofs_packet_hdr hdr; autofs_wqt_t wait_queue_token; __u32 dev; __u64 ino; __u32 uid; __u32 gid; __u32 pid; __u32 tgid; __u32 len; char name[NAME_MAX+1]; };}hj sbah}(h]h ]h"]h$]h&] xml:spacepreserveuh1j hhhMEhja hhubh)}(h!And the format of the header is::h]h And the format of the header is:}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMRhja hhubj )}(hstruct autofs_packet_hdr { int proto_version; /* Protocol version */ int type; /* Type of packet */ };h]hstruct autofs_packet_hdr { int proto_version; /* Protocol version */ int type; /* Type of packet */ };}hj sbah}(h]h ]h"]h$]h&]j j uh1j hhhMThja hhubh)}(hwhere the type is one of ::h]hwhere the type is one of}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMYhja hhubj )}(hqautofs_ptype_missing_indirect autofs_ptype_expire_indirect autofs_ptype_missing_direct autofs_ptype_expire_directh]hqautofs_ptype_missing_indirect autofs_ptype_expire_indirect autofs_ptype_missing_direct autofs_ptype_expire_direct}hj sbah}(h]h ]h"]h$]h&]j j uh1j hhhM[hja hhubh)}(hso messages can indicate that a name is missing (something tried to access it but it isn't there) or that it has been selected for expiry.h]hso messages can indicate that a name is missing (something tried to access it but it isn’t there) or that it has been selected for expiry.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM`hja hhubh)}(hThe pipe will be set to "packet mode" (equivalent to passing `O_DIRECT`) to _pipe2(2)_ so that a read from the pipe will return at most one packet, and any unread portion of a packet will be discarded.h](hAThe pipe will be set to “packet mode” (equivalent to passing }(hj hhhNhNubj)}(h `O_DIRECT`h]hO_DIRECT}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh) to _pipe2(2)_ so that a read from the pipe will return at most one packet, and any unread portion of a packet will be discarded.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMchja hhubh)}(hXOThe `wait_queue_token` is a unique number which can identify a particular request to be acknowledged. When a message is sent over the pipe the affected dentry is marked as either "active" or "expiring" and other accesses to it block until the message is acknowledged using one of the ioctls below with the relevant `wait_queue_token`.h](hThe }(hj hhhNhNubj)}(h`wait_queue_token`h]hwait_queue_token}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubhX. is a unique number which can identify a particular request to be acknowledged. When a message is sent over the pipe the affected dentry is marked as either “active” or “expiring” and other accesses to it block until the message is acknowledged using one of the ioctls below with the relevant }(hj hhhNhNubj)}(h`wait_queue_token`h]hwait_queue_token}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jhj ubh.}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMghja hhubeh}(h](communicating-with-autofs-the-event-pipeah ]h"])communicating with autofs: the event pipeah$]h&]uh1hhhhhhhhM>ubh)}(hhh](h)}(h0Communicating with autofs: root directory ioctlsh]h0Communicating with autofs: root directory ioctls}(hj5 hhhNhNubah}(h]h ]h"]h$]h&]uh1hhj2 hhhhhMoubh)}(hThe root directory of an autofs filesystem will respond to a number of ioctls. The process issuing the ioctl must have the CAP_SYS_ADMIN capability, or must be the automount daemon.h]hThe root directory of an autofs filesystem will respond to a number of ioctls. The process issuing the ioctl must have the CAP_SYS_ADMIN capability, or must be the automount daemon.}(hjC hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMqhj2 hhubh)}(h!The available ioctl commands are:h]h!The available ioctl commands are:}(hjQ hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMuhj2 hhubjF)}(hhh](h)}(h**AUTOFS_IOC_READY**: a notification has been handled. The argument to the ioctl command is the "wait_queue_token" number corresponding to the notification being acknowledged.h]hdefinition_list)}(hhh]hdefinition_list_item)}(h**AUTOFS_IOC_READY**: a notification has been handled. The argument to the ioctl command is the "wait_queue_token" number corresponding to the notification being acknowledged.h](hterm)}(h**AUTOFS_IOC_READY**:h](jD)}(h**AUTOFS_IOC_READY**h]hAUTOFS_IOC_READY}(hjw hhhNhNubah}(h]h ]h"]h$]h&]uh1jChjs ubh:}(hjs hhhNhNubeh}(h]h ]h"]h$]h&]uh1jq hhhMyhjm ubh definition)}(hhh]h)}(ha notification has been handled. The argument to the ioctl command is the "wait_queue_token" number corresponding to the notification being acknowledged.h]ha notification has been handled. The argument to the ioctl command is the “wait_queue_token” number corresponding to the notification being acknowledged.}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMxhj ubah}(h]h ]h"]h$]h&]uh1j hjm ubeh}(h]h ]h"]h$]h&]uh1jk hhhMyhjh ubah}(h]h ]h"]h$]h&]uh1jf hjb ubah}(h]h ]h"]h$]h&]uh1hhj_ hhhNhNubh)}(hf**AUTOFS_IOC_FAIL**: similar to above, but indicates failure with the error code `ENOENT`.h]jg )}(hhh]jl )}(hZ**AUTOFS_IOC_FAIL**: similar to above, but indicates failure with the error code `ENOENT`.h](jr )}(h**AUTOFS_IOC_FAIL**:h](jD)}(h**AUTOFS_IOC_FAIL**h]hAUTOFS_IOC_FAIL}(hj hhhNhNubah}(h]h ]h"]h$]h&]uh1jChj ubh:}(hj hhhNhNubeh}(h]h ]h"]h$]h&]uh1jq hhhM|hj ubj )}(hhh]h)}(hEsimilar to above, but indicates failure with the error code `ENOENT`.h](h**AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD**: same as `close(ioctlfd)`.h](jr )}(h$**AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD**:h](jD)}(h#**AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD**h]hAUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD}(hj7hhhNhNubah}(h]h ]h"]h$]h&]uh1jChj3ubh:}(hj3hhhNhNubeh}(h]h ]h"]h$]h&]uh1jq hhhMhj/ubj )}(hhh]h)}(hsame as `close(ioctlfd)`.h](hsame as }(hjRhhhNhNubj)}(h`close(ioctlfd)`h]hclose(ioctlfd)}(hjZhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjRubh.}(hjRhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjOubah}(h]h ]h"]h$]h&]uh1j hj/ubeh}(h]h ]h"]h$]h&]uh1jk hhhMhj,ubah}(h]h ]h"]h$]h&]uh1jf hj(ubah}(h]h ]h"]h$]h&]uh1hhjahhhNhNubh)}(hX"**AUTOFS_DEV_IOCTL_SETPIPEFD_CMD**: if the filesystem is in catatonic mode, this can provide the write end of a new pipe in `setpipefd.pipefd` to re-establish communication with a daemon. The process group of the calling process is used to identify the daemon.h]jg )}(hhh]jl )}(hX**AUTOFS_DEV_IOCTL_SETPIPEFD_CMD**: if the filesystem is in catatonic mode, this can provide the write end of a new pipe in `setpipefd.pipefd` to re-establish communication with a daemon. The process group of the calling process is used to identify the daemon.h](jr )}(h#**AUTOFS_DEV_IOCTL_SETPIPEFD_CMD**:h](jD)}(h"**AUTOFS_DEV_IOCTL_SETPIPEFD_CMD**h]hAUTOFS_DEV_IOCTL_SETPIPEFD_CMD}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jq hhhMhjubj )}(hhh]h)}(hif the filesystem is in catatonic mode, this can provide the write end of a new pipe in `setpipefd.pipefd` to re-establish communication with a daemon. The process group of the calling process is used to identify the daemon.h](hXif the filesystem is in catatonic mode, this can provide the write end of a new pipe in }(hjhhhNhNubj)}(h`setpipefd.pipefd`h]hsetpipefd.pipefd}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhv to re-establish communication with a daemon. The process group of the calling process is used to identify the daemon.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]uh1jk hhhMhjubah}(h]h ]h"]h$]h&]uh1jf hjubah}(h]h ]h"]h$]h&]uh1hhjahhhNhNubh)}(hX**AUTOFS_DEV_IOCTL_REQUESTER_CMD**: `path` should be a name within the filesystem that has been auto-mounted on. On successful return, `requester.uid` and `requester.gid` will be the UID and GID of the process which triggered that mount.h]jg )}(hhh]jl )}(h**AUTOFS_DEV_IOCTL_REQUESTER_CMD**: `path` should be a name within the filesystem that has been auto-mounted on. On successful return, `requester.uid` and `requester.gid` will be the UID and GID of the process which triggered that mount.h](jr )}(h#**AUTOFS_DEV_IOCTL_REQUESTER_CMD**:h](jD)}(h"**AUTOFS_DEV_IOCTL_REQUESTER_CMD**h]hAUTOFS_DEV_IOCTL_REQUESTER_CMD}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubh:}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1jq hhhMhjubj )}(hhh]h)}(h`path` should be a name within the filesystem that has been auto-mounted on. On successful return, `requester.uid` and `requester.gid` will be the UID and GID of the process which triggered that mount.h](j)}(h`path`h]hpath}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh] should be a name within the filesystem that has been auto-mounted on. On successful return, }(hjhhhNhNubj)}(h`requester.uid`h]h requester.uid}(hj,hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh and }(hjhhhNhNubj)}(h`requester.gid`h]h requester.gid}(hj>hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubhC will be the UID and GID of the process which triggered that mount.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j hjubeh}(h]h ]h"]h$]h&]uh1jk hhhMhjubah}(h]h ]h"]h$]h&]uh1jf hjubah}(h]h ]h"]h$]h&]uh1hhjahhhNhNubh)}(h**AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD**: Check if path is a mountpoint of a particular type - see separate documentation for details. h]jg )}(hhh]jl )}(h**AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD**: Check if path is a mountpoint of a particular type - see separate documentation for details. h](jr )}(h&**AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD**:h](jD)}(h%**AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD**h]h!AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD}(hj}hhhNhNubah}(h]h ]h"]h$]h&]uh1jChjyubh:}(hjyhhhNhNubeh}(h]h ]h"]h$]h&]uh1jq hhhMhjuubj )}(hhh]h)}(h\Check if path is a mountpoint of a particular type - see separate documentation for details.h]h\Check if path is a mountpoint of a particular type - see separate documentation for details.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1j hjuubeh}(h]h ]h"]h$]h&]uh1jk hhhMhjrubah}(h]h ]h"]h$]h&]uh1jf hjnubah}(h]h ]h"]h$]h&]uh1hhjahhhNhNubh)}(h!**AUTOFS_DEV_IOCTL_PROTOVER_CMD**h]h)}(hjh]jD)}(hjh]hAUTOFS_DEV_IOCTL_PROTOVER_CMD}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjahhhhhNubh)}(h$**AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD**h]h)}(hjh]jD)}(hjh]h AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjahhhhhNubh)}(h**AUTOFS_DEV_IOCTL_READY_CMD**h]h)}(hjh]jD)}(hjh]hAUTOFS_DEV_IOCTL_READY_CMD}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjahhhhhNubh)}(h**AUTOFS_DEV_IOCTL_FAIL_CMD**h]h)}(hj h]jD)}(hj h]hAUTOFS_DEV_IOCTL_FAIL_CMD}(hj%hhhNhNubah}(h]h ]h"]h$]h&]uh1jChj"ubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjahhhhhNubh)}(h"**AUTOFS_DEV_IOCTL_CATATONIC_CMD**h]h)}(hj@h]jD)}(hj@h]hAUTOFS_DEV_IOCTL_CATATONIC_CMD}(hjEhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjBubah}(h]h ]h"]h$]h&]uh1hhhhMhj>ubah}(h]h ]h"]h$]h&]uh1hhjahhhhhNubh)}(h **AUTOFS_DEV_IOCTL_TIMEOUT_CMD**h]h)}(hj`h]jD)}(hj`h]hAUTOFS_DEV_IOCTL_TIMEOUT_CMD}(hjehhhNhNubah}(h]h ]h"]h$]h&]uh1jChjbubah}(h]h ]h"]h$]h&]uh1hhhhMhj^ubah}(h]h ]h"]h$]h&]uh1hhjahhhhhNubh)}(h**AUTOFS_DEV_IOCTL_EXPIRE_CMD**h]h)}(hjh]jD)}(hjh]hAUTOFS_DEV_IOCTL_EXPIRE_CMD}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubah}(h]h ]h"]h$]h&]uh1hhhhMhj~ubah}(h]h ]h"]h$]h&]uh1hhjahhhhhNubh)}(h#**AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD** h]h)}(h"**AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD**h]jD)}(hjh]hAUTOFS_DEV_IOCTL_ASKUMOUNT_CMD}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubah}(h]h ]h"]h$]h&]uh1hhhhMhjubah}(h]h ]h"]h$]h&]uh1hhjahhhhhNubeh}(h]h ]h"]h$]h&]jjuh1jEhhhMhjHhhubh)}(hXThese all have the same function as the similarly named **AUTOFS_IOC** ioctls, except that **FAIL** can be given an explicit error number in `fail.status` instead of assuming `ENOENT`, and this **EXPIRE** command corresponds to **AUTOFS_IOC_EXPIRE_MULTI**.h](h8These all have the same function as the similarly named }(hjhhhNhNubjD)}(h**AUTOFS_IOC**h]h AUTOFS_IOC}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubh ioctls, except that }(hjhhhNhNubjD)}(h**FAIL**h]hFAIL}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubh* can be given an explicit error number in }(hjhhhNhNubj)}(h `fail.status`h]h fail.status}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh instead of assuming }(hjhhhNhNubj)}(h`ENOENT`h]hENOENT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh , and this }(hjhhhNhNubjD)}(h **EXPIRE**h]hEXPIRE}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubh command corresponds to }(hjhhhNhNubjD)}(h**AUTOFS_IOC_EXPIRE_MULTI**h]hAUTOFS_IOC_EXPIRE_MULTI}(hj'hhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjHhhubeh}(h],communicating-with-autofs-char-device-ioctlsah ]h"]-communicating with autofs: char-device ioctlsah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hCatatonic modeh]hCatatonic mode}(hjJhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjGhhhhhMubh)}(hAs mentioned, an autofs mount can enter "catatonic" mode. This happens if a write to the notification pipe fails, or if it is explicitly requested by an `ioctl`.h](hAs mentioned, an autofs mount can enter “catatonic” mode. This happens if a write to the notification pipe fails, or if it is explicitly requested by an }(hjXhhhNhNubj)}(h`ioctl`h]hioctl}(hj`hhhNhNubah}(h]h ]h"]h$]h&]uh1jhjXubh.}(hjXhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjGhhubh)}(hxWhen entering catatonic mode, the pipe is closed and any pending notifications are acknowledged with the error `ENOENT`.h](hoWhen entering catatonic mode, the pipe is closed and any pending notifications are acknowledged with the error }(hjxhhhNhNubj)}(h`ENOENT`h]hENOENT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjxubh.}(hjxhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjGhhubh)}(hOnce in catatonic mode attempts to access non-existing names will result in `ENOENT` while attempts to access existing directories will be treated in the same way as if they came from the daemon, so mount traps will not fire.h](hLOnce in catatonic mode attempts to access non-existing names will result in }(hjhhhNhNubj)}(h`ENOENT`h]hENOENT}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh while attempts to access existing directories will be treated in the same way as if they came from the daemon, so mount traps will not fire.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhMhjGhhubh)}(hXWhen the filesystem is mounted a _uid_ and _gid_ can be given which set the ownership of directories and symbolic links. When the filesystem is in catatonic mode, any process with a matching UID can create directories or symlinks in the root directory, but not in other directories.h]hXWhen the filesystem is mounted a _uid_ and _gid_ can be given which set the ownership of directories and symbolic links. When the filesystem is in catatonic mode, any process with a matching UID can create directories or symlinks in the root directory, but not in other directories.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhMhjGhhubh)}(hfCatatonic mode can only be left via the **AUTOFS_DEV_IOCTL_OPENMOUNT_CMD** ioctl on the `/dev/autofs`.h](h(Catatonic mode can only be left via the }(hjhhhNhNubjD)}(h"**AUTOFS_DEV_IOCTL_OPENMOUNT_CMD**h]hAUTOFS_DEV_IOCTL_OPENMOUNT_CMD}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jChjubh ioctl on the }(hjhhhNhNubj)}(h `/dev/autofs`h]h /dev/autofs}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjubh.}(hjhhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM#hjGhhubeh}(h]catatonic-modeah ]h"]catatonic modeah$]h&]uh1hhhhhhhhMubh)}(hhh](h)}(hThe "ignore" mount optionh]hThe “ignore” mount option}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjhhhhhM'ubh)}(hThe "ignore" mount option can be used to provide a generic indicator to applications that the mount entry should be ignored when displaying mount information.h]hThe “ignore” mount option can be used to provide a generic indicator to applications that the mount entry should be ignored when displaying mount information.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM)hjhhubh)}(hIn other OSes that provide autofs and that provide a mount list to user space based on the kernel mount list a no-op mount option ("ignore" is the one use on the most common OSes) is allowed so that autofs file system users can optionally use it.h]hIn other OSes that provide autofs and that provide a mount list to user space based on the kernel mount list a no-op mount option (“ignore” is the one use on the most common OSes) is allowed so that autofs file system users can optionally use it.}(hjhhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM-hjhhubh)}(h|This is intended to be used by user space programs to exclude autofs mounts from consideration when reading the mounts list.h]h|This is intended to be used by user space programs to exclude autofs mounts from consideration when reading the mounts list.}(hj-hhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM2hjhhubeh}(h]the-ignore-mount-optionah ]h"]the "ignore" mount optionah$]h&]uh1hhhhhhhhM'ubh)}(hhh](h)}(h&autofs, name spaces, and shared mountsh]h&autofs, name spaces, and shared mounts}(hjFhhhNhNubah}(h]h ]h"]h$]h&]uh1hhjChhhhhM6ubh)}(hWith bind mounts and name spaces it is possible for an autofs filesystem to appear at multiple places in one or more filesystem name spaces. For this to work sensibly, the autofs filesystem should always be mounted "shared". e.g. ::h]hWith bind mounts and name spaces it is possible for an autofs filesystem to appear at multiple places in one or more filesystem name spaces. For this to work sensibly, the autofs filesystem should always be mounted “shared”. e.g.}(hjThhhNhNubah}(h]h ]h"]h$]h&]uh1hhhhM8hjChhubj )}(h'mount --make-shared /autofs/mount/pointh]h'mount --make-shared /autofs/mount/point}hjbsbah}(h]h ]h"]h$]h&]j j uh1j hhhM=hjChhubh)}(hX The automount daemon is only able to manage a single mount location for an autofs filesystem and if mounts on that are not 'shared', other locations will not behave as expected. In particular access to those other locations will likely result in the `ELOOP` error ::h](hThe automount daemon is only able to manage a single mount location for an autofs filesystem and if mounts on that are not ‘shared’, other locations will not behave as expected. In particular access to those other locations will likely result in the }(hjphhhNhNubj)}(h`ELOOP`h]hELOOP}(hjxhhhNhNubah}(h]h ]h"]h$]h&]uh1jhjpubh error}(hjphhhNhNubeh}(h]h ]h"]h$]h&]uh1hhhhM?hjChhubj )}(h!Too many levels of symbolic linksh]h!Too many levels of symbolic links}hjsbah}(h]h ]h"]h$]h&]j j uh1j hhhMDhjChhubeh}(h]$autofs-name-spaces-and-shared-mountsah ]h"]&autofs, name spaces, and shared mountsah$]h&]uh1hhhhhhhhM6ubeh}(h]autofs-how-it-worksah ]h"]autofs - how it worksah$]h&]uh1hhhhhhhhKubeh}(h]h ]h"]h$]h&]sourcehuh1hcurrent_sourceN current_lineNsettingsdocutils.frontendValues)}(hN generatorN datestampN source_linkN source_urlN toc_backlinksentryfootnote_backlinksK sectnum_xformKstrip_commentsNstrip_elements_with_classesN strip_classesN report_levelK halt_levelKexit_status_levelKdebugNwarning_streamN tracebackinput_encoding utf-8-siginput_encoding_error_handlerstrictoutput_encodingutf-8output_encoding_error_handlerjerror_encodingutf-8error_encoding_error_handlerbackslashreplace language_codeenrecord_dependenciesNconfigN id_prefixhauto_id_prefixid dump_settingsNdump_internalsNdump_transformsNdump_pseudo_xmlNexpose_internalsNstrict_visitorN_disable_configN_sourcehʌ _destinationN _config_files]7/var/lib/git/docbuild/linux/Documentation/docutils.confafile_insertion_enabled raw_enabledKline_length_limitM'pep_referencesN pep_base_urlhttps://peps.python.org/pep_file_url_templatepep-%04drfc_referencesN rfc_base_url&https://datatracker.ietf.org/doc/html/ tab_widthKtrim_footnote_reference_spacesyntax_highlightlong smart_quotessmartquotes_locales]character_level_inline_markupdoctitle_xform docinfo_xformKsectsubtitle_xform image_loadinglinkembed_stylesheetcloak_email_addressessection_self_linkenvNubreporterNindirect_targets]substitution_defs}substitution_names}refnames}refids}nameids}(jjj3j0jhjejjj$j!j) j& j^ j[ j/ j, jEjBjDjAjjj@j=jju nametypes}(jj3jhjj$j) j^ j/ jEjDjj@juh}(jhj0hjej6jjkj!j j& j'j[ j, j, ja jBj2 jAjHjjGj=jjjCu footnote_refs} citation_refs} autofootnotes]autofootnote_refs]symbol_footnotes]symbol_footnote_refs] footnotes] citations]autofootnote_startKsymbol_footnote_startK id_counter collectionsCounter}Rparse_messages]transform_messages] transformerN include_log] decorationNhhub.