cheatsheets/guix.info

1 Guix System and Libreboot
***************************

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.  Advancers, 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:

* Preparation::
* Installation::
* Completion::
* Conclusion::
* References::
* Acknowledgements::
* License::


File: guix.info,  Node: Preparation,  Next: Installation,  Up: Guix System and Libreboot

1.1 Preparation
===============

In the current GNU+Linux system, open terminal as root user.

   Insert USB drive and get the device letter ‘/dev/sdX’, where “X” is
the device letter.

     lsblk --list

     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]

   Unmount the device just in case if it is auto-mounted.

     umount /dev/sdX --verbose

   Download the Guix System ISO installer package and it’s GPG
signature; where “a.b.c” is the version number and “sss” is the system
architecture.
     wget --verbose https://ftp.gnu.org/gnu/guix/guix-system-install-a.b.c.sss-linux.iso.xz
     wget --verbose https://ftp.gnu.org/gnu/guix/guix-system-install-a.b.c.sss-linux.iso.xz.sig

   Import the Guix’s public key.
     gpg --verbose --keyserver pool.sks-keyservers.net –-receive-keys 3CE464558A84FDC69DB40CFB090B11993D9AEBB5

   Verify the GPG signature of the downloaded package.
     gpg --verbose --verify guix-system-install-a.b.c.sss-linux.iso.xz.sig

   Extract ISO image from the downloaded package.
     xz --verbose --decompress guix-system-install-a.b.c.sss-linux.iso.xz

   Write the extracted ISO image to the drive.
     dd if=guix-system-install-a.b.c.sss-linux.iso of=/dev/sdX status=progress; sync

   Reboot the device.
     reboot


File: guix.info,  Node: Installation,  Next: Completion,  Prev: Preparation,  Up: Guix System and Libreboot

1.2 Installation
================

On reboot, as soon as the Libreboot’s graphic art appears, press "S" or
choose ‘Search for GRUB2 configuration on external media [s]’.  Wait for
the Guix System from USB drive to load.

   Once Guix System installer starts, choose "Install using the shell
based process".

   Set your keyboard layout, where “lo” is the two-letter keyboard
layout code (lower-case).
     loadkeys --verbose lo

   Unblock network interfaces.
     rfkill unblock all

   Get the names of network interfaces.
     ifconfig -v -a

     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:58799 errors:0 dropped:71 overruns:0 frame:0
               TX packets:32519 errors:0 dropped:0 overruns:0 carrier:0
               collisions:0 txqueuelen:1000
               RX bytes:44632193  TX bytes:4816175


   Bring the desired network interface (wired or wireless) up, where
“nwif” is the network interface name.
     ifconfig -v nwif up

   For wireless connection, follow the wireless setup.

* Menu:

* Wireless Setup::


File: guix.info,  Node: Wireless Setup,  Up: Installation

1.2.1 Wireless Setup
--------------------

Create a configuration file using text editor, where “fname” is any
desired name for file.
     nano fname.conf

   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:

     network={
       ssid="net"
       key_mgmt=WPA-PSK
       psk="pass"
     }

   (or)

   For most public networks:

     network={
       ssid="net"
       key_mgmt=NONE
     }

   (or)

   For most organizational networks:
     network={
       ssid="net"
       scan_ssid=1
       key_mgmt=WPA-EAP
       identity="uid"
       password="pass"
       eap=PEAP
       phase1="peaplabel=0"
       phase2="auth=MSCHAPV2"
     }

   Connect to the configured network.
     wpa_supplicant -B -c fname.conf -i nwif

   Assign an IP address to the network interface.
     dhclient -v nwif

   Obtain the device letter ‘/dev/sdX’ in which you would like to deploy
and install Guix System, where “X” is the device letter.
     lsblk --list

     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]

   Wipe the device (Ignore if the device is new).
     shred --verbose --random-source=/dev/urandom /dev/sdX

   Load the device-mapper module in the current kernel.
     modprobe --verbose dm_mod

   Partition the device.  Follow the prompts.  Just do, GPT –> New –>
Write –> Quit; defaults will be set.
     cfdisk /dev/sdX
     #+END_SRC>

     Obtain the partition number from the device, where “Y” is the
     partition number.
     #+BEGIN_SRC sh :results output :exports both
     lsblk --list
     #+END_SRC>

     Encrypt the partition. Follow the prompts.
     #+BEGIN_SRC sh :results output :exports both
     cryptsetup --verbose --hash whirlpool --cipher serpent-xts-plain64 --verify-passphrase --use-random --key-size 512 --iter-time 500 luksFormat /dev/sdXY
     #+END_SRC>

     Obtain and note down the UUID of the LUKS partition.
     #+BEGIN_SRC sh :results output :exports both
     cryptsetup --verbose luksUUID /dev/sdXY
     #+END_SRC>

     Open the encrypted partition, where "luks-uuid" is the LUKS UUID and
     “partname” is any desired name for partition.  cryptsetup --verbose
     #+BEGIN_SRC sh :results output :exports both
     luksOpen UUID=luks-uuid partname
     #+END_SRC>

     Create a physical volume in the partition.
     #+BEGIN_SRC sh :results output :exports both
     pvcreate /dev/mapper/partname --verbose
     #+END_SRC>

     Create a volume group in the physical volume, where "vgname" is any desired name for volume group.
     #+BEGIN_SRC sh :results output :exports both
     vgcreate vgname /dev/mapper/partname --verbose
     #+END_SRC>

     Create logical volumes in the volume group; where "num" is the number
     for space in GB, and "lvnameroot" and "lvnamehome" are any desired
     names for root and home volumes respectively.
     #+BEGIN_SRC sh :results output :exports both
     lvcreate --extents 25%VG vgname --name lvnameroot --verbose
     lvcreate --extents 100%FREE vgname --name lvnamehome --verbose
     #+END_SRC>

     Create filesystems on the logical-volumes, where "fsnameroot" and
     "fsnamehome" are any desired names for root and home filesystems
     respectively.
     #+BEGIN_SRC sh :results output :exports both
     mkfs.btrfs --metadata dup --label fsnameroot /dev/vgname/lvnameroot
     mkfs.btrfs --metadata dup --label fsnamehome /dev/vgname/lvnamehome
     #+END_SRC>

     Mount the filesystems under the current system.
     #+BEGIN_SRC sh :results output :exports both
     mount --label fsnameroot --target /mnt --types btrfs --verbose
     mkdir --verbose /mnt/home && mount --label fsnamehome --target /mnt/home --types btrfs --verbose
     #+END_SRC>

     Create a swap file.
     #+BEGIN_SRC sh :results output :exports both
     dd bs=1MiB count=1GiB if=/dev/zero of=/mnt/swapfile status=progress
     mkswap --verbose /mnt/swapfile
     #+END_SRC>

     Make the swap file readable and writable only by root account.
     #+BEGIN_SRC sh :results output :exports both
     chmod --verbose 600 /mnt/swapfile
     #+END_SRC>

     Activate the swap file.
     #+BEGIN_SRC sh :results output :exports both
     swapon --verbose /mnt/swapfile
     #+END_SRC>

     Make the installation packages to be written on the mounted root
     filesystem.
     #+BEGIN_SRC sh :results output :exports both
     herd start cow-store /mnt
     #+END_SRC>


     Create the system-wide configuration files directory.
     #+BEGIN_SRC sh :results output :exports both
     mkdir --verbose /mnt/etc
     #+END_SRC>

     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.
     #+BEGIN_SRC sh :results output :exports both
     nano /mnt/etc/config.scm
     #+END_SRC>

     Snippet:
     #+BEGIN_SRC scheme

     (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
          "iomem=relaxed")
         %default-kernel-arguments))
       (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))
       (timezone "Zone/SubZone")
       (locale "ab_XY.1234")
       (name-service-switch %mdns-host-lookup-nss)
       (services
        (append
         (list
          (service gnome-desktop-service-type))
         %desktop-services)))

   Initialize new Guix System.  #+BEGIN_SRC sh :results output :exports
both guix system init /mnt/etc/config.scm /mnt #+END_SRC>

   Reboot the device.  #+BEGIN_SRC sh :results output :exports both
reboot #+END_SRC>


File: guix.info,  Node: Completion,  Next: Conclusion,  Prev: Installation,  Up: Guix System and Libreboot

1.3 Completion
==============

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.  #+BEGIN_SRC sh :results output :exports both cryptomount -u
luks-uuid set root=(lvm/vgname-lvnameroot) #+END_SRC>

   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.  #+BEGIN_SRC sh
:results output :exports both passwd root #+END_SRC>

   Set passkey for the "username" user.  Follow the prompts.
#+BEGIN_SRC sh :results output :exports both passwd username #+END_SRC>

   Install flashrom and wget.  #+BEGIN_SRC sh :results output :exports
both guix package –-install flashrom wget #+END_SRC>

   Obtain the ROM chip’s model and size.  Look for the output line
“Found [...] flash chip [...]”.  #+BEGIN_SRC sh :results output :exports
both flashrom –verbose –programmer internal #+END_SRC>

   Download Libreboot ROM and utilities, where "YYYYMMDD" is the release
date, ‘devmod’ is the device model and "N" is the ROM chip size.
#+BEGIN_SRC sh :results output :exports both 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_SRC>

   Extract the downloaded files.  #+BEGIN_SRC sh :results output
:exports both tar –extract
–file=libreboot_rYYYYMMDD_grub_devmod_Nmb.tar.xz –verbose tar –extract
–file=libreboot_rYYYYMMDD_util.tar.xz –verbose #+END_SRC>

   Rename the directories of extracted files.  #+BEGIN_SRC sh :results
output :exports both mv –verbose
"libreboot_rYYYYMMDD_grub_devmod_Nmb.tar.xz" "libreboot_rom" mv –verbose
"libreboot_rYYYYMMDD_util" "libreboot_util" #+END_SRC>

   Copy the ROM image to the directory of cbfstool, where "kbdlo" is the
keyboard layout and "arch" is the system architecture.  #+BEGIN_SRC sh
:results output :exports both cp
libreboot_rom/devmod_Nmb_kbdlo_vesafb.rom
libreboot_util/cbfstool/arch/libreboot.rom #+END_SRC>

   Change directory to the directory of cbfstool.  #+BEGIN_SRC sh
:results output :exports both cd libreboot_util/cbfstool/arch/
#+END_SRC>

   Extract the GRUB configuration file from the image.  #+BEGIN_SRC sh
:results output :exports both ./cbfstool libreboot.rom extract -n
grub.cfg -f grub.cfg #+END_SRC>

   Edit the GRUB configuration file and insert the following code
snippet above the line ‘“menuentry 'Load Operating System [o]'
--hotkey='o' --unrestricted { [...] }”’.  #+BEGIN_SRC sh :results output
:exports both nano grub.cfg #+END_SRC>

   Snippet:
     menuentry ‘Guix System (An advanced distribution of the GNU operating system) [g]’ --hotkey=’g’ --unrestricted
     {
     cryptomount -u luks-uuid
     set root=(lvm/vgname-lvnameroot)
     configfile /boot/grub/grub.cfg
     }

   Remove the old GRUB configuration file from the ROM image.
#+BEGIN_SRC sh :results output :exports both ./cbfstool libreboot.rom
remove -n grub.cfg #+END_SRC>

   Insert the new GRUB configuration file into the ROM image.
#+BEGIN_SRC sh :results output :exports both ./cbfstool libreboot.rom
add -n grub.cfg -f grub.cfg -t raw #+END_SRC>

   Move the ROM image to the directory of ich9gen.  #+BEGIN_SRC sh
:results output :exports both mv libreboot.rom
~/libreboot_util/ich9deblob/arch/libreboot.rom #+END_SRC>

   Change directory to the directory of ich9gen.  #+BEGIN_SRC sh
:results output :exports both cd ~/libreboot_util/ich9deblob/arch/
#+END_SRC>

   Generate descriptor+GbE images with the MAC address, where "mac-addr"
is the MAC address of the machine.  #+BEGIN_SRC sh :results output
:exports both ich9gen –macaddress mac-addr #+END_SRC>

   Insert the descriptor+GbE image into the ROM image, where "N" is the
ROM chip size.  #+BEGIN_SRC sh :results output :exports both dd bs=12k
conv=notrunc count=1 if=ich9fdgbe_Nm.bin of=libreboot.rom
status=progress #+END_SRC>

   Move the ROM image to the directory of flash.  #+BEGIN_SRC sh
:results output :exports both mv libreboot.rom
~/libreboot_util/libreboot.rom #+END_SRC>

   Change directory to the directory of flash.  #+BEGIN_SRC sh :results
output :exports both cd ~/libreboot_util #+END_SRC>

   Modify the shebang of flash script, from ‘#!/bin/bash‘ to
‘#!/bin/sh‘.  #+BEGIN_SRC sh :results output :exports both nano flash
#+END_SRC>

   Flash the ROM with the new image.  #+BEGIN_SRC sh :results output
:exports both ./flash update libreboot.rom #+END_SRC>

   (or)

   #+BEGIN_SRC sh :results output :exports both ./flash forceupdate
libreboot.rom #+END_SRC>

   Reboot the device.  #+BEGIN_SRC sh :results output :exports both
reboot #+END_SRC>


File: guix.info,  Node: Conclusion,  Next: References,  Prev: Completion,  Up: Guix System and Libreboot

1.4 Conclusion
==============

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.

   Generally, you will be using Libreboot’s initial/default grub.cfg,
whose Guix menu-entry invokes Guix’s grub.cfg located at ‘/boot/grub/’.
For trouble-shooting, you can also use Libreboot’s ‘grubtest.cfg’, which
hasn’t been modified.

   That is it!  You have now setup Guix System with Full Disk Encryption
on your device powered by Libreboot.  Enjoy!


File: guix.info,  Node: References,  Next: Acknowledgements,  Prev: Conclusion,  Up: Guix System and Libreboot

1.5 References
==============

[1] Guix manual (<http://guix.gnu.org/manual/en/>).

   [2] Libreboot documentation (<https://libreboot.org/docs/>).


File: guix.info,  Node: Acknowledgements,  Next: License,  Prev: References,  Up: Guix System and Libreboot

1.6 Acknowledgements
====================

[1] Thanks to Guix developer, Clement Lassieur (clement@lassieur.org),
for helping me with the Scheme code for the bootloader configuration.

   [2] Thanks to Libreboot founder and developer, Leah Rowe
(leah@libreboot.org), for helping me with the understanding of
Libreboot’s functionalities.


File: guix.info,  Node: License,  Prev: Acknowledgements,  Up: Guix System and Libreboot

1.7 License
===========

This work by Raghav Gururajan is licensed under the Creative Commons
Attribution-ShareAlike 4.0 International License.

   To view a copy of this license, visit
<https://creativecommons.org/licenses/by-sa/4.0/>



Tag Table:
Node: Top69
Node: Guix System and Libreboot420
Node: Preparation1429
Node: Installation2988
Node: Wireless Setup5107
Node: Completion12928
Node: Conclusion17953
Node: References18791
Node: Acknowledgements19054
Node: License19505

End Tag Table


Local Variables:
coding: utf-8
End: