ZFS: Difference between revisions
m Formatting, grammar, etc. |
|||
| Line 1: | Line 1: | ||
[https://zfsonlinux.org/ {{PAGENAME}}] ([[wikipedia:en:{{PAGENAME}}]]) | [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]]. | ||
[[category:filesystem]] | |||
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 ZFS ecosystem available. | |||
ZFS integrates into NixOS via the <code>boot.zfs</code><ref>https://search.nixos.org/options?channel=unstable&query=boot.zfs</ref> and <code>service.zfs</code><ref>https://search.nixos.org/options?channel=unstable&query=services.zfs</ref> options. | |||
== Limitations == | == Limitations == | ||
==== Latest | ==== Latest Kernel compatible with ZFS ==== | ||
Newer | 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. With that being said, NixOS does support a number of Kernel versions that are compatible with ZFS, and while it is important to understand these details on compatibility, they should not be taken as a deterrent from using ZFS on NixOS. | ||
You can pin to a newer | 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|Linux Kernel]] for more information, including which Kernel versions Nixpkgs provides. | ||
Some basic examples of pinning the | Some basic examples of pinning the Kernel: | ||
<syntaxhighlight lang="nix"> | <syntaxhighlight lang="nix"> | ||
| Line 23: | Line 23: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
The following snippet will configure the latest compatible | The following snippet will configure the latest compatible Kernel. | ||
Note that over time, this can jump back to old | Note that over time, this can jump back to old Kernel versions because non-LTS Kernel versions are eventually dropped and their newer replacements might be not supported by ZFS yet. | ||
<syntaxhighlight lang="nix"> | <syntaxhighlight lang="nix"> | ||
| Line 57: | Line 57: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
==== Partial support for | ==== Partial support for swap on ZFS ==== | ||
ZFS does not support swapfiles. | 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 swapfiles on ZFS are not used, set <code>boot.zfs.allowHibernation = true</code>. | ||
==== Zpool not found ==== | ==== Zpool not found ==== | ||
| Line 67: | Line 67: | ||
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. | 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 | When using legacy mountpoints (created with e.g. <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 == | == Guides == | ||
| Line 86: | Line 86: | ||
* Giving understandable, easy to follow instructions which are close to the standard installation guide | * Giving understandable, easy to follow instructions which are close to the standard installation guide | ||
* Integrating ZFS into your existing config | * Integrating ZFS into your existing config | ||
==== '''Simple NixOS ZFS on root installation''' ==== | |||
==== '''Simple NixOS ZFS | |||
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 your favorite partition tool | '''Partition your disk with your favorite partition tool''' | ||
We need the following partitions: | We need the following partitions: | ||
| Line 164: | Line 162: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
'''Make | '''Make a 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. | ||
| Line 203: | Line 201: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
'''Format boot partition with | '''Format boot partition with FAT as filesystem''' | ||
<syntaxhighlight lang="bash"> | <syntaxhighlight lang="bash"> | ||
mkfs.fat -F 32 -n boot $BOOT | mkfs.fat -F 32 -n boot $BOOT | ||
| Line 214: | Line 212: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
'''Installation | '''Installation''' | ||
# Mount boot | # Mount boot | ||
| Line 283: | Line 281: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
Now you may install | Now you may install NixOS with <code>nixos-install</code>. | ||
== Importing on boot == | == Importing on boot == | ||
| Line 348: | Line 346: | ||
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). | ||
== Remote unlock == | == Remote unlock == | ||
=== Unlock encrypted | === Unlock encrypted ZFS via SSH on boot === | ||
{{note|As of 22.05, rebuilding your config with the below directions may result in a situation where, if you want to revert the changes, you may need to do some pretty hairy nix-store manipulation to be able to successfully rebuild, see https://github.com/NixOS/nixpkgs/issues/101462#issuecomment-1172926129}} | {{note|As of 22.05, rebuilding your config with the below directions may result in a situation where, if you want to revert the changes, you may need to do some pretty hairy nix-store manipulation to be able to successfully rebuild, see https://github.com/NixOS/nixpkgs/issues/101462#issuecomment-1172926129}} | ||
| Line 383: | Line 379: | ||
</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 | * 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.kernelModules = [ "r8169" ]; | ||
boot.initrd.kernelModules = [ "r8169" ];</syntaxhighlight> | boot.initrd.kernelModules = [ "r8169" ];</syntaxhighlight> | ||
| Line 454: | Line 450: | ||
Then, set <code>sharenfs</code> property: | Then, set <code>sharenfs</code> property: | ||
<syntaxhighlight lang="console"> | <syntaxhighlight lang="console"> | ||
zfs set sharenfs="ro=192.168.1.0/24,all_squash,anonuid=70,anongid=70" rpool/myData | |||
</syntaxhighlight> | </syntaxhighlight> | ||
For more options, see <code>man 5 exports</code>. | For more options, see <code>man 5 exports</code>. | ||
| Line 462: | Line 458: | ||
== Mail notifications (ZFS Event Daemon) == | == Mail notifications (ZFS Event Daemon) == | ||
ZFS Event Daemon (zed) monitors events generated by the ZFS | 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. [https://search.nixos.org/options?query=services.zfs.zed zed options] | ||
=== Option A: | === Option A: enable mail notifications without re-compliation === | ||
First, we need to configure a mail transfer agent, the program that sends email: | First, we need to configure a mail transfer agent, the program that sends email: | ||
| Line 525: | Line 521: | ||
</syntaxhighlight> | </syntaxhighlight> | ||
=== Option B: Rebuild ZFS with | === Option B: Rebuild ZFS with mail support === | ||
The <code>zfs</code> 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 | The <code>zfs</code> 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. | An alternative solution that does not involve recompliation can be found above. | ||
The following override is needed as <code>zfs</code> is implicitly used in partition mounting: | The following override is needed as <code>zfs</code>is implicitly used in partition mounting: | ||
<syntaxhighlight lang="nix"> | <syntaxhighlight lang="nix"> | ||