docs: filesystems: convert autofs.txt to reST

+133 -117

2 changed files

expand all

Documentation

filesystems

autofs.rst

index.rst

+132 -117

Documentation/filesystems/autofs.txt Documentation/filesystems/autofs.rst

··· 1 - <head> 2 - <style> p { max-width:50em} ol, ul {max-width: 40em}</style> 3 - </head> 4 - 1 + ===================== 5 2 autofs - how it works 6 3 ===================== 7 4 8 5 Purpose 9 - ------- 6 + ======= 10 7 11 8 The goal of autofs is to provide on-demand mounting and race free 12 9 automatic unmounting of various other filesystems. This provides two ··· 25 28 first accessed a name. 26 29 27 30 Context 28 - ------- 31 + ======= 29 32 30 33 The "autofs" filesystem module is only one part of an autofs system. 31 34 There also needs to be a user-space program which looks up names ··· 40 43 can each be managed separately, or all managed by the same daemon. 41 44 42 45 Content 43 - ------- 46 + ======= 44 47 45 48 An autofs filesystem can contain 3 sorts of objects: directories, 46 49 symbolic links and mount traps. Mount traps are directories with ··· 49 52 Objects can only be created by the automount daemon: symlinks are 50 53 created with a regular `symlink` system call, while directories and 51 54 mount traps are created with `mkdir`. The determination of whether a 52 - directory should be a mount trap or not is quite _ad hoc_, largely for 55 + directory should be a mount trap or not is quite ad hoc, largely for 53 56 historical reasons, and is determined in part by the 54 57 *direct*/*indirect*/*offset* mount options, and the *maxproto* mount option. 55 58 ··· 77 80 and whether the mount was *indirect* or not. 78 81 79 82 Mount Traps 80 - --------------- 83 + =========== 81 84 82 85 A core element of the implementation of autofs is the Mount Traps 83 86 which are provided by the Linux VFS. Any directory provided by a ··· 198 201 199 202 200 203 Mountpoint expiry 201 - ----------------- 204 + ================= 202 205 203 206 The VFS has a mechanism for automatically expiring unused mounts, 204 207 much as it can expire any unused dentry information from the dcache. ··· 298 301 necessary), or has been aborted. 299 302 300 303 Communicating with autofs: detecting the daemon 301 - ----------------------------------------------- 304 + =============================================== 302 305 303 306 There are several forms of communication between the automount daemon 304 307 and the filesystem. As we have already seen, the daemon can create and ··· 314 317 provided through an ioctl as will be described below. 315 318 316 319 Communicating with autofs: the event pipe 317 - ----------------------------------------- 320 + ========================================= 318 321 319 322 When an autofs filesystem is mounted, the 'write' end of a pipe must 320 323 be passed using the 'fd=' mount option. autofs will write 321 324 notification messages to this pipe for the daemon to respond to. 322 - For version 5, the format of the message is: 325 + For version 5, the format of the message is:: 323 326 324 - struct autofs_v5_packet { 325 - int proto_version; /* Protocol version */ 326 - int type; /* Type of packet */ 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]; 327 + struct autofs_v5_packet { 328 + int proto_version; /* Protocol version */ 329 + int type; /* Type of packet */ 330 + autofs_wqt_t wait_queue_token; 331 + __u32 dev; 332 + __u64 ino; 333 + __u32 uid; 334 + __u32 gid; 335 + __u32 pid; 336 + __u32 tgid; 337 + __u32 len; 338 + char name[NAME_MAX+1]; 336 339 }; 337 340 338 - where the type is one of 341 + where the type is one of :: 339 342 340 - autofs_ptype_missing_indirect 341 - autofs_ptype_expire_indirect 342 - autofs_ptype_missing_direct 343 - autofs_ptype_expire_direct 343 + autofs_ptype_missing_indirect 344 + autofs_ptype_expire_indirect 345 + autofs_ptype_missing_direct 346 + autofs_ptype_expire_direct 344 347 345 348 so messages can indicate that a name is missing (something tried to 346 349 access it but it isn't there) or that it has been selected for expiry. ··· 357 360 `wait_queue_token`. 358 361 359 362 Communicating with autofs: root directory ioctls 360 - ------------------------------------------------ 363 + ================================================ 361 364 362 365 The root directory of an autofs filesystem will respond to a number of 363 366 ioctls. The process issuing the ioctl must have the CAP_SYS_ADMIN ··· 365 368 366 369 The available ioctl commands are: 367 370 368 - - **AUTOFS_IOC_READY**: a notification has been handled. The argument 369 - to the ioctl command is the "wait_queue_token" number 370 - corresponding to the notification being acknowledged. 371 - - **AUTOFS_IOC_FAIL**: similar to above, but indicates failure with 372 - the error code `ENOENT`. 373 - - **AUTOFS_IOC_CATATONIC**: Causes the autofs to enter "catatonic" 374 - mode meaning that it stops sending notifications to the daemon. 375 - This mode is also entered if a write to the pipe fails. 376 - - **AUTOFS_IOC_PROTOVER**: This returns the protocol version in use. 377 - - **AUTOFS_IOC_PROTOSUBVER**: Returns the protocol sub-version which 378 - is really a version number for the implementation. 379 - - **AUTOFS_IOC_SETTIMEOUT**: This passes a pointer to an unsigned 380 - long. The value is used to set the timeout for expiry, and 381 - the current timeout value is stored back through the pointer. 382 - - **AUTOFS_IOC_ASKUMOUNT**: Returns, in the pointed-to `int`, 1 if 383 - the filesystem could be unmounted. This is only a hint as 384 - the situation could change at any instant. This call can be 385 - used to avoid a more expensive full unmount attempt. 386 - - **AUTOFS_IOC_EXPIRE**: as described above, this asks if there is 387 - anything suitable to expire. A pointer to a packet: 371 + - **AUTOFS_IOC_READY**: 372 + a notification has been handled. The argument 373 + to the ioctl command is the "wait_queue_token" number 374 + corresponding to the notification being acknowledged. 375 + - **AUTOFS_IOC_FAIL**: 376 + similar to above, but indicates failure with 377 + the error code `ENOENT`. 378 + - **AUTOFS_IOC_CATATONIC**: 379 + Causes the autofs to enter "catatonic" 380 + mode meaning that it stops sending notifications to the daemon. 381 + This mode is also entered if a write to the pipe fails. 382 + - **AUTOFS_IOC_PROTOVER**: 383 + This returns the protocol version in use. 384 + - **AUTOFS_IOC_PROTOSUBVER**: 385 + Returns the protocol sub-version which 386 + is really a version number for the implementation. 387 + - **AUTOFS_IOC_SETTIMEOUT**: 388 + This passes a pointer to an unsigned 389 + long. The value is used to set the timeout for expiry, and 390 + the current timeout value is stored back through the pointer. 391 + - **AUTOFS_IOC_ASKUMOUNT**: 392 + Returns, in the pointed-to `int`, 1 if 393 + the filesystem could be unmounted. This is only a hint as 394 + the situation could change at any instant. This call can be 395 + used to avoid a more expensive full unmount attempt. 396 + - **AUTOFS_IOC_EXPIRE**: 397 + as described above, this asks if there is 398 + anything suitable to expire. A pointer to a packet:: 388 399 389 - struct autofs_packet_expire_multi { 390 - int proto_version; /* Protocol version */ 391 - int type; /* Type of packet */ 392 - autofs_wqt_t wait_queue_token; 393 - int len; 394 - char name[NAME_MAX+1]; 395 - }; 400 + struct autofs_packet_expire_multi { 401 + int proto_version; /* Protocol version */ 402 + int type; /* Type of packet */ 403 + autofs_wqt_t wait_queue_token; 404 + int len; 405 + char name[NAME_MAX+1]; 406 + }; 396 407 397 - is required. This is filled in with the name of something 398 - that can be unmounted or removed. If nothing can be expired, 399 - `errno` is set to `EAGAIN`. Even though a `wait_queue_token` 400 - is present in the structure, no "wait queue" is established 401 - and no acknowledgment is needed. 402 - - **AUTOFS_IOC_EXPIRE_MULTI**: This is similar to 403 - **AUTOFS_IOC_EXPIRE** except that it causes notification to be 404 - sent to the daemon, and it blocks until the daemon acknowledges. 405 - The argument is an integer which can contain two different flags. 408 + is required. This is filled in with the name of something 409 + that can be unmounted or removed. If nothing can be expired, 410 + `errno` is set to `EAGAIN`. Even though a `wait_queue_token` 411 + is present in the structure, no "wait queue" is established 412 + and no acknowledgment is needed. 413 + - **AUTOFS_IOC_EXPIRE_MULTI**: 414 + This is similar to 415 + **AUTOFS_IOC_EXPIRE** except that it causes notification to be 416 + sent to the daemon, and it blocks until the daemon acknowledges. 417 + The argument is an integer which can contain two different flags. 406 418 407 - **AUTOFS_EXP_IMMEDIATE** causes `last_used` time to be ignored 408 - and objects are expired if the are not in use. 419 + **AUTOFS_EXP_IMMEDIATE** causes `last_used` time to be ignored 420 + and objects are expired if the are not in use. 409 421 410 - **AUTOFS_EXP_FORCED** causes the in use status to be ignored 411 - and objects are expired ieven if they are in use. This assumes 412 - that the daemon has requested this because it is capable of 413 - performing the umount. 422 + **AUTOFS_EXP_FORCED** causes the in use status to be ignored 423 + and objects are expired ieven if they are in use. This assumes 424 + that the daemon has requested this because it is capable of 425 + performing the umount. 414 426 415 - **AUTOFS_EXP_LEAVES** will select a leaf rather than a top-level 416 - name to expire. This is only safe when *maxproto* is 4. 427 + **AUTOFS_EXP_LEAVES** will select a leaf rather than a top-level 428 + name to expire. This is only safe when *maxproto* is 4. 417 429 418 430 Communicating with autofs: char-device ioctls 419 - --------------------------------------------- 431 + ============================================= 420 432 421 433 It is not always possible to open the root of an autofs filesystem, 422 434 particularly a *direct* mounted filesystem. If the automount daemon ··· 435 429 which can be used to communicate directly with the autofs filesystem. 436 430 It requires CAP_SYS_ADMIN for access. 437 431 438 - The `ioctl`s that can be used on this device are described in a separate 432 + The 'ioctl's that can be used on this device are described in a separate 439 433 document `autofs-mount-control.txt`, and are summarised briefly here. 440 - Each ioctl is passed a pointer to an `autofs_dev_ioctl` structure: 434 + Each ioctl is passed a pointer to an `autofs_dev_ioctl` structure:: 441 435 442 436 struct autofs_dev_ioctl { 443 437 __u32 ver_major; ··· 475 469 476 470 Commands are: 477 471 478 - - **AUTOFS_DEV_IOCTL_VERSION_CMD**: does nothing, except validate and 479 - set version numbers. 480 - - **AUTOFS_DEV_IOCTL_OPENMOUNT_CMD**: return an open file descriptor 481 - on the root of an autofs filesystem. The filesystem is identified 482 - by name and device number, which is stored in `openmount.devid`. 483 - Device numbers for existing filesystems can be found in 484 - `/proc/self/mountinfo`. 485 - - **AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD**: same as `close(ioctlfd)`. 486 - - **AUTOFS_DEV_IOCTL_SETPIPEFD_CMD**: if the filesystem is in 487 - catatonic mode, this can provide the write end of a new pipe 488 - in `setpipefd.pipefd` to re-establish communication with a daemon. 489 - The process group of the calling process is used to identify the 490 - daemon. 491 - - **AUTOFS_DEV_IOCTL_REQUESTER_CMD**: `path` should be a 492 - name within the filesystem that has been auto-mounted on. 493 - On successful return, `requester.uid` and `requester.gid` will be 494 - the UID and GID of the process which triggered that mount. 495 - - **AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD**: Check if path is a 496 - mountpoint of a particular type - see separate documentation for 497 - details. 498 - - **AUTOFS_DEV_IOCTL_PROTOVER_CMD**: 499 - - **AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD**: 500 - - **AUTOFS_DEV_IOCTL_READY_CMD**: 501 - - **AUTOFS_DEV_IOCTL_FAIL_CMD**: 502 - - **AUTOFS_DEV_IOCTL_CATATONIC_CMD**: 503 - - **AUTOFS_DEV_IOCTL_TIMEOUT_CMD**: 504 - - **AUTOFS_DEV_IOCTL_EXPIRE_CMD**: 505 - - **AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD**: These all have the same 506 - function as the similarly named **AUTOFS_IOC** ioctls, except 507 - that **FAIL** can be given an explicit error number in `fail.status` 508 - instead of assuming `ENOENT`, and this **EXPIRE** command 509 - corresponds to **AUTOFS_IOC_EXPIRE_MULTI**. 472 + - **AUTOFS_DEV_IOCTL_VERSION_CMD**: 473 + does nothing, except validate and 474 + set version numbers. 475 + - **AUTOFS_DEV_IOCTL_OPENMOUNT_CMD**: 476 + return an open file descriptor 477 + on the root of an autofs filesystem. The filesystem is identified 478 + by name and device number, which is stored in `openmount.devid`. 479 + Device numbers for existing filesystems can be found in 480 + `/proc/self/mountinfo`. 481 + - **AUTOFS_DEV_IOCTL_CLOSEMOUNT_CMD**: 482 + same as `close(ioctlfd)`. 483 + - **AUTOFS_DEV_IOCTL_SETPIPEFD_CMD**: 484 + if the filesystem is in 485 + catatonic mode, this can provide the write end of a new pipe 486 + in `setpipefd.pipefd` to re-establish communication with a daemon. 487 + The process group of the calling process is used to identify the 488 + daemon. 489 + - **AUTOFS_DEV_IOCTL_REQUESTER_CMD**: 490 + `path` should be a 491 + name within the filesystem that has been auto-mounted on. 492 + On successful return, `requester.uid` and `requester.gid` will be 493 + the UID and GID of the process which triggered that mount. 494 + - **AUTOFS_DEV_IOCTL_ISMOUNTPOINT_CMD**: 495 + Check if path is a 496 + mountpoint of a particular type - see separate documentation for 497 + details. 498 + 499 + - **AUTOFS_DEV_IOCTL_PROTOVER_CMD** 500 + - **AUTOFS_DEV_IOCTL_PROTOSUBVER_CMD** 501 + - **AUTOFS_DEV_IOCTL_READY_CMD** 502 + - **AUTOFS_DEV_IOCTL_FAIL_CMD** 503 + - **AUTOFS_DEV_IOCTL_CATATONIC_CMD** 504 + - **AUTOFS_DEV_IOCTL_TIMEOUT_CMD** 505 + - **AUTOFS_DEV_IOCTL_EXPIRE_CMD** 506 + - **AUTOFS_DEV_IOCTL_ASKUMOUNT_CMD** 507 + 508 + These all have the same 509 + function as the similarly named **AUTOFS_IOC** ioctls, except 510 + that **FAIL** can be given an explicit error number in `fail.status` 511 + instead of assuming `ENOENT`, and this **EXPIRE** command 512 + corresponds to **AUTOFS_IOC_EXPIRE_MULTI**. 510 513 511 514 Catatonic mode 512 - -------------- 515 + ============== 513 516 514 517 As mentioned, an autofs mount can enter "catatonic" mode. This 515 518 happens if a write to the notification pipe fails, or if it is ··· 542 527 **AUTOFS_DEV_IOCTL_OPENMOUNT_CMD** ioctl on the `/dev/autofs`. 543 528 544 529 The "ignore" mount option 545 - ------------------------- 530 + ========================= 546 531 547 532 The "ignore" mount option can be used to provide a generic indicator 548 533 to applications that the mount entry should be ignored when displaying ··· 557 542 mounts from consideration when reading the mounts list. 558 543 559 544 autofs, name spaces, and shared mounts 560 - -------------------------------------- 545 + ====================================== 561 546 562 547 With bind mounts and name spaces it is possible for an autofs 563 548 filesystem to appear at multiple places in one or more filesystem 564 549 name spaces. For this to work sensibly, the autofs filesystem should 565 - always be mounted "shared". e.g. 550 + always be mounted "shared". e.g. :: 566 551 567 - > `mount --make-shared /autofs/mount/point` 552 + mount --make-shared /autofs/mount/point 568 553 569 554 The automount daemon is only able to manage a single mount location for 570 555 an autofs filesystem and if mounts on that are not 'shared', other 571 556 locations will not behave as expected. In particular access to those 572 - other locations will likely result in the `ELOOP` error 557 + other locations will likely result in the `ELOOP` error :: 573 558 574 - > Too many levels of symbolic links 559 + Too many levels of symbolic links

Documentation/filesystems/index.rst

··· 46 46 .. toctree:: 47 47 :maxdepth: 2 48 48 49 + autofs 49 50 virtiofs

Configure Feed

Configure Feed