guix_mirror_bot pushed a commit to branch master
in repository guix.
commit f333fb810d0ef5033db217d2bf12c06646558c70
Author: Hugo Buddelmeijer <[email protected]>
AuthorDate: Tue Feb 17 20:04:06 2026 +0100
doc: Improve raid-device-mapping documentation.
* doc/guix.texi (Mapped Devices): Move examples into the mapping defvars.
Add how to load kernel modules for raid. Add RAID cindex.
Change-Id: If2d3f3c48940d2428b36bdd85d31c8288db35f3b
Signed-off-by: Ludovic Courtès <[email protected]>
Modified-by: Ludovic Courtès <[email protected]>
Merges: #6512
---
doc/guix.texi | 58 +++++++++++++++++++++++++++++++++++++++-------------------
1 file changed, 39 insertions(+), 19 deletions(-)
diff --git a/doc/guix.texi b/doc/guix.texi
index d52be59a1a..0a6020220c 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -18968,7 +18968,7 @@ RAID devices are obtained by @dfn{assembling} several
other devices, such
as hard disks or partitions, into a new one that behaves as one partition.
Mapped devices are declared using the @code{mapped-device} form,
-defined as follows; for examples, see below.
+defined as follows.
@deftp {Data Type} mapped-device
Objects of this type represent device mappings that will be made when
@@ -19064,23 +19064,6 @@ options, along with @option{--allow-discards}:
@end lisp
@end table
-@end defvar
-
-@defvar raid-device-mapping
-This defines a RAID device, which is assembled using the @code{mdadm}
-command from the package with the same name. It requires a Linux kernel
-module for the appropriate RAID level to be loaded, such as @code{raid456}
-for RAID-4, RAID-5 or RAID-6, or @code{raid10} for RAID-10.
-@end defvar
-
-@cindex LVM, logical volume manager
-@defvar lvm-device-mapping
-This defines one or more logical volumes for the Linux
-@uref{https://www.sourceware.org/lvm2/, Logical Volume Manager (LVM)}.
-The volume group is activated by the @command{vgchange} command from the
-@code{lvm2} package.
-@end defvar
-
@cindex disk encryption
@cindex LUKS
The following example specifies a mapping from @file{/dev/sda3} to
@@ -19123,6 +19106,23 @@ swap file is encrypted because the entire device is
encrypted.
@xref{Swap Space}, or @xref{Preparing for Installation,,Disk
Partitioning}, for an example.
+
+@end defvar
+
+@defvar raid-device-mapping
+@cindex RAID
+This defines a RAID device, which is assembled using the @code{mdadm}
+command from the package with the same name. It requires a Linux kernel
+module for the appropriate RAID level to be loaded, such as @code{raid1} for
+RAID-1 (mirroring), @code{raid456} for RAID-4, RAID-5 or RAID-6, or
+@code{raid10} for RAID-10 (@pxref{Initial RAM Disk}).
+
+For example, RAID-1 (mirroring) support can be added with:
+
+@lisp
+(initrd-modules (cons* "raid1" %base-initrd-modules))
+@end lisp
+
A RAID device formed of the partitions @file{/dev/sda1} and @file{/dev/sdb1}
may be declared as follows:
@@ -19137,7 +19137,22 @@ The @file{/dev/md0} device can then be used as the
@code{device} of a
@code{file-system} declaration (@pxref{File Systems}).
Note that the RAID level need not be given; it is chosen during the
initial creation and formatting of the RAID device and is determined
-automatically later.
+automatically later, assuming the correct Linux modules have been loaded.
+
+Not having the right kernel modules loaded might result in an error message
+like this at boot:
+
+@example
+mdadm: failed to RUN_ARRAY /dev/md0: Invalid argument
+@end example
+@end defvar
+
+@cindex LVM, logical volume manager
+@defvar lvm-device-mapping
+This defines one or more logical volumes for the Linux
+@uref{https://www.sourceware.org/lvm2/, Logical Volume Manager (LVM)}.
+The volume group is activated by the @command{vgchange} command from the
+@code{lvm2} package.
LVM logical volumes ``alpha'' and ``beta'' from volume group ``vg0'' can
be declared as follows:
@@ -19152,6 +19167,7 @@ be declared as follows:
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}).
+@end defvar
@node Swap Space
@section Swap Space
@@ -47267,6 +47283,10 @@ file system, you would write:
(initrd-modules (cons "megaraid_sas" %base-initrd-modules)))
@end lisp
+Other useful kernel modules include those necessary for a
+@code{raid-device-mapping}, e.g. @code{raid1}, @code{raid456} and
+@code{raid10} (@pxref{Mapped Devices}).
+
@defvar %base-initrd-modules
This is the list of kernel modules included in the initrd by default.
@end defvar
