ZFS
ZFS, also known as OpenZFS, is a modern filesystem which is well supported on NixOS.
Guides
Installation
Start from here in the NixOS manual [1] and under manual partitioning [2] do this instead:
Partition your disk with an boot and an zfs partition with your favorite partition tool.
Eg. 1G for boot partion, rest for zfs.
Example output from fdisk:
fdisk /dev/nvme0n1
Command (m for help): p
Disk /dev/nvme0n1: 931.51 GiB, 1000204886016 bytes, 1953525168 sectors
...
Device Start End Sectors Size Type
/dev/nvme0n1p1 2048 2099199 2097152 1G EFI System
/dev/nvme0n1p2 2099200 1953523711 1951424512 930.5G Linux filesystem
Note: Remember to set boot partition (first partition) to "EFI System" type
Make zfs pool with encryption and mount points:
Note: zpool config can significantly affect performance (especially the ashift option) so you may want to do some research. The ZFS tuning cheatsheet or ArchWiki is a good place to start.
zpool create -O encryption=on -O keyformat=passphrase -O keylocation=prompt -O compression=on -O mountpoint=none -O xattr=sa -O acltype=posixacl -o ashift=12 zpool /dev/nvme0n1p2
zfs create -o mountpoint=legacy zpool/root
zfs create -o mountpoint=legacy zpool/nix
zfs create -o mountpoint=legacy zpool/var
zfs create -o mountpoint=legacy zpool/home
mkdir /mnt/root
mount -t zfs zpool/root /mnt
mkdir /mnt/nix /mnt/var /mnt/home
mount -t zfs zpool/nix /mnt/nix
mount -t zfs zpool/var /mnt/var
mount -t zfs zpool/home /mnt/home
Output from zpool status:
zpool status
pool: zpool
state: ONLINE
...
config:
NAME STATE READ WRITE CKSUM
zpool ONLINE 0 0 0
nvme-eui.0025384b21406566-part2 ONLINE 0 0 0Make fat filesystem on boot partition
mkfs.fat -F 32 -n boot /dev/nvme0n1p1
Installation:
Install: [3]
Jump to "2. UEFI systems"
mkdir -p /mnt/boot
mount /dev/disk/by-label/boot /mnt/boot
Jump to "4." ... /mnt/etc/nixos/configuration.nix ...
Continue from here and add this boot loader and filesystems config to your configuration.nix:
# Boot loader config for configuration.nix:
boot.loader.grub = {
enable = true;
zfsSupport = true;
efiSupport = true;
efiInstallAsRemovable = true;
mirroredBoots = [
{ devices = [ "nodev"]; path = "/boot"; }
];
};
fileSystems."/" =
{ device = "zpool/root";
fsType = "zfs";
};
fileSystems."/nix" =
{ device = "zpool/nix";
fsType = "zfs";
};
fileSystems."/var" =
{ device = "zpool/var";
fsType = "zfs";
};
fileSystems."/home" =
{ device = "zpool/home";
fsType = "zfs";
};
fileSystems."/boot" =
{ device = "/dev/disk/by-uuid/2A11-F4EF";
fsType = "vfat";
};
swapDevices = [ ];
Note: Remove / comment out boot.loader.systemd-boot.enable = true; config if added bynixos-generate-config
Installation (alternative)
Alternative guide for a NixOS installation with ZFS is maintained at OpenZFS Documentation (Getting Started for NixOS)
Tips
Importing pools at boot
If you create a zpool, it will not be imported on the next boot unless you either add the zpool name to boot.zfs.extraPools:
## In /etc/nixos/configuration.nix:
boot.zfs.extraPools = [ "zpool_name" ];
or if you are using legacy mountpoints, add a fileSystems entry and NixOS will automatically detect that the pool needs to be imported:
## In /etc/nixos/configuration.nix:
fileSystems."/mount/point" = {
device = "zpool_name";
fsType = "zfs";
};
Mounting pools at boot
zfs-mount service is enabled by default on NixOS 22.05.
To automatically mount a dataset at boot, you only need to set canmount=on and mountpoint=/mount/point on the respective datasets.
Reservations
ZFS's performance will deteriorate significantly when more than 80% of the available space is used - to avoid this, reserve disk space beforehand.
To reserve space, create a new unused dataset that gets a guaranteed size of e.g. 10GB.
zfs create -o refreservation=10G -o mountpoint=none zroot/reserved
Automatic scrubbing
Regular scrubbing of ZFS pools is recommended and can be enabled in your NixOS configuration via:
services.zfs.autoScrub.enable = true;
By default, the service will scrub pools once a week.
Automatic snapshots
You can setup automatic snapshots by enabling the zfs.autoSnapshot service:
services.zfs.autoSnapshot.enable = true;.
Alternatively, see services.sanoid.
Trimming
Trimming is enabled by default - it's controlled by this option, if you'd like to disable it:
services.zfs.trim.enable
Note that this is different from the autotrim pool property - for further information, see the zpool-trim and zpoolprops man pages.
Tuning Adaptive Replacement Cache size
To change the maximum size of the ARC to (for example) 12 GB, add this to your NixOS configuration:
boot.kernelParams = [ "zfs.zfs_arc_max=12884901888" ];
Tuning other parameters
To tune other attributes of ARC, L2ARC or of ZFS itself via runtime modprobe config, add this to your NixOS configuration (keys and values are examples only!):
boot.extraModprobeConfig = ''
options zfs l2arc_noprefetch=0 l2arc_write_boost=33554432 l2arc_write_max=16777216 zfs_arc_max=2147483648
'';
You can confirm whether any specified configuration/tuning got applied via commands like arc_summary and arcstat -a -s " ".
Remote unlocking
In case you want unlock a machine remotely (after an update), having an ssh service in initrd for the password prompt is handy:
boot = {
initrd.network = {
# This will use udhcp to get an ip address.
# Make sure you have added the kernel module for your network driver to `boot.initrd.availableKernelModules`,
# so your initrd can load it!
# Static ip addresses might be configured using the ip argument in kernel command line:
# https://www.kernel.org/doc/Documentation/filesystems/nfs/nfsroot.txt
enable = true;
ssh = {
enable = true;
# To prevent ssh clients from freaking out because a different host key is used,
# a different port for ssh is useful (assuming the same host has also a regular sshd running)
port = 2222;
# hostKeys paths must be unquoted strings, otherwise you'll run into issues with boot.initrd.secrets
# the keys are copied to initrd from the path specified; multiple keys can be set
# you can generate any number of host keys using
# `ssh-keygen -t ed25519 -N "" -f /path/to/ssh_host_ed25519_key`
hostKeys = [ /path/to/ssh_host_rsa_key ];
# public ssh key used for login
authorizedKeys = [ "ssh-rsa AAAA..." ];
};
};
};
- In order to use DHCP in the initrd, network manager must not be enabled and
networking.useDHCP = true;must be set. - If your network card isn't started, you'll need to add the according kernel module to the kernel and initrd as well, e.g.
boot.kernelModules = [ "r8169" ]; boot.initrd.kernelModules = [ "r8169" ];
After that you can unlock your datasets using the following ssh command:
ssh -p 2222 root@host "zpool import -a; zfs load-key -a && killall zfs"Alternatively you could also add the commands as postCommands to your configuration.nix, then you just have to ssh into the initrd:
boot = {
initrd.network = {
postCommands = ''
# Import all pools
zpool import -a
# Or import selected pools
zpool import pool2
zpool import pool3
zpool import pool4
# Add the load-key command to the .profile
echo "zfs load-key -a; killall zfs" >> /root/.profile
'';
};
};After that you can unlock your datasets using the following ssh command:
ssh -p 2222 root@hostWith sharenfs property, ZFS has build-in support for generating /etc/exports.d/zfs.exports file, which in turn is processed by NFS service automatically.
To enable NFS share on a dataset, only two steps are needed:
First, enable NFS service:
services.nfs.server.enable = true;
Only this line is needed. Configure firewall if necessary, as described in NFS article.
Then, set sharenfs property:
zfs set sharenfs="ro=192.168.1.0/24,all_squash,anonuid=70,anongid=70" rpool/myData
For more options, see man 5 exports.
Todo: sharesmb property for Samba.
Mail notifications (ZFS Event Daemon)
ZFS Event Daemon (zed) monitors events generated by the ZFS kernel module and runs configured tasks. It can be configured to send an email when a pool scrub is finished or a disk has failed. zed options
Option A: Enable Mail Notification without Re-compliation
First, we need to configure a mail transfer agent, the program that sends email:
{
programs.msmtp = {
enable = true;
setSendmail = true;
defaults = {
aliases = "/etc/aliases";
port = 465;
tls_trust_file = "/etc/ssl/certs/ca-certificates.crt";
tls = "on";
auth = "login";
tls_starttls = "off";
};
accounts = {
default = {
host = "mail.example.com";
passwordeval = "cat /etc/emailpass.txt";
user = "user@example.com";
from = "user@example.com";
};
};
};
}
Then, configure an alias for root account. With this alias configured, all mails sent to root, such as cron job results and failed sudo login events, will be redirected to the configured email account.
tee -a /etc/aliases <<EOF
root: user@example.com
EOF
Finally, override default zed settings with a custom one:
{
services.zfs.zed.settings = {
ZED_DEBUG_LOG = "/tmp/zed.debug.log";
ZED_EMAIL_ADDR = [ "root" ];
ZED_EMAIL_PROG = "${pkgs.msmtp}/bin/msmtp";
ZED_EMAIL_OPTS = "@ADDRESS@";
ZED_NOTIFY_INTERVAL_SECS = 3600;
ZED_NOTIFY_VERBOSE = true;
ZED_USE_ENCLOSURE_LEDS = true;
ZED_SCRUB_AFTER_RESILVER = true;
};
# this option does not work; will return error
services.zfs.zed.enableMail = false;
}
You can now test this by performing a scrub
zpool scrub $pool
Option B: Rebuild ZFS with Mail Support
The zfs package can be rebuilt with mail features. However, please note that this will cause Nix to recompile the entire ZFS package on the computer, and on every kernel update, which could be very time-consuming on lower-end NAS systems.
An alternative solution that does not involve recompliation can be found above.
The following override is needed as zfs is implicitly used in partition mounting:
nixpkgs.config.packageOverrides = pkgs: {
zfsStable = pkgs.zfsStable.override { enableMail = true; };
};
A mail sender like msmtp or postfix is required.
A minimal, testable ZED configuration example:
services.zfs.zed.enableMail = true;
services.zfs.zed.settings = {
ZED_EMAIL_ADDR = [ "root" ];
ZED_NOTIFY_VERBOSE = true;
};
Above, ZED_EMAIL_ADDR is set to root, which most people will have an alias for in their mailer. You can change it to directly mail you: ZED_EMAIL_ADDR = [ "you@example.com" ];
ZED pulls in mailutils and runs mail by default, but you can override it with ZED_EMAIL_PROG. If using msmtp, you may need ZED_EMAIL_PROG = "${pkgs.msmtp}/bin/msmtp";.
You can customize the mail command with ZED_EMAIL_OPTS. For example, if your upstream mail server requires a certain FROM address: ZED_EMAIL_OPTS = "-r 'noreply@example.com' -s '@SUBJECT@' @ADDRESS@";
Limitations
ZFS support for newer kernel versions
Newest kernels are often not supported by ZFS yet. If you are running a newer kernel which is not yet officially supported by ZFS, the ZFS module will refuse to evaluate and show up as broken. It is thus recommended to use the latest LTS kernel version (usually also the NixOS default kernel) to ensure compatibility. If you understand the risks of running pre-release ZFS, using pre-release `pkgs.zfs_unstable` may support a newer kernel version, use it by setting `boot.zfs.package = pkgs.zfs_unstable`.
Missing support for SWAP on ZFS
ZFS does not support swapfiles. Hibernation must be either disabled with boot.kernelParams = [ "nohibernate" ];, or be enabled with a separate, non-ZFS swap partition.
boot.zfs.devNodes in virtual machines
If you are running within a VM and NixOS fails to import the zpool on reboot, you may need to add boot.zfs.devNodes = "/dev/disk/by-path"; or boot.zfs.devNodes = "/dev/disk/by-partuuid"; to your configuration.nix file.
Declarative mounting of ZFS datasets
When using legacy mountpoints (created with egzfs create -o mountpoint=legacy) mountpoints must be specified with fileSystems."/mount/point" = {};. ZFS native mountpoints are not managed as part of the system configuration but better support hibernation with a separate swap partition. This can lead to conflicts if ZFS mount service is also enabled for the same datasets. Disable it with systemd.services.zfs-mount.enable = false;.