how it works — The Linux Kernel documentation (2024)

Purpose¶

The goal of autofs is to provide on-demand mounting and race freeautomatic unmounting of various other filesystems. This provides twokey advantages:

1. There is no need to delay boot until all filesystems thatmight be needed are mounted. Processes that try to access thoseslow filesystems might be delayed but other processes cancontinue freely. This is particularly important fornetwork filesystems (e.g. NFS) or filesystems stored onmedia with a media-changing robot.

2. The names and locations of filesystems can be stored ina remote database and can change at any time. The contentin that data base at the time of access will be used to providea target for the access. The interpretation of names in thefilesystem can even be programmatic rather than database-backed,allowing wildcards for example, and can vary based on the user whofirst accessed a name.

Context¶

The “autofs” filesystem module is only one part of an autofs system.There also needs to be a user-space program which looks up namesand mounts filesystems. This will often be the “automount” program,though other tools including “systemd” can make use of “autofs”.This document describes only the kernel module and the interactionsrequired with any user-space program. Subsequent text refers to thisas the “automount daemon” or simply “the daemon”.

“autofs” is a Linux kernel module which provides the “autofs”filesystem type. Several “autofs” filesystems can be mounted and theycan each be managed separately, or all managed by the same daemon.

Content¶

An autofs filesystem can contain 3 sorts of objects: directories,symbolic links and mount traps. Mount traps are directories withextra properties as described in the next section.

Objects can only be created by the automount daemon: symlinks arecreated with a regular symlink system call, while directories andmount traps are created with mkdir. The determination of whether adirectory should be a mount trap is based on a master map. This mastermap is consulted by autofs to determine which directories are mountpoints. Mount points can be direct/indirect/offset.On most systems, the default master map is located at /etc/auto.master.

If neither the direct or offset mount options are given (so themount is considered to be indirect), then the root directory isalways a regular directory, otherwise it is a mount trap when it isempty and a regular directory when not empty. Note that direct andoffset are treated identically so a concise summary is that the rootdirectory is a mount trap only if the filesystem is mounted directand the root is empty.

Directories created in the root directory are mount traps only if thefilesystem is mounted indirect and they are empty.

Directories further down the tree depend on the maxproto mountoption and particularly whether it is less than five or not.When maxproto is five, no directories further down thetree are ever mount traps, they are always regular directories. Whenthe maxproto is four (or three), these directories are mount trapsprecisely when they are empty.

So: non-empty (i.e. non-leaf) directories are never mount traps. Emptydirectories are sometimes mount traps, and sometimes not depending onwhere in the tree they are (root, top level, or lower), the maxproto,and whether the mount was indirect or not.

Mount Traps¶

A core element of the implementation of autofs is the Mount Trapswhich are provided by the Linux VFS. Any directory provided by afilesystem can be designated as a trap. This involves two separatefeatures that work together to allow autofs to do its job.

DCACHE_NEED_AUTOMOUNT

If a dentry has the DCACHE_NEED_AUTOMOUNT flag set (which gets set ifthe inode has S_AUTOMOUNT set, or can be set directly) then it is(potentially) a mount trap. Any access to this directory beyond a“stat” will (normally) cause the d_op->d_automount() dentry operationto be called. The task of this method is to find the filesystem thatshould be mounted on the directory and to return it. The VFS isresponsible for actually mounting the root of this filesystem on thedirectory.

autofs doesn’t find the filesystem itself but sends a message to theautomount daemon asking it to find and mount the filesystem. Theautofs d_automount method then waits for the daemon to report thateverything is ready. It will then return “NULL” indicating that themount has already happened. The VFS doesn’t try to mount anything butfollows down the mount that is already there.

This functionality is sufficient for some users of mount traps suchas NFS which creates traps so that mountpoints on the server can bereflected on the client. However it is not sufficient for autofs. Asmounting onto a directory is considered to be “beyond a stat”, theautomount daemon would not be able to mount a filesystem on the ‘trap’directory without some way to avoid getting caught in the trap. Forthat purpose there is another flag.

DCACHE_MANAGE_TRANSIT

If a dentry has DCACHE_MANAGE_TRANSIT set then two very different butrelated behaviours are invoked, both using the d_op->d_manage()dentry operation.

Firstly, before checking to see if any filesystem is mounted on thedirectory, d_manage() will be called with the rcu_walk parameter setto false. It may return one of three things:

• A return value of zero indicates that there is nothing specialabout this dentry and normal checks for mounts and automountsshould proceed.

  autofs normally returns zero, but first waits for anyexpiry (automatic unmounting of the mounted filesystem) tocomplete. This avoids races.

• A return value of -EISDIR tells the VFS to ignore any mountson the directory and to not consider calling ->d_automount().This effectively disables the DCACHE_NEED_AUTOMOUNT flagcausing the directory not be a mount trap after all.

  autofs returns this if it detects that the process performing thelookup is the automount daemon and that the mount has beenrequested but has not yet completed. How it determines this isdiscussed later. This allows the automount daemon not to getcaught in the mount trap.

  There is a subtlety here. It is possible that a second autofsfilesystem can be mounted below the first and for both of them tobe managed by the same daemon. For the daemon to be able to mountsomething on the second it must be able to “walk” down past thefirst. This means that d_manage cannot always return -EISDIR forthe automount daemon. It must only return it when a mount hasbeen requested, but has not yet completed.

  d_manage also returns -EISDIR if the dentry shouldn’t be amount trap, either because it is a symbolic link or because it isnot empty.

• Any other negative value is treated as an error and returnedto the caller.

  See Also

  Linux Automount | Learn How Linux Automount Works? (Examples)1.1.23 Disable AutomountingResource Management and Network Services)How to Disable or Enable Auto-Mounting of New Disks and Drives - MiniTool Partition Wizard

  autofs can return

  • -ENOENT if the automount daemon failed to mount anything,

  • -ENOMEM if it ran out of memory,

  • -EINTR if a signal arrived while waiting for expiry tocomplete

  • or any other error sent down by the automount daemon.

The second use case only occurs during an “RCU-walk” and so rcu_walkwill be set.

An RCU-walk is a fast and lightweight process for walking down afilename path (i.e. it is like running on tip-toes). RCU-walk cannotcope with all situations so when it finds a difficulty it falls backto “REF-walk”, which is slower but more robust.

RCU-walk will never call ->d_automount; the filesystems must alreadybe mounted or RCU-walk cannot handle the path.To determine if a mount-trap is safe for RCU-walk mode it calls->d_manage() with rcu_walk set to true.

In this case d_manage() must avoid blocking and should avoid takingspinlocks if at all possible. Its sole purpose is to determine if itwould be safe to follow down into any mounted directory and the onlyreason that it might not be is if an expiry of the mount isunderway.

In the rcu_walk case, d_manage() cannot return -EISDIR to tell theVFS that this is a directory that doesn’t require d_automount. Ifrcu_walk sees a dentry with DCACHE_NEED_AUTOMOUNT set but nothingmounted, it will fall back to REF-walk. d_manage() cannot make theVFS remain in RCU-walk mode, but can only tell it to get out ofRCU-walk mode by returning -ECHILD.

So d_manage(), when called with rcu_walk set, should either return-ECHILD if there is any reason to believe it is unsafe to enter themounted filesystem, otherwise it should return 0.

autofs will return -ECHILD if an expiry of the filesystem has beeninitiated or is being considered, otherwise it returns 0.

Mountpoint expiry¶

The VFS has a mechanism for automatically expiring unused mounts,much as it can expire any unused dentry information from the dcache.This is guided by the MNT_SHRINKABLE flag. This only applies tomounts that were created by d_automount() returning a filesystem to bemounted. As autofs doesn’t return such a filesystem but leaves themounting to the automount daemon, it must involve the automount daemonin unmounting as well. This also means that autofs has more controlover expiry.

The VFS also supports “expiry” of mounts using the MNT_EXPIRE flag tothe umount system call. Unmounting with MNT_EXPIRE will fail unlessa previous attempt had been made, and the filesystem has been inactiveand untouched since that previous attempt. autofs does not depend onthis but has its own internal tracking of whether filesystems wererecently used. This allows individual names in the autofs directoryto expire separately.

With version 4 of the protocol, the automount daemon can try tounmount any filesystems mounted on the autofs filesystem or remove anysymbolic links or empty directories any time it likes. If the unmountor removal is successful the filesystem will be returned to the stateit was before the mount or creation, so that any access of the namewill trigger normal auto-mount processing. In particular, rmdir andunlink do not leave negative entries in the dcache as a normalfilesystem would, so an attempt to access a recently-removed object ispassed to autofs for handling.

With version 5, this is not safe except for unmounting from top-leveldirectories. As lower-level directories are never mount traps, otherprocesses will see an empty directory as soon as the filesystem isunmounted. So it is generally safest to use the autofs expiryprotocol described below.

Normally the daemon only wants to remove entries which haven’t beenused for a while. For this purpose autofs maintains a “last_used”time stamp on each directory or symlink. For symlinks it genuinelydoes record the last time the symlink was “used” or followed to findout where it points to. For directories the field is used slightlydifferently. The field is updated at mount time and during expirechecks if it is found to be in use (ie. open file descriptor orprocess working directory) and during path walks. The update doneduring path walks prevents frequent expire and immediate mount offrequently accessed automounts. But in the case where a GUI continuallyaccess or an application frequently scans an autofs directory treethere can be an accumulation of mounts that aren’t actually beingused. To cater for this case the “strictexpire” autofs mount optioncan be used to avoid the “last_used” update on path walk therebypreventing this apparent inability to expire mounts that aren’treally in use.

The daemon is able to ask autofs if anything is due to be expired,using an ioctl as discussed later. For a direct mount, autofsconsiders if the entire mount-tree can be unmounted or not. For anindirect mount, autofs considers each of the names in the top leveldirectory to determine if any of those can be unmounted and cleanedup.

There is an option with indirect mounts to consider each of the leavesthat has been mounted on instead of considering the top-level names.This was originally intended for compatibility with version 4 of autofsand should be considered as deprecated for Sun Format automount maps.However, it may be used again for amd format mount maps (which aregenerally indirect maps) because the amd automounter allows for thesetting of an expire timeout for individual mounts. But there aresome difficulties in making the needed changes for this.

When autofs considers a directory it checks the last_used time andcompares it with the “timeout” value set when the filesystem wasmounted, though this check is ignored in some cases. It also checks ifthe directory or anything below it is in use. For symbolic links,only the last_used time is ever considered.

If both appear to support expiring the directory or symlink, an actionis taken.

There are two ways to ask autofs to consider expiry. The first is touse the AUTOFS_IOC_EXPIRE ioctl. This only works for indirectmounts. If it finds something in the root directory to expire it willreturn the name of that thing. Once a name has been returned theautomount daemon needs to unmount any filesystems mounted below thename normally. As described above, this is unsafe for non-toplevelmounts in a version-5 autofs. For this reason the current automount(8)does not use this ioctl.

The second mechanism uses either the AUTOFS_DEV_IOCTL_EXPIRE_CMD orthe AUTOFS_IOC_EXPIRE_MULTI ioctl. This will work for both direct andindirect mounts. If it selects an object to expire, it will notifythe daemon using the notification mechanism described below. Thiswill block until the daemon acknowledges the expiry notification.This implies that the “EXPIRE” ioctl must be sent from a differentthread than the one which handles notification.

While the ioctl is blocking, the entry is marked as “expiring” andd_manage will block until the daemon affirms that the unmount hascompleted (together with removing any directories that might have beennecessary), or has been aborted.

Communicating with autofs: detecting the daemon¶

There are several forms of communication between the automount daemonand the filesystem. As we have already seen, the daemon can create andremove directories and symlinks using normal filesystem operations.autofs knows whether a process requesting some operation is the daemonor not based on its process-group id number (see getpgid(1)).

When an autofs filesystem is mounted the pgid of the mountingprocesses is recorded unless the “pgrp=” option is given, in whichcase that number is recorded instead. Any request arriving from aprocess in that process group is considered to come from the daemon.If the daemon ever has to be stopped and restarted a new pgid can beprovided through an ioctl as will be described below.

Communicating with autofs: the event pipe¶

When an autofs filesystem is mounted, the ‘write’ end of a pipe mustbe passed using the ‘fd=’ mount option. autofs will writenotification messages to this pipe for the daemon to respond to.For version 5, the format of the message is:

struct autofs_v5_packet { struct autofs_packet_hdr hdr; autofs_wqt_t wait_queue_token; __u32 dev; __u64 ino; __u32 uid; __u32 gid; __u32 pid; __u32 tgid; __u32 len; char name[NAME_MAX+1];};

And the format of the header is:

struct autofs_packet_hdr { int proto_version; /* Protocol version */ int type; /* Type of packet */};

where the type is one of

autofs_ptype_missing_indirectautofs_ptype_expire_indirectautofs_ptype_missing_directautofs_ptype_expire_direct

so messages can indicate that a name is missing (something tried toaccess it but it isn’t there) or that it has been selected for expiry.

The pipe will be set to “packet mode” (equivalent to passingO_DIRECT) to _pipe2(2)_ so that a read from the pipe will return atmost one packet, and any unread portion of a packet will be discarded.

The wait_queue_token is a unique number which can identify aparticular request to be acknowledged. When a message is sent overthe pipe the affected dentry is marked as either “active” or“expiring” and other accesses to it block until the message isacknowledged using one of the ioctls below with the relevantwait_queue_token.

Communicating with autofs: root directory ioctls¶

The root directory of an autofs filesystem will respond to a number ofioctls. The process issuing the ioctl must have the CAP_SYS_ADMINcapability, or must be the automount daemon.

The available ioctl commands are:

• AUTOFS_IOC_READY:

  a notification has been handled. The argumentto the ioctl command is the “wait_queue_token” numbercorresponding to the notification being acknowledged.

• AUTOFS_IOC_FAIL:

  similar to above, but indicates failure withthe error code ENOENT.

• AUTOFS_IOC_CATATONIC:

  Causes the autofs to enter “catatonic”mode meaning that it stops sending notifications to the daemon.This mode is also entered if a write to the pipe fails.

• AUTOFS_IOC_PROTOVER:

  This returns the protocol version in use.

• AUTOFS_IOC_PROTOSUBVER:

  Returns the protocol sub-version whichis really a version number for the implementation.

• AUTOFS_IOC_SETTIMEOUT:

  This passes a pointer to an unsignedlong. The value is used to set the timeout for expiry, andthe current timeout value is stored back through the pointer.

• AUTOFS_IOC_ASKUMOUNT:

  Returns, in the pointed-to int, 1 ifthe filesystem could be unmounted. This is only a hint asthe situation could change at any instant. This call can beused to avoid a more expensive full unmount attempt.

• AUTOFS_IOC_EXPIRE:

  as described above, this asks if there isanything suitable to expire. A pointer to a packet:

  struct autofs_packet_expire_multi { struct autofs_packet_hdr hdr; autofs_wqt_t wait_queue_token; int len; char name[NAME_MAX+1];};

  is required. This is filled in with the name of somethingthat can be unmounted or removed. If nothing can be expired,errno is set to EAGAIN. Even though a wait_queue_tokenis present in the structure, no “wait queue” is establishedand no acknowledgment is needed.

• AUTOFS_IOC_EXPIRE_MULTI:

  This is similar toAUTOFS_IOC_EXPIRE except that it causes notification to besent to the daemon, and it blocks until the daemon acknowledges.The argument is an integer which can contain two different flags.

  AUTOFS_EXP_IMMEDIATE causes last_used time to be ignoredand objects are expired if the are not in use.

  AUTOFS_EXP_FORCED causes the in use status to be ignoredand objects are expired ieven if they are in use. This assumesthat the daemon has requested this because it is capable ofperforming the umount.

  AUTOFS_EXP_LEAVES will select a leaf rather than a top-levelname to expire. This is only safe when maxproto is 4.

Communicating with autofs: char-device ioctls¶

It is not always possible to open the root of an autofs filesystem,particularly a direct mounted filesystem. If the automount daemonis restarted there is no way for it to regain control of existingmounts using any of the above communication channels. To address thisneed there is a “miscellaneous” character device (major 10, minor 235)which can be used to communicate directly with the autofs filesystem.It requires CAP_SYS_ADMIN for access.

The ‘ioctl’s that can be used on this device are described in a separatedocument Miscellaneous Device control operations for the autofs kernel module, and are summarised briefly here.Each ioctl is passed a pointer to an autofs_dev_ioctl structure:

struct autofs_dev_ioctl { __u32 ver_major; __u32 ver_minor; __u32 size; /* total size of data passed in * including this struct */ __s32 ioctlfd; /* automount command fd */ /* Command parameters */ union { struct args_protover protover; struct args_protosubver protosubver; struct args_openmount openmount; struct args_ready ready; struct args_fail fail; struct args_setpipefd setpipefd; struct args_timeout timeout; struct args_requester requester; struct args_expire expire; struct args_askumount askumount; struct args_ismountpoint ismountpoint; }; char path[];};

For the OPEN_MOUNT and IS_MOUNTPOINT commands, the targetfilesystem is identified by the path. All other commands identifythe filesystem by the ioctlfd which is a file descriptor open on theroot, and which can be returned by OPEN_MOUNT.

The ver_major and ver_minor are in/out parameters which check thatthe requested version is supported, and report the maximum versionthat the kernel module can support.

Commands are:

• AUTOFS_DEV_IOCTL_VERSION_CMD:

  does nothing, except validate andset version numbers.

• AUTOFS_DEV_IOCTL_OPENMOUNT_CMD:

  return an open file descriptoron the root of an autofs filesystem. The filesystem is identifiedby name and device number, which is stored in openmount.devid.Device numbers for existing filesystems can be found in/proc/self/mountinfo.

• AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD:

  same as close(ioctlfd).

• AUTOFS_DEV_IOCTL_SETPIPEFD_CMD:

  if the filesystem is incatatonic mode, this can provide the write end of a new pipein setpipefd.pipefd to re-establish communication with a daemon.The process group of the calling process is used to identify thedaemon.

• AUTOFS_DEV_IOCTL_REQUESTER_CMD:

  path should be aname within the filesystem that has been auto-mounted on.On successful return, requester.uid and requester.gid will bethe UID and GID of the process which triggered that mount.

• AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD:

  Check if path is amountpoint of a particular type - see separate documentation fordetails.

• AUTOFS_DEV_IOCTL_PROTOVER_CMD

• AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD

• AUTOFS_DEV_IOCTL_READY_CMD

• AUTOFS_DEV_IOCTL_FAIL_CMD

• AUTOFS_DEV_IOCTL_CATATONIC_CMD

• AUTOFS_DEV_IOCTL_TIMEOUT_CMD

• AUTOFS_DEV_IOCTL_EXPIRE_CMD

• AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD

These all have the samefunction as the similarly named AUTOFS_IOC ioctls, exceptthat FAIL can be given an explicit error number in fail.statusinstead of assuming ENOENT, and this EXPIRE commandcorresponds to AUTOFS_IOC_EXPIRE_MULTI.

Catatonic mode¶

As mentioned, an autofs mount can enter “catatonic” mode. Thishappens if a write to the notification pipe fails, or if it isexplicitly requested by an ioctl.

When entering catatonic mode, the pipe is closed and any pendingnotifications are acknowledged with the error ENOENT.

Once in catatonic mode attempts to access non-existing names willresult in ENOENT while attempts to access existing directories willbe treated in the same way as if they came from the daemon, so mounttraps will not fire.

When the filesystem is mounted a _uid_ and _gid_ can be given whichset the ownership of directories and symbolic links. When thefilesystem is in catatonic mode, any process with a matching UID cancreate directories or symlinks in the root directory, but not in otherdirectories.

Catatonic mode can only be left via theAUTOFS_DEV_IOCTL_OPENMOUNT_CMD ioctl on the /dev/autofs.

The “ignore” mount option¶

The “ignore” mount option can be used to provide a generic indicatorto applications that the mount entry should be ignored when displayingmount information.

In other OSes that provide autofs and that provide a mount list to userspace based on the kernel mount list a no-op mount option (“ignore” isthe one use on the most common OSes) is allowed so that autofs filesystem users can optionally use it.

This is intended to be used by user space programs to exclude autofsmounts from consideration when reading the mounts list.