Review of installation manual draft

Review of installation manual draft

[Petter]

Hi,

During the last week on IRC a few of us have been putting together a 
proposal for updating the GuixSD installation instructions in the 
manual. It was initially intended to be a guide for how to install 
GuixSD with encrypted root to the Libreboot site; but as the steps are 
generic, and the GuixSD manual doesn't address this we thought we'd make 
a proposal here instead. The instructions for encrypted root are quite 
detailed, and to try and keep the entire installation manual in the same 
vein, other steps have been redone with detailed, step for step, 
instructions. Which will hopefully make it easier for less experienced 
users to get GuixSD up and running, with or without encryption.

First of all we'd like to know if there are any major issues/objections 
with this proposal, issues that would result in restructuring, or even 
that we drop it altogether. Better we know now before going into polish 
mode. We're also very interested in comments and suggestions to make it 
better of course.

Current issues:
  - typing in the mapped-devices field perfectly is error-prone, maybe 
put a commented out mapped-devices field in the example configuration 
instead and the manual will say to enable it for users opting for 
encryption.
  - it would be nice to print a list of available layouts for the 
loadkeys command. Please let me know if you know how to do this.
  - maybe elaborate on how to use cfdisk and/or similar tools

Ideas:
  - maybe it would be good to use a dedicated bare-bones config for (1) 
fully encrypted, (2) encrypted root without /boot, (3) encrypted /home, 
(4) unencrypted; to get people up and running quickly, then add desktop 
environment etc. in a post-installation document.

Thanks,
Petter

------------------current draft-------------------------------

7.1.3 Booting the installation image
Once you have successfully booted the image on the USB stick, you should 
end up with a root prompt. Several console TTYs are configured and can 
be used to run commands as root. TTY2 shows this documentation, 
browsable using the Info reader commands (see Help in Info: An 
Introduction).



7.1.3.1 Keyboard
The installation image uses the US Qwerty keyboard layout. To change you 
can use the "loadkeys" command with your preferred layout. Example 
<layout>: "dvorak".
# loadkeys <layout>



7.1.3.2 Network
Run this to see what your network interfaces are called:
# ifconfig -a

To configure the network run this command, substituting 
<network-interface> with the one you want to use. Example 
<network-interface>: "eno1".
# ifconfig <network-interface> up && dhclient <network-interface>

Try to ping a server to see if a connection was established. For 
example, gnu.org.
# ping -c 3 gnu.org

If ping fails with a `ping: unknown host` error, first check if there is 
an issue with your cable. If not, try to restart nscd.
# deco restart nscd





7.1.4 Preparing the disk
First you need to decide if you want encrypted root or not. If you're 
going for unencrypted skip to the next paragraph. For encrypted root you 
need to figure out if you can have /boot encrypted or not. For /boot to 
be encrypted you need boot firmware with an embedded boot loader, such 
as Coreboot/Libreboot. Otherwise you'll need to leave /boot unencrypted, 
in this case create a separate partition for it. 100 MB should be 
enough, make it type "Linux (83)".

Your main partition will be where you install root (/). If you're going 
to install a desktop this partition should be at least 15 GB. Make it 
use the rest of your disk (after potentially making a boot partition) if 
you don't know how large to make it. Make it type "Linux (83)"



7.1.4.1 Disk partitioning
Before proceeding with partitioning you need to be sure about the device 
name of the disk you're installing to. Example "/dev/sda"
For partitioning there are several tools available, cfdisk is one.
# cfdisk /dev/<disk>

If you went for unencrypted we'll refer to your root partition as 
"<your-root-partition>".
If you went for encrypted we'll refer to your encrypted root partition 
as "<your-encrypted-root-partition>". Any separate partition for /boot 
will be referred to as "<your-boot-partition>".
Typical value: "sda1".



7.1.4.2 Disk encryption
Skip this chapter if you're not doing encrypted root.

Encrypt the encrypted partition with LUKS, using your favorite 
cryptsetup invocation, for example:
# cryptsetup -v --cipher serpent-xts-plain64 --key-size 512 --hash 
whirlpool --use-random --verify-passphrase luksFormat 
/dev/<your-encrypted-root-partition>

Open the LUKS partition. You can verify its effect by doing "ls 
/dev/mapper" before and after this command, on success a "guixsd" file 
will appear.
# cryptsetup luksOpen /dev/<your-encrypted-root-partition> guixsd

We'll later refer to your mapped device (f.ex. "mapper/guixsd") as 
"<your-root-partition>".



7.1.4.3 Filesystem and mount
Make a filesystem, f.ex. ext4. For unencrypted root you can use the "-L" 
flag, with a string argument, to create a label for later reference.
# mkfs.ext4 /dev/<your-root-partition>

Mount it under /mnt
# mount /dev/<your-root-partition> /mnt

Run this command to make /gnu/store copy-on-write, such that packages 
added to it during the installation phase will be written to the target 
disk rather than kept in memory.
# deco start cow-store /mnt

Create the /etc on your mounted partition
# mkdir /mnt/etc





7.1.5 Preparing the configuration file
Now we're going to prepare the configuration file. There are two example 
configuration files available in the live image, located in 
/etc/configuration.
"bare-bones.scm" is a minimal configuration with no X11 display server.
"desktop.scm" will install some desktop environments.
Even if you want a desktop eventually you can start with 
"bare-bones.scm"; and once you're able to boot properly add X11 and 
desktop environments etc. to your configuration and reconfigure your 
system. This will save you time if you run into problems and need to 
install GuixSD again.
# cp /etc/configuration/bare-bones.scm /mnt/etc/config.scm

Now we'll open and modify the configuration file. The live image comes 
with two text editors: GNU nano (see GNU nano Manual), and GNU Zile, an 
Emacs clone. Open your configuration file with one of them.
# zile /mnt/etc/config.scm

We'll do the updates in turn from top to bottom. you'll recognize some 
of the crypto steps from earlier, but note that previously we've been 
setting up the partition for the installation. These steps gives 
instructions to be used when booting the system.

Adjust "host-name", "timezone" and "locale" to your wishes. If you're 
going to change locale you should check what is available and exactly 
how it is typed; close the editor or change virtual console 
(Ctrl-Alt-F#), and run the command "locale -a".

Update "device" in the bootloader field to "/dev/<disk>". This will 
instruct the installation to install GRUB to the MBR of your disk. This 
is fine even if you're going to use the boot loader in your boot 
firmware, it will just be unused in this case.



7.1.5.1 Special configuration for encrypted root
Skip this chapter if you're doing unencrypted root.

For encrypted root setups we need to add some lines to the configuration 
with instructions on how do decrypt your partition during boot. Add the 
"mapped-devices" field below to your your operating-system declaration.
(If that last sentence didn't make much sense: Insert the code snippet 
below between the lines (bootloader ...) and (file-systems ...))
Make sure to update the following fields:
"source", the device name of your encrypted partition. Example 
"/dev/sda1"
"target", a name you make up that will appear in /dev/mapper/ after 
decryption. We'll later refer to this as "<target-name>". Example 
"guixsd".
    (mapped-devices (list (mapped-device
      (source "/dev/<your-encrypted-partition>")
      (target "<target-name>")
      (type luks-device-mapping))))

Moving on to the file-systems field, update these two fields:
"device", set this value to "/dev/mapper/<target-name>". Example 
"/dev/mapper/guixsd"
"title", change this value to "'device". (Makes the "device" field be 
interpreted as a file name rather than a partition label name)

*****TODO: Unencrypted /boot*****



7.1.5.2 Special configuration for unencrypted root
Skip this chapter if you're doing encrypted root.

In the file-systems field, update this field:
"device", set this value to the label you made when you created the 
filesystem. Example "my-root"



7.1.5.3 Finishing up the configuration
And finally, update the values in the "users" field.
"name", the username.
"comment", you can set this to the name of the user.
"home-directory", set this to "/home/<username>".

This concludes the updates to the configuration file and the preparation 
for installation.





7.1.6 Installation
What remains now is to actually install the system. First run this 
command to get up to speed with the project's progress since this 
installer was created.
# guix pull

Then run this command to initialize the system based on the 
configuration file you've prepared.
# guix system init /mnt/etc/config.scm /mnt

This will copy all the necessary files, and install GRUB on /dev/<disk>, 
unless you pass the --no-grub option. For more information, see Invoking 
guix system. This command may trigger downloads or builds of missing 
packages, which can take some time.

Once that command has completed—and hopefully succeeded!—you can run 
reboot and boot into the new system. The root password in the new system 
is initially empty; other users’ passwords need to be initialized by 
running the passwd command as root, unless your configuration specifies 
otherwise (see user account passwords).

Join us on #guix on the Freenode IRC network or on guix-devel@gnu.org to 
share your experience—good or not so good.





ADDENDUM #1
Manual steps to boot your fully encrypted system from an embedded GRUB.
Press "c" in GRUB to enter command mode.

First find the partition here which corresponds to your /dev/<disk> from 
earlier. For example "/dev/sda1" on GPT will be "ahci0,gpt1"
# ls

Now decrypt it, <grub-partition> is the partition you found in the 
previous step. Don't use quotes.
# cryptomount <grub-partition>

Load GuixSD's GRUB configuration file
# configfile (crypto0)/boot/grub/grub.cfg





ADDENDUM #2
When you're ready to update the GRUB configuration file in your boot 
firmware you can base them off of these examples. Values to update:
"cryptomount" (there's one in both menu entries).
"--root" flag, to point to "/dev/<your-root-partition>". Example 
"/dev/mapper/guixsd".

menuentry "GuixSD (current)" {
   cryptomount <grub-partition>
   set root=(crypto0)
   set guix_system=/var/guix/profiles/system
   linux  ${guix_system}/kernel/bzImage --root=/dev/<your-root-partition> 
--system=${guix_system} --load=${guix_system}/boot
   initrd ${guix_system}/initrd
}

menuentry "GuixSD fallback" {
   cryptomount <grub-partition>
   configfile (crypto0)/boot/grub/grub.cfg
}

Re: Review of installation manual draft

[Ludovic Courtès]

HI Petter,

Thanks a lot for working on it!  I’m at FOSDEM now but I hope to review
while on the train later today.

It would be easier for me if it were a diff against guix.texi.  Do you
think you could do that?  That would be awesome.  (If not I’ll comment
on what you sent.)

Ludo’.

Re: Review of installation manual draft

[Petter]

Hi Ludo,

Yes, i should be able to do that. I don't know texinfo yet but i'm 
learning it now.

Petter

Re: Review of installation manual draft

[Petter]

[-- Attachment #1: Type: text/plain, Size: 488 bytes --]

Hi Ludo,

Attached is a diff against guix.texi. I'm very new to texinfo so there 
may be some silly mistakes.

Petter

On 2016-01-31 10:28, ludo@gnu.org wrote:
> HI Petter,
> 
> Thanks a lot for working on it!  I’m at FOSDEM now but I hope to review
> while on the train later today.
> 
> It would be easier for me if it were a diff against guix.texi.  Do you
> think you could do that?  That would be awesome.  (If not I’ll comment
> on what you sent.)
> 
> Ludo’.

[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: 0001-Merged-installation-proposal-into-guix.texi.patch --]
[-- Type: text/x-diff; name=0001-Merged-installation-proposal-into-guix.texi.patch, Size: 17501 bytes --]

From 1ce9e2929843150f1ec1f6e265187cfe31f82f61 Mon Sep 17 00:00:00 2001
From: Petter <petter@mykolab.ch>
Date: Fri, 5 Feb 2016 18:33:24 +0100
Subject: [PATCH] Merged installation proposal into guix.texi

---
 doc/guix.texi | 331 +++++++++++++++++++++++++++++++++++++++++++++-------------
 1 file changed, 256 insertions(+), 75 deletions(-)

diff --git a/doc/guix.texi b/doc/guix.texi
index 66ab384..1b8d1d2 100644
--- a/doc/guix.texi
+++ b/doc/guix.texi
@@ -5623,104 +5623,230 @@ Introduction}).  The installation system runs the GPM mouse daemon,
 which allows you to select text with the left mouse button and to paste
 it with the middle button.
 
-To install the system, you would:
+@subsubsection Keyboard
 
-@enumerate
+The installation image uses the US Qwerty keyboard layout. If you want to change it you can use the @command{loadkeys} command with your preferred layout. Example @var{layout}: @samp{dvorak}.
+@example
+loadkeys @var{layout}
+@end example
 
-@item
-Configure the network, by running:
+@subsubsection Network
 
+Run the following command see what your network interfaces are called. Wired interfaces often start with @samp{e}, like @samp{eno1}. Wireless interfaces often start with @samp{w}, like @samp{w1p2s0}.
 @example
-ifconfig eno1 up && dhclient eno1
+ifconfig -a
 @end example
 
-to get an automatically assigned IP address from the wired
-network interface controller@footnote{
-@c http://cgit.freedesktop.org/systemd/systemd/tree/src/udev/udev-builtin-net_id.c#n20
-The name @code{eno1} is for the first on-board Ethernet controller.  The
-interface name for an Ethernet controller that is in the first slot of
-the first PCI bus, for instance, would be @code{enp1s0}.  Use
-@command{ifconfig -a} to list all the available network interfaces.},
-or using the @command{ifconfig} command.
+@ftable @asis
+@item Wired connection
+To configure a wired network run the following command, substituting @var{network-interface} with the wired interface you want to use.
+@example
+ifconfig @var{network-interface} up
+@end example
 
-The system automatically loads drivers for your network interface
-controllers.
+@item Wireless connection
+To configure a wireless network create a configuration file and add a network stanza to it. Create and open a configuration file (location is not important)
+@example
+zile wpa_supplicant.conf
+@end example
 
-Setting up network access is almost always a requirement because the
-image does not contain all the software and tools that may be needed.
+Add the following stanza to it and update with actual ssid and password for the network you're connecting to:
+@example
+network=@{
+    ssid=@var{network_name}
+    key_mgmt=WPA-PSK
+    psk=@var{network_password}
+@}
+@end example
+    
+Start the wireless service and run it in the background with the following command. Substitute @var{network-interface} with the one you want to use.
+@example
+wpa_supplicant -c wpa_supplicant.conf -i @var{network-interface} -B
+@end example
+@end ftable
 
-@item
-Unless this has already been done, you must partition, and then format
-the target partition.
-
-Preferably, assign partitions a label so that you can easily and
-reliably refer to them in @code{file-system} declarations (@pxref{File
-Systems}).  This is typically done using the @code{-L} option of
-@command{mkfs.ext4} and related commands.
-
-Be sure that your partition labels match the value of their respective
-@code{device} fields in your @code{file-system} configuration, if your
-@code{file-system} configuration sets the value of @code{title} to
-@code{'label}, as do the example configurations found on the USB
-installation image under @file{/etc/configuration} (@pxref{Using the
-Configuration System}).
-
-@c FIXME: Uncomment this once GRUB fully supports encrypted roots.
-@c A typical command sequence may be:
-@c
-@c @example
-@c # fdisk /dev/sdX
-@c @dots{} Create partitions etc.@dots{}
-@c # cryptsetup luksFormat /dev/sdX1
-@c # cryptsetup open --type luks /dev/sdX1 my-partition
-@c # mkfs.ext4 -L my-root /dev/mapper/my-partition
-@c @end example
-
-The installation image includes Parted (@pxref{Overview,,, parted, GNU
-Parted User Manual}), @command{fdisk}, Cryptsetup/LUKS for disk
-encryption, and e2fsprogs, the suite of tools to manipulate
-ext2/ext3/ext4 file systems.
+Acquire an IP address. If you're on a network with DHCP you can run
+@example
+dhclient @var{network-interface}
+@end example
 
-@item
-Once that is done, mount the target root partition under @file{/mnt}.
+Try to ping a server to see if your network is up and running.
+@example
+ping -c 3 gnu.org
+@end example
 
-@item
-Lastly, run @code{herd start cow-store /mnt}.
+If ping fails with a @samp{ping: unknown host} error you can try restarting nscd.
+@example
+deco restart nscd
+@end example
 
-This will make @file{/gnu/store} copy-on-write, such that packages added
-to it during the installation phase will be written to the target disk
-rather than kept in memory.
+The system automatically loads drivers for your network interface controllers.
 
-@end enumerate
+Setting up network access is almost always a requirement because the image does not contain all the software and tools that may be needed. 
+
+@subsubsection Disk partitioning
+
+First you need to decide if you want encrypted root or not. If you're going for unencrypted skip to the next paragraph. For encrypted root you need to figure out if you want/can have /boot encrypted or not. For /boot to be encrypted you need boot firmware with an embedded boot loader, such as Coreboot/Libreboot. Otherwise you'll need to leave /boot unencrypted, in this case create a separate partition for it. 30 MB should be enough, make it type "Linux (83)". Note that the kernel and initramfs do not reside in /boot like on most other systems. On GuixSD they're stored in /gnu/store.
+
+Your main partition will be where you install root, /. If you're going to install a desktop this partition should be at least 15 GB. Make it use the rest of your disk (after potentially making a boot partition) if you don't know how large to make it. Make it type "Linux (83)"
+
+For partitioning there are several tools available, @command{cfdisk} is one. Run it and set up your disk with the partition layout you want
+@example
+cfdisk
+@end example
+
+@subsubsection Encrypted root
+
+@emph{Skip this chapter if you're not doing encrypted root.}
 
+Encrypt the partition you've set off for root with LUKS, using your favorite cryptsetup invocation. For example the command below. Substitute @var{your-encrypted-root-partition} with the corresponding value on your system, typically @samp{/dev/sda1}.
+@example
+cryptsetup -v --cipher serpent-xts-plain64 --key-size 512 --hash whirlpool --use-random --verify-passphrase luksFormat @var{your-encrypted-root-partition}
+@end example
+
+Open the LUKS partition with the command below. The last argument is the name we'll assume for the remainder of this installation. Leave it as it is unless you really want to get out of touch with this document. Its lifetime is limited to the installation process anyway. If you want to use a different name for your installed system you'll specify this later. You can verify that it works by doing @code{ls /dev/mapper} before and after the command below. On success a @samp{guixsd} file will appear.
+@example
+cryptsetup luksOpen @var{your-encrypted-root-partition} guixsd
+@end example
+
+Make a filesystem, f.ex. ext4 like below.
+@example
+mkfs.ext4 /dev/mapper/guixsd
+@end example
+
+Mount it under /mnt
+@example
+mount /dev/mapper/guixsd /mnt
+@end example
+
+@subsubsection Unencrypted root
+
+@emph{Skip this chapter if you're not doing unencrypted root.}
+
+Make a filesystem, f.ex. ext4. You can use the "-L" flag, with a string argument, to create a label for later reference. Substitute @var{your-root-partition} with the corresponding value on your system, typically @samp{/dev/sda1}.
+@example
+mkfs.ext4 -L guixsd @var{your-root-partition}
+@end example
+
+Mount it under /mnt
+@example
+mount @var{your-root-partition} /mnt
+@end example
 
-@subsection Proceeding with the Installation
+@subsubsection Filesystem and mount
 
-With the target partitions ready, you now have to edit a file and
-provide the declaration of the operating system to be installed.  To
-that end, the installation system comes with two text editors: GNU nano
-(@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone.
-It is better to store that file on the target root file system, say, as
-@file{/mnt/etc/config.scm}.
+Run this command to make /gnu/store copy-on-write, such that packages added to it during the installation phase will be written to the target disk rather than kept in memory.
+@example
+deco start cow-store /mnt
+@end example
 
-@xref{Using the Configuration System}, for examples of operating system
-configurations.  These examples are available under
-@file{/etc/configuration} in the installation image, so you can copy
-them and use them as a starting point for your own configuration.
+Create the /etc on your mounted partition
+@example
+mkdir /mnt/etc
+@end example
 
-Once you are done preparing the configuration file, the new system must
-be initialized (remember that the target root file system is mounted
-under @file{/mnt}):
+@subsection Preparing the configuration file
 
+With the target partitions ready, you now have to edit a file and provide the declaration of the operating system to be installed. To that end, the installation system comes with two text editors: GNU nano (@pxref{Top,,, nano, GNU nano Manual}), and GNU Zile, an Emacs clone. It is better to store that file on the target root file system, say, as @file{/mnt/etc/config.scm}.
+
+@xref{Using the Configuration System}, for examples of operating system configurations. These examples are available under @file{/etc/configuration} in the installation image, so you can copy them and use them as a starting point for your own configuration.
+
+Open the file in one of the editors. We'll now walk you through the updates you need to make in the operating-system declaration in turn from top to bottom.
+
+@table @asis
+@item @samp{host-name}
+Will be the name for this system. It'll be used for identifying this system on the network and should be unique amongst the computers in your LAN(s). You may also see it in shell prompts. Use ASCII letters and digits only unless you know what you're doing.
+
+@item @samp{timezone}
+This value must match a supported timezone exactly. To find the value you need here you can run the command
+@example
+tzselect
+@end example
+and answer its questions. When it asks "Is the above information OK?" answer "1" (Yes). The value in the last line of output is the value to use in your configuration.
+To get a shell prompt for running commands you can change virtual console (Ctrl-Alt-F#), or close the editor.
+
+@item @samp{locale}
+This value must match a supported locale exactly. To get a list of supported locales and their typing run the command
+@example
+ls /run/current-system/locale/@var{X.Y}
+@end @samp{example}
+where X.Y is the libc version (just press TAB at this level). Find the locale you want in the listed output and take note of exactly how it is typed (trailing / is not included in the name).
+To get a shell prompt for running commands you can change virtual console (Ctrl-Alt-F#), or close the editor.
+
+@item @samp{bootloader}
+Update the @samp{device} argument according to the comment in the example configuration. Typical value is @var{/dev/sda}, note there's no trailing digit. This will instruct the installation to install GRUB to the MBR of your disk. This is fine even if you're going to use the boot loader in your boot firmware, it will just be unused in this case.
+@end table
+
+@subsubsection Configuration for encrypted root
+
+@emph{Skip this chapter if you're not doing encrypted root.}
+
+For encrypted root setups we need to add some lines to the configuration with instructions on how do decrypt your partition during boot.
+@table @asis
+@item @code{mapped-devices}
+Add the @code{mapped-devices} field below to your your @code{operating-system} declaration.
+(If that last sentence didn't make much sense: Insert the code snippet below between the lines (bootloader ...) and (file-systems ...))
+@example
+   (mapped-devices (list (mapped-device
+     (source @var{your-encrypted-root-partition})
+     (target @var{target-name})
+     (type luks-device-mapping))))
+@end example
+Make sure to update the following fields:
+@table @asis
+@item @samp{source}
+Substitute @var{your-encrypted-root-partition} with the device name of your encrypted partition. Typically @samp{/dev/sda1}
+@item @samp{target}
+Substitute @var{target-name} with a name of your choice. This is the name that will appear in @file{/dev/mapper/} when the partition has been decrypted. One suitable name is @samp{guixsd}.
+@end table
+
+@item @code{file-systems}
+Update these two fields in the @code{file-systems} field:
+@table @asis
+@item @samp{device}
+Set this value to @file{/dev/mapper/@var{target-name}}. If you used @samp{guixsd} as @var{target-name} previously this will be @samp{/dev/mapper/guixsd}
+@item @samp{title}
+Change this value to @samp{'device}. This makes the @code{device} field be interpreted as a file name rather than a partition label name. Note that it starts with a single quote.
+@end table
+@end table
+
+@subsubsection Configuration for unencrypted root
+
+@emph{Skip this chapter if you're not doing unencrypted root.}
+
+In the @code{file-systems} field, update this field:
+@table @asis
+@item @samp{device}
+Update this value to the label you made when you created the filesystem. If you used the name that was suggested, you'll use @samp{guixsd} here.
+@end table
+
+@subsubsection Finishing up the configuration
+
+And finally, update the values in the @code{users} field.
+@table @asis
+@item @samp{name}
+The username
+@item @samp{comment}
+You can set this to the name of the user
+@item @samp{home-directory}
+Set this to @file{/home/@var{name}}, where @var{name} is the username you previously specified.
+@end table
+
+@subsection Installation
+
+This concludes the updates to the configuration file and the preparation for installation.
+
+What remains now is to actually install the system. First run this command to get up to speed with the projects progress since this installer was created.
+@example
+guix pull
+@end example
+
+Then run this command to initialize the system based on the configuration file you've prepared.
 @example
 guix system init /mnt/etc/config.scm /mnt
 @end example
 
-@noindent
-This will copy all the necessary files, and install GRUB on
-@file{/dev/sdX}, unless you pass the @option{--no-grub} option.  For
-more information, @pxref{Invoking guix system}.  This command may trigger
-downloads or builds of missing packages, which can take some time.
+This will copy all the necessary files, and install GRUB on your hard disk, unless you pass the @option{--no-grub} option. For more information, @pxref{Invoking guix system}.  This command may trigger downloads or builds of missing packages, which can take some time.
 
 Once that command has completed---and hopefully succeeded!---you can run
 @command{reboot} and boot into the new system.  The @code{root} password
@@ -5733,6 +5859,61 @@ Join us on @code{#guix} on the Freenode IRC network or on
 @file{guix-devel@@gnu.org} to share your experience---good or not so
 good.
 
+@subsection Booting a fully encrypted system
+
+@emph{This chapter is only for systems with encrypted boot.}
+
+To be able to boot with encrypted boot you need a system with GRUB flashed into the boot firmware, like with Coreboot/Libreboot.
+
+@table @asis
+@item Manual steps to boot your fully encrypted system
+Press @kbd{c} in GRUB to enter command mode.
+
+First find the partition here which corresponds to @var{your-encrypted-root-partition} from earlier. For example @file{/dev/sda1} on GPT will be @samp{ahci0,gpt1}
+@example
+ls
+@end example
+
+Now decrypt it, @var{grub-partition} is the partition you found in the previous step. Don't use quotes.
+@example
+cryptomount @var{grub-partition}
+@end example
+
+Load GuixSD's GRUB configuration file, you can do @command{ls} again to see what name the decrypted partition got. Typically it'll be @samp{crypto0}
+@example
+configfile (crypto0)/boot/grub/grub.cfg
+@end example
+
+@item Update the GRUB config in your boot firmware
+These are just examples for menu entries in the GRUB config, for the actual flash process you should consult with your boot firmware.
+
+@example
+menuentry "GuixSD (current)" @{
+  cryptomount @var{grub-partition}
+  set root=(crypto0)
+  set guix_system=/var/guix/profiles/system
+  linux  $@{guix_system@}/kernel/bzImage --root=@var{your-root-partition} --system=$@{guix_system@} --load=$@{guix_system@}/boot
+  initrd $@{guix_system@}/initrd
+@}
+@end example
+@example
+menuentry "GuixSD fallback" @{
+  cryptomount @var{grub-partition}
+  configfile (crypto0)/boot/grub/grub.cfg
+@}
+@end example
+
+Fields to update:
+@table @asis
+@item @samp{cryptomount}
+Note there's one in each menu entry
+@item @samp{--root option}
+Point this to @file{@var{your-root-partition}}". Example @file{/dev/mapper/guixsd}.
+@end table
+
+@end table
+
+
 @subsection Building the Installation Image
 
 The installation image described above was built using the @command{guix
-- 
2.6.3

Re: Review of installation manual draft

[Ludovic Courtès]

Hi Petter,

Thanks a lot for the additions to the manual!

There was a lot more than I expected.  ;-)  For now, I’ve focused on the
improvements to the “System Installation” section, leading to commit
dedb8d5.

It turned out to be more work than I expected because I had to find out
what the differences were (some paragraphs had been moved to a single
line, which made it hard to spot the differences), and then ended up
doing a few things differently to preserve consistency.

In the future, it would be awesome if you could send more focused
patches and make sure the diffs don’t show unrelated “noise.”

Petter <petter@mykolab.ch> skribis:

> +Open the file in one of the editors. We'll now walk you through the updates you need to make in the operating-system declaration in turn from top to bottom.
> +
> +@table @asis
> +@item @samp{host-name}
> +Will be the name for this system. It'll be used for identifying this system on the network and should be unique amongst the computers in your LAN(s). You may also see it in shell prompts. Use ASCII letters and digits only unless you know what you're doing.
> +
> +@item @samp{timezone}
> +This value must match a supported timezone exactly. To find the value you need here you can run the command
> +@example
> +tzselect
> +@end example
> +and answer its questions. When it asks "Is the above information OK?" answer "1" (Yes). The value in the last line of output is the value to use in your configuration.
> +To get a shell prompt for running commands you can change virtual console (Ctrl-Alt-F#), or close the editor.
> +
> +@item @samp{locale}
> +This value must match a supported locale exactly. To get a list of supported locales and their typing run the command
> +@example
> +ls /run/current-system/locale/@var{X.Y}
> +@end @samp{example}
> +where X.Y is the libc version (just press TAB at this level). Find the locale you want in the listed output and take note of exactly how it is typed (trailing / is not included in the name).
> +To get a shell prompt for running commands you can change virtual console (Ctrl-Alt-F#), or close the editor.
> +
> +@item @samp{bootloader}
> +Update the @samp{device} argument according to the comment in the example configuration. Typical value is @var{/dev/sda}, note there's no trailing digit. This will instruct the installation to install GRUB to the MBR of your disk. This is fine even if you're going to use the boot loader in your boot firmware, it will just be unused in this case.
> +@end table

I did not include this as is because I think most of it is redundant
with (or should be covered by) the “operating-system Reference” section.

I have not yet integrated the bits about setting up an encrypted root
etc. because I first want the bits below to be fixed in the code.

> +@subsection Booting a fully encrypted system
> +
> +@emph{This chapter is only for systems with encrypted boot.}
> +
> +To be able to boot with encrypted boot you need a system with GRUB flashed into the boot firmware, like with Coreboot/Libreboot.

It’s not clear to me how much of it is specific to Coreboot/Libreboot.
It seems like it could equally well work when GRUB is spawned by a
random proprietary BIOS no?

> +@table @asis
> +@item Manual steps to boot your fully encrypted system
> +Press @kbd{c} in GRUB to enter command mode.

Seems to me that GuixSD should automatically DTRT when installing on an
encrypted root file system.  See <http://bugs.gnu.org/21843>.

> +menuentry "GuixSD (current)" @{
> +  cryptomount @var{grub-partition}
> +  set root=(crypto0)
> +  set guix_system=/var/guix/profiles/system
> +  linux  $@{guix_system@}/kernel/bzImage --root=@var{your-root-partition} --system=$@{guix_system@} --load=$@{guix_system@}/boot
> +  initrd $@{guix_system@}/initrd
> +@}

I think this sort of answers the above bug report, no?

Thanks a lot for your feedback on this!

Ludo’.

Re: Review of installation manual draft

[Petter]

Hi Ludo,

Thanks for looking at it.

On 2016-02-10 22:16, ludo@gnu.org wrote:
> Hi Petter,
> 
> Thanks a lot for the additions to the manual!
> 
> There was a lot more than I expected.  ;-)  For now, I’ve focused on 
> the
> improvements to the “System Installation” section, leading to commit
> dedb8d5.
> 
> It turned out to be more work than I expected because I had to find out
> what the differences were (some paragraphs had been moved to a single
> line, which made it hard to spot the differences), and then ended up
> doing a few things differently to preserve consistency.
> 
> In the future, it would be awesome if you could send more focused
> patches and make sure the diffs don’t show unrelated “noise.”

I'm sorry that it caused you extra work! For the record, this wasn't 
intended as a patch. We'd been working on this for a little while and 
wanted to get some feedback on particuarly the general direction before 
going any further. With a patch proposal i would have been more careful 
with noise etc.. This was really just a quick translation into guix.texi 
as requested. Maybe it would have been better if you had reviewed the 
link initially provided instead, as this was clearly not a patch.

> Petter <petter@mykolab.ch> skribis:
> 
>> +Open the file in one of the editors. We'll now walk you through the 
>> updates you need to make in the operating-system declaration in turn 
>> from top to bottom.
>> +
>> +@table @asis
>> +@item @samp{host-name}
>> +Will be the name for this system. It'll be used for identifying this 
>> system on the network and should be unique amongst the computers in 
>> your LAN(s). You may also see it in shell prompts. Use ASCII letters 
>> and digits only unless you know what you're doing.
>> +
>> +@item @samp{timezone}
>> +This value must match a supported timezone exactly. To find the value 
>> you need here you can run the command
>> +@example
>> +tzselect
>> +@end example
>> +and answer its questions. When it asks "Is the above information OK?" 
>> answer "1" (Yes). The value in the last line of output is the value to 
>> use in your configuration.
>> +To get a shell prompt for running commands you can change virtual 
>> console (Ctrl-Alt-F#), or close the editor.
>> +
>> +@item @samp{locale}
>> +This value must match a supported locale exactly. To get a list of 
>> supported locales and their typing run the command
>> +@example
>> +ls /run/current-system/locale/@var{X.Y}
>> +@end @samp{example}
>> +where X.Y is the libc version (just press TAB at this level). Find 
>> the locale you want in the listed output and take note of exactly how 
>> it is typed (trailing / is not included in the name).
>> +To get a shell prompt for running commands you can change virtual 
>> console (Ctrl-Alt-F#), or close the editor.
>> +
>> +@item @samp{bootloader}
>> +Update the @samp{device} argument according to the comment in the 
>> example configuration. Typical value is @var{/dev/sda}, note there's 
>> no trailing digit. This will instruct the installation to install GRUB 
>> to the MBR of your disk. This is fine even if you're going to use the 
>> boot loader in your boot firmware, it will just be unused in this 
>> case.
>> +@end table
> 
> I did not include this as is because I think most of it is redundant
> with (or should be covered by) the “operating-system Reference” 
> section.

Ok. Well, this started as a standalone guide for libreboot.org. And the 
general idea was to guide the user through the entire installation 
process. Also there have been a few issues with locale on IRC, like 
specifying a locale that's not supported.

> I have not yet integrated the bits about setting up an encrypted root
> etc. because I first want the bits below to be fixed in the code.
> 
>> +@subsection Booting a fully encrypted system
>> +
>> +@emph{This chapter is only for systems with encrypted boot.}
>> +
>> +To be able to boot with encrypted boot you need a system with GRUB 
>> flashed into the boot firmware, like with Coreboot/Libreboot.
> 
> It’s not clear to me how much of it is specific to Coreboot/Libreboot.
> It seems like it could equally well work when GRUB is spawned by a
> random proprietary BIOS no?

Yes, these are GRUB specific instructions, not Coreboot/Libreboot. These 
projects are used as examples.

This should be good for any system that can start GRUB without /boot 
access. I have only tried on Libreboot, which load the crypto modules 
automatically. Other systems may not do this and these modules would 
need to be loaded manually in this case. That's the only thing i can 
think of that could be different.

>> +@table @asis
>> +@item Manual steps to boot your fully encrypted system
>> +Press @kbd{c} in GRUB to enter command mode.
> 
> Seems to me that GuixSD should automatically DTRT when installing on an
> encrypted root file system.  See <http://bugs.gnu.org/21843>.
> 
>> +menuentry "GuixSD (current)" @{
>> +  cryptomount @var{grub-partition}
>> +  set root=(crypto0)
>> +  set guix_system=/var/guix/profiles/system
>> +  linux  $@{guix_system@}/kernel/bzImage 
>> --root=@var{your-root-partition} --system=$@{guix_system@} 
>> --load=$@{guix_system@}/boot
>> +  initrd $@{guix_system@}/initrd
>> +@}
> 
> I think this sort of answers the above bug report, no?

I don't think so. The bug report looks to be concerned with the 
installation routine. The draft is here concerned with booting.

When i installed, and when i reconfigure, I also get the error:
     Path '/mnt/boot/grub' is not readable by GRUB on boot.
     Installation is impossible. Aborting.

But it hasn't been a problem for me. The (/mnt)?/boot/grub.cfg file has 
luckily been generated when this happens. What fails is the installation 
of GRUB. I don't know why it failed in this case, in my case it's 
because i've specified /dev/sda1, which is my encrypted root partition. 
(I do this because i don't want GuixSD to install GRUB.) However, 
specifying a disk and not a partition, like /dev/sda, i'd expect it to 
install without problems. If this fails maybe the master boot record 
(MBR) is the problem? From the bug report it doesn't look like a reboot 
was attempted. Maybe the system was indeed fine and it's just the 
message that's a bit dramatic?

If you have encrypted /boot you'd most likely want to use GRUB provided 
by your boot firmware anyway, so you can update the GRUB configuration.

We discussed this in #guix and agreed that better than providing a note 
to ignore this message is that the installation routine is made aware 
there are systems where this is ok. I'm not sure if this thread made it 
out of #guix though.

> Thanks a lot for your feedback on this!
> 
> Ludo’.

I'm sorry again this took you more time than what was intended.

Petter