Toggle diff (751 lines)
diff --git a/doc/guix-cookbook.texi b/doc/guix-cookbook.texi
index 2e627ecc51..ef8f3425d6 100644
--- a/doc/guix-cookbook.texi
+++ b/doc/guix-cookbook.texi
@@ -18,6 +18,7 @@ Copyright @copyright{} 2020 Brice Waegeneire@*
Copyright @copyright{} 2020 André Batista@*
Copyright @copyright{} 2020 Christopher Lemmer Webber
Copyright @copyright{} 2021 Joshua Branson@*
+Copyright @copyright{} 2021 Raghav Gururajan@*
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
@@ -1358,6 +1359,7 @@ reference.
* Customizing the Kernel:: Creating and using a custom Linux kernel on Guix System.
* Guix System Image API:: Customizing images to target specific platforms.
* Connecting to Wireguard VPN:: Connecting to a Wireguard VPN.
+* Guix System with Full Disk Encryption:: Guix System with Full Disk Encryption
* Customizing a Window Manager:: Handle customization of a Window manager on Guix System.
* Running Guix on a Linode Server:: Running Guix on a Linode Server
* Setting up a bind mount:: Setting up a bind mount in the file-systems definition.
@@ -1938,6 +1940,728 @@ For more specific information about NetworkManager and wireguard
@uref{https://blogs.gnome.org/thaller/2019/03/15/wireguard-in-networkmanager/,see
+@node Guix System with Full Disk Encryption
+@section Guix System with Full Disk Encryption
+@cindex libreboot, full disk encryption
+Guix System is an exotic distribution of GNU/Linux operating system,
+with Guix as package/system manager, Linux-Libre as kernel and
+Shepherd as init system.
+Libreboot is a de-blobbed distribution of Coreboot firmware. By
+default, Libreboot comes with GRUB bootloader as a payload.
+The objective of this manual is to provide step-by-step guide for
+setting up Guix System (stand-alone Guix), with Full Disk
+Encryption (FDE), on devices powered by Libreboot.
+Any users, for their generalized use cases, need not stumble away from
+this guide to accomplish the setup. Advanced users, for deviant use
+cases, will have to explore outside this guide for customization;
+although this guide provides information that is of paramount use.
+* Create Boot-able USB::
+* Installing and Setup::
+* Tweaking Libreboot's Grub Payload::
+@node Create Boot-able USB
+@subsection Create Boot-able USB
+In the current GNU+Linux system, open terminal as root user.
+Insert USB drive and get the device letter @code{/dev/sdX}, where “X” is the
+NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
+sda3 8:3 0 219.9G 0 part /
+zram0 251:0 0 512M 0 disk [SWAP]
+Just in case the device is auto-mounted, unmount the device.
+umount /dev/sdX --verbose
+Download the Guix System ISO installer package and it’s GPG signature;
+where @code{A.B.C} is the version number and @code{SSS} is the system
+wget --verbose https://ftp.gnu.org/gnu/guix/guix-system-install-A.B.C.SSS-linux.iso.xz
+wget --verbose https://ftp.gnu.org/gnu/guix/guix-system-install-A.B.C.SSS-linux.iso.xz.sig
+Import the Guix's public key.
+gpg --verbose --keyserver pool.sks-keyservers.net –-receive-keys 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
+Verify the GPG signature of the downloaded package.
+gpg --verbose --verify guix-system-install-A.B.C.SSS-linux.iso.xz.sig
+Extract ISO image from the downloaded package.
+xz --verbose --decompress guix-system-install-A.B.C.SSS-linux.iso.xz
+Write the extracted ISO image to the drive.
+dd if=guix-system-install-A.B.C.SSS-linux.iso of=/dev/sdX status=progress; sync
+@node Installing and Setup
+@subsection Installing and Setup
+On reboot, as soon as the Libreboot's graphic art appears, press "S"
+or choose @code{Search for GRUB2 configuration on external media [s]}. Wait
+for the Guix System from USB drive to load.
+Once Guix System installer starts, choose @code{Install using the shell
+Set your keyboard layout, where @code{lo} is the two-letter keyboard
+layout code (lower-case).
+Unblock network interfaces.
+Get the names of network interfaces.
+enp0s25 Link encap:Ethernet HWaddr 00:1C:25:9A:37:BA
+ UP BROADCAST MULTICAST MTU:1500 Metric:1
+ RX packets:0 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ Interrupt:16 Memory:98800000-98820000
+lo Link encap:Local Loopback
+ inet addr:127.0.0.1 Bcast:0.0.0.0 Mask:255.0.0.0
+ UP LOOPBACK RUNNING MTU:65536 Metric:1
+ RX packets:265 errors:0 dropped:0 overruns:0 frame:0
+ TX packets:265 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:164568 TX bytes:164568
+wlp2s0 Link encap:Ethernet HWaddr E4:CE:8F:59:D6:BF
+ inet addr:192.168.1.133 Bcast:192.168.1.255 Mask:255.255.255.0
+ UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
+ RX packets:60084 errors:0 dropped:71 overruns:0 frame:0
+ TX packets:33232 errors:0 dropped:0 overruns:0 carrier:0
+ collisions:0 txqueuelen:1000
+ RX bytes:45965805 TX bytes:4905457
+Bring the desired network interface (wired or wireless) up, where
+@code{nwif} is the network interface name.
+For wireless connection, follow the wireless setup.
+@subsubsection Wireless Setup
+Create a configuration file using text editor, where @code{fname} is any
+Choose, type and save ONE of the following snippets, where ‘net’ is
+the network name, ‘pass’ is the password or passphrase and ‘uid’ is
+For most private networks:
+For most public networks:
+For most organizational networks:
+Connect to the configured network.
+wpa_supplicant -B -c fname.conf -i nwif
+Assign an IP address to the network interface.
+Obtain the device letter @code{/dev/sdX} in which you would like to deploy
+and install Guix System, where “X” is the device letter.
+NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
+sda3 8:3 0 219.9G 0 part /
+zram0 251:0 0 512M 0 disk [SWAP]
+Wipe the device (Ignore if the device is new).
+shred --verbose --random-source=/dev/urandom /dev/sdX
+Load the device-mapper module in the current kernel.
+modprobe --verbose dm_mod
+Partition the device. Follow the prompts. Just do, GPT --> New -->
+Write --> Quit; defaults will be set.
+Obtain the partition number from the device, where “Y” is the
+Encrypt the partition. Follow the prompts.
+cryptsetup --verbose --hash whirlpool --cipher serpent-xts-plain64 \
+--verify-passphrase --use-random --key-size 512 --iter-time 500 \
+Obtain and note down the UUID of the LUKS partition.
+cryptsetup --verbose luksUUID /dev/sdXY
+Open the encrypted partition, where @code{luks-uuid} is the LUKS UUID,
+and @code{partname} is any desired name for the partition.
+luksOpen UUID=luks-uuid partname
+Create a physical volume in the partition.
+pvcreate /dev/mapper/partname --verbose
+Create a volume group in the physical volume, where @code{vgname} is any
+desired name for volume group.
+vgcreate vgname /dev/mapper/partname --verbose
+Create logical volumes in the volume group; where "num" is the number
+for space in GB, and @code{lvnameroot} and @code{lvnamehome} are any
+desired names for root and home volumes respectively.
+lvcreate --extents 25%VG vgname --name lvnameroot --verbose
+lvcreate --extents 100%FREE vgname --name lvnamehome --verbose
+Create filesystems on the logical-volumes, where @code{fsnameroot} and
+@code{fsnamehome} are any desired names for root and home filesystems
+mkfs.btrfs --metadata dup --label fsnameroot /dev/vgname/lvnameroot
+mkfs.btrfs --metadata dup --label fsnamehome /dev/vgname/lvnamehome
+Mount the filesystems under the current system.
+mount --label fsnameroot --target /mnt --types btrfs --verbose
+mkdir --verbose /mnt/home && mount --label fsnamehome --target \
+/mnt/home --types btrfs --verbose
+dd bs=1MiB count=1GiB if=/dev/zero of=/mnt/swapfile status=progress
+mkswap --verbose /mnt/swapfile
+Make the swap file readable and writable only by root account.
+chmod --verbose 600 /mnt/swapfile
+swapon --verbose /mnt/swapfile
+Install packages on the mounted root filesystem.
+herd start cow-store /mnt
+Create the system-wide configuration files directory.
+mkdir --verbose /mnt/etc
+Create, edit and save the system configuration file by typing the
+following code snippet. WATCH-OUT for variables in the code snippet
+and replace them with the relevant values.
+nano /mnt/etc/config.scm
+The content of config.scm is:
+ (kernel linux-libre-lts)
+ ;; this is needed to flash the libreboot ROM. After, you
+ ;; have flashed your rom, it is a good idea to remove
+ ;; iomem=relaxed from your kernel arguments
+ %default-kernel-arguments))
+ (timezone "Zone/SubZone")
+ (name-service-switch %mdns-host-lookup-nss)
+ (bootloader-configuration
+ (inherit grub-bootloader)
+ (installer #~(const #t))))
+ (keyboard-layout keyboard-layout)))
+ (type luks-device-mapping))
+ (type lvm-device-mapping))))
+ (device "/dev/mapper/VGNAME-LVNAMEROOT")
+ (options "space_cache=v2")
+ (dependencies mapped-devices))
+ (device "/dev/mapper/VGNAME-LVNAMEHOME")
+ (options "space_cache=v2")
+ (dependencies mapped-devices)))
+ (supplementary-groups '("audio" "cdrom"
+ (service gnome-desktop-service-type))
+Initialize new Guix System.
+guix system init /mnt/etc/config.scm /mnt
+@node Tweaking Libreboot's Grub Payload
+@subsection Tweaking Libreboot's Grub Payload
+On reboot, as soon as the Libreboot graphic art appears, press “C” to
+Enter the following commands and respond to first command with the LUKS
+cryptomount -u luks-uuid
+set root=(lvm/vgname-lvnameroot)
+Upon Guix's GRUB menu, go with the default option.
+Enter the LUKS Key again, for kernel, as prompted.
+Upon login screen, login as "root" with password field empty.
+Set passkey for the "root" user. Follow the prompts.
+Set passkey for the "username" user. Follow the prompts.
+Install flashrom and wget.
+guix package –-install flashrom wget
+Obtain the ROM chip's model and size. Look for the output line “Found
+[@dots{}] flash chip [@dots{}]”.
+flashrom --verbose --programmer internal
+Download Libreboot ROM and utilities, where "YYYYMMDD" is the release
+date, @code{devmod} is the device model and "N" is the ROM chip size.
+wget --verbose https://rsync.libreboot.org/stable/YYYYMMDD/rom/grub/libreboot_rYYYYMMDD_grub_devmod_Nmb.tar.xz
+wget --verbose https://rsync.libreboot.org/stable/YYYYMMDD/libreboot_rYYYYMMDD_util.tar.xz
+Extract the downloaded files.
+tar --extract --file=libreboot_rYYYYMMDD_grub_devmod_Nmb.tar.xz --verbose
+tar --extract --file=libreboot_rYYYYMMDD_util.tar.xz --verbose
+Rename the directories of extracted files.
+mv --verbose "libreboot_rYYYYMMDD_grub_devmod_Nmb.tar.xz" "libreboot_rom"
+mv --verbose "libreboot_rYYYYMMDD_util" "libreboot_util"
+Copy the ROM image to the directory of cbfstool, where "kbdlo" is the
+keyboard layout and "arch" is the system architecture.
+cp libreboot_rom/devmod_Nmb_kbdlo_vesafb.rom libreboot_util/cbfstool/arch/libreboot.rom
+Change directory to the directory of cbfstool.
+cd libreboot_util/cbfstool/arch/
+Extract the GRUB configuration file from the image.
+./cbfstool libreboot.rom extract -n grub.cfg -f grub.cfg
+Edit the GRUB configuration file and insert the following code snippet
+above the line @code{“menuentry 'Load Operating System [o]' --hotkey='o'
+--unrestricted @{ [...] @}”}.
+menuentry ‘Guix System (An advanced distribution of the GNU operating system) [g]’ --hotkey=’g’ --unrestricted
+cryptomount -u luks-uuid
+set root=(lvm/vgname-lvnameroot)
+configfile /boot/grub/grub.cfg
+Remove the old GRUB configuration file from the ROM image.
+./cbfstool libreboot.rom remove -n grub.cfg
+Insert the new GRUB configuration file into the ROM image.
+./cbfstool libreboot.rom add -n grub.cfg -f grub.cfg -t raw
+Move the ROM image to the directory of ich9gen.
+mv libreboot.rom ~/libreboot_util/ich9deblob/arch/libreboot.rom
+Change directory to the directory of ich9gen.
+cd ~/libreboot_util/ich9deblob/arch/
+Generate descriptor+GbE images with the MAC address, where "mac-addr"
+is the MAC address of the machine.
+ich9gen --macaddress mac-addr
+Insert the descriptor+GbE image into the ROM image, where "N" is the
+dd bs=12k conv=notrunc count=1 if=ich9fdgbe_Nm.bin of=libreboot.rom status=progress
+Move the ROM image to the directory of flash.
+mv libreboot.rom ~/libreboot_util/libreboot.rom
+Change directory to the directory of flash.
+Modify the shebang of flash script, from `#!/bin/bash` to `#!/bin/sh`.
+Flash the ROM with the new image.
+./flash update libreboot.rom
+./flash forceupdate libreboot.rom
+@subsection Closing Thoughts
+Everything should be stream-lined from now. Upon Libreboot's GRUB
+menu, you can either press "G" or choose "Guix System (An advanced
+distribution of the GNU operating system) [g]".
+During the boot process, as prompted, you have to type LUKS key twice;
+once for Libreboot's GRUB and once more for Linux-Libre kernel.
+Retyping a passphrase is a minor annoyance, but it is a secure method of
+opening up your device. There are methods that exist to only type the
+passphrase once, but none are currently integrated into Guix System.
+Generally, you will be using Libreboot's initial/default grub.cfg,
+whose Guix menu-entry invokes Guix's grub.cfg located at
+@code{/boot/grub/}. For trouble-shooting, you can also use Libreboot's
+@code{grubtest.cfg}, which hasn't been modified.
+Now that you have a working Guix System with full disk encryption, you
+may want to remove the @code{iomem=relaxed} from your
+@code{kernel-arguments}. @code{iomem=relaxed} is needed to reflash your
+rom. Since, most users will probably not flash their rom often, those
+users may wish to disable that feature:
+ ;; optionally remove this bit of code from your config.scm
+ ;; this is needed to flash the libreboot ROM. After, you
+ ;; have flashed your rom, it is a good idea to remove
+ ;; iomem=relaxed from your kernel arguments
+ %default-kernel-arguments))
+That is it! You have now setup Guix System with Full Disk Encryption on
+your device powered by Libreboot. Enjoy!
+More information about Libreboot can be found at their official
+documentation: @uref{https://libreboot.org/docs/}.
+@subsection Special Thanks
+Thanks to Guix developer, Clement Lassieur (clement@@lassieur.org),
+for helping me with the Scheme code for the bootloader configuration.
+Thanks to Libreboot founder and developer, Leah Rowe
+(leah@@libreboot.org), for helping me with the understanding of
+Libreboot’s functionalities.
@node Customizing a Window Manager
@section Customizing a Window Manager