ZFS: Difference between revisions

(22 intermediate revisions by 7 users not shown)

Line 1:

[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 ==

==== ~~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.

==== ~~partial 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.

{

lib,

pkgs,

config,

...

}:

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>

~~ZFS does not~~ support ~~swapfiles.~~ SWAP devices must 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 / after that pull request is merged, it does not fully mitigate the risk. If you wish to enable hibernation regardless, set <code>boot.zfs.allowHibernation = ~~true</code>.~~

==== Partial support for SWAP on ZFS ====

~~====~~ boot.zfs.~~devNodes ===~~=

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>.

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.

==== 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 ====

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].

Line 52:

Line 95:

* 1G for boot partition with "boot" as the partition label (also called name in some tools) and ef00 as partition code

* ~~10G~~ 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.

* 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)

Line 58:

Line 101:

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:

sudo gdisk /dev/nvme0n1

GPT fdisk (gdisk) version 1.0.~~9.1~~

GPT fdisk (gdisk) version 1.0.10

...

Command (? for help): p

# boot partition

~~Disk /dev/nvme0n1: 500118192 sectors~~, ~~238.5 GiB~~

Command (? for help): n

~~Sector size (logical/physical~~): ~~512/512 bytes~~

Partition number (1-128, default 1):

~~Disk identifier~~ (~~GUID~~): ~~CA926E8C-47F6-416A-AD1A-C2190CF5D1F8~~

First sector (2048-1000215182, default = 2048) or {+-}size{KMGTP}:

~~Partition table holds up to 128 entries~~

Last sector (2048-1000215182, default = 1000215175) or {+-}size{KMGTP}: +1G

~~Main partition table begins at~~ sector ~~2 and ends at sector 33~~

Current type is 8300 (Linux filesystem)

~~First usable sector is 34~~, ~~last usable sector is 500118158~~

Hex code or GUID (L to show codes, Enter = 8300): ef00

~~Partitions will be aligned on 2048~~-~~sector boundaries~~

Changed type of partition to 'EFI system partition'

~~Total free space~~ is ~~2669 sectors~~ (~~1.3 MiB~~)

# 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

Number Start (sector) End (sector) Size Code Name

1 2048 2099199 1024.0 MiB EF00 ~~boot~~

1 2048 2099199 1024.0 MiB EF00 EFI system partition

2 2099200 ~~23070719~~ 10.0 GiB 8200 swap

2 2099200 10487807 4.0 GiB 8200 Linux swap

3 ~~23070720 500117503~~ ~~227~~.5 GiB 8300 ~~root~~

3 10487808 1000215175 471.9 GiB 8300 Linux filesystem

</syntaxhighlight>

~~Command (?~~ for ~~help):~~

'''Let's use variables from now on for simplicity.

</syntaxhighlight>

Get the device ID in <code>/dev/disk/by-id/</code>, in our case here it is <code>nvme-SKHynix_HFS512GDE9X081N_FNB6N634510106K5O</code>

'''

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.

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:

# Create datasets

zfs create zpool/root

zfs create zpool/nix

Line 93:

Line 176:

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

Line 116:

Line 199:

</syntaxhighlight>

'''~~Make~~ fat filesystem ~~on boot partition~~'''

'''Format boot partition with fat as filesystem'''

mkfs.fat -F 32 -n boot ~~/dev/nvme0n1p1~~

mkfs.fat -F 32 -n boot $BOOT

</syntaxhighlight>

'''Enable swap'''

mkswap -L swap $SWAP

swapon $SWAP

</syntaxhighlight>

'''Installation:'''

~~Install: [https://nixos.org/manual/nixos/stable/~~#~~sec-installation-manual-installing]~~

# Mount boot

~~Jump to "2. UEFI systems"~~

mkdir -p /mnt/boot

mount /~~dev~~/~~disk~~/by-~~partlabel~~/~~boot~~ /~~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>

~~Jump to "4." ..~~. /mnt/etc/nixos/configuration.nix ~~...~~

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.

~~Continue from here and add this boot loader~~ and ~~filesystems config~~ to ~~your configuration~~.~~nix:~~

{

...

# Boot loader config for configuration.nix:

boot.loader.systemd-boot.enable = true;

Line 144:

Line 235:

# for local disks that are not shared over the network, we don't need this to be random

networking.hostId = "8425e349";

...

</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.

...

fileSystems."/" = {

device = "zpool/root";

Line 171:

Line 268:

fileSystems."/boot" = {

device = "/dev/disk/by-~~partlabel~~/~~boot~~";

device = "/dev/disk/by-id/nvme-SKHynix_HFS512GDE9X081N_FNB6N634510106K5O-part1";

fsType = "vfat";

~~options = [ "zfsutil" ];~~

};

swapDevices = [{

device = "/dev/disk/by-~~partlabel~~/~~swap~~";

device = "/dev/disk/by-id/nvme-SKHynix_HFS512GDE9X081N_FNB6N634510106K5O-part2";

randomEncryption = true;

}];

Line 183:

Line 279:

</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 ==

Line 204:

Line 300:

</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:

Line 211:

Line 308:

</syntaxhighlight>

The import setting is reflected in <syntaxhighlight inline>/etc/zfs/~~zfs~~.cache</syntaxhighlight>, so it ~~will~~ persist through subsequent boots.

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 ==