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