ZFS: Difference between revisions

← Older edit
VisualWikitext
imported>Pmarreck
Add how to change runtime zfs tuning options via modprobe config
improve module that selects the oldest kernel.
 
(62 intermediate revisions by 26 users not shown)
Line 1: Line 1:
== Notes ==
[https://zfsonlinux.org/ {{PAGENAME}}] ([[wikipedia:en:{{PAGENAME}}]]) - also known as [https://openzfs.org/ OpenZFS] ([[wikipedia:en:OpenZFS]]) - is a modern filesystem[[category:filesystem]] which is well supported on [[NixOS]].
* 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 <code>boot.kernelPackages = config.boot.zfs.package.latestCompatibleLinuxPackages;</code>


* ZFS does not support swap.  Hibernation must be either disabled with <code><nowiki>boot.kernelParams = [ "nohibernate" ];</nowiki></code>, or enabled with a separate, non-ZFS swap partition.
Besides the ''zfs'' package (''ZFS Filesystem Linux Kernel module'') <ref>https://search.nixos.org/packages?channel=unstable&show=zfs&query=zfs</ref> itself there are many packages in the [[{{PAGENAME}}]] ecosystem available.


* By default, all ZFS pools available to the system will be forcibly imported during boot. This behaviour can be disabled by setting <syntaxhighlight lang="nix" inline>boot.zfs.forceImportAll = false;</syntaxhighlight>.
[[{{PAGENAME}}]] integrates into NixOS via the ''boot.zfs''<ref>https://search.nixos.org/options?channel=unstable&query=boot.zfs</ref> and ''service.zfs''<ref>https://search.nixos.org/options?channel=unstable&query=services.zfs</ref> options.


* If you are running within a VM and NixOS fails to import the zpool on reboot, you may need to add <syntaxhighlight lang="nix" inline>boot.zfs.devNodes = "/dev/disk/by-path";</syntaxhighlight> to your configuration.nix file.
== Limitations ==


== Enable ZFS support ==
==== Latest kernel compatible with ZFS ====


Common ZFS installation guides are now maintained at [https://openzfs.github.io/openzfs-docs/Getting%20Started/NixOS/index.html OpenZFS Documentation] website. Visit there for details and if an issue arises, submit an issue or pull request.
Newer kernels might not be supported by ZFS yet. If you are running a kernel which is not officially supported by zfs, the module will refuse to evaluate and show an error.


== Root on ZFS ==
You can pin to a newer kernel version explicitly, but note that this version may be dropped by upstream and in nixpkgs prior to zfs supporting the next version. See [[Linux kernel]] for more information.<syntaxhighlight lang="nix">
{
  boot.kernelPackages = pkgs.linuxPackages_latest;
  # OR
  boot.kernelPackages = pkgs.linuxPackages_6_6
}
</syntaxhighlight>


Root on ZFS guide is now maintained at [https://openzfs.github.io/openzfs-docs/Getting%20Started/NixOS/Root%20on%20ZFS.html OpenZFS Documentation] website. Visit there for details and if an issue arises, submit an issue or pull request.
This snippet will configure the latest compatible kernel.
Note that this can over time jump back to old kernel versions because non-lts kernel version
get removed over time and their newer replacements might be not supported by zfs yet.


== Immutable Root on ZFS ==
<syntaxhighlight lang="nix">
{
  lib,
  pkgs,
  config,
  ...
}:


After following the [https://openzfs.github.io/openzfs-docs/Getting%20Started/NixOS/Root%20on%20ZFS.html OpenZFS Documentation], immutable root can be optionally enabled to clean up root filesystem at boot.
let
  isUnstable = config.boot.zfs.package == pkgs.zfsUnstable;
  zfsCompatibleKernelPackages = lib.filterAttrs (
    name: kernelPackages:
    (builtins.match "linux_[0-9]+_[0-9]+" name) != null
    && (builtins.tryEval kernelPackages).success
    && (
      (!isUnstable && !kernelPackages.zfs.meta.broken)
      || (isUnstable && !kernelPackages.zfs_unstable.meta.broken)
    )
  ) pkgs.linuxKernel.packages;
  latestKernelPackage = lib.last (
    lib.sort (a: b: (lib.versionOlder a.kernel.version b.kernel.version)) (
      builtins.attrValues zfsCompatibleKernelPackages
    )
  );
in
{
  # Note this might jump back and worth as kernel get added or removed.
  boot.kernelPackages = latestKernelPackage;
}
</syntaxhighlight>


This involves mounting the existing root at a different location and bind mount necessary configuration files from the new mount point. We will use <code>/altroot</code> here.
==== Partial support for SWAP on ZFS ====
 
ZFS does not support swapfiles. SWAP devices can be used instead. Additionally, hibernation is disabled by default due to a [https://github.com/NixOS/nixpkgs/pull/208037 high risk] of data corruption. Note that even if that pull request is merged, it does not fully mitigate the risk. If you wish to enable hibernation regardless and made sure that not swapfiles on ZFS are used, set <code>boot.zfs.allowHibernation = true</code>.
 
==== Zpool not found ====
 
If NixOS fails to import the zpool on reboot, you may need to add <syntaxhighlight lang="nix" inline>boot.zfs.devNodes = "/dev/disk/by-path";</syntaxhighlight> or <syntaxhighlight lang="nix" inline>boot.zfs.devNodes = "/dev/disk/by-partuuid";</syntaxhighlight> to your configuration.nix file.
 
The differences can be tested by running <code>zpool import -d /dev/disk/by-id</code> when none of the pools are discovered, eg. a live iso.
 
==== declarative mounting of ZFS datasets ====
 
When using legacy mountpoints (created with eg<code>zfs create -o mountpoint=legacy</code>) mountpoints must be specified with <code>fileSystems."/mount/point" = {};</code>. 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 <code>systemd.services.zfs-mount.enable = false;</code>.
 
== Guides ==
 
==== '''OpenZFS Documentation for installing''' ====
 
{{warning|This guide is not endorsed by NixOS and some features like immutable root do not have upstream support and could break on updates. If an issue arises while following this guide, please consult the guides support channels.}}
 
One guide for a NixOS installation with ZFS is maintained at [https://openzfs.github.io/openzfs-docs/Getting%20Started/NixOS/ OpenZFS Documentation (''Getting Started'' for ''NixOS'')]
 
It is about:
* [https://openzfs.github.io/openzfs-docs/Getting%20Started/NixOS/index.html#installation enabling ZFS on an existing NixOS installation] and
* [https://openzfs.github.io/openzfs-docs/Getting%20Started/NixOS/#root-on-zfs (installing NixOS with) Root on ZFS].
 
It is not about:
* Give understandable, easy to follow and close to the standard installation guide instructions
* integrating ZFS into your existing config
 
 
==== '''Simple NixOS ZFS in root installation''' ====
 
Start from here in the NixOS manual: [https://nixos.org/manual/nixos/stable/#sec-installation-manual].
Under manual partitioning [https://nixos.org/manual/nixos/stable/#sec-installation-manual-partitioning] do this instead:
 
'''Partition your disk with your favorite partition tool.'''
 
We need the following partitions:
 
* 1G for boot partition with "boot" as the partition label (also called name in some tools) and ef00 as partition code
* 4G for a swap partition with "swap" as the partition label and 8200 as partition code. We will encrypt this with a random secret on each boot.
* The rest of disk space for zfs with "root" as the partition label and 8300 as partition code (default code)
 
Reason for swap partition: ZFS does use a caching mechanism that is different from the normal Linux cache infrastructure.
In low-memory situations, ZFS therefore might need a bit longer to free up memory from its cache. The swap partition will help with that.
 
Example with gdisk:
 
<syntaxhighlight lang="bash">
sudo gdisk /dev/nvme0n1
GPT fdisk (gdisk) version 1.0.10
...
# boot partition
Command (? for help): n
Partition number (1-128, default 1):
First sector (2048-1000215182, default = 2048) or {+-}size{KMGTP}:
Last sector (2048-1000215182, default = 1000215175) or {+-}size{KMGTP}: +1G
Current type is 8300 (Linux filesystem)
Hex code or GUID (L to show codes, Enter = 8300): ef00
Changed type of partition to 'EFI system partition'
 
# Swap partition
Command (? for help): n
Partition number (2-128, default 2):
First sector (2099200-1000215182, default = 2099200) or {+-}size{KMGTP}:
Last sector (2099200-1000215182, default = 1000215175) or {+-}size{KMGTP}: +4G
Current type is 8300 (Linux filesystem)
Hex code or GUID (L to show codes, Enter = 8300): 8200
Changed type of partition to 'Linux swap'
 
# root partition
Command (? for help): n
Partition number (3-128, default 3):
First sector (10487808-1000215182, default = 10487808) or {+-}size{KMGTP}:
Last sector (10487808-1000215182, default = 1000215175) or {+-}size{KMGTP}:
Current type is 8300 (Linux filesystem)
Hex code or GUID (L to show codes, Enter = 8300):
Changed type of partition to 'Linux filesystem'
 
# write changes
Command (? for help): w
 
Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
PARTITIONS!!
 
Do you want to proceed? (Y/N): y
OK; writing new GUID partition table (GPT) to /dev/nvme0n1.
The operation has completed successfully.
</syntaxhighlight>
Final partition table
<syntaxhighlight lang=bash>
Number  Start (sector)    End (sector)  Size      Code  Name
  1            2048        2099199  1024.0 MiB  EF00  EFI system partition
  2        2099200        10487807  4.0 GiB    8200  Linux swap
  3        10487808      1000215175  471.9 GiB  8300  Linux filesystem
</syntaxhighlight>
 
'''Let's use variables from now on for simplicity.
Get the device ID in <code>/dev/disk/by-id/</code>, in our case here it is <code>nvme-SKHynix_HFS512GDE9X081N_FNB6N634510106K5O</code>
'''
<syntaxhighlight lang=bash>
BOOT=/dev/disk/by-id/nvme-SKHynix_HFS512GDE9X081N_FNB6N634510106K5O-part1
SWAP=/dev/disk/by-id/nvme-SKHynix_HFS512GDE9X081N_FNB6N634510106K5O-part2
DISK=/dev/disk/by-id/nvme-SKHynix_HFS512GDE9X081N_FNB6N634510106K5O-part3
 
'''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 [https://jrs-s.net/2018/08/17/zfs-tuning-cheat-sheet/ ZFS tuning cheatsheet] or [https://wiki.archlinux.org/title/ZFS#Storage_pools ArchWiki] is a good place to start.
 
<syntaxhighlight lang="bash">
zpool create -O encryption=on -O keyformat=passphrase -O keylocation=prompt -O compression=zstd -O mountpoint=none -O xattr=sa -O acltype=posixacl -o ashift=12 zpool $DISK
# enter the password to decrypt the pool at boot
Enter new passphrase:
Re-enter new passphrase:
 
# Create datasets
zfs create zpool/root
zfs create zpool/nix
zfs create zpool/var
zfs create zpool/home
 
mkdir -p /mnt
mount -t zfs zpool/root /mnt -o zfsutil
mkdir /mnt/nix /mnt/var /mnt/home
 
mount -t zfs zpool/nix /mnt/nix -o zfsutil
mount -t zfs zpool/var /mnt/var -o zfsutil
mount -t zfs zpool/home /mnt/home -o zfsutil
</syntaxhighlight>
 
Output from <syntaxhighlight lang="bash" inline>zpool status</syntaxhighlight>:
<syntaxhighlight >
zpool status
  pool: zpool
state: ONLINE
...
config:
 
NAME                              STATE    READ WRITE CKSUM
zpool                              ONLINE      0    0    0
  nvme-eui.0025384b21406566-part2  ONLINE      0    0    0
 
</syntaxhighlight>
 
'''Format boot partition with fat as filesystem'''
<syntaxhighlight lang="bash">
mkfs.fat -F 32 -n boot $BOOT
</syntaxhighlight>
 
'''Enable swap'''
<syntaxhighlight lang="bash">
mkswap -L swap $SWAP
swapon $SWAP
</syntaxhighlight>
 
'''Installation:'''
# Mount boot
<syntaxhighlight lang="bash">
mkdir -p /mnt/boot
mount $BOOT /mnt/boot
 
# Generate the nixos config
nixos-generate-config --root /mnt
...
writing /mnt/etc/nixos/hardware-configuration.nix...
writing /mnt/etc/nixos/configuration.nix...
For more hardware-specific settings, see https://github.com/NixOS/nixos-hardware.
</syntaxhighlight>
 
Now edit the configuration.nix that was just created in <code>/mnt/etc/nixos/configuration.nix</code> and make sure to have at least the following content in it.


<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
## In /etc/nixos/configuration.nix:
{
   systemd.services.zfs-mount.enable = false;
...
  # Boot loader config for configuration.nix:
   boot.loader.systemd-boot.enable = true;


boot.initrd.postDeviceCommands = ''
  # for local disks that are not shared over the network, we don't need this to be random
   zpool import -Nf rpool
   networking.hostId = "8425e349";
  zfs rollback -r rpool/nixos/empty@start
...
  zpool export -a
'';
</syntaxhighlight>
</syntaxhighlight>
Now check the hardware-configuration.nix in <code>/mnt/etc/nixos/hardware-configuration.nix</code> and add whats missing e.g. <code>options = [ "zfsutil" ]</code> for all filesystems except boot and <code>randomEncryption = true;</code> for the swap partition. Also change the generated swap device to the partition we created e.g. <code>/dev/disk/by-id/nvme-SKHynix_HFS512GDE9X081N_FNB6N634510106K5O-part2</code> in this case and <code>/dev/disk/by-id/nvme-SKHynix_HFS512GDE9X081N_FNB6N634510106K5O-part1</code> for boot.


<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
## In /etc/nixos/hardware-configuration.nix:
...
  fileSystems."/" = {
    device = "zpool/root";
    fsType = "zfs";
    # the zfsutil option is needed when mounting zfs datasets without "legacy" mountpoints
    options = [ "zfsutil" ];
  };


## Create new root datasets
  fileSystems."/nix" = {
# zfs create -o canmount=noauto -o mountpoint=/ rpool/nixos/empty
    device = "zpool/nix";
# zfs snapshot rpool/nixos/empty@start
    fsType = "zfs";
    options = [ "zfsutil" ];
  };


## Replace existing entry for / (root) with
   fileSystems."/var" = {
   fileSystems."/" =
     device = "zpool/var";
     { device = "rpool/nixos/empty";
    fsType = "zfs";
      fsType = "zfs"; options = [ "zfsutil" "noatime" "X-mount.mkdir" ];
    options = [ "zfsutil" ];
    };
  };


## Mount old root at /altroot
   fileSystems."/home" = {
## noatime option is used for better performance
     device = "zpool/home";
   fileSystems."/altroot" =
    fsType = "zfs";
     { device = "rpool/nixos/root";
    options = [ "zfsutil" ];
      fsType = "zfs"; options = [ "zfsutil" "noatime" "X-mount.mkdir" ];
  };
      neededForBoot = true;
    };


## /nix/ is needed for the system to boot, so
   fileSystems."/boot" = {  
## bind mount it from old root
  device = "/dev/disk/by-id/nvme-SKHynix_HFS512GDE9X081N_FNB6N634510106K5O-part1";
   fileSystems."/nix" = {
  fsType = "vfat";
    device = "/altroot/nix";
    fsType = "none";
    options = [ "bind" "X-mount.mkdir" ];
   };
   };


## /etc/nixos/ stores system configuration
  swapDevices = [{
  fileSystems."/etc/nixos" = {
    device = "/dev/disk/by-id/nvme-SKHynix_HFS512GDE9X081N_FNB6N634510106K5O-part2";
    device = "/altroot/etc/nixos";
    randomEncryption = true;
    fsType = "none";
  }];
    options = [ "bind" "X-mount.mkdir" ];
}
  };
</syntaxhighlight>
 
Now you may install nixos with <code>nixos-install</code>
 
== 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 <syntaxhighlight lang="nix" inline>boot.zfs.extraPools</syntaxhighlight>:
 
<syntaxhighlight lang="nix">
## In /etc/nixos/configuration.nix:
boot.zfs.extraPools = [ "zpool_name" ];
</syntaxhighlight>
 
or if you are using legacy mountpoints, add a <syntaxhighlight lang="nix" inline>fileSystems</syntaxhighlight> entry and NixOS will automatically detect that the pool needs to be imported:
 
<syntaxhighlight lang="nix">
## In /etc/nixos/configuration.nix:
fileSystems."/mount/point" = {
  device = "zpool_name";
  fsType = "zfs";
};
</syntaxhighlight>
 
=== Zpool created with bus-based disk names ===
If you used bus-based disk names in the <syntaxhighlight inline>zpool create</syntaxhighlight> command, e.g., <syntaxhighlight inline>/dev/sda</syntaxhighlight>, NixOS may run into issues importing the pool if the names change. Even if the pool is able to be mounted (with <syntaxhighlight lang="nix" inline>boot.zfs.devNodes = "/dev/disk/by-partuuid";</syntaxhighlight> set), this may manifest as a <syntaxhighlight inline>FAULTED</syntaxhighlight> disk and a <syntaxhighlight inline>DEGRADED</syntaxhighlight> pool reported by <syntaxhighlight inline>zpool status</syntaxhighlight>. The fix is to re-import the pool using disk IDs:
 
<syntaxhighlight>
# zpool export zpool_name
# zpool import -d /dev/disk/by-id zpool_name
</syntaxhighlight>
</syntaxhighlight>
The import setting is reflected in <syntaxhighlight inline="" lang="bash">/etc/zfs/zpool.cache</syntaxhighlight>, so it should persist through subsequent boots.
=== Zpool created with disk IDs ===
If you used disk IDs to refer to disks in the <code>zpool create</code> command, e.g., <code>/dev/disk/by-id</code>, then NixOS may consistently fail to import the pool unless <code>boot.zfs.devNodes = "/dev/disk/by-id"</code> is also set.


== Mount datasets at boot ==
== Mount datasets at boot ==
Line 102: Line 345:
You can tweak the interval (defaults to once a week) and which pools should be scrubbed (defaults to all).
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.
<syntaxhighlight lang="console">
# zfs create -o refreservation=10G -o mountpoint=none zroot/reserved
</syntaxhighlight>
== Auto ZFS trimming ==
<syntaxhighlight lang="nix" inline>services.zfs.trim.enable = true;</syntaxhighlight>.
For further information read the man pages.
== Take snapshots automatically ==
See <code>services.sanoid</code> section in <code>man configuration.nix</code>.


== Remote unlock ==
== Remote unlock ==
Line 151: Line 375:
       authorizedKeys = [ "ssh-rsa AAAA..." ];
       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
        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
    '';
   };
   };
};
};
</syntaxhighlight>
</syntaxhighlight>
* In order to use DHCP in the initrd, network manager must not be enabled and <syntaxhighlight lang="nix" inline>networking.useDHCP = true;</syntaxhighlight> must be set.
* In order to use DHCP in the initrd, network manager must not be enabled and <syntaxhighlight lang="nix" inline>networking.useDHCP = true;</syntaxhighlight> 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. <syntaxhighlight lang="nix" inline>boot.initrd.kernelModules = [ "r8169" ];</syntaxhighlight>
* 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. <syntaxhighlight lang="nix">
boot.kernelModules = [ "r8169" ];
boot.initrd.kernelModules = [ "r8169" ];</syntaxhighlight>


=== Import and unlock multiple encrypted pools/dataset at boot ===
After that you can unlock your datasets using the following ssh command:
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 <code>boot.initrd.network.postCommands</code> option.


Unfortunately having an unlock key file stored in an encrypted zfs dataset cannot be used directly, so the pool must use <code>keyformat=passphrase</code> and <code>keylocation=prompt</code>.
<syntaxhighlight>
ssh -p 2222 root@host "zpool import -a; zfs load-key -a && killall zfs"
</syntaxhighlight>


The following example follows the remote unlocking with OpenSSH, but imports another pool also and prompts for unlocking (either when at the machine itself or when logging in remotely:
Alternatively you could also add the commands as postCommands to your configuration.nix, then you just have to ssh into the initrd:


<syntaxhighlight lang="nix">
<syntaxhighlight>
boot = {
boot = {
   initrd.network = {
   initrd.network = {
    enable = true;
    ssh = {
      enable = true;
      port = 2222;
      hostKeys = [ /path/to/ssh_host_rsa_key ];
      authorizedKeys = [ "ssh-rsa AAAA..." ];
    };
     postCommands = ''
     postCommands = ''
      zpool import tankXXX
    # Import all pools
      echo "zfs load-key -a; killall zfs" >> /root/.profile
    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
     '';
     '';
   };
   };
Line 195: Line 408:
</syntaxhighlight>
</syntaxhighlight>


When you login by SSH into the box 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.
After that you can unlock your datasets using the following ssh command:
 
<syntaxhighlight>
ssh -p 2222 root@host
</syntaxhighlight>
 
== 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.
 
<syntaxhighlight lang="console">
# zfs create -o refreservation=10G -o mountpoint=none zroot/reserved
</syntaxhighlight>
 
== Auto ZFS trimming ==
 
<syntaxhighlight lang="nix" inline>services.zfs.trim.enable = true;</syntaxhighlight>.
 
This will periodically run <code>zpool trim</code>. Note that this is different from the <code>autotrim</code> pool property. For further information, see the <code>zpool-trim</code> and <code>zpoolprops</code> man pages.
 
== Take snapshots automatically ==
 
See <code>services.sanoid</code> section in <code>man configuration.nix</code>.


== NFS share ==
== NFS share ==
With <code>sharenfs</code> property, ZFS has build-in support for generating <code>/etc/exports.d/zfs.exports</code> file, which in turn is processed by NFS service automatically.
With <code>sharenfs</code> property, ZFS has build-in support for generating <code>/etc/exports.d/zfs.exports</code> file, which in turn is processed by NFS service automatically.


Line 216: Line 454:
For more options, see <code>man 5 exports</code>.
For more options, see <code>man 5 exports</code>.


Todo: smbshare property for Samba.
Todo: sharesmb property for Samba.


== Mail notification for ZFS Event Daemon ==
== Mail notification for ZFS Event Daemon ==
Retrieved from "https://wiki.nixos.org/wiki/ZFS"