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