swapon: (man page) add details about fstab configuration

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@redhat.com>

diff --git a/sys-utils/fstab.5.adoc b/sys-utils/fstab.5.adoc
index f5b4d0dcbcba81ab71650018e5018656d42fbe17..53d7dced5131d08e1da80f20cb6bf43adb7cc8f7 100644 (file)
--- 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 a25309d181bde686a281533966a1d7d6fdaf5aed..f9a9ffd3be387663780de642f3a2306f91c9c811 100644 (file)
--- 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 the *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: