ZFS/rootfs

This article is focused on using ZFS as the rootfs on Gentoo and designed to be used with the Handbook. Over time more advanced setups will be added so please check the TODO section to see if there is something that can be added to improve this article.

Partitions

Layout

Follow the Handbook section on Preparing the disks returning at the creating file systems section.

This guide will be using the example below however it should be simple enough to adapt this to the user's needs.

/dev/sda1   | 1024 MiB      | EFI System Partition   | /efi
/dev/sda2   | 2048 MiB      | swap                   | swap
/dev/sda3   | Rest of Disk  | ZFS Partition          | /, /boot, /home, ...

Boot

Create a 1GB FAT32 filesystem:

Swap

Swap performance on a ZFS partition is known to be poor and using a swapfile is not supported, instead it is recommended to use its own partition.

ZFS Setup

Generate host ID

Randomly generate host ID into /etc/hostid allowing output overwrite.

Alternatively, set a specific host ID, 0x00bab10c in this example.

Create a ZFS pool

Load ZFS kernel module and create a ZFS pool tank on /dev/sda3.

-o ashift=12 \
-o autotrim=on \
-o compatibility=grub2 \
-O acltype=posixacl \
-O xattr=sa \
-O relatime=on \
-O compression=lz4 \

Alternative: Create a ZFS pool with LUKS encryption

Using LUKS involves creating an encrypted container on the physical partition first, then placing the ZFS pool inside that container.

Prepare the encrypted partition

First, initialize the physical partition (e.g., /dev/sda3) with LUKS. You will be prompted to set a password.

Open the encrypted device. This creates a virtual block device at /dev/mapper/cryptroot.

Create the ZFS pool on LUKS

Now, create the pool using the mapper device instead of the raw partition.

-o ashift=12 \
-o autotrim=on \
-o compatibility=grub2 \
-O acltype=posixacl \
-O xattr=sa \
-O relatime=on \
-O compression=lz4 \

After this, proceed to Create ZFS file systems as usual. Note that you will need to unlock this partition every time you import the pool manually.

Update Dracut and Bootloader

For the system to boot, the initramfs must know how to unlock the LUKS device.

1. Find the UUID of your physical partition (e.g., /dev/sda3):

2. Add the crypt module to your Dracut configuration in /etc/dracut.conf.d/zol.conf:

nofsck="yes"
add_dracutmodules+=" zfs crypt "

3. Add the LUKS UUID to your kernel command line. For GRUB, edit /etc/default/grub:

GRUB_CMDLINE_LINUX="rd.luks.uuid=YOUR-UUID-HERE"

Replace YOUR-UUID-HERE with the UUID from the blkid command. Finally, rebuild your initramfs and update your bootloader configuration.

Alternative: Create a ZFS pool with native encryption

Native ZFS encryption can also be used by adding additional options when creating our zpool.

-o ashift=12 \
-o autotrim=on \
-o compatibility=openzfs-2.1-linux \
-O acltype=posixacl \
-O xattr=sa \
-O relatime=on \
-O compression=lz4 \
-O encryption=aes-256-gcm \
-O keylocation=prompt \
-O keyformat=passphrase \

Create ZFS file systems

This guide will be only creating root and home file systems. However, the user is free to create additional file systems if desired.

Set the preferred boot file system of the pool.

Export and re-import a pool, mount file systems

To export and re-import a pool with a specified mountpoint and without automatically mounting the file systems, run the following commands.

It is then possible to mount root and home file systems.

If you followed the example you can also mount your efi partition.

After mounting the file systems, it is advisable to verify mountpoints by checking the output of the command below.

Here is an example of the command output in case of successful mounting of file systems.

tank/os/gentoo /mnt/gentoo type zfs (rw,relatime,xattr,posixacl)
tank/home on /mnt/gentoo/home type zfs (rw,relatime,xattr,posixacl)

Update device symbolic links:

Return to the Handbook - EFI_system_partition_filesyste and return just before entering chroot command.

Copy host ID file

Return to Handbook - Installing Gentoo base system and return here at Kernel configuration and compilation.

Kernel

The user can choose between manually configured kernel or the distribution kernel.

Distribution kernel

Enabling USE flag

If using the distribution kernel then the dist-kernel USE flag will need to be enabled:

USE="dist-kernel"

Installing distribution kernel

Or, if you prefer using the pre-compiled binary,

Manual kernel config

configure the kernel as desired, save and build ( do not install yet )

install the zfs package ( if a kernel version error appears use the previous version )

then add zfs kernel module in dracut as shown previusly also write root=ZFS=tank/os/gentoo to /etc/cmdline or the initramfs will refuse to build now build and install, use installkernel for simplicity sake ( dracut and grub use flags enabled )

everytime the gentoo-sources are emerged or the kernel config is changed you have to repeat this or it won't boot

ZFS userland utilities and kernel module

The sys-fs/zfs package is necessary to allow your system to interact with and manage your ZFS pools. Make sure the module flag is set

Initramfs

Configure Dracut

Create a directory for Dracut configuration files if it does not exist.

Then, create a file zol.conf with the following content in this directory:

nofsck="yes"
add_dracutmodules+=" zfs "

Build the initramfs for the distribution kernel

Or, if the binary version was installed,

You can return to the Handbook - Configuring the system and return here at Configuring the bootloader.

Bootloader

ZFSBootMenu

An overview of the ZFSBootMenu installation is given here, but a more in depth guide can be found at ZFS/ZFSBootMenu

Setting kernel command-line

Mounting the EFI System Partition

If the ESP was not mounted previously, it is necessary to do it now:

Installing ZFSBootMenu (from source)

ZFSBootMenu ebuild is available in the GURU repository, which has to be added first, if not done already:

The package then needs to be unmasked.

sys-boot/zfsbootmenu ~amd64

sys-boot/zfsbootmenu can then be installed.

After that, the ZFSBootMenu configuration needs to be adjusted in order to:

• Enable automatic management of images: ManageImages:true
• Point to the EFI mount point: BootMountPoint: /efi
• Enable EFI binary generation: Enabled: true in the EFI section

Global:
  ManageImages: true
  BootMountPoint: /efi
  DracutConfDir: /etc/zfsbootmenu/dracut.conf.d
  PreHooksDir: /etc/zfsbootmenu/generate-zbm.pre.d
  PostHooksDir: /etc/zfsbootmenu/generate-zbm.post.d
  InitCPIOConfig: /etc/zfsbootmenu/mkinitcpio.conf
Components:
  ImageDir: /efi/EFI/BOOT
  Versions: 3
  Enabled: true
EFI:
  ImageDir: /efi/EFI/BOOT
  Stub: /usr/lib/systemd/boot/efi/linuxx64.efi.stub
  Versions: false
  Enabled: true
Kernel:
  CommandLine: ro loglevel=0

Then the bootloader image needs to be generated:

This will output an EFI image to /efi/EFI/BOOT/vmlinuz.EFI, which can then be copied to /efi/EFI/BOOT/BOOTX64.EFI, or sys-boot/efibootmgr can be used.

Installing ZFSBootMenu (prebuilt)

Create a directory for the bootloader and download the EFI binary into it.

Creating an EFI boot entry

Install the package sys-boot/efibootmgr.

Then, an EFI boot entry can be created with the following command, if ZFSBootMenu was built from source:

Otherwise, in case the prebuilt ZFSBootMenu binary is used:

Optional: Native Encryption

If you've opted for native encryption when you set up your zpool as described in Alternative: Create a ZFS pool with native encryption, it is possible to set up ZFSBootMenu to prompt for the passphrase once and have dracut have access to encryption keys at boot, or alternatively by setting the org.zfsbootmenu:keysource attribute and storing encryption keys on a separate dataset.

See the ZFSBootMenu documentation for info on how to properly set this up.

Limine

Limine is a modern, advanced, portable, multiprotocol bootloader and boot manager which also provides the reference implementation of the Limine boot protocol.

Follow the Limine article and making sure to follow the Limine#Using_Limine_With_ZFS_Root section.

Grand Unified Bootloader (GRUB)

Enable ZFS support for GRUB

Set the libzfs flag on the sys-boot/grub package to enable support for ZFS (by building sys-fs/zfs and sys-fs/zfs-kmod):

Build GRUB with ZFS support

Ensure the GRUB_PLATFORMS setting is properly configured for systems with EFI partition

Build the sys-boot/grub package:

Install GRUB to mounted EFI partition

Add CMDLINE for first boot only

execute "grub-mkconfig -o /boot/grub/grub.cfg" and when booting into gentoo remove it and reconfigure grub again with the command above

Finalize setup

Add the zfs-import and zfs-mount to boot service, otherwise the system will not boot.

OpenRC

Rebooting the system

Exit the chrooted environment and unmount all mounted partitions, do not forget to export the pool. After that, the system can be rebooted.

Gentoo doesn't boot after reboot

Press E key in the grub entry and add "refresh" to the cmdline

TODO

Sections needed to be added for a more complete guide

• Add instructions for alternative bootloaders
• Add instructions for ZFSBootMenu installation via generate-zbm (likely requires using GURU)