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 with 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