From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mp0 ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by ms0.migadu.com with LMTPS id GAZLD/jCkmFIWwEAgWs5BA (envelope-from ) for ; Mon, 15 Nov 2021 21:28:40 +0100 Received: from aspmx1.migadu.com ([2001:41d0:8:6d80::]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits)) by mp0 with LMTPS id ADgIC/jCkmFGegAA1q6Kng (envelope-from ) for ; Mon, 15 Nov 2021 20:28:40 +0000 Received: from lists.gnu.org (lists.gnu.org [209.51.188.17]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by aspmx1.migadu.com (Postfix) with ESMTPS id C98E314576 for ; Mon, 15 Nov 2021 21:28:39 +0100 (CET) Received: from localhost ([::1]:58564 helo=lists1p.gnu.org) by lists.gnu.org with esmtp (Exim 4.90_1) (envelope-from ) id 1mmial-0008F6-1q for larch@yhetil.org; Mon, 15 Nov 2021 15:28:39 -0500 Received: from eggs.gnu.org ([209.51.188.92]:56598) by lists.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_256_GCM_SHA384:256) (Exim 4.90_1) (envelope-from ) id 1mmiaD-0007hK-IT for guix-patches@gnu.org; Mon, 15 Nov 2021 15:28:05 -0500 Received: from debbugs.gnu.org ([209.51.188.43]:44745) by eggs.gnu.org with esmtps (TLS1.2:ECDHE_RSA_AES_128_GCM_SHA256:128) (Exim 4.90_1) (envelope-from ) id 1mmiaD-00037U-AT for guix-patches@gnu.org; Mon, 15 Nov 2021 15:28:05 -0500 Received: from Debian-debbugs by debbugs.gnu.org with local (Exim 4.84_2) (envelope-from ) id 1mmiaC-0008WE-6Z for guix-patches@gnu.org; Mon, 15 Nov 2021 15:28:04 -0500 X-Loop: help-debbugs@gnu.org Subject: [bug#51346] [PATCH v3 5/5] doc: Add new Swap Space section. Resent-From: Josselin Poiret Original-Sender: "Debbugs-submit" Resent-CC: guix-patches@gnu.org Resent-Date: Mon, 15 Nov 2021 20:28:04 +0000 Resent-Message-ID: Resent-Sender: help-debbugs@gnu.org X-GNU-PR-Message: followup 51346 X-GNU-PR-Package: guix-patches X-GNU-PR-Keywords: patch To: Ludovic =?UTF-8?Q?Court=C3=A8s?= Cc: Josselin Poiret , Tobias Geerinckx-Rice , 51346@debbugs.gnu.org Received: via spool by 51346-submit@debbugs.gnu.org id=B51346.163700804332648 (code B ref 51346); Mon, 15 Nov 2021 20:28:04 +0000 Received: (at 51346) by debbugs.gnu.org; 15 Nov 2021 20:27:23 +0000 Received: from localhost ([127.0.0.1]:56284 helo=debbugs.gnu.org) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mmiZW-0008UQ-O6 for submit@debbugs.gnu.org; Mon, 15 Nov 2021 15:27:23 -0500 Received: from jpoiret.xyz ([206.189.101.64]:35210) by debbugs.gnu.org with esmtp (Exim 4.84_2) (envelope-from ) id 1mmiZT-0008U1-6O for 51346@debbugs.gnu.org; Mon, 15 Nov 2021 15:27:19 -0500 Received: from authenticated-user (jpoiret.xyz [206.189.101.64]) by jpoiret.xyz (Postfix) with ESMTPA id 423E4184B88; Mon, 15 Nov 2021 20:27:18 +0000 (UTC) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=jpoiret.xyz; s=dkim; t=1637008038; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding: in-reply-to:in-reply-to:references:references; bh=geye6H3GvUKPXTskGMybTA9Uv/BH0Wc7kK/Xdw2ztxA=; b=fMcZsUabOTGDHBpxNV7/pd4qYIMz6//7aRpebDejX9VVCH9MQr4mqOfwRJ6jj+VEia/4ov absvmeX47RKtevDAYKdehEZZgISyLQi06NntJmzhOe4v/9TJVkz33tiZc0X7rCnOcDoP91 pJ+Ti47cnhGxIO5ggKLU+6M94aaqLe9Detxg15bgnNJ7TE7Srhan1/0Og+iQopEV3kdu7G +lNwemhSuGtJbxLkxw18oPxMNrSg0odh43PnBrQZrd8r7q/MibTvyvSajoi2BNspPQU0DJ uyFkN8in0b6YUck83NYNnOBDvP/4khRKsKiEiJuQdDIM3ydp98JQHLXfU42U8g== Date: Mon, 15 Nov 2021 20:26:31 +0000 Message-Id: <20211115202631.6032-6-dev@jpoiret.xyz> In-Reply-To: <20211115202631.6032-1-dev@jpoiret.xyz> References: <87y25p65on.fsf_-_@gnu.org> <20211115202631.6032-1-dev@jpoiret.xyz> MIME-Version: 1.0 Content-Transfer-Encoding: 8bit X-Spamd-Bar: / X-BeenThere: debbugs-submit@debbugs.gnu.org X-Mailman-Version: 2.1.18 Precedence: list X-BeenThere: guix-patches@gnu.org List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: guix-patches-bounces+larch=yhetil.org@gnu.org Sender: "Guix-patches" Reply-to: Josselin Poiret X-ACL-Warn: , Josselin Poiret via Guix-patches From: Josselin Poiret via Guix-patches via X-Migadu-Flow: FLOW_IN ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=yhetil.org; s=key1; t=1637008119; h=from:from:sender:sender:reply-to:reply-to:subject:subject:date:date: message-id:message-id:to:to:cc:cc:mime-version:mime-version: content-transfer-encoding:content-transfer-encoding:resent-cc: resent-from:resent-sender:resent-message-id:in-reply-to:in-reply-to: references:references:list-id:list-help:list-unsubscribe: list-subscribe:list-post:dkim-signature; bh=geye6H3GvUKPXTskGMybTA9Uv/BH0Wc7kK/Xdw2ztxA=; b=jUF7iXHSWkc5khMVqE7b+ptLmIL1ZzzTfredOzlYa/45zJzBE2duOjssp1pTAlAaEW4+HR I8iaqYomEooZJ50tEY/IZLJkKiMYEA+sjn+aOYPpt1BfwukZN35DxaWUPBGLBQlShOqmLQ LCjpearg/xlivPSUGH6EErO0cBKiCIqwhxAkrsIzaqfuIcn5ZbVBAtWq6VHRhiVwc7rbmU V2yOxp5h3bTSNOIOVBhJoQmEotNmCbNFnHnnVTLJCS0g7O5WpKpsfovK9MY8UYfBBqyR+e VJ0Jdq7MGoT9aplK4KLuvy01RNoJ6j8laoymh/1x1wWTnG939P9vpGo9ObsIsQ== ARC-Seal: i=1; s=key1; d=yhetil.org; t=1637008119; a=rsa-sha256; cv=none; b=JEc86ttJMjp9VKZT7ihoHGY8xnEj78Nc+YZQwuecQCeUzkonYsKt1ewF5bRZBtwgbfI5a4 myPw2u74pUHZQe7ziVTQo+lNOiMuj+u4n2evOts/kmPQa5rVOhMJC5udYRDpNnHliDX/6Q Q7DHvCgxO4FPKT6+JwHtJWPqWj1VMrH9z5Ido9cPqsMrn0w4y0eldKfTgdXx8Z/9gaIliL OOl+fpqc5zwNumG8++ujRkykyhAzRy1ptsKmjqrD5igPPxA1ta2wr1pjCz9z1MP/q2JQny D1/U3JxqtqPS8RBVwObD5gAiBxBnjsnreOhN9VQa5lukQuLz0FMwZ6KC6hZ+4Q== ARC-Authentication-Results: i=1; aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=jpoiret.xyz header.s=dkim header.b=fMcZsUab; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of guix-patches-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=guix-patches-bounces@gnu.org X-Migadu-Spam-Score: 0.66 Authentication-Results: aspmx1.migadu.com; dkim=fail ("headers rsa verify failed") header.d=jpoiret.xyz header.s=dkim header.b=fMcZsUab; dmarc=pass (policy=none) header.from=gnu.org; spf=pass (aspmx1.migadu.com: domain of guix-patches-bounces@gnu.org designates 209.51.188.17 as permitted sender) smtp.mailfrom=guix-patches-bounces@gnu.org X-Migadu-Queue-Id: C98E314576 X-Spam-Score: 0.66 X-Migadu-Scanner: scn1.migadu.com X-TUID: Kychke5+gI7n * doc/guix.texi (operating-system Reference): Update swap-devices. * doc/guix.texi (Swap Space): Add it. * gnu/system/examples/desktop.tmpl: Add swap-devices example. --- doc/guix.texi | 147 +++++++++++++++++++++++-------- gnu/system/examples/desktop.tmpl | 7 +- 2 files changed, 116 insertions(+), 38 deletions(-) diff --git a/doc/guix.texi b/doc/guix.texi index 95d286a836..6838a3691f 100644 --- a/doc/guix.texi +++ b/doc/guix.texi @@ -320,6 +320,7 @@ System Configuration * operating-system Reference:: Detail of operating-system declarations. * File Systems:: Configuring file system mounts. * Mapped Devices:: Block device extra processing. +* Swap Space:: Backing RAM with disk space. * User Accounts:: Specifying user accounts. * Keyboard Layout:: How the system interprets key strokes. * Locales:: Language and cultural convention settings. @@ -2527,10 +2528,9 @@ system relative to this path. If you have opted for @file{/boot/efi} as an EFI mount point for example, mount it at @file{/mnt/boot/efi} now so it is found by @code{guix system init} afterwards. -Finally, if you plan to use one or more swap partitions (@pxref{Memory -Concepts, swap space,, libc, The GNU C Library Reference Manual}), make -sure to initialize them with @command{mkswap}. Assuming you have one -swap partition on @file{/dev/sda3}, you would run: +Finally, if you plan to use one or more swap partitions (@pxref{Swap +Space}), make sure to initialize them with @command{mkswap}. Assuming +you have one swap partition on @file{/dev/sda3}, you would run: @example mkswap /dev/sda3 @@ -14012,6 +14012,7 @@ instance to support new system services. * operating-system Reference:: Detail of operating-system declarations. * File Systems:: Configuring file system mounts. * Mapped Devices:: Block device extra processing. +* Swap Space:: Backing RAM with disk space. * User Accounts:: Specifying user accounts. * Keyboard Layout:: How the system interprets key strokes. * Locales:: Language and cultural convention settings. @@ -14180,7 +14181,7 @@ configuration, but with a few modifications. @cindex encrypted disk The configuration for a typical ``desktop'' usage, with an encrypted -root partition, the X11 display +root partition, a swap file on the root partition, the X11 display server, GNOME and Xfce (users can choose which of these desktop environments to use at the log-in screen by pressing @kbd{F1}), network management, power management, and more, would look like this: @@ -14378,38 +14379,9 @@ A list of mapped devices. @xref{Mapped Devices}. @item @code{file-systems} A list of file systems. @xref{File Systems}. -@cindex swap devices -@cindex swap space @item @code{swap-devices} (default: @code{'()}) -A list of UUIDs, file system labels, or strings identifying devices or -files to be used for ``swap -space'' (@pxref{Memory Concepts,,, libc, The GNU C Library Reference -Manual}). Here are some examples: - -@table @code -@item (list (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb")) -Use the swap partition with the given UUID@. You can learn the UUID of a -Linux swap partition by running @command{swaplabel @var{device}}, where -@var{device} is the @file{/dev} file name of that partition. - -@item (list (file-system-label "swap")) -Use the partition with label @code{swap}. Again, the -@command{swaplabel} command allows you to view and change the label of a -Linux swap partition. - -@item (list "/swapfile") -Use the file @file{/swapfile} as swap space. - -@item (list "/dev/sda3" "/dev/sdb2") -Use the @file{/dev/sda3} and @file{/dev/sdb2} partitions as swap space. -We recommend referring to swap devices by UUIDs or labels as shown above -instead. -@end table - -It is possible to specify a swap file in a file system on a mapped -device (under @file{/dev/mapper}), provided that the necessary device -mapping and file system are also specified. @xref{Mapped Devices} and -@ref{File Systems}. +@cindex swap devices +A list of swap spaces. @xref{Swap Space}. @item @code{users} (default: @code{%base-user-accounts}) @itemx @code{groups} (default: @code{%base-groups}) @@ -14999,7 +14971,8 @@ It is also desirable to encrypt swap space, since swap space may contain sensitive data. One way to accomplish that is to use a swap file in a file system on a device mapped via LUKS encryption. In this way, the swap file is encrypted because the entire device is encrypted. -@xref{Preparing for Installation,,Disk Partitioning}, for an example. +@xref{Swap Space}, or @xref{Preparing for Installation,,Disk +Partitioning}, for an example. A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1} may be declared as follows: @@ -15031,6 +15004,106 @@ Devices @file{/dev/mapper/vg0-alpha} and @file{/dev/mapper/vg0-beta} can then be used as the @code{device} of a @code{file-system} declaration (@pxref{File Systems}). +@node Swap Space +@section Swap Space +@cindex swap space + +Swap space, as it is commonly called, is a disk area specifically +designated for paging: the process in charge of memory management +(the Linux kernel or Hurd's default pager) can decide that some memory +pages stored in RAM which belong to a running program but are unused +should be stored on disk instead. It unloads those from the RAM, +freeing up precious fast memory, and writes them to the swap space. If +the program tries to access that very page, the memory management +process loads it back into memory for the program to use. + +A common misconception about swap is that it is only useful when small +amounts of RAM are available to the system. However, it should be noted +that kernels often use all available RAM for disk access caching to make +I/O faster, and thus paging out unused portions of program memory will +expand the RAM available for such caching. + +For a more detailed description of how memory is managed from the +viewpoint of a monolithic kernel, @xref{Memory +Concepts,,, libc, The GNU C Library Reference Manual}. + +The Linux kernel has support for swap partitions and swap files: the +former uses a whole disk partition for paging, whereas the second uses a +file on a file system for that (the file system driver needs to support +it). On a comparable setup, both have the same performance, so one +should consider ease of use when deciding between them. Partitions are +``simpler'' and do not need file system support, but need to be +allocated at disk formatting time (logical volumes notwithstanding), +whereas files can be allocated and deallocated at any time. + +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 +Devices}). + +@deftp {Data Type} swap-space +Objects of this type represent swap spaces. They contain the following +members: + +@table @asis +@item @code{target} +The device or file to use, either a UUID, a @code{file-system-label} or +a string, as in the definition of a @code{file-system} (@pxref{File +Systems}). + +@item @code{dependencies} (default: @code{'()}) +A list of @code{file-system} or @code{mapped-device} objects, upon which +the availability of the space depends. Note that just like for +@code{file-system} objects, dependencies which are needed for boot and +mounted in early userspace are not managed by the Shepherd, and so +automatically filtered out for you. + +@item @code{priority} (default: @code{#f}) +Only supported by the Linux kernel. Either @code{#f} to disable swap +priority, or an integer between 0 and 32767. The kernel will first use +swap spaces of higher priority when paging, and use same priority spaces +on a round-robin basis. The kernel will use swap spaces without a set +priority after prioritized spaces, and in the order that they appeared in +(not round-robin). + +@item @code{discard?} (default: @code{#f}) +Only supported by the Linux kernel. When true, the kernel will notify +the disk controller of discarded pages, for example with the TRIM +operation on Solid State Drives. + +@end table +@end deftp + +Here are some examples: + +@lisp +(swap-space (target (uuid "4dab5feb-d176-45de-b287-9b0a6e4c01cb"))) +@end lisp + +Use the swap partition with the given UUID@. You can learn the UUID of a +Linux swap partition by running @command{swaplabel @var{device}}, where +@var{device} is the @file{/dev} file name of that partition. + +@lisp +(swap-space + (target (file-system-label "swap")) + (dependencies (list lvm-device))) +@end lisp + +Use the partition with label @code{swap}, which can be found after the +@var{lvm-device} mapped device has been opened. Again, the +@command{swaplabel} command allows you to view and change the label of a +Linux swap partition. + +@lisp +(swap-space + (target "/btrfs/swapfile") + (dependencies (list btrfs-fs))) +@end lisp + +Use the file @file{/btrfs/swapfile} as swap space, which is present on the +@var{btrfs-fs} filesystem. + @node User Accounts @section User Accounts diff --git a/gnu/system/examples/desktop.tmpl b/gnu/system/examples/desktop.tmpl index c928008c92..6df53844b1 100644 --- a/gnu/system/examples/desktop.tmpl +++ b/gnu/system/examples/desktop.tmpl @@ -1,6 +1,6 @@ ;; This is an operating system configuration template ;; for a "desktop" setup with GNOME and Xfce where the -;; root partition is encrypted with LUKS. +;; root partition is encrypted with LUKS, and a swap file. (use-modules (gnu) (gnu system nss)) (use-service-modules desktop xorg) @@ -42,6 +42,11 @@ (type "vfat"))) %base-file-systems)) + ;; Specify a swap file for the system, which resides on the + ;; root file system. + (swap-devices (list (swap-space + (target "/swapfile")))) + ;; Create user `bob' with `alice' as its initial password. (users (cons (user-account (name "bob") -- 2.33.1