From Gentoo Wiki
Jump to:navigation Jump to:search
See also
For those looking to find general information on using ZFS on Linux then please see the ZFS page instead.

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.

Live Media

Currently only the admincd includes the zfs tools required to setup as root.



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                     | /boot
/dev/sda2   | 2048 MiB      |   swap                                     | swap
/dev/sda3   | Rest of Disk  |   ZFS (or Encrypted ZFS)                   | /, /home, ...

Create a 1GB FAT32 filesystem:

root #mkfs.vfat /dev/sda1

Swap performance on a ZFS partition is known to be poor and using a swapfile isn't supported, instead it is recommended to use it's own partition.

root #mkswap /dev/sda2
root #swapon /dev/sda2
Alternately, ZRAM could be used on systems with a large amount of RAM but do note ZFS will cache data to RAM for speed.

ZFS Setup

Create a Zpool
root #modprobe zfs
root #zpool create -f -o ashift=12 -o cachefile= -O compression=lz4 -O atime=off -m none -R /mnt/gentoo tank /dev/sda3
Create ZFS Datasets

This guide will be only creating a root and /home dataset however the user is free to create any extras that is needed.

root #zfs create tank/os
root #zfs create -o mountpoint=/ tank/os/main
root #zfs create -o mountpoint=/home tank/home

Return to the Handbook - Installing the Gentoo installation files and return just before entering chroot command.

Copy Zpool Cache
root #mkdir /mnt/gentoo/etc/zfs
root #cp /etc/zfs/zpool.cache /mnt/gentoo/etc/zfs

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


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


If using the dist-kernel then the useflag dist-kernel will need to be added to make.conf:

FILE /etc/portage/make.confmake.conf - example
Emerge dist-kernel
root #emerge -av sys-kernel/gentoo-kernel

Or, if you prefer using the precompiled binary,

root #emerge -av sys-kernel/gentoo-kernel-bin

ZFS program and kernel module

The sys-fs/zfs and sys-fs/zfs-kmod packages are necessary to allow your system to interact with and manage your ZFS pools.

root #emerge -av sys-fs/zfs sys-fs/zfs-kmod


Configure dracut

Tell Dracut to include the ZFS module to the initramfs.

FILE /etc/dracut.conf
add_dracutmodules+=" zfs "
Build the initramfs for the dist-kernel
root #emerge --config gentoo-kernel