Installing Gentoo with encrypted ZFS rootfs and EFIstub kernel

A little while ago, I got a new work laptop. As is customary, I installed my preferred GNU+Linux environment onto it. Consequently, a few people have asked me to detail my steps to get this system up and running, as they would like to try out a similar setup as I did. It’s also been a while since I made another blog post, so here’s killing two birds with one stone!

Preparing disks

Make sure you get the right device name, or you’ll purge the data on some other drive!

parted -a optimal /dev/nvme1n1
mklabel gpt
mkpart esp      1  5130
mkpart rootfs 5130   -1
set 1 boot on
quit

Get IDs of partitions

For partitioning I’ve lately come to love using disk IDs, rather than their /dev/sd* entries. They’re easy to look up, so copy them over to use them later on.

ls -l /dev/disk/by-id

• nvme-eui.36483331545090280025385800000001-part1 -> ESP
• nvme-eui.36483331545090280025385800000001-part2 -> ZFS

Formatting

ESP

The ESP partition holds the kernel and initramfs, and must be FAT32.

mkfs.vfat -F32 /dev/disk/by-id/nvme-eui.36483331545090280025385800000001-part1

zpool

The zpool settings used here are the settings I used. You should verify these settings also work optimally for your setup! I generally name my pools after the device they’re running from, in this case ivdea. Any name will work here, just make sure to be consistent later down the guide!

rm -f /etc/hostid && zgenhostid

zpool create -f \
    -O acltype=posixacl \
    -O compression=lz4 \
    -O dedup=off \
    -O encryption=aes-256-gcm \
    -O keyformat=passphrase \
    -O keylocation=prompt \
    -O relatime=on \
    -O xattr=sa \
    -R /mnt/gentoo \
    -m none \
    -o ashift=12 \
    -o cachefile=/etc/zfs/zpool.cache \
    ivdea0 \
        /dev/disk/by-id/nvme-eui.36483331545090280025385800000001-part2

zfs create -o mountpoint=none       ivdea0/rootfs
zfs create -o mountpoint=/          ivdea0/rootfs/gentoo
zfs create -o mountpoint=none       ivdea0/rootfs/gentoo/usr
zfs create -o mountpoint=none       ivdea0/rootfs/gentoo/var
zfs create -o mountpoint=none       ivdea0/rootfs/gentoo/var/lib
zfs create -o mountpoint=none       ivdea0/home
zfs create -o mountpoint=/home/tyil ivdea0/home/tyil

zpool set bootfs=ivdea0/rootfs/gentoo ivdea0

Preparing chroot

You will want to grab the latest Gentoo autobuild tarball for your architecture. I’m not using systemd, if you do desire this for some reason, you may need to alter some steps.

Initial

cd /mnt/gentoo
mkdir efi
mount /dev/disk/by-id/nvme-eui.36483331545090280025385800000001-part1 efi
wget $STAGE3 # Use whichever URL for the stage3 tarball you need
tar xpf stage3*.tar.xz --xattrs-include='*.*' --numeric-owner

Recovery

This section is labeled “Recovery” to easily find it later, in case you need to go back into the chroot to fix up any issues that prevent you from booting it.

mkdir -p etc/zfs
cp /etc/zfs/zpool.cache etc/zfs
cp --dereference /etc/resolv.conf /mnt/gentoo/etc/
mount -t proc /proc proc
mount --rbind --make-rslave /sys sys
mount --rbind --make-rslave /dev dev
mount --rbind --make-rslave /run run
chroot . /bin/bash -l

Configuring the system

The base system is now installed, and most of the following steps are for configuring it to actually work properly.

Portage

Run the initial Portage tree download. This will use webrsync, you can configure it to use git at a later stage if desired.

mkdir -p /etc/portage/repos.conf
cp /usr/share/portage/config/repos.conf /etc/portage/repos.conf/gentoo.conf
emerge-webrsync

Editor

Ofcourse, you can stick to nano, but I’ve been a vim guy for a very long time now, and without it I feel sad. It is the first thing I install, to make the rest of the configuration easier to do, by virtue of having the best editor available.

emerge vim

Once vim (or whichever worse editor you prefer) is installed, you can go around editing configuration files as needed.

locale

Enable all the locales you desire in /etc/locale.gen. Once all the desird locales are uncommented, you can generate the locales with locale-gen. You will most likely also want to add the locales to the L10N variable in your make.conf.

timezone

Set your timezone by making /etc/localtime a symlink to the timezone you use.

ln -fs /usr/share/zoneinfo/Europe/Amsterdam /etc/localtime

hostname

Set the machine’s short hostname in /etc/conf.d/hostname first, then add your hostname aliases to /etc/hosts.

# /etc/conf.d/hostname
hostname="ivdea"

# /etc/hosts
127.0.0.1  ivdea.tyil.net ivdea
::1        ivdea.tyil.net ivdea

kernel

By the time you’re reading this, the kernel version used here is probably outdated. You will want to update it to whichever kernel version you’re going to use.

emerge \
    busybox \
    dracut \
    efibootmgr \
    gentoo-kernel \
    intel-microcode \
    linux-firmware

emerge sys-fs/zfs-kmod sys-fs/zfs
emerge --config gentoo-kernel

rc-update add zfs-import boot
rc-update add zfs-mount boot
rc-update add zfs-share default
rc-update add zfs-zed default

zgenhostid

cp /boot/vmlinuz-5.15.59-gentoo-dist /efi/efi/gentoo/vmlinuz-5.15.59-gentoo-dist.efi
cp /boot/initramfs-5.15.59-gentoo-dist /efi/efi/gentoo/initramfs-5.15.59-gentoo-dist.img

efibootmgr \
    --disk /dev/disk/by-id/nvme-eui.36483331545090280025385800000001 \
    --part 1 \
    --create \
    --label "Gentoo ZFS 5.15.59" \
    --loader 'efi\gentoo\vmlinuz-5.15.59-gentoo-dist.efi' \
    --unicode \
    'dozfs root=ZFS=ivdea0/rootfs/gentoo ro initrd=\efi\gentoo\initramfs-5.15.59-gentoo-dist.img encrypted'

Root password

Set the root password using passwd. This would also be a good time to add any other users you want to use, and configure them with the correct permissions and groups.

Misc

If you have any other software requirements, such as wireless network management or privilege escalation utilities, this is the most appropriate time to install and configure them.

Reboot

Now you can reboot into the system, and be done with this guide. If anything isn’t working properly, return to the “Recovery” step and fix any outstanding issues.