From 47fdb7f5da58dcb8efbc850f24e955140d684e80 Mon Sep 17 00:00:00 2001 From: David Sterba Date: Thu, 22 Apr 2021 23:00:58 +0200 Subject: [PATCH] btrfs-progs: docs: how to use swapfile from fstab This was asked on reddit, how to automatically mount a swapfile from fstab. As this is not completely obvious, document it with an example. Signed-off-by: David Sterba --- Documentation/btrfs-man5.asciidoc | 36 +++++++++++++++++++++++++------ 1 file changed, 30 insertions(+), 6 deletions(-) diff --git a/Documentation/btrfs-man5.asciidoc b/Documentation/btrfs-man5.asciidoc index cf2127b4..c442b121 100644 --- a/Documentation/btrfs-man5.asciidoc +++ b/Documentation/btrfs-man5.asciidoc @@ -657,33 +657,35 @@ SWAPFILE SUPPORT The swapfile is supported since kernel 5.0. Use `swapon`(8) to activate the swapfile. There are some limitations of the implementation in btrfs and linux swap subsystem: - + * filesystem - must be only single device * filesystem - must have only 'single' data profile * swapfile - the containing subvolume cannot be snapshotted * swapfile - must be preallocated * swapfile - must be nodatacow (ie. also nodatasum) * swapfile - must not be compressed - + The limitations come namely from the COW-based design and mapping layer of blocks that allows the advanced features like relocation and multi-device filesystems. However, the swap subsystem expects simpler mapping and no background changes of the file blocks once they've been attached to swap. - + With active swapfiles, the following whole-filesystem operations will skip swapfile extents or may fail: - + * balance - block groups with swapfile extents are skipped and reported, the rest will be processed normally * resize grow - unaffected * resize shrink - works as long as the extents are outside of the shrunk range * device add - a new device does not interfere with existing swapfile and this operation will work, though no new swapfile can be activated afterwards * device delete - if the device has been added as above, it can be also deleted * device replace - ditto - + When there are no active swapfiles and a whole-filesystem exclusive operation is running (ie. balance, device delete, shrink), the swapfiles cannot be temporarily activated. The operation must finish first. - + +To create and activate a swapfile run the following commands: + -------------------- # truncate -s 0 swapfile # chattr +C swapfile @@ -693,6 +695,28 @@ temporarily activated. The operation must finish first. # swapon swapfile -------------------- +Please note that the UUID returned by the 'mkswap' utility identifies the swap +"filesystem" and because it's stored in a file, it's not generally visible and +usable as an identifier unlike if it was on a block device. + +The file will appear in '/proc/swaps': + +-------------------- +# cat /proc/swaps +Filename Type Size Used Priority +/path/swapfile file 2097152 0 -2 +-------------------- + +The swapfile can be created as one-time operation or, once properly created, +activated on each boot by the 'swapon -a' command (usually started by the +service manager). Add the following entry to '/etc/fstab', assuming the +filesystem that provides the '/path' has been already mounted at this point. +Additional mount options relevant for the swapfile can be set too (like +priority, not the btrfs mount options). + +-------------------- +/path/swapfile none swap defaults 0 0 +-------------------- CHECKSUM ALGORITHMS -------------------