ZFS

NixOS has native support for ZFS. It uses the code from the ZFS on Linux project, including kernel modules and userspace utilities.

What works

All functionality supported by ZFS on Linux, including:

• Using ZFS as the root filesystem (using either MS-DOS or GPT partitions)
• Encrypted ZFS pools (using either native encryption or Linux's dm-crypt)
• All the other ZFS goodies (cheap snapshotting, checksumming, compression, RAID-Z, ...)
• Auto-snapshotting service

Known issues

• As of 2014-03-04, you shouldn't use a ZVol as a swap device, as it can deadlock under memory pressure
• As of 2014-03-04, you should set the mountpoint property of your ZFS filesystems to be legacy and let NixOS mount them like any other filesystem (such as ext4 or btrfs), otherwise some filesystems may fail to mount due to ordering issues
• As of 2014-03-04, all ZFS pools available to the system will be forcibly imported during boot, regardless if you had imported them before or not. You should be careful not to have any other system accessing them at the same time, otherwise it will corrupt your pools. Normally (for the common desktop user) this should not be a problem, as a hard disk is usually only directly connected to one machine.

How to use it

Just add the following to your configuration.nix file:

boot.supportedFilesystems = [ "zfs" ];

Be sure to also set networking.hostId, see https://nixos.org/nixos/manual/options.html#opt-networking.hostId

To activate the configuration and load the ZFS kernel module, run:

nixos-rebuild switch

All ZFS functionality should now be available.

If you want NixOS to auto-mount your ZFS filesystems during boot, you should set their mountpoint property to legacy and treat it like if it were any other filesystem, i.e.: mount the filesystem manually and regenerate your list of filesystems, as such:

zfs set mountpoint=legacy <pool>/<fs>
mount -t zfs <pool>/<fs> <mountpoint>

# This will regenerate your /etc/nixos/hardware-configuration.nix file:
nixos-generate-config

nixos-rebuild switch

NixOS will now make sure that your filesystem is always mounted during boot. The nixos-generate-config command regenerates your /etc/nixos/hardware-configuration.nix file, which includes the list of filesystems for NixOS to mount during boot, e.g.:

  fileSystems."/home" =
    { device = "rpool/home";
      fsType = "zfs";
    };

  fileSystems."/backup" =
    { device = "rpool/backup";
      fsType = "zfs";
    };

Changing the Cache Size

ZFS has a complicated cache system. The cache you're most likely to want to fiddle with is the called Adaptive Replacement Cache, usually abbreviated ARC. This is the first-level (fastest) of ZFS's caches.

You can increase or decrease a parameter which represents approximately the maximum size of the ARC cache. You can't set its actual size (ZFS does that adaptively according to its workload), nor can you set its exact maximum size.

To change the maximum size of the ARC cache to (for example) 12 GB, add this to your NixOS configuration:

boot.kernelParams = ["zfs.zfs_arc_max=12884901888"];

In some versions of ZFS, you can change the maximum size of the ARC on the fly, but in NixOS 18.03 this is not possible. (Nor is it possible in other versions of ZFS on Linux yet, according to Stack Exchange.)

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

Since zfs is a copy-on-write filesystem even for deleting files disk space is needed. Therefore it should be avoided to run out of disk space. Luckily it is possible to reserve disk space for datasets to prevent this. To enable reservations pick any dataset of your and do:

$ zfs set reservation=1G zroot # reserves enough disk space to have room for cleanups/deletion

where zroot should be replaced by a dataset in your pool.

How to use the auto-snapshotting service

To auto-snapshot a ZFS filesystem or a ZVol, set its com.sun:auto-snapshot property to true, like this:

$ zfs set com.sun:auto-snapshot=true <pool>/<fs>

(Note that by default this property will be inherited by all descendent datasets, but you can set their properties to false if you prefer.)

Then, to enable the auto-snapshot service, add this to your configuration.nix:

services.zfs.autoSnapshot.enable = true;

And finally, run nixos-rebuild switch to activate the new configuration!

By default, the auto-snapshot service will keep the latest four 15-minute, 24 hourly, 7 daily, 4 weekly and 12 monthly snapshots. You can globally override this configuration by setting the desired number of snapshots in your configuration.nix, like this:

services.zfs.autoSnapshot = {
  enable = true;
  frequent = 8; # keep the latest eight 15-minute snapshots (instead of four)
  monthly = 1;  # keep only one monthly snapshot (instead of twelve)
};

You can also disable a given type of snapshots on a per-dataset basis by setting a ZFS property, like this:

$ zfs set com.sun:auto-snapshot:weekly=false <pool>/<fs>

This would disable only weekly snapshots on the given filesystem.

How to install NixOS on a ZFS root filesystem

Here's an example of how to create a ZFS root pool using 4 disks in RAID-10 mode (striping+mirroring), create a ZFS root+home filesystems and install NixOS on them: (thanks to Danny Wilson for the instructions)

# Add the zfs filesystem to the install environment:
nano /etc/nixos/configuration.nix

## ---8<-------------------------8<---
  boot.supportedFilesystems = [ "zfs" ];
## ---8<-------------------------8<---

nixos-rebuild switch

# Load the just installed ZFS kernel module
modprobe zfs

# Create boot partition and (zfs) data partition
# See: https://github.com/zfsonlinux/pkg-zfs/wiki/HOWTO-install-Ubuntu-to-a-Native-ZFS-Root-Filesystem#step-2-disk-partitioning
fdisk /dev/sda

# Copy the partition table to the other disks
sfdisk --dump /dev/sda | sfdisk /dev/sdb
sfdisk --dump /dev/sda | sfdisk /dev/sdc
sfdisk --dump /dev/sda | sfdisk /dev/sdd

# Create a RAID-10 ZFS pool. Use "-o ashift=12" to create your ZFS pool with 4K sectors
zpool create -o ashift=12 -o altroot=/mnt rpool mirror /dev/sda2 /dev/sdb2 mirror /dev/sdc2 /dev/sdd2

# Create the filesystems
zfs create -o mountpoint=none rpool/root
zfs create -o mountpoint=legacy rpool/root/nixos
zfs create -o mountpoint=legacy rpool/home
zfs set compression=lz4 rpool/home    # compress the home directories automatically

# Mount the filesystems manually
mount -t zfs rpool/root/nixos /mnt

mkdir /mnt/home
mount -t zfs rpool/home /mnt/home

# Create a raid mirror of the first partitions for /boot (GRUB)
mdadm --create /dev/md127 --metadata=0.90 --level=1 --raid-devices=4 /dev/sd[a,b,c,d]1
mkfs.ext4 -m 0 -L boot -j /dev/md127

mkdir /mnt/boot
mount /dev/md127 /mnt/boot

# Generate the NixOS configuration, as per the NixOS manual
nixos-generate-config --root /mnt

# Now edit the generated hardware config:
nano /mnt/etc/nixos/hardware-configuration.nix

## ---8<-------------------------8<---
# This is what you want:

  fileSystems."/" =
    { device = "rpool/root/nixos";
      fsType = "zfs";
    };

  fileSystems."/home" =
    { device = "rpool/home";
      fsType = "zfs";
    };

  fileSystems."/boot" =
    { device = "/dev/md127";
      fsType = "ext4";
    };
## ---8<-------------------------8<---

# configuration.nix needs an adjustment:
nano /mnt/etc/nixos/configuration.nix

## ---8<-------------------------8<---
# This is some more of what you want:

  boot.loader.grub.devices = [ "/dev/sda" "/dev/sdb" "/dev/sdc" "/dev/sdd" ];
  boot.supportedFilesystems = [ "zfs" ];
## ---8<-------------------------8<---

# Ready to go!
nixos-install

Encrypted ZFS

Native encryption is only available in the zfsUnstable package of NixOS, which was added in PR-29426 in unstable and will be part of 18.03. In older versions it is also possible to use full disk encryption by creating zfs top of cryptsetup.

In the unstable channel at the moment it is necessary to set boot.zfs.enableUnstable = true; to get zfs version based on master branch as zfsStable does not yet have this feature.

Assuming that a zpool named zroot has been already created as described. Encrypted datasets can be added on top as follow:

$ zfs create -o encryption=aes-256-gcm -o keyformat=passphrase -o mountpoint=none zroot/root

Instead of encrypting just a dataset (and all its child datasets) you can also directly encrypt the whole pool upon creation:

$ zpool create -o ashift=12 -o altroot="/mnt" -O encryption=aes-256-gcm -O keyformat=passphrase zroot /dev/sdxy

All child datasets will inherit the encryption. Note that using grub to boot directly from zfs with encryption enabled might not work at the moment, so a separate boot partition is required. A full encrypted nixos installation on an UEFI system could look like this:

$ zfs create -o mountpoint=legacy -o sync=disabled zroot/root/tmp
$ zfs create -o mountpoint=legacy -o com.sun:auto-snapshot=true zroot/root/home
$ zfs create -o mountpoint=legacy -o com.sun:auto-snapshot=true zroot/root/nixos
$ mount -t zfs zroot/root/nixos /mnt
$ mkdir /mnt/{home,tmp,boot}
$ # assuming that /dev/sda1 is the boot partition
$ mkfs.vfat /dev/sda1
$ mount /dev/sda1 /mnt/boot/
$ mount -t zfs zroot/root/home /mnt/home/
$ mount -t zfs zroot/root/tmp /mnt/tmp/
$ nixos-generate-config  --root /mnt

Unlock encrypted zfs via ssh on boot

In case you want unlock a machine remotely (after an update), having a dropbear 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 from freaking out because a different host key is used,
        # a different port for dropbear is useful (assuming the same host has also a normal sshd running)
        port = 2222; 
        # dropbear uses key format different from openssh; can be generated by using:
        # $ nix-shell -p dropbear --command "dropbearkey -t ecdsa -f /tmp/initrd-ssh-key"
        hostECDSAKey = /run/keys/initrd-ssh-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 = ''
       echo "zfs load-key -a; killall zfs" >> /root/.profile
     '';
   };
};

• 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 initrd as well, e.g. boot.initrd.kernelModules = [ "r8169" ];

Import and unlock multiple encrypted pools/dataset at boot

If you have not only one encrypted pool/dataset but multiple ones and you want to import and unlock them at boot, so that they can be automounted using the hardware-configuration.nix, you could just amend the boot.initrd.network.postCommands option.

Unfortunately having an unlock key file stored in an encrypted zfs dataset cannot be used directly, so the pool must use keyformat=password and keylocation=prompt.

The following example follows the remote unlocking with dropbear, but imports another pool also and prompts for unlocking (either when at the machine itself or when logging in remotely:

 boot = {
   initrd.network = {
     enable = true;
     ssh = {
        enable = true;
        port = 2222; 
        hostECDSAKey = /run/keys/initrd-ssh-key;
        authorizedKeys = [ "ssh-rsa AAAA..." ];
     };
     postCommands = ''
       zpool import tankXXX
       echo "zfs load-key -a; killall zfs" >> /root/.profile
     '';
   };
};

When you login by SSH into dropbear or when you have physical access to the machine itself, you will be prompted to supply the unlocking password for your zroot and tankXXX pools.

Encrypted Dataset Format Change

The introduction of native encryption on ZFS was highly anticipated. However since it was introduced, there have been various issues discovered. Due to this, a rather large patch containing many fixes was merged into master, see https://github.com/zfsonlinux/zfs/pull/6864 for more information.

However this leads to a format change of the encrypted datasets. As a result of this format change, encrypted datasets that were created by older zfs versions can only be mounted as read-only. Encrypted datasets created with the new format cannot be opened at all on older versions. Unencrypted datasets were not altered and work as before.

If you've followed this wiki entry and didn't create an encrypted top-level dataset but a child-dataset, e.g. zroot/root/nixos where zroot is the name of the pool and the top-level dataset and root is the encrypted child-dataset, then you can easily use zfs send/recv to migrate it to the new format.

1. Create a custom NixOS iso with crypto stability patch applied
2. Boot into that live environment
3. Import the pool and load the key
4. Create a new encrypted dataset, e.g.
   zfs create -o encryption=aes-256-gcm -o keyformat=passphrase -o mountpoint=none zroot/rootNEW
5. Use zfs send and receive to copy the data to new format:
   zfs send zpool/root/nixos | zfs receive zpool/rootNew/nixos
6. Set correct mountpoint for the newly created dataset:
   zfs set moutpoint=legacy zpool/root/New/nixos
7. Rename the old and new datasets:
   zfs rename zpool/root zpool/rootOLD
zfs rename zpool/rootNEW zpool/root
8. That should allow to boot Nixos already with new format. If you have other encrypted mounts, you will probably need to convert them to new format as well first.

It's also recommended to have two usb sticks available. One custom iso with the old zfs format and one with the new one. So you can easily switch between them.

If you don't have enough free space to move a dataset completely, you can just use both usb sticks to boot either version and transfer files partially by rsync like this:

1. Boot usb with stability patches applied
2. Import the pool and load the key
3. Create a new encrypted dataset, e.g.
   zfs create -o encryption=aes-256-gcm -o keyformat=passphrase -o mountpoint=legacy zroot/mediaNEW
4. Mount the format one and the new format one, e.g.
   mkdir -p /mtn/media{OLD,NEW}
mount -o ro -t zfs zroot/media /mnt/mediaOLD
mount -t zfs zroot/mediaNEW /mnt/mediaNEW
5. Once mounted, you can use rsync to transfer (part) of the data:
   rsync -avp /mnt/mediaOLD/Music /mnt/mediaNew/
   Notice: In the source folder there's no trailing "/" so that in the destination location provided that whole folder will be created. Of course you can also just start with a sub folder if one is too big.
6. Rsync (or copy) over as much data as you can. Since the old format dataset can only be mounted as read-only, you'll have to boot into the other usb stick with the old format, mount the old media folder and delete files in there. You may also need to delete snapshots first.
7. Afterwards boot again into the new format usb stick and repeat.

Of course if there's no sensitive data that needs encryption, you can just boot up into the old format, create a new, non-encrypted dataset and start moving files over. Once done, boot into new format, create an encrypted pool and move files over again.

Regarding installation of NixOS to ZFS direct from installation media

• Users coming to NixOS from other distributions should note that you don’t need to make your own ISO for ZFS support, you can enable it in the existing ISO at run time using the instructions above! (source)
• It is also possible to build a custom installation ISO supporting ZFS - see creation instructions in the manual. (source)
• According to a 2018-11-08 post: We had zfs in past in the default installer, but removed it due some people having concerns regarding the license. Realistically I don’t see any company soon to sue us for that. I guess somebody could sneak in an iso image automatically build on travis-ci or so and hope for the best. I would always recommend with zfsonlinux and systemd to use the legacy mounts. Automounts are probablematic until we have a way to inform systemd that orders all the mounts to be aware of the zfs pools.

Need more info?

Feel free to ask your questions on the NixOS mailing list or the IRC channel: http://nixos.org/development/