path: root/content/posts/2022/2022-08-06-installing-gentoo-encrypted-zfs-efistub.md

---
date: 2022-11-20
title: "Installing Gentoo with encrypted ZFS rootfs and EFIstub kernel"
tags:
- GNU+Linux
- Gentoo
- Tutorial
- ZFS
---

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!

```sh
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.

```sh
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.

```sh
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!

```sh
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

```sh
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.

```sh
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.

```sh
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.

```sh
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.

```sh
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`.

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

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

### kernel

{{< admonition title="Note" >}}
This will build the initramfs twice, since emerging gentoo-kernel will build it
automagically. This can be "fixed" by removing a USE flag, but this is easier to
me.
{{</ admonition >}}

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.

```sh
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.