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