Dataset Backup Contract
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.
Contract Reference
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
requestoptions.The provider reads from the
requestoptions and backs up the requested dataset. It communicates to the requester what script is used to backup and restore the files through theresultoptions.Type: submodule
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.serviceType: 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>
Usage
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!
Providers of the Backup Contract
Requester Blocks and Services
ZFS.