581 lines · plain
1=====================2autofs - how it works3=====================4 5Purpose6=======7 8The goal of autofs is to provide on-demand mounting and race free9automatic unmounting of various other filesystems. This provides two10key advantages:11 121. There is no need to delay boot until all filesystems that13 might be needed are mounted. Processes that try to access those14 slow filesystems might be delayed but other processes can15 continue freely. This is particularly important for16 network filesystems (e.g. NFS) or filesystems stored on17 media with a media-changing robot.18 192. The names and locations of filesystems can be stored in20 a remote database and can change at any time. The content21 in that database at the time of access will be used to provide22 a target for the access. The interpretation of names in the23 filesystem can even be programmatic rather than database-backed,24 allowing wildcards for example, and can vary based on the user who25 first accessed a name.26 27Context28=======29 30The "autofs" filesystem module is only one part of an autofs system.31There also needs to be a user-space program which looks up names32and mounts filesystems. This will often be the "automount" program,33though other tools including "systemd" can make use of "autofs".34This document describes only the kernel module and the interactions35required with any user-space program. Subsequent text refers to this36as the "automount daemon" or simply "the daemon".37 38"autofs" is a Linux kernel module which provides the "autofs"39filesystem type. Several "autofs" filesystems can be mounted and they40can each be managed separately, or all managed by the same daemon.41 42Content43=======44 45An autofs filesystem can contain 3 sorts of objects: directories,46symbolic links and mount traps. Mount traps are directories with47extra properties as described in the next section.48 49Objects can only be created by the automount daemon: symlinks are50created with a regular `symlink` system call, while directories and51mount traps are created with `mkdir`. The determination of whether a52directory should be a mount trap is based on a master map. This master53map is consulted by autofs to determine which directories are mount54points. Mount points can be *direct*/*indirect*/*offset*.55On most systems, the default master map is located at */etc/auto.master*.56 57If neither the *direct* or *offset* mount options are given (so the58mount is considered to be *indirect*), then the root directory is59always a regular directory, otherwise it is a mount trap when it is60empty and a regular directory when not empty. Note that *direct* and61*offset* are treated identically so a concise summary is that the root62directory is a mount trap only if the filesystem is mounted *direct*63and the root is empty.64 65Directories created in the root directory are mount traps only if the66filesystem is mounted *indirect* and they are empty.67 68Directories further down the tree depend on the *maxproto* mount69option and particularly whether it is less than five or not.70When *maxproto* is five, no directories further down the71tree are ever mount traps, they are always regular directories. When72the *maxproto* is four (or three), these directories are mount traps73precisely when they are empty.74 75So: non-empty (i.e. non-leaf) directories are never mount traps. Empty76directories are sometimes mount traps, and sometimes not depending on77where in the tree they are (root, top level, or lower), the *maxproto*,78and whether the mount was *indirect* or not.79 80Mount Traps81===========82 83A core element of the implementation of autofs is the Mount Traps84which are provided by the Linux VFS. Any directory provided by a85filesystem can be designated as a trap. This involves two separate86features that work together to allow autofs to do its job.87 88**DCACHE_NEED_AUTOMOUNT**89 90If a dentry has the DCACHE_NEED_AUTOMOUNT flag set (which gets set if91the inode has S_AUTOMOUNT set, or can be set directly) then it is92(potentially) a mount trap. Any access to this directory beyond a93"`stat`" will (normally) cause the `d_op->d_automount()` dentry operation94to be called. The task of this method is to find the filesystem that95should be mounted on the directory and to return it. The VFS is96responsible for actually mounting the root of this filesystem on the97directory.98 99autofs doesn't find the filesystem itself but sends a message to the100automount daemon asking it to find and mount the filesystem. The101autofs `d_automount` method then waits for the daemon to report that102everything is ready. It will then return "`NULL`" indicating that the103mount has already happened. The VFS doesn't try to mount anything but104follows down the mount that is already there.105 106This functionality is sufficient for some users of mount traps such107as NFS which creates traps so that mountpoints on the server can be108reflected on the client. However it is not sufficient for autofs. As109mounting onto a directory is considered to be "beyond a `stat`", the110automount daemon would not be able to mount a filesystem on the 'trap'111directory without some way to avoid getting caught in the trap. For112that purpose there is another flag.113 114**DCACHE_MANAGE_TRANSIT**115 116If a dentry has DCACHE_MANAGE_TRANSIT set then two very different but117related behaviours are invoked, both using the `d_op->d_manage()`118dentry operation.119 120Firstly, before checking to see if any filesystem is mounted on the121directory, d_manage() will be called with the `rcu_walk` parameter set122to `false`. It may return one of three things:123 124- A return value of zero indicates that there is nothing special125 about this dentry and normal checks for mounts and automounts126 should proceed.127 128 autofs normally returns zero, but first waits for any129 expiry (automatic unmounting of the mounted filesystem) to130 complete. This avoids races.131 132- A return value of `-EISDIR` tells the VFS to ignore any mounts133 on the directory and to not consider calling `->d_automount()`.134 This effectively disables the **DCACHE_NEED_AUTOMOUNT** flag135 causing the directory not be a mount trap after all.136 137 autofs returns this if it detects that the process performing the138 lookup is the automount daemon and that the mount has been139 requested but has not yet completed. How it determines this is140 discussed later. This allows the automount daemon not to get141 caught in the mount trap.142 143 There is a subtlety here. It is possible that a second autofs144 filesystem can be mounted below the first and for both of them to145 be managed by the same daemon. For the daemon to be able to mount146 something on the second it must be able to "walk" down past the147 first. This means that d_manage cannot *always* return -EISDIR for148 the automount daemon. It must only return it when a mount has149 been requested, but has not yet completed.150 151 `d_manage` also returns `-EISDIR` if the dentry shouldn't be a152 mount trap, either because it is a symbolic link or because it is153 not empty.154 155- Any other negative value is treated as an error and returned156 to the caller.157 158 autofs can return159 160 - -ENOENT if the automount daemon failed to mount anything,161 - -ENOMEM if it ran out of memory,162 - -EINTR if a signal arrived while waiting for expiry to163 complete164 - or any other error sent down by the automount daemon.165 166 167The second use case only occurs during an "RCU-walk" and so `rcu_walk`168will be set.169 170An RCU-walk is a fast and lightweight process for walking down a171filename path (i.e. it is like running on tip-toes). RCU-walk cannot172cope with all situations so when it finds a difficulty it falls back173to "REF-walk", which is slower but more robust.174 175RCU-walk will never call `->d_automount`; the filesystems must already176be mounted or RCU-walk cannot handle the path.177To determine if a mount-trap is safe for RCU-walk mode it calls178`->d_manage()` with `rcu_walk` set to `true`.179 180In this case `d_manage()` must avoid blocking and should avoid taking181spinlocks if at all possible. Its sole purpose is to determine if it182would be safe to follow down into any mounted directory and the only183reason that it might not be is if an expiry of the mount is184underway.185 186In the `rcu_walk` case, `d_manage()` cannot return -EISDIR to tell the187VFS that this is a directory that doesn't require d_automount. If188`rcu_walk` sees a dentry with DCACHE_NEED_AUTOMOUNT set but nothing189mounted, it *will* fall back to REF-walk. `d_manage()` cannot make the190VFS remain in RCU-walk mode, but can only tell it to get out of191RCU-walk mode by returning `-ECHILD`.192 193So `d_manage()`, when called with `rcu_walk` set, should either return194-ECHILD if there is any reason to believe it is unsafe to enter the195mounted filesystem, otherwise it should return 0.196 197autofs will return `-ECHILD` if an expiry of the filesystem has been198initiated or is being considered, otherwise it returns 0.199 200 201Mountpoint expiry202=================203 204The VFS has a mechanism for automatically expiring unused mounts,205much as it can expire any unused dentry information from the dcache.206This is guided by the MNT_SHRINKABLE flag. This only applies to207mounts that were created by `d_automount()` returning a filesystem to be208mounted. As autofs doesn't return such a filesystem but leaves the209mounting to the automount daemon, it must involve the automount daemon210in unmounting as well. This also means that autofs has more control211over expiry.212 213The VFS also supports "expiry" of mounts using the MNT_EXPIRE flag to214the `umount` system call. Unmounting with MNT_EXPIRE will fail unless215a previous attempt had been made, and the filesystem has been inactive216and untouched since that previous attempt. autofs does not depend on217this but has its own internal tracking of whether filesystems were218recently used. This allows individual names in the autofs directory219to expire separately.220 221With version 4 of the protocol, the automount daemon can try to222unmount any filesystems mounted on the autofs filesystem or remove any223symbolic links or empty directories any time it likes. If the unmount224or removal is successful the filesystem will be returned to the state225it was before the mount or creation, so that any access of the name226will trigger normal auto-mount processing. In particular, `rmdir` and227`unlink` do not leave negative entries in the dcache as a normal228filesystem would, so an attempt to access a recently-removed object is229passed to autofs for handling.230 231With version 5, this is not safe except for unmounting from top-level232directories. As lower-level directories are never mount traps, other233processes will see an empty directory as soon as the filesystem is234unmounted. So it is generally safest to use the autofs expiry235protocol described below.236 237Normally the daemon only wants to remove entries which haven't been238used for a while. For this purpose autofs maintains a "`last_used`"239time stamp on each directory or symlink. For symlinks it genuinely240does record the last time the symlink was "used" or followed to find241out where it points to. For directories the field is used slightly242differently. The field is updated at mount time and during expire243checks if it is found to be in use (ie. open file descriptor or244process working directory) and during path walks. The update done245during path walks prevents frequent expire and immediate mount of246frequently accessed automounts. But in the case where a GUI continually247access or an application frequently scans an autofs directory tree248there can be an accumulation of mounts that aren't actually being249used. To cater for this case the "`strictexpire`" autofs mount option250can be used to avoid the "`last_used`" update on path walk thereby251preventing this apparent inability to expire mounts that aren't252really in use.253 254The daemon is able to ask autofs if anything is due to be expired,255using an `ioctl` as discussed later. For a *direct* mount, autofs256considers if the entire mount-tree can be unmounted or not. For an257*indirect* mount, autofs considers each of the names in the top level258directory to determine if any of those can be unmounted and cleaned259up.260 261There is an option with indirect mounts to consider each of the leaves262that has been mounted on instead of considering the top-level names.263This was originally intended for compatibility with version 4 of autofs264and should be considered as deprecated for Sun Format automount maps.265However, it may be used again for amd format mount maps (which are266generally indirect maps) because the amd automounter allows for the267setting of an expire timeout for individual mounts. But there are268some difficulties in making the needed changes for this.269 270When autofs considers a directory it checks the `last_used` time and271compares it with the "timeout" value set when the filesystem was272mounted, though this check is ignored in some cases. It also checks if273the directory or anything below it is in use. For symbolic links,274only the `last_used` time is ever considered.275 276If both appear to support expiring the directory or symlink, an action277is taken.278 279There are two ways to ask autofs to consider expiry. The first is to280use the **AUTOFS_IOC_EXPIRE** ioctl. This only works for indirect281mounts. If it finds something in the root directory to expire it will282return the name of that thing. Once a name has been returned the283automount daemon needs to unmount any filesystems mounted below the284name normally. As described above, this is unsafe for non-toplevel285mounts in a version-5 autofs. For this reason the current `automount(8)`286does not use this ioctl.287 288The second mechanism uses either the **AUTOFS_DEV_IOCTL_EXPIRE_CMD** or289the **AUTOFS_IOC_EXPIRE_MULTI** ioctl. This will work for both direct and290indirect mounts. If it selects an object to expire, it will notify291the daemon using the notification mechanism described below. This292will block until the daemon acknowledges the expiry notification.293This implies that the "`EXPIRE`" ioctl must be sent from a different294thread than the one which handles notification.295 296While the ioctl is blocking, the entry is marked as "expiring" and297`d_manage` will block until the daemon affirms that the unmount has298completed (together with removing any directories that might have been299necessary), or has been aborted.300 301Communicating with autofs: detecting the daemon302===============================================303 304There are several forms of communication between the automount daemon305and the filesystem. As we have already seen, the daemon can create and306remove directories and symlinks using normal filesystem operations.307autofs knows whether a process requesting some operation is the daemon308or not based on its process-group id number (see getpgid(1)).309 310When an autofs filesystem is mounted the pgid of the mounting311processes is recorded unless the "pgrp=" option is given, in which312case that number is recorded instead. Any request arriving from a313process in that process group is considered to come from the daemon.314If the daemon ever has to be stopped and restarted a new pgid can be315provided through an ioctl as will be described below.316 317Communicating with autofs: the event pipe318=========================================319 320When an autofs filesystem is mounted, the 'write' end of a pipe must321be passed using the 'fd=' mount option. autofs will write322notification messages to this pipe for the daemon to respond to.323For version 5, the format of the message is::324 325 struct autofs_v5_packet {326 struct autofs_packet_hdr hdr;327 autofs_wqt_t wait_queue_token;328 __u32 dev;329 __u64 ino;330 __u32 uid;331 __u32 gid;332 __u32 pid;333 __u32 tgid;334 __u32 len;335 char name[NAME_MAX+1];336 };337 338And the format of the header is::339 340 struct autofs_packet_hdr {341 int proto_version; /* Protocol version */342 int type; /* Type of packet */343 };344 345where the type is one of ::346 347 autofs_ptype_missing_indirect348 autofs_ptype_expire_indirect349 autofs_ptype_missing_direct350 autofs_ptype_expire_direct351 352so messages can indicate that a name is missing (something tried to353access it but it isn't there) or that it has been selected for expiry.354 355The pipe will be set to "packet mode" (equivalent to passing356`O_DIRECT`) to _pipe2(2)_ so that a read from the pipe will return at357most one packet, and any unread portion of a packet will be discarded.358 359The `wait_queue_token` is a unique number which can identify a360particular request to be acknowledged. When a message is sent over361the pipe the affected dentry is marked as either "active" or362"expiring" and other accesses to it block until the message is363acknowledged using one of the ioctls below with the relevant364`wait_queue_token`.365 366Communicating with autofs: root directory ioctls367================================================368 369The root directory of an autofs filesystem will respond to a number of370ioctls. The process issuing the ioctl must have the CAP_SYS_ADMIN371capability, or must be the automount daemon.372 373The available ioctl commands are:374 375- **AUTOFS_IOC_READY**:376 a notification has been handled. The argument377 to the ioctl command is the "wait_queue_token" number378 corresponding to the notification being acknowledged.379- **AUTOFS_IOC_FAIL**:380 similar to above, but indicates failure with381 the error code `ENOENT`.382- **AUTOFS_IOC_CATATONIC**:383 Causes the autofs to enter "catatonic"384 mode meaning that it stops sending notifications to the daemon.385 This mode is also entered if a write to the pipe fails.386- **AUTOFS_IOC_PROTOVER**:387 This returns the protocol version in use.388- **AUTOFS_IOC_PROTOSUBVER**:389 Returns the protocol sub-version which390 is really a version number for the implementation.391- **AUTOFS_IOC_SETTIMEOUT**:392 This passes a pointer to an unsigned393 long. The value is used to set the timeout for expiry, and394 the current timeout value is stored back through the pointer.395- **AUTOFS_IOC_ASKUMOUNT**:396 Returns, in the pointed-to `int`, 1 if397 the filesystem could be unmounted. This is only a hint as398 the situation could change at any instant. This call can be399 used to avoid a more expensive full unmount attempt.400- **AUTOFS_IOC_EXPIRE**:401 as described above, this asks if there is402 anything suitable to expire. A pointer to a packet::403 404 struct autofs_packet_expire_multi {405 struct autofs_packet_hdr hdr;406 autofs_wqt_t wait_queue_token;407 int len;408 char name[NAME_MAX+1];409 };410 411 is required. This is filled in with the name of something412 that can be unmounted or removed. If nothing can be expired,413 `errno` is set to `EAGAIN`. Even though a `wait_queue_token`414 is present in the structure, no "wait queue" is established415 and no acknowledgment is needed.416- **AUTOFS_IOC_EXPIRE_MULTI**:417 This is similar to418 **AUTOFS_IOC_EXPIRE** except that it causes notification to be419 sent to the daemon, and it blocks until the daemon acknowledges.420 The argument is an integer which can contain two different flags.421 422 **AUTOFS_EXP_IMMEDIATE** causes `last_used` time to be ignored423 and objects are expired if the are not in use.424 425 **AUTOFS_EXP_FORCED** causes the in use status to be ignored426 and objects are expired even if they are in use. This assumes427 that the daemon has requested this because it is capable of428 performing the umount.429 430 **AUTOFS_EXP_LEAVES** will select a leaf rather than a top-level431 name to expire. This is only safe when *maxproto* is 4.432 433Communicating with autofs: char-device ioctls434=============================================435 436It is not always possible to open the root of an autofs filesystem,437particularly a *direct* mounted filesystem. If the automount daemon438is restarted there is no way for it to regain control of existing439mounts using any of the above communication channels. To address this440need there is a "miscellaneous" character device (major 10, minor 235)441which can be used to communicate directly with the autofs filesystem.442It requires CAP_SYS_ADMIN for access.443 444The 'ioctl's that can be used on this device are described in a separate445document `autofs-mount-control.txt`, and are summarised briefly here.446Each ioctl is passed a pointer to an `autofs_dev_ioctl` structure::447 448 struct autofs_dev_ioctl {449 __u32 ver_major;450 __u32 ver_minor;451 __u32 size; /* total size of data passed in452 * including this struct */453 __s32 ioctlfd; /* automount command fd */454 455 /* Command parameters */456 union {457 struct args_protover protover;458 struct args_protosubver protosubver;459 struct args_openmount openmount;460 struct args_ready ready;461 struct args_fail fail;462 struct args_setpipefd setpipefd;463 struct args_timeout timeout;464 struct args_requester requester;465 struct args_expire expire;466 struct args_askumount askumount;467 struct args_ismountpoint ismountpoint;468 };469 470 char path[];471 };472 473For the **OPEN_MOUNT** and **IS_MOUNTPOINT** commands, the target474filesystem is identified by the `path`. All other commands identify475the filesystem by the `ioctlfd` which is a file descriptor open on the476root, and which can be returned by **OPEN_MOUNT**.477 478The `ver_major` and `ver_minor` are in/out parameters which check that479the requested version is supported, and report the maximum version480that the kernel module can support.481 482Commands are:483 484- **AUTOFS_DEV_IOCTL_VERSION_CMD**:485 does nothing, except validate and486 set version numbers.487- **AUTOFS_DEV_IOCTL_OPENMOUNT_CMD**:488 return an open file descriptor489 on the root of an autofs filesystem. The filesystem is identified490 by name and device number, which is stored in `openmount.devid`.491 Device numbers for existing filesystems can be found in492 `/proc/self/mountinfo`.493- **AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD**:494 same as `close(ioctlfd)`.495- **AUTOFS_DEV_IOCTL_SETPIPEFD_CMD**:496 if the filesystem is in497 catatonic mode, this can provide the write end of a new pipe498 in `setpipefd.pipefd` to re-establish communication with a daemon.499 The process group of the calling process is used to identify the500 daemon.501- **AUTOFS_DEV_IOCTL_REQUESTER_CMD**:502 `path` should be a503 name within the filesystem that has been auto-mounted on.504 On successful return, `requester.uid` and `requester.gid` will be505 the UID and GID of the process which triggered that mount.506- **AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD**:507 Check if path is a508 mountpoint of a particular type - see separate documentation for509 details.510 511- **AUTOFS_DEV_IOCTL_PROTOVER_CMD**512- **AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD**513- **AUTOFS_DEV_IOCTL_READY_CMD**514- **AUTOFS_DEV_IOCTL_FAIL_CMD**515- **AUTOFS_DEV_IOCTL_CATATONIC_CMD**516- **AUTOFS_DEV_IOCTL_TIMEOUT_CMD**517- **AUTOFS_DEV_IOCTL_EXPIRE_CMD**518- **AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD**519 520These all have the same521function as the similarly named **AUTOFS_IOC** ioctls, except522that **FAIL** can be given an explicit error number in `fail.status`523instead of assuming `ENOENT`, and this **EXPIRE** command524corresponds to **AUTOFS_IOC_EXPIRE_MULTI**.525 526Catatonic mode527==============528 529As mentioned, an autofs mount can enter "catatonic" mode. This530happens if a write to the notification pipe fails, or if it is531explicitly requested by an `ioctl`.532 533When entering catatonic mode, the pipe is closed and any pending534notifications are acknowledged with the error `ENOENT`.535 536Once in catatonic mode attempts to access non-existing names will537result in `ENOENT` while attempts to access existing directories will538be treated in the same way as if they came from the daemon, so mount539traps will not fire.540 541When the filesystem is mounted a _uid_ and _gid_ can be given which542set the ownership of directories and symbolic links. When the543filesystem is in catatonic mode, any process with a matching UID can544create directories or symlinks in the root directory, but not in other545directories.546 547Catatonic mode can only be left via the548**AUTOFS_DEV_IOCTL_OPENMOUNT_CMD** ioctl on the `/dev/autofs`.549 550The "ignore" mount option551=========================552 553The "ignore" mount option can be used to provide a generic indicator554to applications that the mount entry should be ignored when displaying555mount information.556 557In other OSes that provide autofs and that provide a mount list to user558space based on the kernel mount list a no-op mount option ("ignore" is559the one use on the most common OSes) is allowed so that autofs file560system users can optionally use it.561 562This is intended to be used by user space programs to exclude autofs563mounts from consideration when reading the mounts list.564 565autofs, name spaces, and shared mounts566======================================567 568With bind mounts and name spaces it is possible for an autofs569filesystem to appear at multiple places in one or more filesystem570name spaces. For this to work sensibly, the autofs filesystem should571always be mounted "shared". e.g. ::572 573 mount --make-shared /autofs/mount/point574 575The automount daemon is only able to manage a single mount location for576an autofs filesystem and if mounts on that are not 'shared', other577locations will not behave as expected. In particular access to those578other locations will likely result in the `ELOOP` error ::579 580 Too many levels of symbolic links581