Table of Contents
This NixOS contract represents a backup job that will backup one ZFS dataset.
It is a contract between a service that manages ZFS datasets and a service that backs up ZFS datasets.
These are all the options that are expected to exist for this contract to be respected.
shb.contracts.datasetbackup
Contract for backing up ZFS datasets.
The requester communicates to the provider
the dataset to backup
through the request options.
The provider reads from the request options
and backs up the requested dataset.
It communicates to the requester what script is used
to backup and restore the files
through the result options.
Type: submodule
Default:
{ }
Declared by:
<selfhostblocks/modules/contracts/datasetbackup/dummyModule.nix>
|
shb.contracts.datasetbackup.request
Request part of the backup contract.
Options set by the requester module enforcing how to backup files.
Type: submodule
Default:
{ }
Declared by:
<selfhostblocks/modules/contracts/datasetbackup/dummyModule.nix>
|
shb.contracts.datasetbackup.request.dataset
Dataset to backup, including the pool name.
Type: string
Default:
""
Example:
"root/home"
Declared by:
<selfhostblocks/modules/contracts/datasetbackup/dummyModule.nix>
|
shb.contracts.datasetbackup.result
Result part of the backup contract.
Options set by the provider module that indicates the name of the backup and restore scripts.
Type: submodule
Default:
{ }
Declared by:
<selfhostblocks/modules/contracts/datasetbackup/dummyModule.nix>
|
shb.contracts.datasetbackup.result.backupService
Name of service backing up the database.
This script can be ran manually to backup the database:
$ systemctl start backup.service
Type: string
Default:
"backup.service"
Declared by:
<selfhostblocks/modules/contracts/datasetbackup/dummyModule.nix>
|
shb.contracts.datasetbackup.result.restoreScript
Name of script that can restore the database. One can then list snapshots with:
$ restore snapshots
<snapshot 1> <metadata>
<snapshot 2> <metadata>
And restore the database with:
$ restore restore <snapshot 1>
It is not garanteed to be able to restore back to a snapshot in the future.
With the above example, it may not be possible to restore <snapshot 2>
after having restored <snapshot 1>.
Type: string
Default:
"restore"
Declared by:
<selfhostblocks/modules/contracts/datasetbackup/dummyModule.nix>
|
shb.contracts.datasetbackup.settings
Optional attribute set with options specific to the provider.
Type: anything
Declared by:
<selfhostblocks/modules/contracts/datasetbackup/dummyModule.nix>
|
A service that manages ZFS datasets that can be backed up will provide a datasetbackup option.
Here is an example module defining such a backup option,
which defines what directories to backup (sourceDirectories)
and the user to backup with (user).
{
options = {
myservice.datasetbackup = mkOption {
type = lib.types.submodule {
options = shb.contracts.datasetbackup.mkRequester {
dataset = "root/test";
};
};
};
};
};
Now, on the other side we have a service that uses this datasetbackup option and actually backs up the dataset.
This service is a provider of this contract and will provide a result option.
Let’s assume such a module is available under the backupService option
and that one can create multiple backup instances under backupService.instances.
Then, to actually backup the myservice service, one would write:
backupService.instances.myservice = {
request = myservice.datasetbackup.request;
settings = {
enable = true;
targetDataset = "backup/myservice";
# ... Other options specific to backupService like scheduling.
};
};
It is advised to backup files to different location, to improve redundancy.
Thanks to using contracts, this can be made easily either with the same backupService:
backupService.instances.myservice_2 = {
request = myservice.datasetbackup.request;
settings = {
enable = true;
targetDataset = "backup2/myservice";
};
};
Or with another module backupService_2!
ZFS.