138 lines
3.7 KiB
Markdown
138 lines
3.7 KiB
Markdown
# ZFS Block {#blocks-zfs}
|
|
|
|
Defined in [`/modules/blocks/zfs.nix`](@REPO@/modules/blocks/zfs.nix):
|
|
|
|
```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 {#blocks-zfs-features}
|
|
|
|
- Creates ZFS dataset which is [optionally mounted](#blocks-zfs-options-shb.zfs.pools._name_.datasets._name_.path).
|
|
- Sets permissions, [owner](#blocks-zfs-options-shb.zfs.pools._name_.datasets._name_.owner), [group](#blocks-zfs-options-shb.zfs.pools._name_.datasets._name_.group) and [ACL](#blocks-zfs-options-shb.zfs.pools._name_.datasets._name_.defaultACLs) on the mount point.
|
|
- Backup of the files in the dataset [`shb.zfs.<name>.backup`][backup] through the [backup contract](./contracts-backup.html).
|
|
- Backup of the dataset itself [`shb.zfs.<name>.datasetbackup`][datasetbackup] through the [dataset backup contract](./contracts-datasetbackup.html).
|
|
- Take a snapshot [before activating or deploying][activationsnapshot] allowing a safe rollback.
|
|
|
|
[backup]: #blocks-zfs-options-shb.zfs.pools._name_.datasets._name_.backup
|
|
[datasetbackup]: #blocks-zfs-options-shb.zfs.pools._name_.datasets._name_.datasetbackup
|
|
[activationsnapshot]: #blocks-zfs-options-shb.zfs.snapshotBeforeActivation.enable
|
|
|
|
## Usage {#blocks-zfs-usage}
|
|
|
|
Create a dataset at `root/safe/users` mounted on `/var/lib/nixos`:
|
|
|
|
```nix
|
|
shb.zfs.pools.root.datasets."safe/users".path = "/var/lib/nixos";
|
|
```
|
|
|
|
Create a dataset at `backup/syncoid` but do not mount it:
|
|
|
|
```nix
|
|
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.
|
|
|
|
```nix
|
|
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 {#blocks-zfs-usage-backup-dataset}
|
|
|
|
To backup the dataset directly, use the [dataset backup contract](contracts-datasetbackup.html).
|
|
For example, with the sanoid module as the dataset backup contract provider:
|
|
|
|
```nix
|
|
{
|
|
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](blocks-sanoid.html) for more examples.
|
|
|
|
### Backup files {#blocks-zfs-usage-backup-files}
|
|
|
|
To backup the files in the dataset, use the [file backup contract](contracts-backup.html).
|
|
For example, with the restic module as the file backup contract provider:
|
|
|
|
```nix
|
|
{
|
|
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](blocks-restic.html) for more examples.
|
|
|
|
### Snapshot before activation {#blocks-zfs-usage-snapshot-before-activation}
|
|
|
|
To take a snapshot of all datasets before activating a new configuration:
|
|
|
|
```nix
|
|
{
|
|
shb.zfs.snapshotBeforeActivation.enable = true;
|
|
}
|
|
```
|
|
|
|
This does not take a recursive snapshot by default, to do it recursively, do:
|
|
|
|
```nix
|
|
{
|
|
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:
|
|
|
|
```nix
|
|
{
|
|
shb.zfs.snapshotBeforeActivation = {
|
|
enable = true;
|
|
datasets = [ "root" "root/var" ];
|
|
};
|
|
}
|
|
```
|
|
|
|
## Options Reference {#blocks-zfs-options}
|
|
|
|
```{=include=} options
|
|
id-prefix: blocks-zfs-options-
|
|
list-id: selfhostblocks-block-zfs-options
|
|
source: @OPTIONS_JSON@
|
|
```
|