[DOCUMENTATION] [PATCH] doc: Introduce using Swap Space for hibernation, with an example.

  • Done
  • quality assurance status badge
Details
2 participants
  • Ivan Vilata i Balaguer
  • Ludovic Courtès
Owner
unassigned
Submitted by
Ivan Vilata i Balaguer
Severity
normal
I
I
Ivan Vilata i Balaguer wrote on 1 Dec 2022 18:17
(address . guix-patches@gnu.org)
Y4jhfPnEfceDLD1/@sax
* doc/guix.texi (Swap Space): Add a concise introduction to hibernation and
specifying a swap space to the kernel to make resume work. Mention space
requirements and the need of an offset for swap files (missing info on how to
obtain it, but at least hint on the needed kernel argument). Include a
trivial example on how to set up swap space for hibernation.
---
doc/guix.texi | 26 ++++++++++++++++++++++++++
1 file changed, 26 insertions(+)

Toggle diff (59 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 47b805dc7f..76441fd4db 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -109,6 +109,7 @@
Copyright @copyright{} 2022 Simon Streit@*
Copyright @copyright{} 2022 (@*
Copyright @copyright{} 2022 John Kehayias@*
+Copyright @copyright{} 2022 Ivan Vilata-i-Balaguer@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -17072,6 +17073,14 @@ Swap Space
allocated at disk formatting time (logical volumes notwithstanding),
whereas files can be allocated and deallocated at any time.
+Also, a swap space is required in order to hibernate (suspend to disk) a
+system using the Linux kernel. The kernel needs to know about the swap
+space to be used to resume from hibernation on boot (via a kernel
+argument). When using a swap file, its offset in the device holding it
+also needs to be given to the kernel, but that value has to be updated
+if the file is recreated. Hibernation uses at most half the size of the
+RAM in the configured swap space.
+
Note that swap space is not zeroed on shutdown, so sensitive data (such
as passwords) may linger on it if it was paged out. As such, you should
consider having your swap reside on an encrypted device (@pxref{Mapped
@@ -17157,6 +17166,23 @@ Swap Space
file system mounted at @file{/btrfs}. Note how we use Guile's filter to
select the file system in an elegant fashion!
+@lisp
+(swap-devices
+ (list (swap-space
+ (target "/dev/mapper/my-swap")
+ (dependencies mapped-devices))))
+
+(kernel-arguments
+ (cons* "resume=/dev/mapper/my-swap"
+ %default-kernel-arguments))
+@end lisp
+
+Use the mapped device @file{/dev/mapper/my-swap} as swap space, and tell
+the kernel to use it for hibernation via the @code{resume} kernel
+argument (@pxref{operating-system Reference}, @code{kernel-arguments}).
+If a swap file was used, the @code{resume_offset} argument would also be
+needed.
+
@node User Accounts
@section User Accounts

base-commit: 5e03354ef535ab1e548f444ac0af0b645a4081de
--
2.38.1


--
Ivan Vilata i Balaguer -- https://elvil.net/
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCAAdFiEEHpvwBPZcchIQr6TuPezBBfXdI4IFAmOI4ZQACgkQPezBBfXd
I4KS8g/8CSssMtgQMHMBb5ifmXY2Taw4/wfcKpz3CBWtv3mViqtA16J274CYMFfh
hpN7oh3Edqed9ZxlLE2K0H1+cZbFBNTYV5P0x0n5ZcsbA6tOsBI+XtN08Srl2SNs
BpEN8mcdRXqjpmAKLC4NFQDNUA85Ag24ltrNYiqnFzqGZvIRAHC0zorPj7VOTF9n
vOcJ8ijvQm6LCFALATuGzSWBmijVJEYxK0af6K5pw81YoJUdXmwLWT2Wpuoo1o5+
aEaEhkE6pjy/kHMxvhYktos+G9MPFdpgYTaXfjTgqpgg7xXE2w5v4CaGBwJUq+iF
8us8JxEJGOoIFuBtuWRQCZqE4FoD7v9KZgVEcQQD9cMwd3Lq+s7Xkru95SOgv7nR
MoA/DbDN7tI6s0pnOFgf3Lekzo1wafunkxPhL0V0PCeOBrmk8VzKTBH5xgigcQ6P
aiHys12jZDlAlh8kkV6qSFnDzS5ykt4WIBdKrEJXFj93eu/UCig3BWrurK5Du88q
V+cEDbKHtShyqgVVlZ0GwZ8gMbFYFCG1pCwtGeAO2Df/M6WLDGdBQGwCiusOFO2j
59J0PkWw/9NNoNUcgp3DeJCifFD/qBMm5A8x6kzvQrR+P+hRI6DqUkNqxSof34dG
HsWOMHkg18V/rd9Rwl07Jc/dua8lyyJP6MdUwV6Xd4Kdr3D7QDI=
=TfGp
-----END PGP SIGNATURE-----


I
I
Ivan Vilata i Balaguer wrote on 21 Dec 2022 13:16
(address . 59746@debbugs.gnu.org)
Y6L5O7vAqok7+U10@sax
This patch replaces the previous one and enhances it with several minor fixes
and the missing information related to computing the swap file offset, as
discussed [in the guix-devel thread][1].


Thanks and cheers!

--
Ivan Vilata i Balaguer -- https://elvil.net/
From e95d79ef8c466e495c730f722b7aefc4d2d5969f Mon Sep 17 00:00:00 2001
From: Ivan Vilata-i-Balaguer <ivan@selidor.net>
Date: Wed, 21 Dec 2022 13:08:48 +0100
Subject: [PATCH] doc: Introduce using swap space for hibernation, with
examples.

* doc/guix.texi (Swap Space): Add a concise introduction to hibernation and
specifying a swap space to the kernel to make resume work. Mention space
requirements and the need of an offset for swap files. Include a trivial
example on how to set up a mapped swap volume for hibernation and another one
for a swap file, including how to compute the file offset.
---
doc/guix.texi | 61 +++++++++++++++++++++++++++++++++++++++++++++++++++
1 file changed, 61 insertions(+)

Toggle diff (88 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index aacf748838..f04a541583 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -109,6 +109,7 @@
Copyright @copyright{} 2022 Simon Streit@*
Copyright @copyright{} 2022 (@*
Copyright @copyright{} 2022 John Kehayias@*
+Copyright @copyright{} 2022 Ivan Vilata-i-Balaguer@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -17072,6 +17073,15 @@ Swap Space
allocated at disk formatting time (logical volumes notwithstanding),
whereas files can be allocated and deallocated at any time.
+A swap space is also required in order to hibernate a system using the
+Linux kernel. Hibernation (also called suspend to disk) uses at most
+half the size of the RAM in the configured swap space. The kernel needs
+to know about the swap space to be used to resume from hibernation on
+boot (via a kernel argument). When using a swap file, its offset in the
+device holding it also needs to be given to the kernel, but that value
+has to be updated if the file is initialized again as swap (e.g. because
+its size was changed).
+
Note that swap space is not zeroed on shutdown, so sensitive data (such
as passwords) may linger on it if it was paged out. As such, you should
consider having your swap reside on an encrypted device (@pxref{Mapped
@@ -17157,6 +17167,57 @@ Swap Space
file system mounted at @file{/btrfs}. Note how we use Guile's filter to
select the file system in an elegant fashion!
+@lisp
+(swap-devices
+ (list
+ (swap-space
+ (target "/dev/mapper/my-swap")
+ (dependencies mapped-devices))))
+
+(kernel-arguments
+ (cons* "resume=/dev/mapper/my-swap"
+ %default-kernel-arguments))
+@end lisp
+
+The previous snippet of an @code{operating-system} declaration enables
+the mapped device @file{/dev/mapper/my-swap} (which may be part of an
+encrypted device) as swap space, and tells the kernel to use it for
+hibernation via the @code{resume} kernel argument
+(@pxref{operating-system Reference}, @code{kernel-arguments}).
+
+@lisp
+(swap-devices
+ (list
+ (swap-space
+ (target "/swapfile")
+ (dependencies (filter (file-system-mount-point-predicate "/")
+ file-systems)))))
+
+(kernel-arguments
+ (cons* "resume=/swapfile"
+ "resume_offset=92514304"
+ %default-kernel-arguments))
+@end lisp
+
+This other snippet of @code{operating-system} enables the swap file
+@file{/swapfile} for hibernation by telling the kernel about the file
+(@code{resume} argument) and its offset on disk (@code{resume_offset}
+argument). The latter value can be found in the output of the command
+@command{filefrag -e} as the first number right under the
+@code{physical_offset} column header (the second command extracts its
+value directly):
+
+@smallexample
+$ sudo filefrag -e /swapfile
+Filesystem type is: ef53
+File size of /swapfile is 2463842304 (601524 blocks of 4096 bytes)
+ ext: logical_offset: physical_offset: length: expected: flags:
+ 0: 0.. 2047: 92514304.. 92516351: 2048:
+@dots{}
+$ sudo filefrag -e /swapfile | grep '^ *0:' | cut -d: -f3 | cut -d. -f1
+ 92514304
+@end smallexample
+
@node User Accounts
@section User Accounts
--
2.38.1
-----BEGIN PGP SIGNATURE-----

iQIzBAEBCAAdFiEEHpvwBPZcchIQr6TuPezBBfXdI4IFAmOi+SoACgkQPezBBfXd
I4J5dw/+KQ/I7/6FkjAhLf6Lfvc8sw7RSHdf2m5CtaQFN+P1rDkaVww+5XZhyAxE
dVdNlUVe6I5BciPdCR34vC3j+nGsrM8HvZzAwn82et/pVGVFM7UMoiIQVlmPc1Ps
0vHm9kCaNg9Q51n5AQJafYROQzZOYLKlA86z/kbJEwXSYQDD2wunnLSDXMYsOBOj
VWX4mucTS+dYxIdkOMVaYSDYlyMicNjv3X92Iwx7jFICOrQFXxH4ruKUSgJDgkbE
EbGzsqAVGBSh594zomwd2HqQmLUqGSualV386uLekkGhzhX5Ve7WTImUVz37rguf
Y+htLkzvK4c4yB0PDqezwX5wfrXAPqXNmz6gloBQxXK2ck/1tX/kA23MlmHevO7M
CIbyhsyMb8ckcZ/I+3qBOldUxxdLF5kqLm72NeJEJWC7VrA8f7v072pKfBDsHnU1
3v0prP2Pc62L1+T5fAwGEQobQlfI8EGUR5WArYaB4+jmUfggG5KJH/bNYOTyu5bX
dfUpHZ/nZRG1kZCZy4NpKhjUKhak+PDFTU2klNEZElZODMXwJS+BkM/K4MFARgtP
pnfsdlD3546YMJ3WaQP4xVlydzfP3fbgoG418hC64TKazIhkDbu9o1XwFM/DCDJa
YvjYDJrv2pYmX5ieinvItXC7FM3fju2gdIUmJBibiu5+W9bfilQ=
=og8r
-----END PGP SIGNATURE-----


L
L
Ludovic Courtès wrote on 5 Jan 23:01 +0100
Re: bug#59746: [DOCUMENTATION] [PATCH] doc: Introduce using Swap Space for hibernation, with an example.
(name . Ivan Vilata i Balaguer)(address . ivan@selidor.net)(address . 59746-done@debbugs.gnu.org)
87tu141w0s.fsf_-_@gnu.org
Hi,

Ivan Vilata i Balaguer <ivan@selidor.net> skribis:

Toggle quote (23 lines)
> This patch replaces the previous one and enhances it with several minor fixes
> and the missing information related to computing the swap file offset, as
> discussed [in the guix-devel thread][1].
>
> [1]: https://lists.gnu.org/archive/html/guix-devel/2022-12/msg00028.html
>
> Thanks and cheers!
>
> --
> Ivan Vilata i Balaguer -- https://elvil.net/
>
> From e95d79ef8c466e495c730f722b7aefc4d2d5969f Mon Sep 17 00:00:00 2001
> From: Ivan Vilata-i-Balaguer <ivan@selidor.net>
> Date: Wed, 21 Dec 2022 13:08:48 +0100
> Subject: [PATCH] doc: Introduce using swap space for hibernation, with
> examples.
>
> * doc/guix.texi (Swap Space): Add a concise introduction to hibernation and
> specifying a swap space to the kernel to make resume work. Mention space
> requirements and the need of an offset for swap files. Include a trivial
> example on how to set up a mapped swap volume for hibernation and another one
> for a swap file, including how to compute the file offset.

Very nice! Applied with the tweaks below.

Thanks,
Ludo’.
Toggle diff (40 lines)
diff --git a/doc/guix.texi b/doc/guix.texi
index 9a74ae64d6..293c3016aa 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -17109,14 +17109,18 @@ should consider ease of use when deciding between them. Partitions are
allocated at disk formatting time (logical volumes notwithstanding),
whereas files can be allocated and deallocated at any time.
-A swap space is also required in order to hibernate a system using the
-Linux kernel. Hibernation (also called suspend to disk) uses at most
-half the size of the RAM in the configured swap space. The kernel needs
-to know about the swap space to be used to resume from hibernation on
-boot (via a kernel argument). When using a swap file, its offset in the
-device holding it also needs to be given to the kernel, but that value
-has to be updated if the file is initialized again as swap (e.g. because
-its size was changed).
+@cindex hibernation
+@cindex suspend to disk
+Swap space is also required to put the system into @dfn{hibernation}
+(also called @dfn{suspend to disk}), whereby memory is dumped to swap
+before shutdown so it can be restored when the machine is eventually
+restarted. Hibernation uses at most half the size of the RAM in the
+configured swap space. The Linux kernel needs to know about the swap
+space to be used to resume from hibernation on boot (@i{via} a kernel
+argument). When using a swap file, its offset in the device holding it
+also needs to be given to the kernel; that value has to be updated if
+the file is initialized again as swap---e.g., because its size was
+changed.
Note that swap space is not zeroed on shutdown, so sensitive data (such
as passwords) may linger on it if it was paged out. As such, you should
@@ -17215,7 +17219,7 @@ select the file system in an elegant fashion!
%default-kernel-arguments))
@end lisp
-The previous snippet of an @code{operating-system} declaration enables
+The above snippet of an @code{operating-system} declaration enables
the mapped device @file{/dev/mapper/my-swap} (which may be part of an
encrypted device) as swap space, and tells the kernel to use it for
hibernation via the @code{resume} kernel argument
Closed
?