About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / filesystems / autofs4.txt


Based on kernel version 4.16.1. Page generated on 2018-04-09 11:53 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog