ZFS
Notes
- Newest kernels might not be supported by ZFS yet. If you are running an newer kernel which is not yet officially supported by zfs, the zfs module will refuse to evaluate and show up as broken. Use
boot.kernelPackages = config.boot.zfs.package.latestCompatibleLinuxPackages;
- ZFS does not support swap. Hibernation must be either disabled with
boot.kernelParams = [ "nohibernate" ];, or enabled with a separate, non-ZFS swap partition.
- By default, all ZFS pools available to the system will be forcibly imported during boot. This behaviour can be disabled by setting
boot.zfs.forceImportAll = false;.
- 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";to your configuration.nix file.
Enable ZFS support
Common ZFS installation guides are now maintained at OpenZFS Documentation website. Visit there for details and if an issue arises, submit an issue or pull request.
Importing on 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";
};
Root on ZFS
Root on ZFS guide is now maintained at OpenZFS Documentation website. Visit there for details and if an issue arises, submit an issue or pull request.
Immutable Root on ZFS
After following the OpenZFS Documentation, immutable root can be optionally enabled to clean up root filesystem at boot.
This involves mounting the existing root at a different location and bind mount necessary configuration files from the new mount point. We will use /altroot here.
## In /etc/nixos/configuration.nix:
systemd.services.zfs-mount.enable = false;
boot.initrd.postDeviceCommands = ''
zpool import -Nf rpool
zfs rollback -r rpool/nixos/empty@start
zpool export -a
'';
## In /etc/nixos/hardware-configuration.nix:
## Create new root datasets
# zfs create -o canmount=noauto -o mountpoint=/ rpool/nixos/empty
# zfs snapshot rpool/nixos/empty@start
## Replace existing entry for / (root) with
fileSystems."/" =
{ device = "rpool/nixos/empty";
fsType = "zfs"; options = [ "zfsutil" "noatime" "X-mount.mkdir" ];
};
## Mount old root at /altroot
## noatime option is used for better performance
fileSystems."/altroot" =
{ device = "rpool/nixos/root";
fsType = "zfs"; options = [ "zfsutil" "noatime" "X-mount.mkdir" ];
neededForBoot = true;
};
## /nix/ is needed for the system to boot, so
## bind mount it from old root
fileSystems."/nix" = {
device = "/altroot/nix";
fsType = "none";
options = [ "bind" "X-mount.mkdir" ];
};
## /etc/nixos/ stores system configuration
fileSystems."/etc/nixos" = {
device = "/altroot/etc/nixos";
fsType = "none";
options = [ "bind" "X-mount.mkdir" ];
};
Mount datasets 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.
Changing the 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 " ".
Automatic scrubbing
Regular scrubbing of ZFS pools is recommended and can be enabled in your NixOS configuration via:
services.zfs.autoScrub.enable = true;
You can tweak the interval (defaults to once a week) and which pools should be scrubbed (defaults to all).
Reservations
On ZFS, the 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 disk space of 10GB.
# zfs create -o refreservation=10G -o mountpoint=none zroot/reserved
Auto ZFS trimming
services.zfs.trim.enable = true;.
For further information read the man pages.
Take snapshots automatically
See services.sanoid section in man configuration.nix.
Remote unlock
Unlock encrypted zfs via ssh on boot
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..." ];
};
# this will automatically load the zfs password prompt on login
# and kill the other prompt so boot can continue
postCommands = ''
cat <<EOF > /root/.profile
if pgrep -x "zfs" > /dev/null
then
zpool import -a
zfs load-key -a
killall zfs
else
echo "zfs not running -- maybe the pool is taking some time to load for some unforseen reason."
fi
EOF
'';
};
};
- 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" ];
With 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: smbshare property for Samba.
Mail notification for 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
Alternative 1: 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
Alternative 2: 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@";