The fstab(5) man page already describes some basic aspects of "swap," but it makes sense to be more specific in the swapon man page and describe everything in one place, serving as a normative reference for what is expected on Linux in fstab for swap. Fixes: https://github.com/util-linux/util-linux/issues/3667 Signed-off-by: Karel Zak <kzak@xxxxxxxxxx> --- sys-utils/fstab.5.adoc | 2 ++ sys-utils/swapon.8.adoc | 47 +++++++++++++++++++++++++++++++++++++++++ 2 files changed, 49 insertions(+) diff --git a/sys-utils/fstab.5.adoc b/sys-utils/fstab.5.adoc index f5b4d0dcb..53d7dced5 100644 --- a/sys-utils/fstab.5.adoc +++ b/sys-utils/fstab.5.adoc @@ -56,6 +56,8 @@ The file *fstab* contains descriptive information about the filesystems the syst The file is not read by *mount*(8) only but often is used by many other tools and daemons, and proper functionality may require additional steps. For example, on systemd-based systems, it's recommended to use *systemctl daemon-reload* after *fstab* modification. +See the *swapon*(8) man page for details about swap area fstab configuration. + Each filesystem is described on a separate line, with fields separated by tabs or spaces. The line is split into fields before being parsed. This means that any spaces or tabs within the fields must be escaped using \040 or \011, even within quoted strings (e.g. LABEL="foo\040bar"). Lines starting with '#' are comments. Blank lines are ignored. diff --git a/sys-utils/swapon.8.adoc b/sys-utils/swapon.8.adoc index a25309d18..f4516c66a 100644 --- a/sys-utils/swapon.8.adoc +++ b/sys-utils/swapon.8.adoc @@ -30,6 +30,7 @@ Calls to *swapon* normally occur in the system boot scripts making all swap devi *-a*, *--all*:: All devices marked as "swap" in _/etc/fstab_ are made available, except for those with the "noauto" option. Devices that are already being used as swap are silently skipped. +See *FSTAB CONFIGURATION* section for more details. *-T*, *--fstab* _path_:: Specifies an alternative fstab file for compatibility with *mount*(8). If _path_ is a directory, then the files in the directory are sorted by *strverscmp*(3); files that start with "." or without an .fstab extension are ignored. The option can be specified more than once. This option is mostly designed for initramfs or chroot scripts where additional configuration is specified beyond standard system configuration. @@ -91,6 +92,52 @@ Be verbose. include::man-common/help-version.adoc[] +== FSTAB CONFIGURATION + +The command *swapon --all* reads configuration from _/etc/fstab_ (or from a file specified by the *--fstab* command line option). Only fstab entries with the filesystem type (3rd field) set to "swap" are relevant. + +The option *--options* accepts values in the same form as can be specified in the fourth field in fstab. + +=== The first field (source) + +Specify the swap source. If the source is a regular file, it is addressed by an absolute path. + +If the swap is a block device, it can be addressed by device path, swap area tags *LABEL=* or *UUID=* (see *mkswap*(8) for more details), or by partition tags like *PARTLABEL=* or *PARTUUID=*. + +=== The second field (target) + +Unused by *swapon*, the recommended convention is to use "none". + +=== The third field (type) + +Requires "swap" as the filesystem type. + +=== The fourth field (options) + +It is formatted as a comma-separated list of options. All unknown options are silently ignored. If options are unnecessary, the recommended convention is to use "default". The options specified in fstab extend or overwrite settings specified on the swapon command line. + +Supported swap options: + +*noauto*:: +Ignore entry when *swapon --all* is given. + +*nofail*:: +Do not report errors for this device if it does not exist. + +*discard*[**=**_policy_]:: +Enable swap discard. The supported settings are *discard*, *discard=once*, or *discard=pages*. For more details, see the **--discard** command line option. + +**pri=**_priority_:: +Specify the priority of the swap device. For more details, see the **--priority** command line option. + +=== The fifth field + +Unused by *swapon*, the recommended convention is to keep it empty. + +=== The sixth field + +Unused by *swapon*, the recommended convention is to keep it empty. + == EXIT STATUS *swapoff* has the following exit status values since v2.36: -- 2.50.1
