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