1f11f2a3cSJaskaran Singh===================== 2f11f2a3cSJaskaran Singhautofs - how it works 3f11f2a3cSJaskaran Singh===================== 4f11f2a3cSJaskaran Singh 5f11f2a3cSJaskaran SinghPurpose 6f11f2a3cSJaskaran Singh======= 7f11f2a3cSJaskaran Singh 8f11f2a3cSJaskaran SinghThe goal of autofs is to provide on-demand mounting and race free 9f11f2a3cSJaskaran Singhautomatic unmounting of various other filesystems. This provides two 10f11f2a3cSJaskaran Singhkey advantages: 11f11f2a3cSJaskaran Singh 12f11f2a3cSJaskaran Singh1. There is no need to delay boot until all filesystems that 13f11f2a3cSJaskaran Singh might be needed are mounted. Processes that try to access those 14f11f2a3cSJaskaran Singh slow filesystems might be delayed but other processes can 15f11f2a3cSJaskaran Singh continue freely. This is particularly important for 16f11f2a3cSJaskaran Singh network filesystems (e.g. NFS) or filesystems stored on 17f11f2a3cSJaskaran Singh media with a media-changing robot. 18f11f2a3cSJaskaran Singh 19f11f2a3cSJaskaran Singh2. The names and locations of filesystems can be stored in 20f11f2a3cSJaskaran Singh a remote database and can change at any time. The content 21f11f2a3cSJaskaran Singh in that data base at the time of access will be used to provide 22f11f2a3cSJaskaran Singh a target for the access. The interpretation of names in the 23f11f2a3cSJaskaran Singh filesystem can even be programmatic rather than database-backed, 24f11f2a3cSJaskaran Singh allowing wildcards for example, and can vary based on the user who 25f11f2a3cSJaskaran Singh first accessed a name. 26f11f2a3cSJaskaran Singh 27f11f2a3cSJaskaran SinghContext 28f11f2a3cSJaskaran Singh======= 29f11f2a3cSJaskaran Singh 30f11f2a3cSJaskaran SinghThe "autofs" filesystem module is only one part of an autofs system. 31f11f2a3cSJaskaran SinghThere also needs to be a user-space program which looks up names 32f11f2a3cSJaskaran Singhand mounts filesystems. This will often be the "automount" program, 33f11f2a3cSJaskaran Singhthough other tools including "systemd" can make use of "autofs". 34f11f2a3cSJaskaran SinghThis document describes only the kernel module and the interactions 35f11f2a3cSJaskaran Singhrequired with any user-space program. Subsequent text refers to this 36f11f2a3cSJaskaran Singhas the "automount daemon" or simply "the daemon". 37f11f2a3cSJaskaran Singh 3853b606faSWasin Thonkaew"autofs" is a Linux kernel module which provides the "autofs" 39f11f2a3cSJaskaran Singhfilesystem type. Several "autofs" filesystems can be mounted and they 40f11f2a3cSJaskaran Singhcan each be managed separately, or all managed by the same daemon. 41f11f2a3cSJaskaran Singh 42f11f2a3cSJaskaran SinghContent 43f11f2a3cSJaskaran Singh======= 44f11f2a3cSJaskaran Singh 45f11f2a3cSJaskaran SinghAn autofs filesystem can contain 3 sorts of objects: directories, 46f11f2a3cSJaskaran Singhsymbolic links and mount traps. Mount traps are directories with 47f11f2a3cSJaskaran Singhextra properties as described in the next section. 48f11f2a3cSJaskaran Singh 49f11f2a3cSJaskaran SinghObjects can only be created by the automount daemon: symlinks are 50f11f2a3cSJaskaran Singhcreated with a regular `symlink` system call, while directories and 51f11f2a3cSJaskaran Singhmount traps are created with `mkdir`. The determination of whether a 52e8a9e30dSJaskaran Singhdirectory should be a mount trap is based on a master map. This master 53e8a9e30dSJaskaran Singhmap is consulted by autofs to determine which directories are mount 54e8a9e30dSJaskaran Singhpoints. Mount points can be *direct*/*indirect*/*offset*. 55e8a9e30dSJaskaran SinghOn most systems, the default master map is located at */etc/auto.master*. 56f11f2a3cSJaskaran Singh 57f11f2a3cSJaskaran SinghIf neither the *direct* or *offset* mount options are given (so the 58f11f2a3cSJaskaran Singhmount is considered to be *indirect*), then the root directory is 59f11f2a3cSJaskaran Singhalways a regular directory, otherwise it is a mount trap when it is 60f11f2a3cSJaskaran Singhempty and a regular directory when not empty. Note that *direct* and 61f11f2a3cSJaskaran Singh*offset* are treated identically so a concise summary is that the root 62f11f2a3cSJaskaran Singhdirectory is a mount trap only if the filesystem is mounted *direct* 63f11f2a3cSJaskaran Singhand the root is empty. 64f11f2a3cSJaskaran Singh 65f11f2a3cSJaskaran SinghDirectories created in the root directory are mount traps only if the 66f11f2a3cSJaskaran Singhfilesystem is mounted *indirect* and they are empty. 67f11f2a3cSJaskaran Singh 68f11f2a3cSJaskaran SinghDirectories further down the tree depend on the *maxproto* mount 69f11f2a3cSJaskaran Singhoption and particularly whether it is less than five or not. 70f11f2a3cSJaskaran SinghWhen *maxproto* is five, no directories further down the 71f11f2a3cSJaskaran Singhtree are ever mount traps, they are always regular directories. When 72f11f2a3cSJaskaran Singhthe *maxproto* is four (or three), these directories are mount traps 73f11f2a3cSJaskaran Singhprecisely when they are empty. 74f11f2a3cSJaskaran Singh 75f11f2a3cSJaskaran SinghSo: non-empty (i.e. non-leaf) directories are never mount traps. Empty 76f11f2a3cSJaskaran Singhdirectories are sometimes mount traps, and sometimes not depending on 77f11f2a3cSJaskaran Singhwhere in the tree they are (root, top level, or lower), the *maxproto*, 78f11f2a3cSJaskaran Singhand whether the mount was *indirect* or not. 79f11f2a3cSJaskaran Singh 80f11f2a3cSJaskaran SinghMount Traps 81f11f2a3cSJaskaran Singh=========== 82f11f2a3cSJaskaran Singh 83f11f2a3cSJaskaran SinghA core element of the implementation of autofs is the Mount Traps 84f11f2a3cSJaskaran Singhwhich are provided by the Linux VFS. Any directory provided by a 85f11f2a3cSJaskaran Singhfilesystem can be designated as a trap. This involves two separate 86f11f2a3cSJaskaran Singhfeatures that work together to allow autofs to do its job. 87f11f2a3cSJaskaran Singh 88f11f2a3cSJaskaran Singh**DCACHE_NEED_AUTOMOUNT** 89f11f2a3cSJaskaran Singh 90f11f2a3cSJaskaran SinghIf a dentry has the DCACHE_NEED_AUTOMOUNT flag set (which gets set if 91f11f2a3cSJaskaran Singhthe inode has S_AUTOMOUNT set, or can be set directly) then it is 92f11f2a3cSJaskaran Singh(potentially) a mount trap. Any access to this directory beyond a 93f11f2a3cSJaskaran Singh"`stat`" will (normally) cause the `d_op->d_automount()` dentry operation 94f11f2a3cSJaskaran Singhto be called. The task of this method is to find the filesystem that 95f11f2a3cSJaskaran Singhshould be mounted on the directory and to return it. The VFS is 96f11f2a3cSJaskaran Singhresponsible for actually mounting the root of this filesystem on the 97f11f2a3cSJaskaran Singhdirectory. 98f11f2a3cSJaskaran Singh 99f11f2a3cSJaskaran Singhautofs doesn't find the filesystem itself but sends a message to the 100f11f2a3cSJaskaran Singhautomount daemon asking it to find and mount the filesystem. The 101f11f2a3cSJaskaran Singhautofs `d_automount` method then waits for the daemon to report that 102f11f2a3cSJaskaran Singheverything is ready. It will then return "`NULL`" indicating that the 103f11f2a3cSJaskaran Singhmount has already happened. The VFS doesn't try to mount anything but 104f11f2a3cSJaskaran Singhfollows down the mount that is already there. 105f11f2a3cSJaskaran Singh 106f11f2a3cSJaskaran SinghThis functionality is sufficient for some users of mount traps such 107f11f2a3cSJaskaran Singhas NFS which creates traps so that mountpoints on the server can be 108f11f2a3cSJaskaran Singhreflected on the client. However it is not sufficient for autofs. As 109f11f2a3cSJaskaran Singhmounting onto a directory is considered to be "beyond a `stat`", the 110f11f2a3cSJaskaran Singhautomount daemon would not be able to mount a filesystem on the 'trap' 111f11f2a3cSJaskaran Singhdirectory without some way to avoid getting caught in the trap. For 112f11f2a3cSJaskaran Singhthat purpose there is another flag. 113f11f2a3cSJaskaran Singh 114f11f2a3cSJaskaran Singh**DCACHE_MANAGE_TRANSIT** 115f11f2a3cSJaskaran Singh 116f11f2a3cSJaskaran SinghIf a dentry has DCACHE_MANAGE_TRANSIT set then two very different but 117f11f2a3cSJaskaran Singhrelated behaviours are invoked, both using the `d_op->d_manage()` 118f11f2a3cSJaskaran Singhdentry operation. 119f11f2a3cSJaskaran Singh 120f11f2a3cSJaskaran SinghFirstly, before checking to see if any filesystem is mounted on the 121f11f2a3cSJaskaran Singhdirectory, d_manage() will be called with the `rcu_walk` parameter set 122f11f2a3cSJaskaran Singhto `false`. It may return one of three things: 123f11f2a3cSJaskaran Singh 124f11f2a3cSJaskaran Singh- A return value of zero indicates that there is nothing special 125f11f2a3cSJaskaran Singh about this dentry and normal checks for mounts and automounts 126f11f2a3cSJaskaran Singh should proceed. 127f11f2a3cSJaskaran Singh 128f11f2a3cSJaskaran Singh autofs normally returns zero, but first waits for any 129f11f2a3cSJaskaran Singh expiry (automatic unmounting of the mounted filesystem) to 130f11f2a3cSJaskaran Singh complete. This avoids races. 131f11f2a3cSJaskaran Singh 132f11f2a3cSJaskaran Singh- A return value of `-EISDIR` tells the VFS to ignore any mounts 133f11f2a3cSJaskaran Singh on the directory and to not consider calling `->d_automount()`. 134f11f2a3cSJaskaran Singh This effectively disables the **DCACHE_NEED_AUTOMOUNT** flag 135f11f2a3cSJaskaran Singh causing the directory not be a mount trap after all. 136f11f2a3cSJaskaran Singh 137f11f2a3cSJaskaran Singh autofs returns this if it detects that the process performing the 138f11f2a3cSJaskaran Singh lookup is the automount daemon and that the mount has been 139f11f2a3cSJaskaran Singh requested but has not yet completed. How it determines this is 140f11f2a3cSJaskaran Singh discussed later. This allows the automount daemon not to get 141f11f2a3cSJaskaran Singh caught in the mount trap. 142f11f2a3cSJaskaran Singh 143f11f2a3cSJaskaran Singh There is a subtlety here. It is possible that a second autofs 144f11f2a3cSJaskaran Singh filesystem can be mounted below the first and for both of them to 145f11f2a3cSJaskaran Singh be managed by the same daemon. For the daemon to be able to mount 146f11f2a3cSJaskaran Singh something on the second it must be able to "walk" down past the 147f11f2a3cSJaskaran Singh first. This means that d_manage cannot *always* return -EISDIR for 148f11f2a3cSJaskaran Singh the automount daemon. It must only return it when a mount has 149f11f2a3cSJaskaran Singh been requested, but has not yet completed. 150f11f2a3cSJaskaran Singh 151f11f2a3cSJaskaran Singh `d_manage` also returns `-EISDIR` if the dentry shouldn't be a 152f11f2a3cSJaskaran Singh mount trap, either because it is a symbolic link or because it is 153f11f2a3cSJaskaran Singh not empty. 154f11f2a3cSJaskaran Singh 155f11f2a3cSJaskaran Singh- Any other negative value is treated as an error and returned 156f11f2a3cSJaskaran Singh to the caller. 157f11f2a3cSJaskaran Singh 158f11f2a3cSJaskaran Singh autofs can return 159f11f2a3cSJaskaran Singh 160f11f2a3cSJaskaran Singh - -ENOENT if the automount daemon failed to mount anything, 161f11f2a3cSJaskaran Singh - -ENOMEM if it ran out of memory, 162f11f2a3cSJaskaran Singh - -EINTR if a signal arrived while waiting for expiry to 163f11f2a3cSJaskaran Singh complete 164f11f2a3cSJaskaran Singh - or any other error sent down by the automount daemon. 165f11f2a3cSJaskaran Singh 166f11f2a3cSJaskaran Singh 167f11f2a3cSJaskaran SinghThe second use case only occurs during an "RCU-walk" and so `rcu_walk` 168f11f2a3cSJaskaran Singhwill be set. 169f11f2a3cSJaskaran Singh 170f11f2a3cSJaskaran SinghAn RCU-walk is a fast and lightweight process for walking down a 171f11f2a3cSJaskaran Singhfilename path (i.e. it is like running on tip-toes). RCU-walk cannot 172f11f2a3cSJaskaran Singhcope with all situations so when it finds a difficulty it falls back 173f11f2a3cSJaskaran Singhto "REF-walk", which is slower but more robust. 174f11f2a3cSJaskaran Singh 175f11f2a3cSJaskaran SinghRCU-walk will never call `->d_automount`; the filesystems must already 176f11f2a3cSJaskaran Singhbe mounted or RCU-walk cannot handle the path. 177f11f2a3cSJaskaran SinghTo determine if a mount-trap is safe for RCU-walk mode it calls 178f11f2a3cSJaskaran Singh`->d_manage()` with `rcu_walk` set to `true`. 179f11f2a3cSJaskaran Singh 180f11f2a3cSJaskaran SinghIn this case `d_manage()` must avoid blocking and should avoid taking 181f11f2a3cSJaskaran Singhspinlocks if at all possible. Its sole purpose is to determine if it 182f11f2a3cSJaskaran Singhwould be safe to follow down into any mounted directory and the only 183f11f2a3cSJaskaran Singhreason that it might not be is if an expiry of the mount is 184f11f2a3cSJaskaran Singhunderway. 185f11f2a3cSJaskaran Singh 186f11f2a3cSJaskaran SinghIn the `rcu_walk` case, `d_manage()` cannot return -EISDIR to tell the 187f11f2a3cSJaskaran SinghVFS that this is a directory that doesn't require d_automount. If 188f11f2a3cSJaskaran Singh`rcu_walk` sees a dentry with DCACHE_NEED_AUTOMOUNT set but nothing 189f11f2a3cSJaskaran Singhmounted, it *will* fall back to REF-walk. `d_manage()` cannot make the 190f11f2a3cSJaskaran SinghVFS remain in RCU-walk mode, but can only tell it to get out of 191f11f2a3cSJaskaran SinghRCU-walk mode by returning `-ECHILD`. 192f11f2a3cSJaskaran Singh 193f11f2a3cSJaskaran SinghSo `d_manage()`, when called with `rcu_walk` set, should either return 194f11f2a3cSJaskaran Singh-ECHILD if there is any reason to believe it is unsafe to enter the 195f11f2a3cSJaskaran Singhmounted filesystem, otherwise it should return 0. 196f11f2a3cSJaskaran Singh 197f11f2a3cSJaskaran Singhautofs will return `-ECHILD` if an expiry of the filesystem has been 198f11f2a3cSJaskaran Singhinitiated or is being considered, otherwise it returns 0. 199f11f2a3cSJaskaran Singh 200f11f2a3cSJaskaran Singh 201f11f2a3cSJaskaran SinghMountpoint expiry 202f11f2a3cSJaskaran Singh================= 203f11f2a3cSJaskaran Singh 204f11f2a3cSJaskaran SinghThe VFS has a mechanism for automatically expiring unused mounts, 205f11f2a3cSJaskaran Singhmuch as it can expire any unused dentry information from the dcache. 206f11f2a3cSJaskaran SinghThis is guided by the MNT_SHRINKABLE flag. This only applies to 207f11f2a3cSJaskaran Singhmounts that were created by `d_automount()` returning a filesystem to be 208f11f2a3cSJaskaran Singhmounted. As autofs doesn't return such a filesystem but leaves the 209f11f2a3cSJaskaran Singhmounting to the automount daemon, it must involve the automount daemon 210f11f2a3cSJaskaran Singhin unmounting as well. This also means that autofs has more control 211f11f2a3cSJaskaran Singhover expiry. 212f11f2a3cSJaskaran Singh 213f11f2a3cSJaskaran SinghThe VFS also supports "expiry" of mounts using the MNT_EXPIRE flag to 214f11f2a3cSJaskaran Singhthe `umount` system call. Unmounting with MNT_EXPIRE will fail unless 215f11f2a3cSJaskaran Singha previous attempt had been made, and the filesystem has been inactive 216f11f2a3cSJaskaran Singhand untouched since that previous attempt. autofs does not depend on 217f11f2a3cSJaskaran Singhthis but has its own internal tracking of whether filesystems were 218f11f2a3cSJaskaran Singhrecently used. This allows individual names in the autofs directory 219f11f2a3cSJaskaran Singhto expire separately. 220f11f2a3cSJaskaran Singh 221f11f2a3cSJaskaran SinghWith version 4 of the protocol, the automount daemon can try to 222f11f2a3cSJaskaran Singhunmount any filesystems mounted on the autofs filesystem or remove any 223f11f2a3cSJaskaran Singhsymbolic links or empty directories any time it likes. If the unmount 224f11f2a3cSJaskaran Singhor removal is successful the filesystem will be returned to the state 225f11f2a3cSJaskaran Singhit was before the mount or creation, so that any access of the name 226f11f2a3cSJaskaran Singhwill trigger normal auto-mount processing. In particular, `rmdir` and 227f11f2a3cSJaskaran Singh`unlink` do not leave negative entries in the dcache as a normal 228f11f2a3cSJaskaran Singhfilesystem would, so an attempt to access a recently-removed object is 229f11f2a3cSJaskaran Singhpassed to autofs for handling. 230f11f2a3cSJaskaran Singh 231f11f2a3cSJaskaran SinghWith version 5, this is not safe except for unmounting from top-level 232f11f2a3cSJaskaran Singhdirectories. As lower-level directories are never mount traps, other 233f11f2a3cSJaskaran Singhprocesses will see an empty directory as soon as the filesystem is 234f11f2a3cSJaskaran Singhunmounted. So it is generally safest to use the autofs expiry 235f11f2a3cSJaskaran Singhprotocol described below. 236f11f2a3cSJaskaran Singh 237f11f2a3cSJaskaran SinghNormally the daemon only wants to remove entries which haven't been 238f11f2a3cSJaskaran Singhused for a while. For this purpose autofs maintains a "`last_used`" 239f11f2a3cSJaskaran Singhtime stamp on each directory or symlink. For symlinks it genuinely 240f11f2a3cSJaskaran Singhdoes record the last time the symlink was "used" or followed to find 241f11f2a3cSJaskaran Singhout where it points to. For directories the field is used slightly 242f11f2a3cSJaskaran Singhdifferently. The field is updated at mount time and during expire 243f11f2a3cSJaskaran Singhchecks if it is found to be in use (ie. open file descriptor or 244f11f2a3cSJaskaran Singhprocess working directory) and during path walks. The update done 245f11f2a3cSJaskaran Singhduring path walks prevents frequent expire and immediate mount of 246f11f2a3cSJaskaran Singhfrequently accessed automounts. But in the case where a GUI continually 247f11f2a3cSJaskaran Singhaccess or an application frequently scans an autofs directory tree 248f11f2a3cSJaskaran Singhthere can be an accumulation of mounts that aren't actually being 249f11f2a3cSJaskaran Singhused. To cater for this case the "`strictexpire`" autofs mount option 250f11f2a3cSJaskaran Singhcan be used to avoid the "`last_used`" update on path walk thereby 251f11f2a3cSJaskaran Singhpreventing this apparent inability to expire mounts that aren't 252f11f2a3cSJaskaran Singhreally in use. 253f11f2a3cSJaskaran Singh 254f11f2a3cSJaskaran SinghThe daemon is able to ask autofs if anything is due to be expired, 255f11f2a3cSJaskaran Singhusing an `ioctl` as discussed later. For a *direct* mount, autofs 256f11f2a3cSJaskaran Singhconsiders if the entire mount-tree can be unmounted or not. For an 257f11f2a3cSJaskaran Singh*indirect* mount, autofs considers each of the names in the top level 258f11f2a3cSJaskaran Singhdirectory to determine if any of those can be unmounted and cleaned 259f11f2a3cSJaskaran Singhup. 260f11f2a3cSJaskaran Singh 261f11f2a3cSJaskaran SinghThere is an option with indirect mounts to consider each of the leaves 262f11f2a3cSJaskaran Singhthat has been mounted on instead of considering the top-level names. 263f11f2a3cSJaskaran SinghThis was originally intended for compatibility with version 4 of autofs 264f11f2a3cSJaskaran Singhand should be considered as deprecated for Sun Format automount maps. 265f11f2a3cSJaskaran SinghHowever, it may be used again for amd format mount maps (which are 266f11f2a3cSJaskaran Singhgenerally indirect maps) because the amd automounter allows for the 267f11f2a3cSJaskaran Singhsetting of an expire timeout for individual mounts. But there are 268f11f2a3cSJaskaran Singhsome difficulties in making the needed changes for this. 269f11f2a3cSJaskaran Singh 270f11f2a3cSJaskaran SinghWhen autofs considers a directory it checks the `last_used` time and 271f11f2a3cSJaskaran Singhcompares it with the "timeout" value set when the filesystem was 272f11f2a3cSJaskaran Singhmounted, though this check is ignored in some cases. It also checks if 273f11f2a3cSJaskaran Singhthe directory or anything below it is in use. For symbolic links, 274f11f2a3cSJaskaran Singhonly the `last_used` time is ever considered. 275f11f2a3cSJaskaran Singh 276f11f2a3cSJaskaran SinghIf both appear to support expiring the directory or symlink, an action 277f11f2a3cSJaskaran Singhis taken. 278f11f2a3cSJaskaran Singh 279f11f2a3cSJaskaran SinghThere are two ways to ask autofs to consider expiry. The first is to 280f11f2a3cSJaskaran Singhuse the **AUTOFS_IOC_EXPIRE** ioctl. This only works for indirect 281f11f2a3cSJaskaran Singhmounts. If it finds something in the root directory to expire it will 282f11f2a3cSJaskaran Singhreturn the name of that thing. Once a name has been returned the 283f11f2a3cSJaskaran Singhautomount daemon needs to unmount any filesystems mounted below the 284f11f2a3cSJaskaran Singhname normally. As described above, this is unsafe for non-toplevel 285f11f2a3cSJaskaran Singhmounts in a version-5 autofs. For this reason the current `automount(8)` 286f11f2a3cSJaskaran Singhdoes not use this ioctl. 287f11f2a3cSJaskaran Singh 288f11f2a3cSJaskaran SinghThe second mechanism uses either the **AUTOFS_DEV_IOCTL_EXPIRE_CMD** or 289f11f2a3cSJaskaran Singhthe **AUTOFS_IOC_EXPIRE_MULTI** ioctl. This will work for both direct and 290f11f2a3cSJaskaran Singhindirect mounts. If it selects an object to expire, it will notify 291f11f2a3cSJaskaran Singhthe daemon using the notification mechanism described below. This 292f11f2a3cSJaskaran Singhwill block until the daemon acknowledges the expiry notification. 293f11f2a3cSJaskaran SinghThis implies that the "`EXPIRE`" ioctl must be sent from a different 294f11f2a3cSJaskaran Singhthread than the one which handles notification. 295f11f2a3cSJaskaran Singh 296f11f2a3cSJaskaran SinghWhile the ioctl is blocking, the entry is marked as "expiring" and 297f11f2a3cSJaskaran Singh`d_manage` will block until the daemon affirms that the unmount has 298f11f2a3cSJaskaran Singhcompleted (together with removing any directories that might have been 299f11f2a3cSJaskaran Singhnecessary), or has been aborted. 300f11f2a3cSJaskaran Singh 301f11f2a3cSJaskaran SinghCommunicating with autofs: detecting the daemon 302f11f2a3cSJaskaran Singh=============================================== 303f11f2a3cSJaskaran Singh 304f11f2a3cSJaskaran SinghThere are several forms of communication between the automount daemon 305f11f2a3cSJaskaran Singhand the filesystem. As we have already seen, the daemon can create and 306f11f2a3cSJaskaran Singhremove directories and symlinks using normal filesystem operations. 307f11f2a3cSJaskaran Singhautofs knows whether a process requesting some operation is the daemon 308f11f2a3cSJaskaran Singhor not based on its process-group id number (see getpgid(1)). 309f11f2a3cSJaskaran Singh 310f11f2a3cSJaskaran SinghWhen an autofs filesystem is mounted the pgid of the mounting 311f11f2a3cSJaskaran Singhprocesses is recorded unless the "pgrp=" option is given, in which 312f11f2a3cSJaskaran Singhcase that number is recorded instead. Any request arriving from a 313f11f2a3cSJaskaran Singhprocess in that process group is considered to come from the daemon. 314f11f2a3cSJaskaran SinghIf the daemon ever has to be stopped and restarted a new pgid can be 315f11f2a3cSJaskaran Singhprovided through an ioctl as will be described below. 316f11f2a3cSJaskaran Singh 317f11f2a3cSJaskaran SinghCommunicating with autofs: the event pipe 318f11f2a3cSJaskaran Singh========================================= 319f11f2a3cSJaskaran Singh 320f11f2a3cSJaskaran SinghWhen an autofs filesystem is mounted, the 'write' end of a pipe must 321f11f2a3cSJaskaran Singhbe passed using the 'fd=' mount option. autofs will write 322f11f2a3cSJaskaran Singhnotification messages to this pipe for the daemon to respond to. 323f11f2a3cSJaskaran SinghFor version 5, the format of the message is:: 324f11f2a3cSJaskaran Singh 325f11f2a3cSJaskaran Singh struct autofs_v5_packet { 326c11565e8SJaskaran Singh struct autofs_packet_hdr hdr; 327f11f2a3cSJaskaran Singh autofs_wqt_t wait_queue_token; 328f11f2a3cSJaskaran Singh __u32 dev; 329f11f2a3cSJaskaran Singh __u64 ino; 330f11f2a3cSJaskaran Singh __u32 uid; 331f11f2a3cSJaskaran Singh __u32 gid; 332f11f2a3cSJaskaran Singh __u32 pid; 333f11f2a3cSJaskaran Singh __u32 tgid; 334f11f2a3cSJaskaran Singh __u32 len; 335f11f2a3cSJaskaran Singh char name[NAME_MAX+1]; 336f11f2a3cSJaskaran Singh }; 337f11f2a3cSJaskaran Singh 338c11565e8SJaskaran SinghAnd the format of the header is:: 339c11565e8SJaskaran Singh 340c11565e8SJaskaran Singh struct autofs_packet_hdr { 341c11565e8SJaskaran Singh int proto_version; /* Protocol version */ 342c11565e8SJaskaran Singh int type; /* Type of packet */ 343c11565e8SJaskaran Singh }; 344c11565e8SJaskaran Singh 345f11f2a3cSJaskaran Singhwhere the type is one of :: 346f11f2a3cSJaskaran Singh 347f11f2a3cSJaskaran Singh autofs_ptype_missing_indirect 348f11f2a3cSJaskaran Singh autofs_ptype_expire_indirect 349f11f2a3cSJaskaran Singh autofs_ptype_missing_direct 350f11f2a3cSJaskaran Singh autofs_ptype_expire_direct 351f11f2a3cSJaskaran Singh 352f11f2a3cSJaskaran Singhso messages can indicate that a name is missing (something tried to 353f11f2a3cSJaskaran Singhaccess it but it isn't there) or that it has been selected for expiry. 354f11f2a3cSJaskaran Singh 355f11f2a3cSJaskaran SinghThe pipe will be set to "packet mode" (equivalent to passing 356f11f2a3cSJaskaran Singh`O_DIRECT`) to _pipe2(2)_ so that a read from the pipe will return at 357f11f2a3cSJaskaran Singhmost one packet, and any unread portion of a packet will be discarded. 358f11f2a3cSJaskaran Singh 359f11f2a3cSJaskaran SinghThe `wait_queue_token` is a unique number which can identify a 360f11f2a3cSJaskaran Singhparticular request to be acknowledged. When a message is sent over 361f11f2a3cSJaskaran Singhthe pipe the affected dentry is marked as either "active" or 362f11f2a3cSJaskaran Singh"expiring" and other accesses to it block until the message is 363f11f2a3cSJaskaran Singhacknowledged using one of the ioctls below with the relevant 364f11f2a3cSJaskaran Singh`wait_queue_token`. 365f11f2a3cSJaskaran Singh 366f11f2a3cSJaskaran SinghCommunicating with autofs: root directory ioctls 367f11f2a3cSJaskaran Singh================================================ 368f11f2a3cSJaskaran Singh 369f11f2a3cSJaskaran SinghThe root directory of an autofs filesystem will respond to a number of 370f11f2a3cSJaskaran Singhioctls. The process issuing the ioctl must have the CAP_SYS_ADMIN 371f11f2a3cSJaskaran Singhcapability, or must be the automount daemon. 372f11f2a3cSJaskaran Singh 373f11f2a3cSJaskaran SinghThe available ioctl commands are: 374f11f2a3cSJaskaran Singh 375f11f2a3cSJaskaran Singh- **AUTOFS_IOC_READY**: 376f11f2a3cSJaskaran Singh a notification has been handled. The argument 377f11f2a3cSJaskaran Singh to the ioctl command is the "wait_queue_token" number 378f11f2a3cSJaskaran Singh corresponding to the notification being acknowledged. 379f11f2a3cSJaskaran Singh- **AUTOFS_IOC_FAIL**: 380f11f2a3cSJaskaran Singh similar to above, but indicates failure with 381f11f2a3cSJaskaran Singh the error code `ENOENT`. 382f11f2a3cSJaskaran Singh- **AUTOFS_IOC_CATATONIC**: 383f11f2a3cSJaskaran Singh Causes the autofs to enter "catatonic" 384f11f2a3cSJaskaran Singh mode meaning that it stops sending notifications to the daemon. 385f11f2a3cSJaskaran Singh This mode is also entered if a write to the pipe fails. 386f11f2a3cSJaskaran Singh- **AUTOFS_IOC_PROTOVER**: 387f11f2a3cSJaskaran Singh This returns the protocol version in use. 388f11f2a3cSJaskaran Singh- **AUTOFS_IOC_PROTOSUBVER**: 389f11f2a3cSJaskaran Singh Returns the protocol sub-version which 390f11f2a3cSJaskaran Singh is really a version number for the implementation. 391f11f2a3cSJaskaran Singh- **AUTOFS_IOC_SETTIMEOUT**: 392f11f2a3cSJaskaran Singh This passes a pointer to an unsigned 393f11f2a3cSJaskaran Singh long. The value is used to set the timeout for expiry, and 394f11f2a3cSJaskaran Singh the current timeout value is stored back through the pointer. 395f11f2a3cSJaskaran Singh- **AUTOFS_IOC_ASKUMOUNT**: 396f11f2a3cSJaskaran Singh Returns, in the pointed-to `int`, 1 if 397f11f2a3cSJaskaran Singh the filesystem could be unmounted. This is only a hint as 398f11f2a3cSJaskaran Singh the situation could change at any instant. This call can be 399f11f2a3cSJaskaran Singh used to avoid a more expensive full unmount attempt. 400f11f2a3cSJaskaran Singh- **AUTOFS_IOC_EXPIRE**: 401f11f2a3cSJaskaran Singh as described above, this asks if there is 402f11f2a3cSJaskaran Singh anything suitable to expire. A pointer to a packet:: 403f11f2a3cSJaskaran Singh 404f11f2a3cSJaskaran Singh struct autofs_packet_expire_multi { 405c11565e8SJaskaran Singh struct autofs_packet_hdr hdr; 406f11f2a3cSJaskaran Singh autofs_wqt_t wait_queue_token; 407f11f2a3cSJaskaran Singh int len; 408f11f2a3cSJaskaran Singh char name[NAME_MAX+1]; 409f11f2a3cSJaskaran Singh }; 410f11f2a3cSJaskaran Singh 411f11f2a3cSJaskaran Singh is required. This is filled in with the name of something 412f11f2a3cSJaskaran Singh that can be unmounted or removed. If nothing can be expired, 413f11f2a3cSJaskaran Singh `errno` is set to `EAGAIN`. Even though a `wait_queue_token` 414f11f2a3cSJaskaran Singh is present in the structure, no "wait queue" is established 415f11f2a3cSJaskaran Singh and no acknowledgment is needed. 416f11f2a3cSJaskaran Singh- **AUTOFS_IOC_EXPIRE_MULTI**: 417f11f2a3cSJaskaran Singh This is similar to 418f11f2a3cSJaskaran Singh **AUTOFS_IOC_EXPIRE** except that it causes notification to be 419f11f2a3cSJaskaran Singh sent to the daemon, and it blocks until the daemon acknowledges. 420f11f2a3cSJaskaran Singh The argument is an integer which can contain two different flags. 421f11f2a3cSJaskaran Singh 422f11f2a3cSJaskaran Singh **AUTOFS_EXP_IMMEDIATE** causes `last_used` time to be ignored 423f11f2a3cSJaskaran Singh and objects are expired if the are not in use. 424f11f2a3cSJaskaran Singh 425f11f2a3cSJaskaran Singh **AUTOFS_EXP_FORCED** causes the in use status to be ignored 426f11f2a3cSJaskaran Singh and objects are expired ieven if they are in use. This assumes 427f11f2a3cSJaskaran Singh that the daemon has requested this because it is capable of 428f11f2a3cSJaskaran Singh performing the umount. 429f11f2a3cSJaskaran Singh 430f11f2a3cSJaskaran Singh **AUTOFS_EXP_LEAVES** will select a leaf rather than a top-level 431f11f2a3cSJaskaran Singh name to expire. This is only safe when *maxproto* is 4. 432f11f2a3cSJaskaran Singh 433f11f2a3cSJaskaran SinghCommunicating with autofs: char-device ioctls 434f11f2a3cSJaskaran Singh============================================= 435f11f2a3cSJaskaran Singh 436f11f2a3cSJaskaran SinghIt is not always possible to open the root of an autofs filesystem, 437f11f2a3cSJaskaran Singhparticularly a *direct* mounted filesystem. If the automount daemon 438f11f2a3cSJaskaran Singhis restarted there is no way for it to regain control of existing 439f11f2a3cSJaskaran Singhmounts using any of the above communication channels. To address this 440f11f2a3cSJaskaran Singhneed there is a "miscellaneous" character device (major 10, minor 235) 441f11f2a3cSJaskaran Singhwhich can be used to communicate directly with the autofs filesystem. 442f11f2a3cSJaskaran SinghIt requires CAP_SYS_ADMIN for access. 443f11f2a3cSJaskaran Singh 444f11f2a3cSJaskaran SinghThe 'ioctl's that can be used on this device are described in a separate 445f11f2a3cSJaskaran Singhdocument `autofs-mount-control.txt`, and are summarised briefly here. 446f11f2a3cSJaskaran SinghEach ioctl is passed a pointer to an `autofs_dev_ioctl` structure:: 447f11f2a3cSJaskaran Singh 448f11f2a3cSJaskaran Singh struct autofs_dev_ioctl { 449f11f2a3cSJaskaran Singh __u32 ver_major; 450f11f2a3cSJaskaran Singh __u32 ver_minor; 451f11f2a3cSJaskaran Singh __u32 size; /* total size of data passed in 452f11f2a3cSJaskaran Singh * including this struct */ 453f11f2a3cSJaskaran Singh __s32 ioctlfd; /* automount command fd */ 454f11f2a3cSJaskaran Singh 455f11f2a3cSJaskaran Singh /* Command parameters */ 456f11f2a3cSJaskaran Singh union { 457f11f2a3cSJaskaran Singh struct args_protover protover; 458f11f2a3cSJaskaran Singh struct args_protosubver protosubver; 459f11f2a3cSJaskaran Singh struct args_openmount openmount; 460f11f2a3cSJaskaran Singh struct args_ready ready; 461f11f2a3cSJaskaran Singh struct args_fail fail; 462f11f2a3cSJaskaran Singh struct args_setpipefd setpipefd; 463f11f2a3cSJaskaran Singh struct args_timeout timeout; 464f11f2a3cSJaskaran Singh struct args_requester requester; 465f11f2a3cSJaskaran Singh struct args_expire expire; 466f11f2a3cSJaskaran Singh struct args_askumount askumount; 467f11f2a3cSJaskaran Singh struct args_ismountpoint ismountpoint; 468f11f2a3cSJaskaran Singh }; 469f11f2a3cSJaskaran Singh 470*e910c8e3SArnd Bergmann char path[]; 471f11f2a3cSJaskaran Singh }; 472f11f2a3cSJaskaran Singh 473f11f2a3cSJaskaran SinghFor the **OPEN_MOUNT** and **IS_MOUNTPOINT** commands, the target 474f11f2a3cSJaskaran Singhfilesystem is identified by the `path`. All other commands identify 475f11f2a3cSJaskaran Singhthe filesystem by the `ioctlfd` which is a file descriptor open on the 476f11f2a3cSJaskaran Singhroot, and which can be returned by **OPEN_MOUNT**. 477f11f2a3cSJaskaran Singh 478f11f2a3cSJaskaran SinghThe `ver_major` and `ver_minor` are in/out parameters which check that 479f11f2a3cSJaskaran Singhthe requested version is supported, and report the maximum version 480f11f2a3cSJaskaran Singhthat the kernel module can support. 481f11f2a3cSJaskaran Singh 482f11f2a3cSJaskaran SinghCommands are: 483f11f2a3cSJaskaran Singh 484f11f2a3cSJaskaran Singh- **AUTOFS_DEV_IOCTL_VERSION_CMD**: 485f11f2a3cSJaskaran Singh does nothing, except validate and 486f11f2a3cSJaskaran Singh set version numbers. 487f11f2a3cSJaskaran Singh- **AUTOFS_DEV_IOCTL_OPENMOUNT_CMD**: 488f11f2a3cSJaskaran Singh return an open file descriptor 489f11f2a3cSJaskaran Singh on the root of an autofs filesystem. The filesystem is identified 490f11f2a3cSJaskaran Singh by name and device number, which is stored in `openmount.devid`. 491f11f2a3cSJaskaran Singh Device numbers for existing filesystems can be found in 492f11f2a3cSJaskaran Singh `/proc/self/mountinfo`. 493f11f2a3cSJaskaran Singh- **AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD**: 494f11f2a3cSJaskaran Singh same as `close(ioctlfd)`. 495f11f2a3cSJaskaran Singh- **AUTOFS_DEV_IOCTL_SETPIPEFD_CMD**: 496f11f2a3cSJaskaran Singh if the filesystem is in 497f11f2a3cSJaskaran Singh catatonic mode, this can provide the write end of a new pipe 498f11f2a3cSJaskaran Singh in `setpipefd.pipefd` to re-establish communication with a daemon. 499f11f2a3cSJaskaran Singh The process group of the calling process is used to identify the 500f11f2a3cSJaskaran Singh daemon. 501f11f2a3cSJaskaran Singh- **AUTOFS_DEV_IOCTL_REQUESTER_CMD**: 502f11f2a3cSJaskaran Singh `path` should be a 503f11f2a3cSJaskaran Singh name within the filesystem that has been auto-mounted on. 504f11f2a3cSJaskaran Singh On successful return, `requester.uid` and `requester.gid` will be 505f11f2a3cSJaskaran Singh the UID and GID of the process which triggered that mount. 506f11f2a3cSJaskaran Singh- **AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD**: 507f11f2a3cSJaskaran Singh Check if path is a 508f11f2a3cSJaskaran Singh mountpoint of a particular type - see separate documentation for 509f11f2a3cSJaskaran Singh details. 510f11f2a3cSJaskaran Singh 511f11f2a3cSJaskaran Singh- **AUTOFS_DEV_IOCTL_PROTOVER_CMD** 512f11f2a3cSJaskaran Singh- **AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD** 513f11f2a3cSJaskaran Singh- **AUTOFS_DEV_IOCTL_READY_CMD** 514f11f2a3cSJaskaran Singh- **AUTOFS_DEV_IOCTL_FAIL_CMD** 515f11f2a3cSJaskaran Singh- **AUTOFS_DEV_IOCTL_CATATONIC_CMD** 516f11f2a3cSJaskaran Singh- **AUTOFS_DEV_IOCTL_TIMEOUT_CMD** 517f11f2a3cSJaskaran Singh- **AUTOFS_DEV_IOCTL_EXPIRE_CMD** 518f11f2a3cSJaskaran Singh- **AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD** 519f11f2a3cSJaskaran Singh 520f11f2a3cSJaskaran SinghThese all have the same 521f11f2a3cSJaskaran Singhfunction as the similarly named **AUTOFS_IOC** ioctls, except 522f11f2a3cSJaskaran Singhthat **FAIL** can be given an explicit error number in `fail.status` 523f11f2a3cSJaskaran Singhinstead of assuming `ENOENT`, and this **EXPIRE** command 524f11f2a3cSJaskaran Singhcorresponds to **AUTOFS_IOC_EXPIRE_MULTI**. 525f11f2a3cSJaskaran Singh 526f11f2a3cSJaskaran SinghCatatonic mode 527f11f2a3cSJaskaran Singh============== 528f11f2a3cSJaskaran Singh 529f11f2a3cSJaskaran SinghAs mentioned, an autofs mount can enter "catatonic" mode. This 530f11f2a3cSJaskaran Singhhappens if a write to the notification pipe fails, or if it is 531f11f2a3cSJaskaran Singhexplicitly requested by an `ioctl`. 532f11f2a3cSJaskaran Singh 533f11f2a3cSJaskaran SinghWhen entering catatonic mode, the pipe is closed and any pending 534f11f2a3cSJaskaran Singhnotifications are acknowledged with the error `ENOENT`. 535f11f2a3cSJaskaran Singh 536f11f2a3cSJaskaran SinghOnce in catatonic mode attempts to access non-existing names will 537f11f2a3cSJaskaran Singhresult in `ENOENT` while attempts to access existing directories will 538f11f2a3cSJaskaran Singhbe treated in the same way as if they came from the daemon, so mount 539f11f2a3cSJaskaran Singhtraps will not fire. 540f11f2a3cSJaskaran Singh 541f11f2a3cSJaskaran SinghWhen the filesystem is mounted a _uid_ and _gid_ can be given which 542f11f2a3cSJaskaran Singhset the ownership of directories and symbolic links. When the 543f11f2a3cSJaskaran Singhfilesystem is in catatonic mode, any process with a matching UID can 544f11f2a3cSJaskaran Singhcreate directories or symlinks in the root directory, but not in other 545f11f2a3cSJaskaran Singhdirectories. 546f11f2a3cSJaskaran Singh 547f11f2a3cSJaskaran SinghCatatonic mode can only be left via the 548f11f2a3cSJaskaran Singh**AUTOFS_DEV_IOCTL_OPENMOUNT_CMD** ioctl on the `/dev/autofs`. 549f11f2a3cSJaskaran Singh 550f11f2a3cSJaskaran SinghThe "ignore" mount option 551f11f2a3cSJaskaran Singh========================= 552f11f2a3cSJaskaran Singh 553f11f2a3cSJaskaran SinghThe "ignore" mount option can be used to provide a generic indicator 554f11f2a3cSJaskaran Singhto applications that the mount entry should be ignored when displaying 555f11f2a3cSJaskaran Singhmount information. 556f11f2a3cSJaskaran Singh 557f11f2a3cSJaskaran SinghIn other OSes that provide autofs and that provide a mount list to user 558f11f2a3cSJaskaran Singhspace based on the kernel mount list a no-op mount option ("ignore" is 559f11f2a3cSJaskaran Singhthe one use on the most common OSes) is allowed so that autofs file 560f11f2a3cSJaskaran Singhsystem users can optionally use it. 561f11f2a3cSJaskaran Singh 562f11f2a3cSJaskaran SinghThis is intended to be used by user space programs to exclude autofs 563f11f2a3cSJaskaran Singhmounts from consideration when reading the mounts list. 564f11f2a3cSJaskaran Singh 565f11f2a3cSJaskaran Singhautofs, name spaces, and shared mounts 566f11f2a3cSJaskaran Singh====================================== 567f11f2a3cSJaskaran Singh 568f11f2a3cSJaskaran SinghWith bind mounts and name spaces it is possible for an autofs 569f11f2a3cSJaskaran Singhfilesystem to appear at multiple places in one or more filesystem 570f11f2a3cSJaskaran Singhname spaces. For this to work sensibly, the autofs filesystem should 571f11f2a3cSJaskaran Singhalways be mounted "shared". e.g. :: 572f11f2a3cSJaskaran Singh 573f11f2a3cSJaskaran Singh mount --make-shared /autofs/mount/point 574f11f2a3cSJaskaran Singh 575f11f2a3cSJaskaran SinghThe automount daemon is only able to manage a single mount location for 576f11f2a3cSJaskaran Singhan autofs filesystem and if mounts on that are not 'shared', other 577f11f2a3cSJaskaran Singhlocations will not behave as expected. In particular access to those 578f11f2a3cSJaskaran Singhother locations will likely result in the `ELOOP` error :: 579f11f2a3cSJaskaran Singh 580f11f2a3cSJaskaran Singh Too many levels of symbolic links 581