selfhostblocks/modules/blocks/zfs/docs/default.md

ZFS Block

Defined in /modules/blocks/zfs.nix:

{
  inputs,
  ...
}:
{
  imports = [
    inputs.selfhostblocks.nixosModules.zfs
  ];
}

This block creates ZFS datasets, optionally mounts them and sets permissions on the mount point. It also enables taking snapshots on activation.

Features

• Creates ZFS dataset which is optionally mounted.
• Sets permissions, owner, group and ACL on the mount point.
• Backup of the files in the dataset shb.zfs.<name>.backup through the backup contract.
• Backup of the dataset itself shb.zfs.<name>.datasetbackup through the dataset backup contract.
• Take a snapshot before activating or deploying allowing a safe rollback.

Usage

Create a dataset at root/safe/users mounted on /var/lib/nixos:

shb.zfs.pools.root.datasets."safe/users".path = "/var/lib/nixos";

Create a dataset at backup/syncoid but do not mount it:

shb.zfs.pools.backup.datasets."syncoid".path = "none";

Create a dataset at root/syncthing and set custom permissions and ACL. Permission and ACL are only enforced for the mount point.

shb.zfs.pools.root.datasets."syncthing" = {
  path = "/srv/syncthing";

  mode = "ug=rwx,g+s,o=";
  owner = "syncthing";
  group = "syncthing";
  defaultACLs = "g:syncthing:rwX";
};

Backup dataset

To backup the dataset directly, use the dataset backup contract. For example, with the sanoid module as the dataset backup contract provider:

{
  shb.zfs.pools.root.datasets.home = {
    path = "/home";
  };

  shb.sanoid.backup."root/home" = {
    request = shb.zfs.pools.root.datasets.home.datasetBackup.request;
    template = "yearly";
  };
}

See the Sanoid block for more examples.

Backup files

To backup the files in the dataset, use the file backup contract. For example, with the restic module as the file backup contract provider:

{
  shb.zfs.pools.root.datasets.home = {
    path = "/home";
  };

  shb.restic.instances."myservice" = {
    request = shb.zfs.pools.root.datasets.home.backup.request;
  };
}

See the Restic block for more examples.

Snapshot before activation

To take a snapshot of all datasets before activating a new configuration:

{
  shb.zfs.snapshotBeforeActivation.enable = true;
}

This does not take a recursive snapshot by default, to do it recursively, do:

{
  shb.zfs.snapshotBeforeActivation = {
    enable = true;
    recursive = true;
  };
}

We did not specify datasets manually, which means the datasets list comes from boot.zfs.extraPools. To specify the datasets manually, you can use:

{
  shb.zfs.snapshotBeforeActivation = {
    enable = true;
    datasets = [ "root" "root/var" ];
  };
}

Options Reference

id-prefix: blocks-zfs-options-
list-id: selfhostblocks-block-zfs-options
source: @OPTIONS_JSON@