[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[bug#49654] [PATCH] doc: Add full disc encryption guide to the cookbook
|
From: |
Sarah Morgensen |
|
Subject: |
[bug#49654] [PATCH] doc: Add full disc encryption guide to the cookbook |
|
Date: |
Wed, 21 Jul 2021 15:50:35 -0700 |
Hello Joshua, Raghav,
Good to see more guides like this. In addition to what others have
already pointed out, I've got few readability suggestions, reading this as a
layperson :) (Questions are intentended to be rhetorical, to illustrate
where a layperson might have questions or be confused.)
Joshua Branson <jbranso@dismail.de> writes:
> From: Joshua Branson <jbranso AT gnucode.me>
>
> The original guide was written by Raghav Gururajan <rg@raghavgururajan.name>
> and edited by Joshua Branson <jbranso@dismail.de>.
>
> * doc/guix-cookbook.texi (System Configuration): New section of full disc
> encryption via libreboot.
> ---
> doc/guix-cookbook.texi | 724 +++++++++++++++++++++++++++++++++++++++++
> 1 file changed, 724 insertions(+)
>
> 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
> this post by thaller}.
>
> +@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,
^ the
> +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
^ a
> +setting up Guix System (stand-alone Guix), with Full Disk
^ You already defined Guix System above
> +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.
Above paragraph does not add useful information and the tone does not
match the rest of the Cookbook. (Sorry!)
> +
> +Let us begin!
> +
> +@menu
> +* Create Boot-able USB::
^ Bootable
> +* Installing and Setup::
> +* Tweaking Libreboot's Grub Payload::
> +* Closing Thoughts::
> +* Special Thanks::
> +@end menu
> +
> +@node Create Boot-able USB
> +@subsection Create Boot-able USB
Likewise.
> +
> +In the current GNU+Linux system, open terminal as root user.
"open a terminal as root" or "open a terminal as the root user"
> +
> +Insert USB drive and get the device letter @code{/dev/sdX}, where “X” is the
> +device letter.
What USB drive? This is the first I've heard of it! Do I need to make
sure it's a specific kind? Is it okay if there's important information
on there that I haven't backed up?
Also note that while usually the device identifier will be 'sdX' this is
not guaranteed; sometimes you'll see 'hdX' or 'mmcblkX'.
> +
> +@example
> +lsblk --list
> +@end example
> +
> +@example
> +NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
> +sda 8:0 0 223.6G 0 disk
> +sda1 8:1 0 2M 0 part
> +sda2 8:2 0 3.7G 0 part
> +sda3 8:3 0 219.9G 0 part /
> +zram0 251:0 0 512M 0 disk [SWAP]
> +@end example
Why are these separate examples? IMO it would be more clear (and is the
usual style in such guides) to combine them and simply add '$ ' to the
beginning of any line that is a command the user should run.
> +
> +
> +Just in case the device is auto-mounted, unmount the device.
> +
> +@example
> +umount /dev/sdX --verbose
> +@end example
> +
> +Download the Guix System ISO installer package and it’s GPG signature;
^ its
> +where @code{A.B.C} is the version number and @code{SSS} is the system
> +architecture.
> +
> +@example
> +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
> +@end example
> +
> +Import the Guix's public key.
^ "the Guix" or "Guix's"
> +
> +@example
> +gpg --verbose --keyserver pool.sks-keyservers.net –-receive-keys
> 3CE464558A84FDC69DB40CFB090B11993D9AEBB5
> +@end example
> +
> +Verify the GPG signature of the downloaded package.
> +
> +@example
> +gpg --verbose --verify guix-system-install-A.B.C.SSS-linux.iso.xz.sig
> +@end example
> +
> +Extract ISO image from the downloaded package.
> +
> +@example
> +xz --verbose --decompress guix-system-install-A.B.C.SSS-linux.iso.xz
> +@end example
> +
> +Write the extracted ISO image to the drive.
> +
> +@example
> +dd if=guix-system-install-A.B.C.SSS-linux.iso of=/dev/sdX status=progress;
> sync
> +@end example
> +
> +Reboot the device.
> +
> +@example
> +reboot
> +@end example
> +
> +@node Installing and Setup
> +@subsection Installing and Setup
> +
> +On reboot, as soon as the Libreboot's graphic art appears, press "S"
^ "the" is not necessary
> +or choose @code{Search for GRUB2 configuration on external media [s]}. Wait
> +for the Guix System from USB drive to load.
This sounds awkward. Perhaps "Wait for Guix System to load from the USB
drive." or "Wait for the Guix System [you just] installed on the USB
drive to load."?
> +
> +Once Guix System installer starts, choose @code{Install using the shell
> +based process}.
> +
> +Set your keyboard layout, where @code{lo} is the two-letter keyboard
> +layout code (lower-case).
How do I know out what my keyboard layout code should be? Even
"layout code (lower-case), for example @code{us} or @code{ru}."
would be helpful.
> +
> +@example
> +loadkeys --verbose lo
> +@end example
> +
> +Unblock network interfaces.
> +
> +@example
> +rfkill unblock all
> +@end example
> +
> +Get the names of network interfaces.
> +
> +@example
> +ifconfig -v -a
> +@end example
> +
> +@example
> +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
> + RX bytes:0 TX bytes:0
> + 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
> +
> +@end example
> +
> +Bring the desired network interface (wired or wireless) up, where
> +@code{nwif} is the network interface name.
How do I know which of the interfaces I should use?
> +
> +@example
> +ifconfig -v nwif up
> +@end example
> +
> +For wireless connection, follow the wireless setup.
^ connections
> +
> +@menu
> +* Wireless Setup::
> +@end menu
> +
> +@node Wireless Setup
> +@subsubsection Wireless Setup
> +
> +Create a configuration file using text editor, where @code{fname} is any
> +desired name for file.
This reads a bit awkwardly. Perhaps something like
"Create the configuration file using a text editor such as
@code{nano}. In this example, we are naming the file
@code{fname.conf}, but any name will do."
Also consider using a more descriptive example filename, like
`wpa_supplicant.conf`. You'd be surprised how many users just use the
example names!
> +
> +@example
> +nano fname.conf
> +@end example
> +
> +Choose, type and save ONE of the following snippets, where ‘net’ is
> +the network name, ‘pass’ is the password or passphrase and ‘uid’ is
> +the user identity.
> +
> +For most private networks:
> +
> +@example
> +network=@{
> + ssid="net"
> + key_mgmt=WPA-PSK
> + psk="pass"
> +@}
> +@end example
> +
> +(or)
> +
> +For most public networks:
> +
> +@example
> +network=@{
> + ssid="net"
> + key_mgmt=NONE
> +@}
> +@end example
> +
> +(or)
> +
> +For most organizational networks:
> +
> +@example
> +network=@{
> + ssid="net"
> + scan_ssid=1
> + key_mgmt=WPA-EAP
> + identity="uid"
> + password="pass"
> + eap=PEAP
> + phase1="peaplabel=0"
> + phase2="auth=MSCHAPV2"
> +@}
> +@end example
> +
> +Connect to the configured network.
> +
> +@example
> +wpa_supplicant -B -c fname.conf -i nwif
> +@end example
> +
> +Assign an IP address to the network interface.
This is a bit misleading, as we aren't actually directly assigning an IP
address, but using dhclient to get one through DHCP.
> +
> +@example
> +dhclient -v nwif
> +@end example
Should there be something indicating the end of "Wireless Setup"? I'm
not sure how texi subsections work, but if I were skipping "Wireless
Setup," how would I know where to skip to?
> +
> +Obtain the device letter @code{/dev/sdX} in which you would like to deploy
> +and install Guix System, where “X” is the device letter.
This reads a bit awkwardly. Perhaps consider
"Find the [device] identifier for the device you are installing Guix
System onto."
> +
> +@example
> +lsblk --list
> +@end example
> +
> +@example
> +NAME MAJ:MIN RM SIZE RO TYPE MOUNTPOINT
> +sda 8:0 0 223.6G 0 disk
> +sda1 8:1 0 2M 0 part
> +sda2 8:2 0 3.7G 0 part
> +sda3 8:3 0 219.9G 0 part /
> +zram0 251:0 0 512M 0 disk [SWAP]
> +@end example
> +
> +Wipe the device (Ignore if the device is new).
^ lowercase; or "skip"
Also, why did the example for the USB drive show all 'sda' devices, and
this one does too? This is potentially confusing. Consider using
examples from the actual process.
> +
> +@example
> +shred --verbose --random-source=/dev/urandom /dev/sdX
> +@end example
> +
> +Load the device-mapper module in the current kernel.
Why? Consider adding "(This is necessary for...)"
> +
> +@example
> +modprobe --verbose dm_mod
> +@end example
> +
> +Partition the device. Follow the prompts. Just do, GPT --> New -->
> +Write --> Quit; defaults will be set.
Consider writing out the steps.
Also: are we just using one partition? Prefer describing what the goal
of a step is before describing the step, so a less knowledgeable user
learns and a more knowledgeable user knows when that step can be
substituted.
> +
> +@example
> +cfdisk /dev/sdX
> +@end example
> +
> +Obtain the partition number from the device, where “Y” is the
> +partition number.
Doesn't cfdisk show the partition number?
> +
> +@example
> +lsblk --list
> +@end example
> +
> +Encrypt the partition. Follow the prompts.
> +
> +@example
> +cryptsetup --verbose --hash whirlpool --cipher serpent-xts-plain64 \
> +--verify-passphrase --use-random --key-size 512 --iter-time 500 \
> +luksFormat /dev/sdXY
> +@end example
> +
> +Obtain and note down the UUID of the LUKS partition.
> +
> +@example
> +cryptsetup --verbose luksUUID /dev/sdXY
> +@end example
> +
> +Open the encrypted partition, where @code{luks-uuid} is the LUKS UUID,
> +and @code{partname} is any desired name for the partition.
Consider suggesting (or using in your example) a default partition name,
like with the .conf file above. Same for all the vg, lv, and fs names
below.
> +
> +@example
> +cryptsetup --verbose
> +luksOpen UUID=luks-uuid partname
> +@end example
Is this supposed to be two lines?
> +
> +Create a physical volume in the partition.
> +
> +@example
> +pvcreate /dev/mapper/partname --verbose
> +@end example
> +
> +Create a volume group in the physical volume, where @code{vgname} is any
> +desired name for volume group.
> +
> +@example
> +vgcreate vgname /dev/mapper/partname --verbose
> +@end example
> +
> +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.
There is not "num" or any GB values in your following example...
> +
> +@example
> +lvcreate --extents 25%VG vgname --name lvnameroot --verbose
> +lvcreate --extents 100%FREE vgname --name lvnamehome --verbose
> +@end example
> +
> +Create filesystems on the logical-volumes, where @code{fsnameroot} and
^ logical volumes
> +@code{fsnamehome} are any desired names for root and home filesystems
> +respectively.
> +
> +@example
> +mkfs.btrfs --metadata dup --label fsnameroot /dev/vgname/lvnameroot
> +mkfs.btrfs --metadata dup --label fsnamehome /dev/vgname/lvnamehome
> +@end example
Why are we using btrfs? Could I use ext4 instead?
> +
> +Mount the filesystems under the current system.
Consider "Mount the new filesystems."
> +
> +@example
> +mount --label fsnameroot --target /mnt --types btrfs --verbose
> +mkdir --verbose /mnt/home && mount --label fsnamehome --target \
> +/mnt/home --types btrfs --verbose
> +@end example
> +
> +Create a swap file.
> +
> +@example
> +dd bs=1MiB count=1GiB if=/dev/zero of=/mnt/swapfile status=progress
> +mkswap --verbose /mnt/swapfile
> +@end example
> +
> +Make the swap file readable and writable only by root account.
"root." or "the root account."
> +
> +@example
> +chmod --verbose 600 /mnt/swapfile
> +@end example
> +
> +Activate the swap file.
> +
> +@example
> +swapon --verbose /mnt/swapfile
> +@end example
> +
> +Install packages on the mounted root filesystem.
> +
> +@example
> +herd start cow-store /mnt
> +@end example
This doesn't actually install packages, does it? The manual says:
"This makes /gnu/store copy-on-write, such that packages added to it
during the installation phase are written to the target disk rather
than kept in memory."
> +
> +Create the system-wide configuration files directory.
> +
> +@example
> +mkdir --verbose /mnt/etc
> +@end example
Why all the verbose, even on mkdir?
> +
> +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.
"Replace placeholders (such as LUKS-UUID) with their values from earlier."
> +
> +@example
> +nano /mnt/etc/config.scm
> +@end example
> +
> +The content of config.scm is:
> +
> +@lisp
> +(use-modules
> + (gnu)
> + (gnu system nss))
> +
> +(use-package-modules
> + certs
> + gnome
> + linux)
> +
> +(use-service-modules
> + desktop
> + xorg)
> +
> +(operating-system
> + (kernel linux-libre-lts)
> + (kernel-arguments
> + (append
> + (list
> + ;; 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
> + "iomem=relaxed")
> + %default-kernel-arguments))
> +
> + (timezone "Zone/SubZone")
> + (locale "ab_XY.1234")
> + (name-service-switch %mdns-host-lookup-nss)
> +
> + (bootloader
> + (bootloader-configuration
> + (bootloader
> + (bootloader
> + (inherit grub-bootloader)
> + (installer #~(const #t))))
> + (keyboard-layout keyboard-layout)))
> +
> + (keyboard-layout
> + (keyboard-layout
> + "xy"
> + "altgr-intl"))
> +
> + (host-name "hostname")
> +
> + (mapped-devices
> + (list
> + (mapped-device
> + (source
> + (uuid "LUKS-UUID"))
> + (target "partname")
> + (type luks-device-mapping))
> + (mapped-device
> + (source "vgname")
> + (targets
> + (list
> + "vgname-lvnameroot"
> + "vgname-lvnamehome"))
> + (type lvm-device-mapping))))
> +
> + (file-systems
> + (append
> + (list
> + (file-system
> + (type "btrfs")
> + (mount-point "/")
> + (device "/dev/mapper/VGNAME-LVNAMEROOT")
> + (flags '(no-atime))
> + (options "space_cache=v2")
> + (needed-for-boot? #t)
> + (dependencies mapped-devices))
> + (file-system
> + (type "btrfs")
> + (mount-point "/home")
> + (device "/dev/mapper/VGNAME-LVNAMEHOME")
> + (flags '(no-atime))
> + (options "space_cache=v2")
> + (dependencies mapped-devices)))
> + %base-file-systems))
> +
> + (swap-devices
> + (list
> + "/swapfile"))
> +
> + (users
> + (append
> + (list
> + (user-account
> + (name "USERNAME")
> + (comment "Full Name")
> + (group "users")
> + (supplementary-groups '("audio" "cdrom"
> + "kvm" "lp" "netdev"
> + "tape" "video"
> + "wheel"))))
> + %base-user-accounts))
> +
> + (packages
> + (append
> + (list
> + nss-certs)
> + %base-packages))
> +
> + (services
> + (append
> + (list
> + (service gnome-desktop-service-type))
> + %desktop-services)))
> +@end lisp
> +
> +Initialize new Guix System.
> +
> +@example
> +guix system init /mnt/etc/config.scm /mnt
> +@end example
> +
> +Reboot the device.
> +
> +@example
> +reboot
> +@end example
> +
> +@node Tweaking Libreboot's Grub Payload
> +@subsection Tweaking Libreboot's Grub Payload
> +@cindex grub payload
> +
> +On reboot, as soon as the Libreboot graphic art appears, press “C” to
> +enter the command-line.
> +
> +Enter the following commands and respond to first command with the LUKS
> +Key.
What key? When did we get a LUKS Key? Am I supposed to come up with a
new key/passphrase?
> +
> +@example
> +cryptomount -u luks-uuid
> +set root=(lvm/vgname-lvnameroot)
> +@end example
> +
> +Upon Guix's GRUB menu, go with the default option.
"At the GRUB menu, selec the default option."
> +
> +Enter the LUKS Key again, for kernel, as prompted.
> +
> +Upon login screen, login as "root" with password field empty.
"At the login screen" ^ the
> +
> +Open terminal.
^ the
> +
> +Set passkey for the "root" user. Follow the prompts.
^ the password
> +
> +@example
> +passwd root
> +@end example
> +
> +Set passkey for the "username" user. Follow the prompts.
^ the password
Also, the guide used the @code{username} style before. Why the change?
> +
> +@example
> +passwd username
> +@end example
> +
> +Install flashrom and wget.
> +
> +@example
> +guix package –-install flashrom wget
> +@end example
> +
> +Obtain the ROM chip's model and size. Look for the output line “Found
> +[@dots{}] flash chip [@dots{}]”.
> +
> +@example
> +flashrom --verbose --programmer internal
> +@end example
> +
> +Download Libreboot ROM and utilities, where "YYYYMMDD" is the release
> +date, @code{devmod} is the device model and "N" is the ROM chip size.
Likewise. The guide also used single quotes for 'sdX' earlier.
> +
> +@example
> +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
> +@end example
> +
> +Extract the downloaded files.
> +@example
> +tar --extract --file=libreboot_rYYYYMMDD_grub_devmod_Nmb.tar.xz --verbose
> +tar --extract --file=libreboot_rYYYYMMDD_util.tar.xz --verbose
> +@end example
> +
> +Rename the directories of extracted files.
> +
> +@example
> +mv --verbose "libreboot_rYYYYMMDD_grub_devmod_Nmb.tar.xz" "libreboot_rom"
> +mv --verbose "libreboot_rYYYYMMDD_util" "libreboot_util"
> +@end example
> +
> +Copy the ROM image to the directory of cbfstool, where "kbdlo" is the
> +keyboard layout and "arch" is the system architecture.
Likewise.
> +
> +@example
> +cp libreboot_rom/devmod_Nmb_kbdlo_vesafb.rom
> libreboot_util/cbfstool/arch/libreboot.rom
> +@end example
> +
> +Change directory to the directory of cbfstool.
> +@example
> +cd libreboot_util/cbfstool/arch/
> +@end example
> +
> +Extract the GRUB configuration file from the image.
> +
> +@example
> +./cbfstool libreboot.rom extract -n grub.cfg -f grub.cfg
> +@end example
> +
> +Edit the GRUB configuration file and insert the following code snippet
> +above the line @code{“menuentry 'Load Operating System [o]' --hotkey='o'
> +--unrestricted @{ [...] @}”}.
> +
> +@example
> +nano grub.cfg
> +@end example
> +
> +Snippet:
> +@example
> +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
> +@}
> +@end example
> +
> +Remove the old GRUB configuration file from the ROM image.
> +
> +@example
> +./cbfstool libreboot.rom remove -n grub.cfg
> +@end example
> +
> +Insert the new GRUB configuration file into the ROM image.
> +
> +@example
> +./cbfstool libreboot.rom add -n grub.cfg -f grub.cfg -t raw
> +@end example
> +
> +Move the ROM image to the directory of ich9gen.
> +
> +@example
> +mv libreboot.rom ~/libreboot_util/ich9deblob/arch/libreboot.rom
> +@end example
> +
> +Change directory to the directory of ich9gen.
> +
> +@example
> +cd ~/libreboot_util/ich9deblob/arch/
> +@end example
> +
> +Generate descriptor+GbE images with the MAC address, where "mac-addr"
> +is the MAC address of the machine.
Likewise.
> +
> +@example
> +ich9gen --macaddress mac-addr
> +@end example
> +
> +Insert the descriptor+GbE image into the ROM image, where "N" is the
> +ROM chip size.
> +@example
> +dd bs=12k conv=notrunc count=1 if=ich9fdgbe_Nm.bin of=libreboot.rom
> status=progress
> +@end example
> +
> +Move the ROM image to the directory of flash.
^ "the flash script"
> +
> +@example
> +mv libreboot.rom ~/libreboot_util/libreboot.rom
> +@end example
> +
> +Change directory to the directory of flash.
> +
> +@example
> +cd ~/libreboot_util
> +@end example
> +
> +Modify the shebang of flash script, from `#!/bin/bash` to `#!/bin/sh`.
^ the ^ no ","
> +@example
> +nano flash
> +@end example
> +
> +Flash the ROM with the new image.
> +@example
> +./flash update libreboot.rom
> +@end example
> +
> +(or)
> +
> +@example
> +./flash forceupdate libreboot.rom
> +@end example
How do I know whether to use 'update' or 'forceupdate'?
> +
> +Reboot the device.
> +@example
> +reboot
> +@end example
> +
> +@node Closing Thoughts
> +@subsection Closing Thoughts
Typically it's "Closing Remarks".
> +
> +Everything should be stream-lined from now. Upon Libreboot's GRUB
What does this mean?
> +menu, you can either press "G" or choose "Guix System (An advanced
> +distribution of the GNU operating system) [g]".
In order to do what?
> +
> +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,
Is this the grub.cfg we setup above? If so, specify that.
> +whose Guix menu-entry invokes Guix's grub.cfg located at
> +@code{/boot/grub/}. For trouble-shooting, you can also use Libreboot's
^ troubleshooting
> +@code{grubtest.cfg}, which hasn't been modified.
But *how* would I use grubtest.cfg?
> +
> +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
^ ROM ^ no "," ^ ROM
> +users may wish to disable that feature:
The change from "you" to "most users"/"those users" is a little jarring.
> +
> +@lisp
> + ;; optionally remove this bit of code from your config.scm
> + (kernel-arguments
> + (append
> + (list
> + ;; 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
> + "iomem=relaxed")
> + %default-kernel-arguments))
> +@end lisp
> +
> +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/}.
Consider embedding the link:
"[...] can be found in the @uref{https://libreboot.org/docs/, official
documentation}."
> +
> +@node Special Thanks
> +@subsection Special Thanks
> +
> +Thanks to Guix developer, Clement Lassieur (clement@@lassieur.org),
^ no "," ^ same
> +for helping me with the Scheme code for the bootloader configuration.
^ "for assisting with" (avoid first person prounouns)
> +
> +Thanks to Libreboot founder and developer, Leah Rowe
^ no ","
> +(leah@@libreboot.org), for helping me with the understanding of
^ no "," ^ "for assistance with Libreboot."
> +Libreboot’s functionalities.
> +
> @node Customizing a Window Manager
> @section Customizing a Window Manager
> @cindex wm
Also, consider referencing relevant sections of the manual, such as
https://guix.gnu.org/manual/en/html_node/Manual-Installation.html
so users know where to find more detailed information.
Hope that helps,
Sarah