diff options
Diffstat (limited to 'nixos/modules/services/backup/borgbackup.nix')
| -rw-r--r-- | nixos/modules/services/backup/borgbackup.nix | 174 |
1 files changed, 87 insertions, 87 deletions
diff --git a/nixos/modules/services/backup/borgbackup.nix b/nixos/modules/services/backup/borgbackup.nix index 4c9ddfe4674b2..147b827497ccd 100644 --- a/nixos/modules/services/backup/borgbackup.nix +++ b/nixos/modules/services/backup/borgbackup.nix @@ -219,7 +219,7 @@ in { ###### interface options.services.borgbackup.jobs = mkOption { - description = '' + description = lib.mdDoc '' 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. @@ -265,9 +265,9 @@ in { paths = mkOption { type = with types; nullOr (coercedTo str lib.singleton (listOf str)); default = null; - description = '' + description = lib.mdDoc '' Path(s) to back up. - Mutually exclusive with <option>dumpCommand</option>. + Mutually exclusive with {option}`dumpCommand`. ''; example = "/home/user"; }; @@ -275,42 +275,42 @@ in { dumpCommand = mkOption { type = with types; nullOr path; default = null; - description = '' + description = lib.mdDoc '' Backup the stdout of this program instead of filesystem paths. - Mutually exclusive with <option>paths</option>. + Mutually exclusive with {option}`paths`. ''; example = "/path/to/createZFSsend.sh"; }; repo = mkOption { type = types.str; - description = "Remote or local repository to back up to."; + description = lib.mdDoc "Remote or local repository to back up to."; example = "user@machine:/path/to/repo"; }; removableDevice = mkOption { type = types.bool; default = false; - description = "Whether the repo (which must be local) is a removable device."; + description = lib.mdDoc "Whether the repo (which must be local) is a removable device."; }; archiveBaseName = mkOption { type = types.nullOr (types.strMatching "[^/{}]+"); default = "${globalConfig.networking.hostName}-${name}"; defaultText = literalExpression ''"''${config.networking.hostName}-<name>"''; - description = '' + description = lib.mdDoc '' How to name the created archives. A timestamp, whose format is - determined by <option>dateFormat</option>, will be appended. The full - name can be modified at runtime (<literal>$archiveName</literal>). - Placeholders like <literal>{hostname}</literal> must not be used. - Use <literal>null</literal> for no base name. + 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. ''; }; dateFormat = mkOption { type = types.str; - description = '' - Arguments passed to <command>date</command> + description = lib.mdDoc '' + Arguments passed to {command}`date` to create a timestamp suffix for the archive name. ''; default = "+%Y-%m-%dT%H:%M:%S"; @@ -347,19 +347,19 @@ in { user = mkOption { type = types.str; - description = '' - The user <command>borg</command> is run as. + description = lib.mdDoc '' + The user {command}`borg` is run as. User or group need read permission - for the specified <option>paths</option>. + for the specified {option}`paths`. ''; default = "root"; }; group = mkOption { type = types.str; - description = '' + description = lib.mdDoc '' The group borg is run as. User or group needs read permission - for the specified <option>paths</option>. + for the specified {option}`paths`. ''; default = "root"; }; @@ -371,20 +371,20 @@ in { "authenticated" "authenticated-blake2" "none" ]; - description = '' + description = lib.mdDoc '' Encryption mode to use. Setting a mode - other than <literal>"none"</literal> requires - you to specify a <option>passCommand</option> - or a <option>passphrase</option>. + other than `"none"` requires + you to specify a {option}`passCommand` + or a {option}`passphrase`. ''; example = "repokey-blake2"; }; encryption.passCommand = mkOption { type = with types; nullOr str; - description = '' + description = lib.mdDoc '' A command which prints the passphrase to stdout. - Mutually exclusive with <option>passphrase</option>. + Mutually exclusive with {option}`passphrase`. ''; default = null; example = "cat /path/to/passphrase_file"; @@ -392,11 +392,11 @@ in { encryption.passphrase = mkOption { type = with types; nullOr str; - description = '' + description = lib.mdDoc '' The passphrase the backups are encrypted with. - Mutually exclusive with <option>passCommand</option>. + Mutually exclusive with {option}`passCommand`. If you do not want the passphrase to be stored in the - world-readable Nix store, use <option>passCommand</option>. + world-readable Nix store, use {option}`passCommand`. ''; default = null; }; @@ -406,9 +406,9 @@ in { # compression mode must be given, # compression level is optional type = types.strMatching "none|(auto,)?(lz4|zstd|zlib|lzma)(,[[:digit:]]{1,2})?"; - description = '' + description = lib.mdDoc '' Compression method to use. Refer to - <command>borg help compression</command> + {command}`borg help compression` for all available options. ''; default = "lz4"; @@ -417,9 +417,9 @@ in { exclude = mkOption { type = with types; listOf str; - description = '' + description = lib.mdDoc '' Exclude paths matching any of the given patterns. See - <command>borg help patterns</command> for pattern syntax. + {command}`borg help patterns` for pattern syntax. ''; default = [ ]; example = [ @@ -430,9 +430,9 @@ in { readWritePaths = mkOption { type = with types; listOf path; - description = '' + description = lib.mdDoc '' By default, borg cannot write anywhere on the system but - <literal>$HOME/.config/borg</literal> and <literal>$HOME/.cache/borg</literal>. + `$HOME/.config/borg` and `$HOME/.cache/borg`. If, for example, your preHook script needs to dump files somewhere, put those directories here. ''; @@ -444,8 +444,8 @@ in { privateTmp = mkOption { type = types.bool; - description = '' - Set the <literal>PrivateTmp</literal> option for + description = lib.mdDoc '' + Set the `PrivateTmp` option for the systemd-service. Set to false if you need sockets or other files from global /tmp. ''; @@ -454,10 +454,10 @@ in { doInit = mkOption { type = types.bool; - description = '' - Run <command>borg init</command> if the - specified <option>repo</option> does not exist. - You should set this to <literal>false</literal> + description = lib.mdDoc '' + 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. ''; @@ -466,10 +466,10 @@ in { appendFailedSuffix = mkOption { type = types.bool; - description = '' - Append a <literal>.failed</literal> suffix + description = lib.mdDoc '' + Append a `.failed` suffix to the archive name, which is only removed if - <command>borg create</command> has a zero exit status. + {command}`borg create` has a zero exit status. ''; default = true; }; @@ -479,9 +479,9 @@ in { # means there is no limit of yearly archives to keep # The regex is for use with e.g. --keep-within 1y type = with types; attrsOf (either int (strMatching "[[:digit:]]+[Hdwmy]")); - description = '' + description = lib.mdDoc '' Prune a repository by deleting all archives not matching any of the - specified retention options. See <command>borg help prune</command> + specified retention options. See {command}`borg help prune` for the available options. ''; default = { }; @@ -497,10 +497,10 @@ in { prune.prefix = mkOption { type = types.nullOr (types.str); - description = '' + description = lib.mdDoc '' Only consider archive names starting with this prefix for pruning. By default, only archives created by this job are considered. - Use <literal>""</literal> or <literal>null</literal> to consider all archives. + Use `""` or `null` to consider all archives. ''; default = config.archiveBaseName; defaultText = literalExpression "archiveBaseName"; @@ -508,7 +508,7 @@ in { environment = mkOption { type = with types; attrsOf str; - description = '' + description = lib.mdDoc '' Environment variables passed to the backup script. You can for example specify which SSH key to use. ''; @@ -518,7 +518,7 @@ in { preHook = mkOption { type = types.lines; - description = '' + description = lib.mdDoc '' Shell commands to run before the backup. This can for example be used to mount file systems. ''; @@ -531,43 +531,43 @@ in { postInit = mkOption { type = types.lines; - description = '' - Shell commands to run after <command>borg init</command>. + description = lib.mdDoc '' + Shell commands to run after {command}`borg init`. ''; default = ""; }; postCreate = mkOption { type = types.lines; - description = '' - Shell commands to run after <command>borg create</command>. The name - of the created archive is stored in <literal>$archiveName</literal>. + description = lib.mdDoc '' + Shell commands to run after {command}`borg create`. The name + of the created archive is stored in `$archiveName`. ''; default = ""; }; postPrune = mkOption { type = types.lines; - description = '' - Shell commands to run after <command>borg prune</command>. + description = lib.mdDoc '' + Shell commands to run after {command}`borg prune`. ''; default = ""; }; postHook = mkOption { type = types.lines; - description = '' + description = lib.mdDoc '' 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 <literal>$exitStatus</literal>. + The latter is available as `$exitStatus`. ''; default = ""; }; extraArgs = mkOption { type = types.str; - description = '' - Additional arguments for all <command>borg</command> calls the + description = lib.mdDoc '' + Additional arguments for all {command}`borg` calls the service has. Handle with care. ''; default = ""; @@ -576,9 +576,9 @@ in { extraInitArgs = mkOption { type = types.str; - description = '' - Additional arguments for <command>borg init</command>. - Can also be set at runtime using <literal>$extraInitArgs</literal>. + description = lib.mdDoc '' + Additional arguments for {command}`borg init`. + Can also be set at runtime using `$extraInitArgs`. ''; default = ""; example = "--append-only"; @@ -586,9 +586,9 @@ in { extraCreateArgs = mkOption { type = types.str; - description = '' - Additional arguments for <command>borg create</command>. - Can also be set at runtime using <literal>$extraCreateArgs</literal>. + description = lib.mdDoc '' + Additional arguments for {command}`borg create`. + Can also be set at runtime using `$extraCreateArgs`. ''; default = ""; example = "--stats --checkpoint-interval 600"; @@ -596,9 +596,9 @@ in { extraPruneArgs = mkOption { type = types.str; - description = '' - Additional arguments for <command>borg prune</command>. - Can also be set at runtime using <literal>$extraPruneArgs</literal>. + description = lib.mdDoc '' + Additional arguments for {command}`borg prune`. + Can also be set at runtime using `$extraPruneArgs`. ''; default = ""; example = "--save-space"; @@ -610,12 +610,12 @@ in { }; options.services.borgbackup.repos = mkOption { - description = '' + description = lib.mdDoc '' 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. <literal>user@machine:.</literal> is enough. (Note colon and dot.) + i.e. `user@machine:.` is enough. (Note colon and dot.) ''; default = { }; type = types.attrsOf (types.submodule ( @@ -623,7 +623,7 @@ in { options = { path = mkOption { type = types.path; - description = '' + description = lib.mdDoc '' Where to store the backups. Note that the directory is created automatically, with correct permissions. ''; @@ -632,30 +632,30 @@ in { user = mkOption { type = types.str; - description = '' - The user <command>borg serve</command> is run as. + description = lib.mdDoc '' + The user {command}`borg serve` is run as. User or group needs write permission - for the specified <option>path</option>. + for the specified {option}`path`. ''; default = "borg"; }; group = mkOption { type = types.str; - description = '' - The group <command>borg serve</command> is run as. + description = lib.mdDoc '' + The group {command}`borg serve` is run as. User or group needs write permission - for the specified <option>path</option>. + for the specified {option}`path`. ''; default = "borg"; }; authorizedKeys = mkOption { type = with types; listOf str; - description = '' + description = lib.mdDoc '' 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</command> + the specified keys are restricted to running {command}`borg serve` and can only access this single repository. ''; default = [ ]; @@ -663,7 +663,7 @@ in { authorizedKeysAppendOnly = mkOption { type = with types; listOf str; - description = '' + description = lib.mdDoc '' 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. @@ -673,11 +673,11 @@ in { allowSubRepos = mkOption { type = types.bool; - description = '' + description = lib.mdDoc '' Allow clients to create repositories in subdirectories of the - specified <option>path</option>. These can be accessed using - <literal>user@machine:path/to/subrepo</literal>. Note that a - <option>quota</option> applies to repositories independently. + 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. ''; @@ -687,9 +687,9 @@ in { quota = mkOption { # See the definition of parse_file_size() in src/borg/helpers/parseformat.py type = with types; nullOr (strMatching "[[:digit:].]+[KMGTP]?"); - description = '' + description = lib.mdDoc '' Storage quota for the repository. This quota is ensured for all - sub-repositories if <option>allowSubRepos</option> is enabled + sub-repositories if {option}`allowSubRepos` is enabled but not for the overall storage space used. ''; default = null; |