Borgbackup

`services.borgbackup.jobs`

Deduplicating backups using BorgBackup. Adding a job will cause a borg-job-NAME wrapper to be added to your system path, so that you can perform maintenance easily. See also the chapter about BorgBackup in the NixOS manual.

Type: attribute set of (submodule)

Default

{ }

Example

{ # for a local backuprootBackup = {paths = "/";exclude = [ "/nix" ];repo = "/path/to/local/repo";encryption = {mode = "repokey";passphrase = "secret";};compression = "auto,lzma";startAt = "weekly";};}{ # Root backing each day up to a remote backup server. We assume that you have# * created a password less key: ssh-keygen -N "" -t ed25519 -f /path/to/ssh_key# best practices are: use -t ed25519, /path/to = /run/keys# * the passphrase is in the file /run/keys/borgbackup_passphrase# * you have initialized the repository manuallypaths = [ "/etc" "/home" ];exclude = [ "/nix" "'**/.cache'" ];doInit = false;repo = "user3@arep.repo.borgbase.com:repo";encryption = {mode = "repokey-blake2";passCommand = "cat /path/to/passphrase";};environment = { BORG_RSH = "ssh -i /path/to/ssh_key"; };compression = "auto,lzma";startAt = "daily";};

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.appendFailedSuffix`

Append a .failed suffix to the archive name, which is only removed if {command}borg create has a zero exit status.

Type: boolean

Default

true

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.archiveBaseName`

How to name the created archives. A timestamp, whose format is determined by {option}dateFormat, will be appended. The full name can be modified at runtime ($archiveName). Placeholders like {hostname} must not be used. Use null for no base name.

Type: null or string matching the pattern [^/{}]+

Default

"${config.networking.hostName}-<name>"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.compression`

Compression method to use. Refer to {command}borg help compression for all available options.

Type: string matching the pattern none|(auto,)?(lz4|zstd|zlib|lzma)(,[[:digit:]]{1,2})?

Default

"lz4"

Example

"auto,lzma"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.dateFormat`

Arguments passed to {command}date to create a timestamp suffix for the archive name.

Type: string

Default

"+%Y-%m-%dT%H:%M:%S"

Example

"-u +%s"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.doInit`

Run {command}borg init if the specified {option}repo does not exist. You should set this to false if the repository is located on an external drive that might not always be mounted.

Type: boolean

Default

true

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.dumpCommand`

Backup the stdout of this program instead of filesystem paths. Mutually exclusive with {option}paths.

Type: null or path

Default

null

Example

"/path/to/createZFSsend.sh"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.encryption.mode`

Encryption mode to use. Setting a mode other than "none" requires you to specify a {option}passCommand or a {option}passphrase.

Type: one of "repokey", "keyfile", "repokey-blake2", "keyfile-blake2", "authenticated", "authenticated-blake2", "none"

Example

"repokey-blake2"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.encryption.passCommand`

A command which prints the passphrase to stdout. Mutually exclusive with {option}passphrase.

Type: null or string

Default

null

Example

"cat /path/to/passphrase_file"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.encryption.passphrase`

The passphrase the backups are encrypted with. Mutually exclusive with {option}passCommand. If you do not want the passphrase to be stored in the world-readable Nix store, use {option}passCommand.

Type: null or string

Default

null

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.environment`

Environment variables passed to the backup script. You can for example specify which SSH key to use.

Type: attribute set of string

Default

{ }

Example

{BORG_RSH = "ssh -i /path/to/key";}

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.exclude`

Exclude paths matching any of the given patterns. See {command}borg help patterns for pattern syntax.

Type: list of string

Default

[ ]

Example

["/home/*/.cache""/nix"]

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.extraArgs`

Additional arguments for all {command}borg calls the service has. Handle with care.

Type: string or (list of string) convertible to it

Default

[ ]

Example

["--remote-path=/path/to/borg"]

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.extraCompactArgs`

Additional arguments for {command}borg compact. Can also be set at runtime using $extraCompactArgs.

Type: string or (list of string) convertible to it

Default

[ ]

Example

["--cleanup-commits"]

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.extraCreateArgs`

Additional arguments for {command}borg create. Can also be set at runtime using $extraCreateArgs.

Type: string or (list of string) convertible to it

Default

[ ]

Example

["--stats""--checkpoint-interval 600"]

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.extraInitArgs`

Additional arguments for {command}borg init. Can also be set at runtime using $extraInitArgs.

Type: string or (list of string) convertible to it

Default

[ ]

Example

["--append-only"]

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.extraPruneArgs`

Additional arguments for {command}borg prune. Can also be set at runtime using $extraPruneArgs.

Type: string or (list of string) convertible to it

Default

[ ]

Example

["--save-space"]

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.failOnWarnings`

Fail the whole backup job if any borg command returns a warning (exit code 1), for example because a file changed during backup.

Type: boolean

Default

true

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.group`

The group borg is run as. User or group needs read permission for the specified {option}paths.

Type: string

Default

"root"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.inhibitsSleep`

Prevents the system from sleeping while backing up.

Type: boolean

Default

false

Example

true

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.paths`

Path(s) to back up. Mutually exclusive with {option}dumpCommand.

Type: null or ((list of string) or string convertible to it)

Default

null

Example

"/home/user"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.patterns`

Include/exclude paths matching the given patterns. The first matching patterns is used, so if an include pattern (prefix +) matches before an exclude pattern (prefix -), the file is backed up. See {command}borg help patterns for pattern syntax.

Type: list of string

Default

[ ]

Example

["+ /home/susan""- /home/*"]

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.persistentTimer`

Set the Persistent option for the {manpage}systemd.timer(5) which triggers the backup immediately if the last trigger was missed (e.g. if the system was powered down).

Type: boolean

Default

false

Example

true

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.postCreate`

Shell commands to run after {command}borg create. The name of the created archive is stored in $archiveName.

Type: strings concatenated with "\n"

Default

""

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.postHook`

Shell commands to run just before exit. They are executed even if a previous command exits with a non-zero exit code. The latter is available as $exitStatus.

Type: strings concatenated with "\n"

Default

""

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.postInit`

Shell commands to run after {command}borg init.

Type: strings concatenated with "\n"

Default

""

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.postPrune`

Shell commands to run after {command}borg prune.

Type: strings concatenated with "\n"

Default

""

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.preHook`

Shell commands to run before the backup. This can for example be used to mount file systems.

Type: strings concatenated with "\n"

Default

""

Example

'' # To add excluded paths at runtime extraCreateArgs="$extraCreateArgs --exclude /some/path"''

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.privateTmp`

Set the PrivateTmp option for the systemd-service. Set to false if you need sockets or other files from global /tmp.

Type: boolean

Default

true

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.prune.keep`

Prune a repository by deleting all archives not matching any of the specified retention options. See {command}borg help prune for the available options.

Type: attribute set of (signed integer or string matching the pattern [[:digit:]]+[Hdwmy])

Default

{ }

Example

{within = "1d"; # Keep all archives from the last daydaily = 7;weekly = 4;monthly = -1; # Keep at least one archive for each month}

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.prune.prefix`

Only consider archive names starting with this prefix for pruning. By default, only archives created by this job are considered. Use "" or null to consider all archives.

Type: null or string

Default

archiveBaseName

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.readWritePaths`

By default, borg cannot write anywhere on the system but $HOME/.config/borg and $HOME/.cache/borg. If, for example, your preHook script needs to dump files somewhere, put those directories here.

Type: list of path

Default

[ ]

Example

["/var/backup/mysqldump"]

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.removableDevice`

Whether the repo (which must be local) is a removable device. Type: boolean

Default

false

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.repo`

Remote or local repository to back up to. Type: string

Example

"user@machine:/path/to/repo"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.startAt`

When or how often the backup should run. Must be in the format described in {manpage}systemd.time(7). If you do not want the backup to start automatically, use [ ]. It will generate a systemd service borgbackup-job-NAME. You may trigger it manually via systemctl restart borgbackup-job-NAME.

Type: string or list of string

Default

"daily"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.jobs.<name>.user`

The user {command}borg is run as. User or group need read permission for the specified {option}paths.

Type: string

Default

"root"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.package`

The borgbackup package to use. Type: package

Default

pkgs.borgbackup

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.repos`

Serve BorgBackup repositories to given public SSH keys, restricting their access to the repository only. See also the chapter about BorgBackup in the NixOS manual. Also, clients do not need to specify the absolute path when accessing the repository, i.e. user@machine:. is enough. (Note colon and dot.)

Type: attribute set of (submodule)

Default

{ }

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.repos.<name>.allowSubRepos`

Allow clients to create repositories in subdirectories of the specified {option}path. These can be accessed using user@machine:path/to/subrepo. Note that a {option}quota applies to repositories independently. Therefore, if this is enabled, clients can create multiple repositories and upload an arbitrary amount of data.

Type: boolean

Default

false

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.repos.<name>.authorizedKeys`

Public SSH keys that are given full write access to this repository. You should use a different SSH key for each repository you write to, because the specified keys are restricted to running {command}borg serve and can only access this single repository.

Type: list of string

Default

[ ]

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.repos.<name>.authorizedKeysAppendOnly`

Public SSH keys that can only be used to append new data (archives) to the repository. Note that archives can still be marked as deleted and are subsequently removed from disk upon accessing the repo with full write access, e.g. when pruning.

Type: list of string

Default

[ ]

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.repos.<name>.group`

The group {command}borg serve is run as. User or group needs write permission for the specified {option}path.

Type: string

Default

"borg"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.repos.<name>.path`

Where to store the backups. Note that the directory is created automatically, with correct permissions.

Type: path

Default

"/var/lib/borgbackup"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.repos.<name>.quota`

Storage quota for the repository. This quota is ensured for all sub-repositories if {option}allowSubRepos is enabled but not for the overall storage space used.

Type: null or string matching the pattern [[:digit:].]+[KMGTP]?

Default

null

Example

"100G"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix

`services.borgbackup.repos.<name>.user`

The user {command}borg serve is run as. User or group needs write permission for the specified {option}path.

Type: string

Default

"borg"

Declared by: https://github.com/nixos/nixpkgs/blob/master/nixos/modules/services/backup/borgbackup.nix