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