^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 1) .. SPDX-License-Identifier: GPL-2.0
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 2)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 3) ====================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 4) Miscellaneous Device control operations for the autofs kernel module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 5) ====================================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 6)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 7) The problem
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 8) ===========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 9)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 10) There is a problem with active restarts in autofs (that is to say
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 11) restarting autofs when there are busy mounts).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 12)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 13) During normal operation autofs uses a file descriptor opened on the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 14) directory that is being managed in order to be able to issue control
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 15) operations. Using a file descriptor gives ioctl operations access to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 16) autofs specific information stored in the super block. The operations
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 17) are things such as setting an autofs mount catatonic, setting the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 18) expire timeout and requesting expire checks. As is explained below,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 19) certain types of autofs triggered mounts can end up covering an autofs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 20) mount itself which prevents us being able to use open(2) to obtain a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 21) file descriptor for these operations if we don't already have one open.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 22)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 23) Currently autofs uses "umount -l" (lazy umount) to clear active mounts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 24) at restart. While using lazy umount works for most cases, anything that
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 25) needs to walk back up the mount tree to construct a path, such as
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 26) getcwd(2) and the proc file system /proc/<pid>/cwd, no longer works
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 27) because the point from which the path is constructed has been detached
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 28) from the mount tree.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 29)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 30) The actual problem with autofs is that it can't reconnect to existing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 31) mounts. Immediately one thinks of just adding the ability to remount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 32) autofs file systems would solve it, but alas, that can't work. This is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 33) because autofs direct mounts and the implementation of "on demand mount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 34) and expire" of nested mount trees have the file system mounted directly
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 35) on top of the mount trigger directory dentry.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 36)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 37) For example, there are two types of automount maps, direct (in the kernel
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 38) module source you will see a third type called an offset, which is just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 39) a direct mount in disguise) and indirect.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 40)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 41) Here is a master map with direct and indirect map entries::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 42)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 43) /- /etc/auto.direct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 44) /test /etc/auto.indirect
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 45)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 46) and the corresponding map files::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 47)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 48) /etc/auto.direct:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 49)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 50) /automount/dparse/g6 budgie:/autofs/export1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 51) /automount/dparse/g1 shark:/autofs/export1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 52) and so on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 53)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 54) /etc/auto.indirect::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 55)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 56) g1 shark:/autofs/export1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 57) g6 budgie:/autofs/export1
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 58) and so on.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 59)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 60) For the above indirect map an autofs file system is mounted on /test and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 61) mounts are triggered for each sub-directory key by the inode lookup
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 62) operation. So we see a mount of shark:/autofs/export1 on /test/g1, for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 63) example.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 64)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 65) The way that direct mounts are handled is by making an autofs mount on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 66) each full path, such as /automount/dparse/g1, and using it as a mount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 67) trigger. So when we walk on the path we mount shark:/autofs/export1 "on
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 68) top of this mount point". Since these are always directories we can
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 69) use the follow_link inode operation to trigger the mount.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 70)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 71) But, each entry in direct and indirect maps can have offsets (making
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 72) them multi-mount map entries).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 73)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 74) For example, an indirect mount map entry could also be::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 75)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 76) g1 \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 77) / shark:/autofs/export5/testing/test \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 78) /s1 shark:/autofs/export/testing/test/s1 \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 79) /s2 shark:/autofs/export5/testing/test/s2 \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 80) /s1/ss1 shark:/autofs/export1 \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 81) /s2/ss2 shark:/autofs/export2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 82)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 83) and a similarly a direct mount map entry could also be::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 84)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 85) /automount/dparse/g1 \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 86) / shark:/autofs/export5/testing/test \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 87) /s1 shark:/autofs/export/testing/test/s1 \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 88) /s2 shark:/autofs/export5/testing/test/s2 \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 89) /s1/ss1 shark:/autofs/export2 \
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 90) /s2/ss2 shark:/autofs/export2
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 91)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 92) One of the issues with version 4 of autofs was that, when mounting an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 93) entry with a large number of offsets, possibly with nesting, we needed
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 94) to mount and umount all of the offsets as a single unit. Not really a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 95) problem, except for people with a large number of offsets in map entries.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 96) This mechanism is used for the well known "hosts" map and we have seen
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 97) cases (in 2.4) where the available number of mounts are exhausted or
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 98) where the number of privileged ports available is exhausted.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 99)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 100) In version 5 we mount only as we go down the tree of offsets and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 101) similarly for expiring them which resolves the above problem. There is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 102) somewhat more detail to the implementation but it isn't needed for the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 103) sake of the problem explanation. The one important detail is that these
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 104) offsets are implemented using the same mechanism as the direct mounts
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 105) above and so the mount points can be covered by a mount.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 106)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 107) The current autofs implementation uses an ioctl file descriptor opened
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 108) on the mount point for control operations. The references held by the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 109) descriptor are accounted for in checks made to determine if a mount is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 110) in use and is also used to access autofs file system information held
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 111) in the mount super block. So the use of a file handle needs to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 112) retained.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 113)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 114)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 115) The Solution
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 116) ============
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 117)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 118) To be able to restart autofs leaving existing direct, indirect and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 119) offset mounts in place we need to be able to obtain a file handle
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 120) for these potentially covered autofs mount points. Rather than just
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 121) implement an isolated operation it was decided to re-implement the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 122) existing ioctl interface and add new operations to provide this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 123) functionality.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 124)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 125) In addition, to be able to reconstruct a mount tree that has busy mounts,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 126) the uid and gid of the last user that triggered the mount needs to be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 127) available because these can be used as macro substitution variables in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 128) autofs maps. They are recorded at mount request time and an operation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 129) has been added to retrieve them.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 130)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 131) Since we're re-implementing the control interface, a couple of other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 132) problems with the existing interface have been addressed. First, when
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 133) a mount or expire operation completes a status is returned to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 134) kernel by either a "send ready" or a "send fail" operation. The
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 135) "send fail" operation of the ioctl interface could only ever send
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 136) ENOENT so the re-implementation allows user space to send an actual
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 137) status. Another expensive operation in user space, for those using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 138) very large maps, is discovering if a mount is present. Usually this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 139) involves scanning /proc/mounts and since it needs to be done quite
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 140) often it can introduce significant overhead when there are many entries
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 141) in the mount table. An operation to lookup the mount status of a mount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 142) point dentry (covered or not) has also been added.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 143)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 144) Current kernel development policy recommends avoiding the use of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 145) ioctl mechanism in favor of systems such as Netlink. An implementation
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 146) using this system was attempted to evaluate its suitability and it was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 147) found to be inadequate, in this case. The Generic Netlink system was
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 148) used for this as raw Netlink would lead to a significant increase in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 149) complexity. There's no question that the Generic Netlink system is an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 150) elegant solution for common case ioctl functions but it's not a complete
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 151) replacement probably because its primary purpose in life is to be a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 152) message bus implementation rather than specifically an ioctl replacement.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 153) While it would be possible to work around this there is one concern
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 154) that lead to the decision to not use it. This is that the autofs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 155) expire in the daemon has become far to complex because umount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 156) candidates are enumerated, almost for no other reason than to "count"
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 157) the number of times to call the expire ioctl. This involves scanning
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 158) the mount table which has proved to be a big overhead for users with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 159) large maps. The best way to improve this is try and get back to the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 160) way the expire was done long ago. That is, when an expire request is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 161) issued for a mount (file handle) we should continually call back to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 162) the daemon until we can't umount any more mounts, then return the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 163) appropriate status to the daemon. At the moment we just expire one
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 164) mount at a time. A Generic Netlink implementation would exclude this
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 165) possibility for future development due to the requirements of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 166) message bus architecture.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 167)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 168)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 169) autofs Miscellaneous Device mount control interface
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 170) ====================================================
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 171)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 172) The control interface is opening a device node, typically /dev/autofs.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 173)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 174) All the ioctls use a common structure to pass the needed parameter
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 175) information and return operation results::
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 176)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 177) struct autofs_dev_ioctl {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 178) __u32 ver_major;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 179) __u32 ver_minor;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 180) __u32 size; /* total size of data passed in
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 181) * including this struct */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 182) __s32 ioctlfd; /* automount command fd */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 183)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 184) /* Command parameters */
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 185) union {
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 186) struct args_protover protover;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 187) struct args_protosubver protosubver;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 188) struct args_openmount openmount;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 189) struct args_ready ready;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 190) struct args_fail fail;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 191) struct args_setpipefd setpipefd;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 192) struct args_timeout timeout;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 193) struct args_requester requester;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 194) struct args_expire expire;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 195) struct args_askumount askumount;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 196) struct args_ismountpoint ismountpoint;
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 197) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 198)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 199) char path[0];
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 200) };
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 201)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 202) The ioctlfd field is a mount point file descriptor of an autofs mount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 203) point. It is returned by the open call and is used by all calls except
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 204) the check for whether a given path is a mount point, where it may
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 205) optionally be used to check a specific mount corresponding to a given
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 206) mount point file descriptor, and when requesting the uid and gid of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 207) last successful mount on a directory within the autofs file system.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 208)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 209) The union is used to communicate parameters and results of calls made
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 210) as described below.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 211)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 212) The path field is used to pass a path where it is needed and the size field
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 213) is used account for the increased structure length when translating the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 214) structure sent from user space.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 215)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 216) This structure can be initialized before setting specific fields by using
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 217) the void function call init_autofs_dev_ioctl(``struct autofs_dev_ioctl *``).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 218)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 219) All of the ioctls perform a copy of this structure from user space to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 220) kernel space and return -EINVAL if the size parameter is smaller than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 221) the structure size itself, -ENOMEM if the kernel memory allocation fails
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 222) or -EFAULT if the copy itself fails. Other checks include a version check
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 223) of the compiled in user space version against the module version and a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 224) mismatch results in a -EINVAL return. If the size field is greater than
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 225) the structure size then a path is assumed to be present and is checked to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 226) ensure it begins with a "/" and is NULL terminated, otherwise -EINVAL is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 227) returned. Following these checks, for all ioctl commands except
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 228) AUTOFS_DEV_IOCTL_VERSION_CMD, AUTOFS_DEV_IOCTL_OPENMOUNT_CMD and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 229) AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD the ioctlfd is validated and if it is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 230) not a valid descriptor or doesn't correspond to an autofs mount point
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 231) an error of -EBADF, -ENOTTY or -EINVAL (not an autofs descriptor) is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 232) returned.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 233)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 234)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 235) The ioctls
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 236) ==========
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 237)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 238) An example of an implementation which uses this interface can be seen
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 239) in autofs version 5.0.4 and later in file lib/dev-ioctl-lib.c of the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 240) distribution tar available for download from kernel.org in directory
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 241) /pub/linux/daemons/autofs/v5.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 242)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 243) The device node ioctl operations implemented by this interface are:
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 244)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 245)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 246) AUTOFS_DEV_IOCTL_VERSION
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 247) ------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 248)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 249) Get the major and minor version of the autofs device ioctl kernel module
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 250) implementation. It requires an initialized struct autofs_dev_ioctl as an
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 251) input parameter and sets the version information in the passed in structure.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 252) It returns 0 on success or the error -EINVAL if a version mismatch is
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 253) detected.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 254)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 255)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 256) AUTOFS_DEV_IOCTL_PROTOVER_CMD and AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 257) ------------------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 258)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 259) Get the major and minor version of the autofs protocol version understood
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 260) by loaded module. This call requires an initialized struct autofs_dev_ioctl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 261) with the ioctlfd field set to a valid autofs mount point descriptor
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 262) and sets the requested version number in version field of struct args_protover
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 263) or sub_version field of struct args_protosubver. These commands return
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 264) 0 on success or one of the negative error codes if validation fails.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 265)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 266)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 267) AUTOFS_DEV_IOCTL_OPENMOUNT and AUTOFS_DEV_IOCTL_CLOSEMOUNT
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 268) ----------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 269)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 270) Obtain and release a file descriptor for an autofs managed mount point
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 271) path. The open call requires an initialized struct autofs_dev_ioctl with
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 272) the path field set and the size field adjusted appropriately as well
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 273) as the devid field of struct args_openmount set to the device number of
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 274) the autofs mount. The device number can be obtained from the mount options
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 275) shown in /proc/mounts. The close call requires an initialized struct
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 276) autofs_dev_ioct with the ioctlfd field set to the descriptor obtained
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 277) from the open call. The release of the file descriptor can also be done
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 278) with close(2) so any open descriptors will also be closed at process exit.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 279) The close call is included in the implemented operations largely for
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 280) completeness and to provide for a consistent user space implementation.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 281)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 282)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 283) AUTOFS_DEV_IOCTL_READY_CMD and AUTOFS_DEV_IOCTL_FAIL_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 284) --------------------------------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 285)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 286) Return mount and expire result status from user space to the kernel.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 287) Both of these calls require an initialized struct autofs_dev_ioctl
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 288) with the ioctlfd field set to the descriptor obtained from the open
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 289) call and the token field of struct args_ready or struct args_fail set
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 290) to the wait queue token number, received by user space in the foregoing
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 291) mount or expire request. The status field of struct args_fail is set to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 292) the errno of the operation. It is set to 0 on success.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 293)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 294)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 295) AUTOFS_DEV_IOCTL_SETPIPEFD_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 296) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 297)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 298) Set the pipe file descriptor used for kernel communication to the daemon.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 299) Normally this is set at mount time using an option but when reconnecting
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 300) to a existing mount we need to use this to tell the autofs mount about
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 301) the new kernel pipe descriptor. In order to protect mounts against
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 302) incorrectly setting the pipe descriptor we also require that the autofs
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 303) mount be catatonic (see next call).
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 304)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 305) The call requires an initialized struct autofs_dev_ioctl with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 306) ioctlfd field set to the descriptor obtained from the open call and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 307) the pipefd field of struct args_setpipefd set to descriptor of the pipe.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 308) On success the call also sets the process group id used to identify the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 309) controlling process (eg. the owning automount(8) daemon) to the process
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 310) group of the caller.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 311)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 312)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 313) AUTOFS_DEV_IOCTL_CATATONIC_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 314) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 315)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 316) Make the autofs mount point catatonic. The autofs mount will no longer
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 317) issue mount requests, the kernel communication pipe descriptor is released
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 318) and any remaining waits in the queue released.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 319)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 320) The call requires an initialized struct autofs_dev_ioctl with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 321) ioctlfd field set to the descriptor obtained from the open call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 322)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 323)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 324) AUTOFS_DEV_IOCTL_TIMEOUT_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 325) ----------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 326)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 327) Set the expire timeout for mounts within an autofs mount point.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 328)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 329) The call requires an initialized struct autofs_dev_ioctl with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 330) ioctlfd field set to the descriptor obtained from the open call.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 331)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 332)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 333) AUTOFS_DEV_IOCTL_REQUESTER_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 334) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 335)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 336) Return the uid and gid of the last process to successfully trigger a the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 337) mount on the given path dentry.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 338)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 339) The call requires an initialized struct autofs_dev_ioctl with the path
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 340) field set to the mount point in question and the size field adjusted
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 341) appropriately. Upon return the uid field of struct args_requester contains
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 342) the uid and gid field the gid.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 343)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 344) When reconstructing an autofs mount tree with active mounts we need to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 345) re-connect to mounts that may have used the original process uid and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 346) gid (or string variations of them) for mount lookups within the map entry.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 347) This call provides the ability to obtain this uid and gid so they may be
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 348) used by user space for the mount map lookups.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 349)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 350)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 351) AUTOFS_DEV_IOCTL_EXPIRE_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 352) ---------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 353)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 354) Issue an expire request to the kernel for an autofs mount. Typically
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 355) this ioctl is called until no further expire candidates are found.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 356)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 357) The call requires an initialized struct autofs_dev_ioctl with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 358) ioctlfd field set to the descriptor obtained from the open call. In
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 359) addition an immediate expire that's independent of the mount timeout,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 360) and a forced expire that's independent of whether the mount is busy,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 361) can be requested by setting the how field of struct args_expire to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 362) AUTOFS_EXP_IMMEDIATE or AUTOFS_EXP_FORCED, respectively . If no
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 363) expire candidates can be found the ioctl returns -1 with errno set to
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 364) EAGAIN.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 365)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 366) This call causes the kernel module to check the mount corresponding
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 367) to the given ioctlfd for mounts that can be expired, issues an expire
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 368) request back to the daemon and waits for completion.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 369)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 370) AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 371) ------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 372)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 373) Checks if an autofs mount point is in use.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 374)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 375) The call requires an initialized struct autofs_dev_ioctl with the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 376) ioctlfd field set to the descriptor obtained from the open call and
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 377) it returns the result in the may_umount field of struct args_askumount,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 378) 1 for busy and 0 otherwise.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 379)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 380)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 381) AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 382) ---------------------------------
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 383)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 384) Check if the given path is a mountpoint.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 385)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 386) The call requires an initialized struct autofs_dev_ioctl. There are two
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 387) possible variations. Both use the path field set to the path of the mount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 388) point to check and the size field adjusted appropriately. One uses the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 389) ioctlfd field to identify a specific mount point to check while the other
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 390) variation uses the path and optionally in.type field of struct args_ismountpoint
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 391) set to an autofs mount type. The call returns 1 if this is a mount point
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 392) and sets out.devid field to the device number of the mount and out.magic
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 393) field to the relevant super block magic number (described below) or 0 if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 394) it isn't a mountpoint. In both cases the device number (as returned
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 395) by new_encode_dev()) is returned in out.devid field.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 396)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 397) If supplied with a file descriptor we're looking for a specific mount,
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 398) not necessarily at the top of the mounted stack. In this case the path
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 399) the descriptor corresponds to is considered a mountpoint if it is itself
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 400) a mountpoint or contains a mount, such as a multi-mount without a root
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 401) mount. In this case we return 1 if the descriptor corresponds to a mount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 402) point and also returns the super magic of the covering mount if there
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 403) is one or 0 if it isn't a mountpoint.
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 404)
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 405) If a path is supplied (and the ioctlfd field is set to -1) then the path
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 406) is looked up and is checked to see if it is the root of a mount. If a
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 407) type is also given we are looking for a particular autofs mount and if
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 408) a match isn't found a fail is returned. If the located path is the
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 409) root of a mount 1 is returned along with the super magic of the mount
^8f3ce5b39 (kx 2023-10-28 12:00:06 +0300 410) or 0 otherwise.
Orange Pi5 kernel
Deprecated Linux kernel 5.10.110 for OrangePi 5/5B/5+ boards
3 Commits
0 Branches
0 Tags