Backup Contract
This NixOS contract represents a backup job that will backup one or more files or directories on a regular schedule.
It is a contract between a service that has files to be backed up and a service that backs up files.
Contract Reference
These are all the options that are expected to exist for this contract to be respected.
-
shb.contracts.backup -
Contract for backing up files between a requester module and a provider module.
The requester communicates to the provider what files to backup through the
requestoptions.The provider reads from the
requestoptions and backs up the requested files. It communicates to the requester what script is used to backup and restore the files through theresultoptions.Type: submodule
Declared by:
<selfhostblocks/modules/contracts/backup/dummyModule.nix> -
shb.contracts.backup.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/backup/dummyModule.nix> -
shb.contracts.backup.request.excludePatterns -
File patterns to exclude.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/contracts/backup/dummyModule.nix> -
shb.contracts.backup.request.hooks -
Hooks to run around the backup.
Type: submodule
Default:
{ }Declared by:
<selfhostblocks/modules/contracts/backup/dummyModule.nix> -
shb.contracts.backup.request.hooks.afterBackup -
Hooks to run after backup.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/contracts/backup/dummyModule.nix> -
shb.contracts.backup.request.hooks.beforeBackup -
Hooks to run before backup.
Type: list of string
Default:
[ ]Declared by:
<selfhostblocks/modules/contracts/backup/dummyModule.nix> -
shb.contracts.backup.request.sourceDirectories -
Directories to backup.
Type: non-empty (list of string)
Default:
[ "/var/lib/example" ]Example:
"/var/lib/vaultwarden"Declared by:
<selfhostblocks/modules/contracts/backup/dummyModule.nix> -
shb.contracts.backup.request.user -
Unix user doing the backups.
Type: string
Default:
""Example:
"vaultwarden"Declared by:
<selfhostblocks/modules/contracts/backup/dummyModule.nix> -
shb.contracts.backup.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/backup/dummyModule.nix> -
shb.contracts.backup.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/backup/dummyModule.nix> -
shb.contracts.backup.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>Type: string
Default:
"restore"Declared by:
<selfhostblocks/modules/contracts/backup/dummyModule.nix> -
shb.contracts.backup.settings -
Optional attribute set with options specific to the provider.
Type: anything
Declared by:
<selfhostblocks/modules/contracts/backup/dummyModule.nix>
Usage
A service that can be backed up will provide a backup 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.backup = mkOption {
type = lib.types.submodule {
options = shb.contracts.backup.mkRequester {
user = "nextcloud";
sourceDirectories = [
"/var/lib/nextcloud"
];
};
};
};
};
};
Now, on the other side we have a service that uses this backup option and actually backs up files.
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.backup.request;
settings = {
enable = true;
repository = {
path = "/srv/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.backup.request;
settings = {
enable = true;
repository = {
path = "<remote path>";
};
};
};
Or with another module backupService_2!
Providers of the Backup Contract
Script
Every provider instance generates a script with the needed credentials embedded in it.
The name of the script is derived from the name of the provider.
For example with the service restic, a backup instance
shb.restic.instances."myservice" would create a script named
restic-backups-myservice.
The available commands are:
list snapshots:
sudo <script> snapshotsto restore a snapshot:
sudo <script> restore <snapshot>to take a snapshot:
sudo <script> backupto execute a custom command where arguments are sent:
sudo <script> exec <args>the available commands depend on the provider but they all accept--help.
Requester Blocks and Services
Audiobookshelf (no manual yet)
Deluge (no manual yet)
Grocy (no manual yet)
Hledger (no manual yet)
Home Assistant (no manual yet)
Jellyfin (no manual yet)
LLDAP (no manual yet)
*arr (no manual yet)