Commit | Line | Data |
---|---|---|
f11f2a3c | 1 | ===================== |
87d672cb N |
2 | autofs - how it works |
3 | ===================== | |
4 | ||
5 | Purpose | |
f11f2a3c | 6 | ======= |
87d672cb N |
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 | |
f11f2a3c | 28 | ======= |
87d672cb | 29 | |
b6bb226a | 30 | The "autofs" filesystem module is only one part of an autofs system. |
87d672cb N |
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, | |
b6bb226a | 33 | though other tools including "systemd" can make use of "autofs". |
87d672cb N |
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 | ||
b6bb226a | 38 | "autofs" is a Linux kernel module with provides the "autofs" |
87d672cb N |
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 | |
f11f2a3c | 43 | ======= |
87d672cb N |
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 | |
e8a9e30d JS |
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*. | |
87d672cb N |
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 | |
d0846dd5 | 66 | filesystem is mounted *indirect* and they are empty. |
87d672cb N |
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 | |
f11f2a3c | 81 | =========== |
87d672cb N |
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 | |
2ad56add | 117 | related behaviours are invoked, both using the `d_op->d_manage()` |
87d672cb N |
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 | |
2ad56add IK |
194 | -ECHILD if there is any reason to believe it is unsafe to enter the |
195 | mounted filesystem, otherwise it should return 0. | |
87d672cb N |
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 | |
f11f2a3c | 202 | ================= |
87d672cb | 203 | |
e662145f | 204 | The VFS has a mechanism for automatically expiring unused mounts, |
87d672cb | 205 | much as it can expire any unused dentry information from the dcache. |
e662145f | 206 | This is guided by the MNT_SHRINKABLE flag. This only applies to |
87d672cb N |
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 | |
2ad56add | 211 | over expiry. |
87d672cb N |
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 | |
b6bb226a | 216 | and untouched since that previous attempt. autofs does not depend on |
87d672cb N |
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 | |
2ad56add | 226 | will trigger normal auto-mount processing. In particular, `rmdir` and |
87d672cb N |
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 | |
92000266 IK |
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. | |
87d672cb N |
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. | |
f23ceaac IK |
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. | |
87d672cb N |
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 | |
2ad56add | 285 | mounts in a version-5 autofs. For this reason the current `automount(8)` |
87d672cb N |
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 | |
f11f2a3c | 302 | =============================================== |
87d672cb N |
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 | ||
e662145f | 310 | When an autofs filesystem is mounted the pgid of the mounting |
87d672cb N |
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 | |
f11f2a3c | 318 | ========================================= |
87d672cb N |
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. | |
f11f2a3c JS |
323 | For version 5, the format of the message is:: |
324 | ||
325 | struct autofs_v5_packet { | |
c11565e8 | 326 | struct autofs_packet_hdr hdr; |
f11f2a3c JS |
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]; | |
87d672cb N |
336 | }; |
337 | ||
c11565e8 JS |
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 | ||
f11f2a3c | 345 | where the type is one of :: |
87d672cb | 346 | |
f11f2a3c JS |
347 | autofs_ptype_missing_indirect |
348 | autofs_ptype_expire_indirect | |
349 | autofs_ptype_missing_direct | |
350 | autofs_ptype_expire_direct | |
87d672cb N |
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 | ||
7cee9384 | 359 | The `wait_queue_token` is a unique number which can identify a |
87d672cb N |
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 | |
2ad56add | 363 | acknowledged using one of the ioctls below with the relevant |
7cee9384 | 364 | `wait_queue_token`. |
87d672cb N |
365 | |
366 | Communicating with autofs: root directory ioctls | |
f11f2a3c | 367 | ================================================ |
87d672cb N |
368 | |
369 | The root directory of an autofs filesystem will respond to a number of | |
d0846dd5 | 370 | ioctls. The process issuing the ioctl must have the CAP_SYS_ADMIN |
87d672cb N |
371 | capability, or must be the automount daemon. |
372 | ||
373 | The available ioctl commands are: | |
374 | ||
f11f2a3c JS |
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 { | |
c11565e8 | 405 | struct autofs_packet_hdr hdr; |
f11f2a3c JS |
406 | autofs_wqt_t wait_queue_token; |
407 | int len; | |
408 | char name[NAME_MAX+1]; | |
409 | }; | |
87d672cb | 410 | |
f11f2a3c JS |
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. | |
87d672cb | 421 | |
f11f2a3c JS |
422 | **AUTOFS_EXP_IMMEDIATE** causes `last_used` time to be ignored |
423 | and objects are expired if the are not in use. | |
87d672cb | 424 | |
f11f2a3c JS |
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. | |
841964e8 | 429 | |
f11f2a3c JS |
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. | |
87d672cb N |
432 | |
433 | Communicating with autofs: char-device ioctls | |
f11f2a3c | 434 | ============================================= |
87d672cb N |
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 | ||
f11f2a3c | 444 | The 'ioctl's that can be used on this device are described in a separate |
2ad56add | 445 | document `autofs-mount-control.txt`, and are summarised briefly here. |
f11f2a3c | 446 | Each ioctl is passed a pointer to an `autofs_dev_ioctl` structure:: |
87d672cb N |
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 | ||
88488080 TK |
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 | }; | |
87d672cb N |
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 | ||
f11f2a3c JS |
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**. | |
87d672cb N |
525 | |
526 | Catatonic mode | |
f11f2a3c | 527 | ============== |
87d672cb N |
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 | ||
1dcaa138 | 550 | The "ignore" mount option |
f11f2a3c | 551 | ========================= |
1dcaa138 IK |
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 | ||
87d672cb | 565 | autofs, name spaces, and shared mounts |
f11f2a3c | 566 | ====================================== |
87d672cb N |
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 | |
f11f2a3c | 571 | always be mounted "shared". e.g. :: |
87d672cb | 572 | |
f11f2a3c | 573 | mount --make-shared /autofs/mount/point |
87d672cb | 574 | |
d0846dd5 | 575 | The automount daemon is only able to manage a single mount location for |
87d672cb N |
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 | |
f11f2a3c | 578 | other locations will likely result in the `ELOOP` error :: |
87d672cb | 579 | |
f11f2a3c | 580 | Too many levels of symbolic links |