ZFS: Difference between revisions

← Older edit
VisualWikitext
imported>Zyansheep
Make a note about how users should read up on ashift and other options when creating the zpool to not loose out on performance
improve module that selects the oldest kernel.
 
(31 intermediate revisions by 10 users not shown)
Line 1: Line 1:
[https://zfsonlinux.org/ {{PAGENAME}}] ([[wikipedia:en:{{PAGENAME}}]]) - also known as [https://openzfs.org/ OpenZFS] ([[wikipedia:en:OpenZFS]]) - is a modern filesystem which is well supported on [[NixOS]].
[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]].


There are a lot of packages for [[{{PAGENAME}}]]. For example there is the ''zfs'' package (''ZFS Filesystem Linux Kernel module'') itself.<ref>https://search.nixos.org/packages?channel=unstable&show=zfs&query=zfs</ref> But there are also a lot of packages of the [[{{PAGENAME}}]] ecosystem available.
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.


[[{{PAGENAME}}]] integrates into NixOS via its [[module]] system.  Examples:
[[{{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.
* ''boot.zfs''<ref>https://search.nixos.org/options?channel=unstable&query=boot.zfs</ref>
* ''service.zfs''<ref>https://search.nixos.org/options?channel=unstable&query=services.zfs</ref>


== Limitations ==
== Limitations ==


==== latestCompatibleLinuxPackages of ZFS for boot.kernelPackages ====
==== Latest kernel compatible with ZFS ====


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> to use the latest compatible kernel.
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.


==== missing support for SWAP 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>
 
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.


ZFS does not support swapfiles. Hibernation must be either disabled with <code><nowiki>boot.kernelParams = [ "nohibernate" ];</nowiki></code>, or be enabled with a separate, non-ZFS swap partition.
<syntaxhighlight lang="nix">
{
  lib,
  pkgs,
  config,
  ...
}:


==== boot.zfs.devNodes in virtual machines ====
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>


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> or <syntaxhighlight lang="nix" inline>boot.zfs.devNodes = "/dev/disk/by-partuuid";</syntaxhighlight> to your configuration.nix file.  
==== 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 ====
==== declarative mounting of ZFS datasets ====
Line 42: Line 85:




==== '''Simple NixOS ZFS installation''' ====
==== '''Simple NixOS ZFS in root installation''' ====


Start from here in the NixOS manual: [https://nixos.org/manual/nixos/stable/#sec-installation-manual].
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:
Under manual partitioning [https://nixos.org/manual/nixos/stable/#sec-installation-manual-partitioning] do this instead:


'''Partition your disk with an boot and an zfs partition with your favorite partition tool.'''
'''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)


Eg. 1G for boot partion, rest for zfs.
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 output from fdisk:
Example with gdisk:


<syntaxhighlight lang="bash">
<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


fdisk /dev/nvme0n1
Final checks complete. About to write GPT data. THIS WILL OVERWRITE EXISTING
Command (m for help): p
PARTITIONS!!


Disk /dev/nvme0n1: 931.51 GiB, 1000204886016 bytes, 1953525168 sectors
Do you want to proceed? (Y/N): y
...
OK; writing new GUID partition table (GPT) to /dev/nvme0n1.
Device          Start       End   Sectors  Size Type
The operation has completed successfully.
/dev/nvme0n1p1   2048   2099199    2097152     1G EFI System
</syntaxhighlight>
/dev/nvme0n1p2 2099200 1953523711 1951424512 930.5G Linux filesystem
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>
</syntaxhighlight>
'''Note:''' Remember to set boot partition (first partition) to "EFI System" type
 
'''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:'''
'''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.
'''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">
<syntaxhighlight lang="bash">
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
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:


zfs create -o mountpoint=legacy zpool/root
# Create datasets
zfs create -o mountpoint=legacy zpool/nix
zfs create zpool/root
zfs create -o mountpoint=legacy zpool/var
zfs create zpool/nix
zfs create -o mountpoint=legacy zpool/home
zfs create zpool/var
zfs create zpool/home


mkdir /mnt/root
mkdir -p /mnt
mount -t zfs zpool/root /mnt
mount -t zfs zpool/root /mnt -o zfsutil
mkdir /mnt/nix /mnt/var /mnt/home
mkdir /mnt/nix /mnt/var /mnt/home


mount -t zfs zpool/nix /mnt/nix
mount -t zfs zpool/nix /mnt/nix -o zfsutil
mount -t zfs zpool/var /mnt/var
mount -t zfs zpool/var /mnt/var -o zfsutil
mount -t zfs zpool/home /mnt/home
mount -t zfs zpool/home /mnt/home -o zfsutil
</syntaxhighlight>
</syntaxhighlight>


Line 100: Line 199:
</syntaxhighlight>
</syntaxhighlight>


'''Make fat filesystem on boot partition'''
'''Format boot partition with fat as filesystem'''
<syntaxhighlight lang="bash">
<syntaxhighlight lang="bash">
mkfs.fat -F 32 -n boot /dev/nvme0n1p1
mkfs.fat -F 32 -n boot $BOOT
</syntaxhighlight>
 
'''Enable swap'''
<syntaxhighlight lang="bash">
mkswap -L swap $SWAP
swapon $SWAP
</syntaxhighlight>
</syntaxhighlight>


'''Installation:'''
'''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>


Install: [https://nixos.org/manual/nixos/stable/#sec-installation-manual-installing]
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.


Jump to "2. UEFI systems"
<syntaxhighlight lang="nix">
{
...
  # Boot loader config for configuration.nix:
  boot.loader.systemd-boot.enable = true;


<syntaxhighlight lang="bash">
  # for local disks that are not shared over the network, we don't need this to be random
mkdir -p /mnt/boot
  networking.hostId = "8425e349";
mount /dev/disk/by-label/boot /mnt/boot
...
</syntaxhighlight>
</syntaxhighlight>


Jump to "4." ... /mnt/etc/nixos/configuration.nix ...
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.
 
Continue from here and add this boot loader and filesystems config to your configuration.nix:


<syntaxhighlight lang="nix">
<syntaxhighlight lang="nix">
Boot loader config for configuration.nix:
...
   boot.loader.grub = {
   fileSystems."/" = {  
     enable = true;
     device = "zpool/root";
     zfsSupport = true;
     fsType = "zfs";
     efiSupport = true;
     # the zfsutil option is needed when mounting zfs datasets without "legacy" mountpoints
     efiInstallAsRemovable = true;
     options = [ "zfsutil" ];
    mirroredBoots = [
      { devices = [ "nodev"]; path = "/boot"; }
    ];
   };
   };


   fileSystems."/" =
   fileSystems."/nix" = {
     { device = "zpool/root";
     device = "zpool/nix";
      fsType = "zfs";
    fsType = "zfs";
     };
     options = [ "zfsutil" ];
  };


   fileSystems."/nix" =
   fileSystems."/var" = {
     { device = "zpool/nix";
     device = "zpool/var";
      fsType = "zfs";
    fsType = "zfs";
     };
     options = [ "zfsutil" ];
  };


   fileSystems."/var" =
   fileSystems."/home" = {
     { device = "zpool/var";
     device = "zpool/home";
      fsType = "zfs";
    fsType = "zfs";
     };
     options = [ "zfsutil" ];
  };


   fileSystems."/home" =
   fileSystems."/boot" = {
    { device = "zpool/home";
  device = "/dev/disk/by-id/nvme-SKHynix_HFS512GDE9X081N_FNB6N634510106K5O-part1";
      fsType = "zfs";
  fsType = "vfat";
    };
  };


   fileSystems."/boot" =
   swapDevices = [{
     { device = "/dev/disk/by-uuid/2A11-F4EF";
     device = "/dev/disk/by-id/nvme-SKHynix_HFS512GDE9X081N_FNB6N634510106K5O-part2";
      fsType = "vfat";
    randomEncryption = true;
    };
  }];
 
}
  swapDevices = [ ];
</syntaxhighlight>
</syntaxhighlight>


'''Note:''' Remove / comment out <syntaxhighlight lang="nix" inline>boot.loader.systemd-boot.enable = true;</syntaxhighlight> config if added by<syntaxhighlight lang="nix" inline>nixos-generate-config</syntaxhighlight>
Now you may install nixos with <code>nixos-install</code>


== Importing on boot ==
== Importing on boot ==
Line 180: Line 299:
};
};
</syntaxhighlight>
</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>
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 271: Line 403:
     # Add the load-key command to the .profile
     # Add the load-key command to the .profile
     echo "zfs load-key -a; killall zfs" >> /root/.profile
     echo "zfs load-key -a; killall zfs" >> /root/.profile
     };
     '';
   };
   };
};
};
Retrieved from "https://wiki.nixos.org/wiki/ZFS"