| Message ID | 20210720052229.15438-1-jbranso@dismail.de |
|---|---|
| State | New |
| Headers | show |
| Series | [bug#49654] doc: Add full disc encryption guide to the cookbook | expand |
| Context | Check | Description |
|---|---|---|
| cbaines/applying patch | fail | View Laminar job |
| cbaines/issue | success | View issue |
Hello Joshua and Raghav, thank you for your guide! I have just a couple of comments. Joshua Branson via Guix-patches via <guix-patches@gnu.org> 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(+) [...] > +* Guix System with Full Disk Encryption:: Guix System with Full Disk Encryption AFAIU the steps, especially the partitioning that does not provide an UEFI dedicated partition, are specific to Libreboot systems: what about to make it more clear in the section title? ...or to adapt the section by separating Libreboot specific instructions from generic system instructions? [...] > +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. > + > +@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 > +@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 using two BTRFS volumes on top of LVM and not directly using BTRFS (with subvolumes if you want) on top of /dev/mapper/partname? AFAIU the "double mapping" it's not needed, BTRFS have a very good (and now mature) built in volume manager. Furthermore, using BTRFS for volume management will allow users to switch to a multi-device system (e.g. RAID1) very easily. I'm still using LVM on some "legacy" systems but for new installations I'd strogly suggest starting using BTRFS on top of "physical" partitions. > +Mount the filesystems under the current system. > + > +@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 I know that since Linux 2.6 swapfile performance is not a big issue if the file is unfragmented (and it'll be for sure on newly partitioned filesystems) but AFAIU swap files are still a little bit problematic on BTRFS https://btrfs.wiki.kernel.org/index.php/FAQ#Does_Btrfs_support_swap_files.3F: --8<---------------cut here---------------start------------->8--- From kernel 5.0+ btrfs have native swap files support, but with some limitations. Swap file - must be fully allocated as NOCOW with no compression on one device. --8<---------------cut here---------------end--------------->8--- I've never tested a system with swap file on BTRFS but I think that your instructions should add how to set NOCOW for the swap file. The above example could be: --8<---------------cut here---------------start------------->8--- @example dd bs=1MiB count=1GiB if=/dev/zero of=/mnt/swapfile status=progress mkswap --verbose /mnt/swapfile chattr +C /mnt/swapfile btrfs property set /mnt/swapfile compression none @end example --8<---------------cut here---------------end--------------->8--- Final note: AFAIU BTRFS supports swap files ONLY in single device settings (that is: NO swap file support on multi device settings), so IMHO it's better to use a dedicated partition for the swap space so users are free to switch to a multi-device setting if they wish (and can). The problem with a fully encrypted dedicated swap partition is that it'll require a third passphrase prompt on boot (the one to unlock the swap partition), but that's a minor annoyance IMHO. What do you think? [...] Happy hacking! Gio'
Giovanni Biscuolo <g@xelera.eu> writes: > Hello Joshua and Raghav, > > thank you for your guide! I have just a couple of comments. > > Joshua Branson via Guix-patches via <guix-patches@gnu.org> 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(+) > > [...] > >> +* Guix System with Full Disk Encryption:: Guix System with Full Disk Encryption > > AFAIU the steps, especially the partitioning that does not provide an > UEFI dedicated partition, are specific to Libreboot systems: what about > to make it more clear in the section title? I will mention this somewhere. Thanks. Perhaps we could mention that libreboot systems are so ancient that they do not support UEFI. I will also mention that newer coreboot devices do not support a UEFI partition, but require proprietary blobs to run properly. > > ...or to adapt the section by separating Libreboot specific instructions > from generic system instructions? as above. > > [...] > >> +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. >> + >> +@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 >> +@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 using two BTRFS volumes on top of LVM and not directly using BTRFS > (with subvolumes if you want) on top of /dev/mapper/partname? This is probably a good idea...however does the grub payload support this? > > AFAIU the "double mapping" it's not needed, BTRFS have a very good (and > now mature) built in volume manager. Furthermore, using BTRFS for > volume management will allow users to switch to a multi-device system > (e.g. RAID1) very easily. That's pretty cool! > > I'm still using LVM on some "legacy" systems but for new installations > I'd strogly suggest starting using BTRFS on top of "physical" > partitions. does btrfs volume manage allow use to use ext4, jfs, or xfs filesystems? Or does on LVM do that? >> +Mount the filesystems under the current system. >> + >> +@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 > > I know that since Linux 2.6 swapfile performance is not a big issue if > the file is unfragmented (and it'll be for sure on newly partitioned > filesystems) but AFAIU swap files are still a little bit problematic on > BTRFS > https://btrfs.wiki.kernel.org/index.php/FAQ#Does_Btrfs_support_swap_files.3F: Ok...maybe we could use ext4 for the swap file? Is there a better filesystem? Again does btrfs volume management allow the swap file to be ext4? Or do we have to use LVM? > From kernel 5.0+ btrfs have native swap files support, but with some > limitations. Swap file - must be fully allocated as NOCOW with no > compression on one device. > > > I've never tested a system with swap file on BTRFS but I think that your > instructions should add how to set NOCOW for the swap file. > > The above example could be: > > > @example > dd bs=1MiB count=1GiB if=/dev/zero of=/mnt/swapfile status=progress > mkswap --verbose /mnt/swapfile > chattr +C /mnt/swapfile > btrfs property set /mnt/swapfile compression none > @end example > > Final note: AFAIU BTRFS supports swap files ONLY in single device > settings (that is: NO swap file support on multi device settings), so > IMHO it's better to use a dedicated partition for the swap space so > users are free to switch to a multi-device setting if they wish (and > can). Ok, I will create a dedicated partition and format it with ext4 and the swap program...but I will probably need help figuring out how to encrypt the swap partition...There are guides online that I can look at... > The problem with a fully encrypted dedicated swap partition is that > it'll require a third passphrase prompt on boot (the one to unlock the > swap partition), but that's a minor annoyance IMHO. Oh no! I hadn't thought about that! grrr! I wonder if bcachefs is better than btrfs...well I guess it's not merged yet. What about instead of using a swap file we use zram? Or how about both? > What do you think? > > [...] > > Happy hacking! Gio' -- Joshua Branson (jab in #guix) Sent from Emacs and Gnus https://gnucode.me https://video.hardlimit.com/accounts/joshua_branson/video-channels https://propernaming.org "You can have whatever you want, as long as you help enough other people get what they want." - Zig Ziglar
Hi Joshua Joshua Branson <jbranso@dismail.de> writes: [...] >> Why using two BTRFS volumes on top of LVM and not directly using BTRFS >> (with subvolumes if you want) on top of /dev/mapper/partname? > > This is probably a good idea...however does the grub payload support > this? Do you mean: does grub support booting from encrypted BTRFS? The answer is yes. WARNING: I've (still) not tried myself to boot Guix System using an encrypted BTRFS (sub)volume but I'm pretty confident that Guix is configuring grub with the needed modules (luks and btrfs) [...] >> I'm still using LVM on some "legacy" systems but for new installations >> I'd strogly suggest starting using BTRFS on top of "physical" >> partitions. > > does btrfs volume manage allow use to use ext4, jfs, or xfs > filesystems? No: BTRFS is a volume manager and a filesystem "all in one", you cannot create a BRTFS subvolume and format it with another filesystem > Or does on LVM do that? LVM is "just" a volume manager with no idea about the overlaying filesystem [...] >> I know that since Linux 2.6 swapfile performance is not a big issue if >> the file is unfragmented (and it'll be for sure on newly partitioned >> filesystems) but AFAIU swap files are still a little bit problematic on >> BTRFS >> https://btrfs.wiki.kernel.org/index.php/FAQ#Does_Btrfs_support_swap_files.3F: > > Ok...maybe we could use ext4 for the swap file? Is there a better > filesystem? Again does btrfs volume management allow the swap file to > be ext4? No, al explained above > Or do we have to use LVM? If we use a dedicated partition for swap there is no need to set up an LVM volume (phisical, VG and then logical): we can just create a dedicate partition during partitioning, encrypt it with LUKS and "mkswap" it (e.g. mkswap /dev/mapper/<encrypted_swap>) [...] >> Final note: AFAIU BTRFS supports swap files ONLY in single device >> settings (that is: NO swap file support on multi device settings), so >> IMHO it's better to use a dedicated partition for the swap space so >> users are free to switch to a multi-device setting if they wish (and >> can). > > Ok, I will create a dedicated partition and format it with ext4 > and the swap program There's no need to format (mkfs.ext4) the partition with ext4, just "mkswap" it :-) > ...but I will probably need help figuring out how to encrypt > the swap partition...There are guides online that I can look at... You have to encrypt it like any other partition, e.g.: --8<---------------cut here---------------start------------->8--- Encrypt swap 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/<swap_partition> @end example Obtain and note down the UUID of the LUKS partition. @example cryptsetup --verbose luksUUID /dev/<swap_partition> @end example Open the encrypted partition, where @code{luks-uuid} is the LUKS UUID, and @code{crypt_swap01} is any desired name for the decrypted swap partition. @example cryptsetup --verbose luksOpen UUID=luks-uuid crypt_swap01 @end example Format the encrypted swap @example mkswap /dev/mapper/crypt_swap01 @end example --8<---------------cut here---------------end--------------->8--- Then, in our (operating-system) declaration, we have to use something like this: --8<---------------cut here---------------start------------->8--- (mapped-devices (list (mapped-device (source (uuid "LUKS-UUID")) (target "partname") (type luks-device-mapping)) ;; This is our new encrypted swap partition (mapped-device (source (uuid "SWAP-LUKS-UUID")) (target "crypt_swap01") (type luks-device-mapping)) (mapped-device (source "vgname") (targets (list "vgname-lvnameroot" "vgname-lvnamehome")) (type lvm-device-mapping)))) (swap-devices (list "/dev/mapper/crypt_swap01")) --8<---------------cut here---------------end--------------->8--- WARNING: please consider I've not tested this code. >> The problem with a fully encrypted dedicated swap partition is that >> it'll require a third passphrase prompt on boot (the one to unlock the >> swap partition), but that's a minor annoyance IMHO. > > Oh no! I hadn't thought about that! grrr! Actually what I said it's NOT true... or better: we could avoid the (third) password prompt for the swap partition if we _add_ a keyfile to the LUKS encrypted swap partition _and_ we have a mechanism to "luksOpen" that mapped volume using that keyfile. I'm not aware of such a mechanism on Guix Systems, in Debian (et al) this is done with /etc/crypttab, AFAIU the luks-device-mapping lacks the option to specify a keyfile. So, as far as this cookbook section is concerned, unfortunately when using a dedicated encrypted swap partition an additional passphrase prompt will be presented to the user at each boot. > I wonder if bcachefs is better than btrfs...well I guess it's not > merged yet. No, still not. AFAIU also still not available in Guix. > What about instead of using a swap file we use zram? Never used zram and I don't know if it's supported (I mean configured by (operating-system)) on Guix System [...] Sorry I've more issues than answers on this topics, nevertheless I hope it somway helps. Thanks! Gio'
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
July 21, 2021 6:50 PM, "Sarah Morgensen" <iskarian@mgsn.dev> wrote: > 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.) Thanks so much for you proof-reading! I'll update and push a new patch! > 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. That is an awesome idea! I will do so! > Hope that helps, > Sarah
Hi Joshua and all, jbranso@dismail.de skribis: > July 21, 2021 6:50 PM, "Sarah Morgensen" <iskarian@mgsn.dev> wrote: > >> 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.) > > Thanks so much for you proof-reading! I'll update and push a new patch! > >> 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. > > That is an awesome idea! I will do so! My main question would be: what do you think is not covered in the “Manual Installation” section? That section covers full disk encryption and other things you propose, such as partitioning, downloading the ISO, authenticating it, changing the keyboard layout, etc. From a maintenance perspective, it does not seem reasonable to maintain to similar pieces of documentation on these matters. From a user perspective, it could be confusing or downright deceiving if one of these two documents is out of date or erroneous. All in all, for the topic we’re discussing, I’d suggest consolidating existing material instead of writing new material. WDYT? Thanks, Ludo’.
August 11, 2021 10:17 AM, "Ludovic Courtès" <ludo@gnu.org> wrote: > Hi Joshua and all, > > jbranso@dismail.de skribis: > >> July 21, 2021 6:50 PM, "Sarah Morgensen" <iskarian@mgsn.dev> wrote: >> >>> 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.) >> >> Thanks so much for you proof-reading! I'll update and push a new patch! >> >>> 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. >> >> That is an awesome idea! I will do so! > > My main question would be: what do you think is not covered in the > “Manual Installation” section? > > That section covers full disk encryption and other things you propose, > such as partitioning, downloading the ISO, authenticating it, changing > the keyboard layout, etc. I think that libreboot does not currently support the latest version of encryption...or only supports LVM v1....something like that. Perhaps those "libreboot specific encryption commands" need not be in the official manual? > > From a maintenance perspective, it does not seem reasonable to maintain > to similar pieces of documentation on these matters. From a user > perspective, it could be confusing or downright deceiving if one of > these two documents is out of date or erroneous. I'm game for that. I personally find the "Manual Installation" section slightly too terse...I've successfully installed guix encrypted before, but I had to use the graphical installation. I have a hard time comprehending how to manually install an encrypted guix, but I also just have a very hard time understanding new guix things too. :) Perhaps, if the manual does not have it, we could provide an example config of an encrypted /home ? I feel like the majority of guix users do not use libreboot, so a encrypted / is not an option for most of them. > > All in all, for the topic we’re discussing, I’d suggest consolidating > existing material instead of writing new material. > > WDYT? > > Thanks, > Ludo’.
Hello! jbranso@dismail.de skribis: > August 11, 2021 10:17 AM, "Ludovic Courtès" <ludo@gnu.org> wrote: [...] >> My main question would be: what do you think is not covered in the >> “Manual Installation” section? >> >> That section covers full disk encryption and other things you propose, >> such as partitioning, downloading the ISO, authenticating it, changing >> the keyboard layout, etc. > > I think that libreboot does not currently support the latest version of > encryption...or only supports LVM v1....something like that. Perhaps those > "libreboot specific encryption commands" need not be in the official manual? Oh, right. Perhaps there could be a subsubsection next to “Disk Partitioning” & co. specifically about LibreBoot support? Would that make sense? >> From a maintenance perspective, it does not seem reasonable to maintain >> to similar pieces of documentation on these matters. From a user >> perspective, it could be confusing or downright deceiving if one of >> these two documents is out of date or erroneous. > > I'm game for that. I personally find the "Manual Installation" section > slightly too terse...I've successfully installed guix encrypted before, > but I had to use the graphical installation. I have a hard time > comprehending how to manually install an encrypted guix, but I also just > have a very hard time understanding new guix things too. :) If you could pinpoint specific things that are missing or too vague in that section, that’d be great. Of course we don’t want to explain too much in there because that’d be too much work, so this section assumes familiarity with GNU/Linux; and overall, we want to encourage users, both newbies and seasoned GNU/Linux users, to use the installer, because it’s so much more convenient. > Perhaps, if the manual does not have it, we could provide an example > config of an encrypted /home ? I feel like the majority of guix users > do not use libreboot, so a encrypted / is not an option for most of them. Why is it not an option? I use encrypted root without Libreboot and the installer offers that option. Thanks! Ludo’.
August 12, 2021 4:04 AM, "Ludovic Courtès" <ludo@gnu.org> wrote: > Hello! > > jbranso@dismail.de skribis: > >> August 11, 2021 10:17 AM, "Ludovic Courtès" <ludo@gnu.org> wrote: > > [...] > >>> My main question would be: what do you think is not covered in the >>> “Manual Installation” section? >>> >>> That section covers full disk encryption and other things you propose, >>> such as partitioning, downloading the ISO, authenticating it, changing >>> the keyboard layout, etc. >> >> I think that libreboot does not currently support the latest version of >> encryption...or only supports LVM v1....something like that. Perhaps those >> "libreboot specific encryption commands" need not be in the official manual? > > Oh, right. Perhaps there could be a subsubsection next to “Disk > Partitioning” & co. specifically about LibreBoot support? Would that > make sense? I'm game for that! If you think that belongs in the manual proper, I'm game to put it there! >>> From a maintenance perspective, it does not seem reasonable to maintain >>> to similar pieces of documentation on these matters. From a user >>> perspective, it could be confusing or downright deceiving if one of >>> these two documents is out of date or erroneous. >> >> I'm game for that. I personally find the "Manual Installation" section >> slightly too terse...I've successfully installed guix encrypted before, >> but I had to use the graphical installation. I have a hard time >> comprehending how to manually install an encrypted guix, but I also just >> have a very hard time understanding new guix things too. :) > > If you could pinpoint specific things that are missing or too vague in > that section, that’d be great. I was actually going to point out that the manual lacks an example config for encrypted /...but this is apparently not the case. 10.1 has such an example, and I'm delighted to see that the Manual Installation, specifically 3.6.2 Proceeding with the Installation links to 10.1, which has all of the example configs. That is super helpful! > Of course we don’t want to explain too much in there because that’d be > too much work, so this section assumes familiarity with GNU/Linux; and > overall, we want to encourage users, both newbies and seasoned GNU/Linux > users, to use the installer, because it’s so much more convenient. > >> Perhaps, if the manual does not have it, we could provide an example >> config of an encrypted /home ? I feel like the majority of guix users >> do not use libreboot, so a encrypted / is not an option for most of them. > > Why is it not an option? I use encrypted root without Libreboot and the > installer offers that option. Forgive me. This is an example of me not being very technical... I'm assuming that "encrypted /" is the same as "full disc encryption". That's my mistake. :) As stated above, the manual does have an example of encrypted /. :) > Thanks! > > Ludo’.
On 2021-08-12 10:04, Ludovic Courtès wrote: > Hello! > > jbranso@dismail.de skribis: > >> August 11, 2021 10:17 AM, "Ludovic Courtès" <ludo@gnu.org> wrote: > > [...] > >>> My main question would be: what do you think is not covered in the >>> “Manual Installation” section? >>> >>> That section covers full disk encryption and other things you >>> propose, >>> such as partitioning, downloading the ISO, authenticating it, >>> changing >>> the keyboard layout, etc. >> >> I think that libreboot does not currently support the latest version >> of >> encryption...or only supports LVM v1....something like that. Perhaps >> those >> "libreboot specific encryption commands" need not be in the official >> manual? > > Oh, right. Perhaps there could be a subsubsection next to “Disk > Partitioning” & co. specifically about LibreBoot support? Would that > make sense? > >>> From a maintenance perspective, it does not seem reasonable to >>> maintain >>> to similar pieces of documentation on these matters. From a user >>> perspective, it could be confusing or downright deceiving if one of >>> these two documents is out of date or erroneous. >> >> I'm game for that. I personally find the "Manual Installation" >> section >> slightly too terse...I've successfully installed guix encrypted >> before, >> but I had to use the graphical installation. I have a hard time >> comprehending how to manually install an encrypted guix, but I also >> just >> have a very hard time understanding new guix things too. :) > > If you could pinpoint specific things that are missing or too vague in > that section, that’d be great. > > Of course we don’t want to explain too much in there because that’d be > too much work, so this section assumes familiarity with GNU/Linux; and > overall, we want to encourage users, both newbies and seasoned > GNU/Linux > users, to use the installer, because it’s so much more convenient. > >> Perhaps, if the manual does not have it, we could provide an example >> config of an encrypted /home ? I feel like the majority of guix users >> do not use libreboot, so a encrypted / is not an option for most of >> them. > > Why is it not an option? I use encrypted root without Libreboot and > the > installer offers that option. Hi! Im happy to see this added to the cookbook. Just to clarify: with libreboot you can have the *entire* root partition encrypted without a separate boot partition (with /boot mounted under the encrypted root) - i.e. an actually fully encrypted disk (save the luks headers). So this is why you need to carefully setup the grub.cfg that's in libreboot's ROM (assuming you use Grub as payload) to use something like: cryptomount -a ; configfile (crypto0)/boot/grub/grub.cfg, so that you point to Guix's continuously updated version of grub.cfg inside the encrypted partition. If you want to have /boot on an encrypted partition without using libreboot, you need to pack crypttools or whatever (cryptomount command) to initrd which is generated with guile code. Guix currently don't offering such options to my knowledge. Related note: there has also been discussions in Grub dev mailing lists about adding the option to specify luks headers in grub.cfg which would allow for actual full disk encryption of internal drives (indistinguishable from random wiped disk), and then you could probably accomplish this by mounting /boot in your config.scm from external usb. This would also be a nice thing to add to the cookbook IMO (when that feature is available in Grub).
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, +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. + +Let us begin! + +@menu +* Create Boot-able USB:: +* Installing and Setup:: +* Tweaking Libreboot's Grub Payload:: +* Closing Thoughts:: +* Special Thanks:: +@end menu + +@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 +device letter. + +@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 + + +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; +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. + +@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" +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 +based process}. + +Set your keyboard layout, where @code{lo} is the two-letter keyboard +layout code (lower-case). + +@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. + +@example +ifconfig -v nwif up +@end example + +For wireless connection, follow the wireless setup. + +@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. + +@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. + +@example +dhclient -v nwif +@end example + +Obtain the device letter @code{/dev/sdX} in which you would like to deploy +and install Guix System, where “X” is the device letter. + +@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). + +@example +shred --verbose --random-source=/dev/urandom /dev/sdX +@end example + +Load the device-mapper module in the current kernel. + +@example +modprobe --verbose dm_mod +@end example + +Partition the device. Follow the prompts. Just do, GPT --> New --> +Write --> Quit; defaults will be set. + +@example +cfdisk /dev/sdX +@end example + +Obtain the partition number from the device, where “Y” is 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. + +@example +cryptsetup --verbose +luksOpen UUID=luks-uuid partname +@end example + +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. + +@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 +@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 + +Mount the filesystems under the current system. + +@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. + +@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 + +Create the system-wide configuration files directory. + +@example +mkdir --verbose /mnt/etc +@end example + +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. + +@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. + +@example +cryptomount -u luks-uuid +set root=(lvm/vgname-lvnameroot) +@end example + +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. + +Open terminal. + +Set passkey for the "root" user. Follow the prompts. + +@example +passwd root +@end example + +Set passkey for the "username" user. Follow the prompts. + +@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. + +@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. + +@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. + +@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. + +@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`. +@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 + +Reboot the device. +@example +reboot +@end example + +@node Closing Thoughts +@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: + +@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/}. + +@node Special Thanks +@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 @cindex wm
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(+)