Documentation/filesystems/autofs.rst

2 autofs - how it works
8 The goal of autofs is to provide on-demand mounting and race free
17    media with a media-changing robot.
23    filesystem can even be programmatic rather than database-backed,
31 There also needs to be a user-space program which looks up names
35 required with any user-space program.  Subsequent text refers to this
55 On most systems, the default master map is located at */etc/auto.master*.
75 So: non-empty (i.e. non-leaf) directories are never mount traps. Empty
93 "`stat`" will (normally) cause the `d_op->d_automount()` dentry operation
117 related behaviours are invoked, both using the `d_op->d_manage()`
124 -  A return value of zero indicates that there is nothing special
132 -  A return value of `-EISDIR` tells the VFS to ignore any mounts
133    on the directory and to not consider calling `->d_automount()`.
137    autofs returns this if it detects that the process performing the
147    first.  This means that d_manage cannot *always* return -EISDIR for
151    `d_manage` also returns `-EISDIR` if the dentry shouldn't be a
155 -  Any other negative value is treated as an error and returned
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 to
164    - or any other error sent down by the automount daemon.
167 The second use case only occurs during an "RCU-walk" and so `rcu_walk`
170 An RCU-walk is a fast and lightweight process for walking down a
171 filename path (i.e. it is like running on tip-toes).  RCU-walk cannot
173 to "REF-walk", which is slower but more robust.
175 RCU-walk will never call `->d_automount`; the filesystems must already
176 be mounted or RCU-walk cannot handle the path.
177 To determine if a mount-trap is safe for RCU-walk mode it calls
178 `->d_manage()` with `rcu_walk` set to `true`.
186 In the `rcu_walk` case, `d_manage()` cannot return -EISDIR to tell the
189 mounted, it *will* fall back to REF-walk.  `d_manage()` cannot make the
190 VFS remain in RCU-walk mode, but can only tell it to get out of
191 RCU-walk mode by returning `-ECHILD`.
194 -ECHILD if there is any reason to believe it is unsafe to enter the
197 autofs will return `-ECHILD` if an expiry of the filesystem has been
226 will trigger normal auto-mount processing.  In particular, `rmdir` and
228 filesystem would, so an attempt to access a recently-removed object is
231 With version 5, this is not safe except for unmounting from top-level
232 directories.  As lower-level directories are never mount traps, other
256 considers if the entire mount-tree can be unmounted or not.  For an
262 that has been mounted on instead of considering the top-level names.
284 name normally.  As described above, this is unsafe for non-toplevel
285 mounts in a version-5 autofs.  For this reason the current `automount(8)`
308 or not based on its process-group id number (see getpgid(1)).
375 - **AUTOFS_IOC_READY**:
379 - **AUTOFS_IOC_FAIL**:
382 - **AUTOFS_IOC_CATATONIC**:
386 - **AUTOFS_IOC_PROTOVER**:
388 - **AUTOFS_IOC_PROTOSUBVER**:
389 	Returns the protocol sub-version which
391 - **AUTOFS_IOC_SETTIMEOUT**:
395 - **AUTOFS_IOC_ASKUMOUNT**:
396 	Returns, in the pointed-to `int`, 1 if
400 - **AUTOFS_IOC_EXPIRE**:
416 - **AUTOFS_IOC_EXPIRE_MULTI**:
430 	**AUTOFS_EXP_LEAVES** will select a leaf rather than a top-level
433 Communicating with autofs: char-device ioctls
445 document `autofs-mount-control.txt`, and are summarised briefly here.
484 - **AUTOFS_DEV_IOCTL_VERSION_CMD**:
487 - **AUTOFS_DEV_IOCTL_OPENMOUNT_CMD**:
493 - **AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD**:
495 - **AUTOFS_DEV_IOCTL_SETPIPEFD_CMD**:
498 	in `setpipefd.pipefd` to re-establish communication with a daemon.
501 - **AUTOFS_DEV_IOCTL_REQUESTER_CMD**:
503 	name within the filesystem that has been auto-mounted on.
506 - **AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD**:
508 	mountpoint of a particular type - see separate documentation for
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**
536 Once in catatonic mode attempts to access non-existing names will
558 space based on the kernel mount list a no-op mount option ("ignore" is
573 	mount --make-shared /autofs/mount/point