01/02: doc: Document encrypted root partitions.

[Ludovic Courtès]

civodul pushed a commit to branch master
in repository guix.

commit 13fb1bd94e77ca231faaae25e8c9e3c4bde1b0f2
Author: Ludovic Courtès <address@hidden>
Date:   Thu Nov 24 23:03:04 2016 +0100

    doc: Document encrypted root partitions.
    
    This is a followup to f7f292d359e0eb77617f4ecf6b3164f868ec1784.
    
    * doc/guix.texi (Preparing for Installation): Give commands for
    encrypted root installation.
    (Proceeding with the Installation): Add item about mapped devices.
    (File Systems): Mention that 'dependencies' can list <mapped-device>
    objects.
    * gnu/system/examples/desktop.tmpl (mapped-devices): New field.
    (file-systems): Add 'dependencies' field.
---
 doc/guix.texi                    |   48 ++++++++++++++++++++++----------------
 gnu/system/examples/desktop.tmpl |   15 ++++++++++--
 2 files changed, 41 insertions(+), 22 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 4d9c107..e488c5a 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -6665,27 +6665,26 @@ partition lives at @file{/dev/sda1}, a file system with 
the label
 mkfs.ext4 -L my-root /dev/sda1
 @end example
 
address@hidden FIXME: Uncomment this once GRUB fully supports encrypted roots.
address@hidden A typical command sequence may be:
address@hidden
address@hidden @example
address@hidden # fdisk /dev/sdX
address@hidden @dots{} Create partitions address@hidden
address@hidden # cryptsetup luksFormat /dev/sdX1
address@hidden # cryptsetup open --type luks /dev/sdX1 my-partition
address@hidden # mkfs.ext4 -L my-root /dev/mapper/my-partition
address@hidden @end example
-
-In addition to e2fsprogs, the suite of tools to manipulate
-ext2/ext3/ext4 file systems, the installation image includes
-Cryptsetup/LUKS for disk encryption.
address@hidden encrypted disk
+If you are instead planning to encrypt the root partition, you can use
+the Cryptsetup/LUKS utilities to do that (see @inlinefmtifelse{html,
address@hidden://linux.die.net/man/8/cryptsetup, @code{man cryptsetup}},
address@hidden cryptsetup}} for more information.)  Assuming you want to
+store the root partition on @file{/dev/sda1}, the command sequence would
+be along these lines:
+
address@hidden
+cryptsetup luksFormat /dev/sda1
+cryptsetup open --type luks /dev/sda1 my-partition
+mkfs.ext4 -L my-root /dev/mapper/my-partition
address@hidden example
 
 Once that is done, mount the target root partition under @file{/mnt}
-with a command like (again, assuming @file{/dev/sda1} is the root
-partition):
+with a command like (again, assuming @code{my-root} is the label of the
+root partition):
 
 @example
-mount /dev/sda1 /mnt
+mount LABEL=my-root /mnt
 @end example
 
 Finally, if you plan to use one or more swap partitions (@pxref{Memory
@@ -6748,6 +6747,10 @@ Be sure that your partition labels match the value of 
their respective
 @code{device} fields in your @code{file-system} configuration, assuming
 your @code{file-system} configuration sets the value of @code{title} to
 @code{'label}.
+
address@hidden
+If there are encrypted or RAID partitions, make sure to add a
address@hidden field to describe them (@pxref{Mapped Devices}).
 @end itemize
 
 Once you are done preparing the configuration file, the new system must
@@ -6992,7 +6995,9 @@ desired configuration.  In particular, notice how we use 
@code{inherit}
 to create a new configuration which has the same values as the old
 configuration, but with a few modifications.
 
-The configuration for a typical ``desktop'' usage, with the X11 display
address@hidden encrypted disk
+The configuration for a typical ``desktop'' usage, with an encrypted
+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:
@@ -7317,13 +7322,16 @@ errors before being mounted.
 When true, the mount point is created if it does not exist yet.
 
 @item @code{dependencies} (default: @code{'()})
-This is a list of @code{<file-system>} objects representing file systems
-that must be mounted before (and unmounted after) this one.
+This is a list of @code{<file-system>} or @code{<mapped-device>} objects
+representing file systems that must be mounted or mapped devices that
+must be opened before (and unmounted or closed after) this one.
 
 As an example, consider a hierarchy of mounts: @file{/sys/fs/cgroup} is
 a dependency of @file{/sys/fs/cgroup/cpu} and
 @file{/sys/fs/cgroup/memory}.
 
+Another example is a file system that depends on a mapped device, for
+example for an encrypted partition (@pxref{Mapped Devices}).
 @end table
 @end deftp
 
diff --git a/gnu/system/examples/desktop.tmpl b/gnu/system/examples/desktop.tmpl
index 2fcf90f..82687e7 100644
--- a/gnu/system/examples/desktop.tmpl
+++ b/gnu/system/examples/desktop.tmpl
@@ -1,5 +1,6 @@
 ;; This is an operating system configuration template
-;; for a "desktop" setup with GNOME and Xfce.
+;; for a "desktop" setup with GNOME and Xfce where the
+;; root partition is encrypted with LUKS.
 
 (use-modules (gnu) (gnu system nss))
 (use-service-modules desktop)
@@ -13,11 +14,21 @@
   ;; Assuming /dev/sdX is the target hard disk, and "my-root"
   ;; is the label of the target root file system.
   (bootloader (grub-configuration (device "/dev/sdX")))
+
+  ;; Specify a mapped device for the encrypted root partition.
+  ;; The UUID is that returned by 'cryptsetup luksUUID'.
+  (mapped-devices
+   (list (mapped-device
+          (source (uuid "12345678-1234-1234-1234-123456789abc"))
+          (target "the-root-device")
+          (type luks-device-mapping))))
+
   (file-systems (cons (file-system
                         (device "my-root")
                         (title 'label)
                         (mount-point "/")
-                        (type "ext4"))
+                        (type "ext4")
+                        (dependencies mapped-devices))
                       %base-file-systems))
 
   (users (cons (user-account