From f6f93f6d8f8efa5a8fb0e07ba88c0d49d801a25d Mon Sep 17 00:00:00 2001 From: Fredrik Salomonsson Date: Tue, 19 May 2026 18:57:19 -0700 Subject: doc: Add documentation for btrfs swap file. * doc/guix.texi (Keyboard Layout and Networking and Partitioning): Add btrfs example with a subvolume. (Proceeding with the Installation): Note about dependencies when using subvolumes in btrfs for the swap file. (Swap Space): Add info on how to get the offset to the swap file when using btrfs. Merges: guix/guix!8829 Change-Id: I0c9c271d73520966ac8a7e87ca9d93120134cf41 Signed-off-by: Florian Pelz --- doc/guix.texi | 63 ++++++++++++++++++++++++++++++++++++++++++++++++++++------- 1 file changed, 56 insertions(+), 7 deletions(-) (limited to 'doc') diff --git a/doc/guix.texi b/doc/guix.texi index f5efd34024e..a9930d01e6b 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -153,6 +153,7 @@ Copyright @copyright{} 2026 Nguyễn Gia Phong@* Copyright @copyright{} 2026 Yarl Baudig@* Copyright @copyright{} 2026 Joan Vilardaga Castro@* Copyright @copyright{} 2026 Nemin@* +Copyright @copyright{} 2026 Fredrik Salomonsson@* Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.3 or @@ -2717,7 +2718,7 @@ bootloaders. Once you are done partitioning the target hard disk drive, you have to create a file system on the relevant partition(s)@footnote{Currently -Guix System can mount only ext4, btrfs, JFS, F2FS, and XFS file systems +Guix System can mount only ext4, Btrfs, JFS, F2FS, and XFS file systems at boot time. In particular, code that reads file system UUIDs and labels works only for these file system types. The code for bcachefs is in place, but support for loading out-of-tree kernel modules in the @@ -2784,12 +2785,18 @@ mkswap /dev/sda3 swapon /dev/sda3 @end example -Alternatively, you may use a swap file. For example, assuming that in -the new system you want to use the file @file{/swapfile} as a swap file, -you would run@footnote{This example will work for many types of file -systems (e.g., ext4). However, for copy-on-write file systems (e.g., -btrfs), the required steps may be different. For details, see the -manual pages for @command{mkswap} and @command{swapon}.}: +Alternatively, you may use a swap file, whose size can be trivially +modified at a later date. Creating a swap file will look a bit +different depending on what sort of file system your new system is +using. We therefore have two examples on how to create a swap file, the +first will work for many types of file systems (e.g., ext4) but not +Btrfs@footnote{For other copy-on-write file systems, the required steps +may also be different. For details, see the manual pages for +@command{mkswap} and @command{swapon}.}. The second example is +specifically for Btrfs. + +For the common case, assuming that in the new system you want to use the +file @file{/swapfile} as a swap file, you would run: @example # This is 10 GiB of swap space. Adjust "count" to change the size. @@ -2800,6 +2807,35 @@ mkswap /mnt/swapfile swapon /mnt/swapfile @end example +When you use Btrfs the steps for creating a swap file are slightly +different and it comes with a few caveats. I.e. it must be on a single +device, the filesystem must only have @code{single} as the data profile +and the subvolume that contains the active swap file or files cannot be +snapshotted. It is therefore best to put the swap file in a separate +subvolume to allow to snapshot the rest of the filesystem. This example +assumes the label for the Btrfs file system is @code{btrfs-pool} and the +subvolume for the root is @code{rootfs}. + +@example +# Temporarily unmount btrfs-pool +umount /mnt +# Mount the top level subvolume +mount LABEL=btrfs-pool -o subvolid=5 /mnt +# Create the subvolume (swap) that will hold the swap file +cd /mnt && btrfs subvolume create swap && cd - +# Remount the target file system +unmount /mnt +mount LABEL=btrfs-pool -o subvol=rootfs /mnt +# Create the directory where it should mount the swap subvolume +mkdir /mnt/swap +# Mount the swap subvolume +mount LABEL=btrfs-pool -o subvol=swap /mnt/swap +# Create a 10 GiB of swap space. It accepts k/m/g/e/p as suffix +btrfs filesystem mkswapfile --size 10G /mnt/swap/swapfile +# Activate the swap file +swapon /mnt/swap/swapfile +@end example + Note that if you have encrypted the root partition and created a swap file in its file system as described above, then the encryption also protects the swap file, just like any other file in that file system. @@ -2865,6 +2901,10 @@ Be sure that your file system labels match the value of their respective your @code{file-system} configuration uses the @code{file-system-label} procedure in its @code{device} field. +If you are using Btrfs and your swap file is in a subvolume make sure to +list the root partition as its dependency in its @code{file-system} +entry to make sure everything is mounted in the right order. + @item If there are encrypted or RAID partitions, make sure to add a @code{mapped-devices} field to describe them (@pxref{Mapped Devices}). @@ -19813,6 +19853,15 @@ $ sudo filefrag -e /swapfile | grep '^ *0:' | cut -d: -f3 | cut -d. -f1 92514304 @end smallexample +Note that if the swap file is on a Btrfs file system use @command{btrfs +inspect-internal map-swapfile -r} instead of @command{filefrag} to get +the offset as the latter will not give the right offset. + +@smallexample +$ sudo btrfs inspect-internal map-swapfile -r /swapfile + 163845376 +@end smallexample + @node User Accounts @section User Accounts -- cgit v1.2.3