Improve configuration reference documentation readability via more aggressive word-wrapping in configuration schema descriptions.
This commit is contained in:
parent
b320e74ad5
commit
7fb4061759
3 changed files with 274 additions and 193 deletions
2
NEWS
2
NEWS
|
@ -1,5 +1,7 @@
|
||||||
1.5.7.dev0
|
1.5.7.dev0
|
||||||
* Update documentation code fragments theme to better match the rest of the page.
|
* Update documentation code fragments theme to better match the rest of the page.
|
||||||
|
* Improve configuration reference documentation readability via more aggressive word-wrapping in
|
||||||
|
configuration schema descriptions.
|
||||||
|
|
||||||
1.5.6
|
1.5.6
|
||||||
* #292: Allow before_backup and similiar hooks to exit with a soft failure without altering the
|
* #292: Allow before_backup and similiar hooks to exit with a soft failure without altering the
|
||||||
|
|
|
@ -3,9 +3,10 @@ version: 1
|
||||||
map:
|
map:
|
||||||
location:
|
location:
|
||||||
desc: |
|
desc: |
|
||||||
Where to look for files to backup, and where to store those backups. See
|
Where to look for files to backup, and where to store those backups.
|
||||||
https://borgbackup.readthedocs.io/en/stable/quickstart.html and
|
See https://borgbackup.readthedocs.io/en/stable/quickstart.html and
|
||||||
https://borgbackup.readthedocs.io/en/stable/usage.html#borg-create for details.
|
https://borgbackup.readthedocs.io/en/stable/usage/create.html
|
||||||
|
for details.
|
||||||
required: true
|
required: true
|
||||||
map:
|
map:
|
||||||
source_directories:
|
source_directories:
|
||||||
|
@ -13,7 +14,8 @@ map:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
List of source directories to backup (required). Globs and tildes are expanded.
|
List of source directories to backup (required). Globs and
|
||||||
|
tildes are expanded.
|
||||||
example:
|
example:
|
||||||
- /home
|
- /home
|
||||||
- /etc
|
- /etc
|
||||||
|
@ -23,21 +25,25 @@ map:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
Paths to local or remote repositories (required). Tildes are expanded. Multiple
|
Paths to local or remote repositories (required). Tildes are
|
||||||
repositories are backed up to in sequence. See ssh_command for SSH options like
|
expanded. Multiple repositories are backed up to in
|
||||||
identity file or port.
|
sequence. See ssh_command for SSH options like identity file
|
||||||
|
or port.
|
||||||
example:
|
example:
|
||||||
- user@backupserver:sourcehostname.borg
|
- user@backupserver:sourcehostname.borg
|
||||||
one_file_system:
|
one_file_system:
|
||||||
type: bool
|
type: bool
|
||||||
desc: |
|
desc: |
|
||||||
Stay in same file system (do not cross mount points). Defaults to false. But when
|
Stay in same file system (do not cross mount points).
|
||||||
a database hook is used, the setting here is ignored and one_file_system is
|
Defaults to false. But when a database hook is used, the
|
||||||
considered true.
|
setting here is ignored and one_file_system is considered
|
||||||
|
true.
|
||||||
example: true
|
example: true
|
||||||
numeric_owner:
|
numeric_owner:
|
||||||
type: bool
|
type: bool
|
||||||
desc: Only store/extract numeric user and group identifiers. Defaults to false.
|
desc: |
|
||||||
|
Only store/extract numeric user and group identifiers.
|
||||||
|
Defaults to false.
|
||||||
example: true
|
example: true
|
||||||
atime:
|
atime:
|
||||||
type: bool
|
type: bool
|
||||||
|
@ -49,27 +55,32 @@ map:
|
||||||
example: false
|
example: false
|
||||||
birthtime:
|
birthtime:
|
||||||
type: bool
|
type: bool
|
||||||
desc: Store birthtime (creation date) into archive. Defaults to true.
|
desc: |
|
||||||
|
Store birthtime (creation date) into archive. Defaults to
|
||||||
|
true.
|
||||||
example: false
|
example: false
|
||||||
read_special:
|
read_special:
|
||||||
type: bool
|
type: bool
|
||||||
desc: |
|
desc: |
|
||||||
Use Borg's --read-special flag to allow backup of block and other special
|
Use Borg's --read-special flag to allow backup of block and
|
||||||
devices. Use with caution, as it will lead to problems if used when
|
other special devices. Use with caution, as it will lead to
|
||||||
backing up special devices such as /dev/zero. Defaults to false. But when a
|
problems if used when backing up special devices such as
|
||||||
database hook is used, the setting here is ignored and read_special is
|
/dev/zero. Defaults to false. But when a database hook is
|
||||||
|
used, the setting here is ignored and read_special is
|
||||||
considered true.
|
considered true.
|
||||||
example: false
|
example: false
|
||||||
bsd_flags:
|
bsd_flags:
|
||||||
type: bool
|
type: bool
|
||||||
desc: Record bsdflags (e.g. NODUMP, IMMUTABLE) in archive. Defaults to true.
|
desc: |
|
||||||
|
Record bsdflags (e.g. NODUMP, IMMUTABLE) in archive.
|
||||||
|
Defaults to true.
|
||||||
example: true
|
example: true
|
||||||
files_cache:
|
files_cache:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Mode in which to operate the files cache. See
|
Mode in which to operate the files cache. See
|
||||||
https://borgbackup.readthedocs.io/en/stable/usage/create.html#description for
|
http://borgbackup.readthedocs.io/en/stable/usage/create.html
|
||||||
details. Defaults to "ctime,size,inode".
|
for details. Defaults to "ctime,size,inode".
|
||||||
example: ctime,size,inode
|
example: ctime,size,inode
|
||||||
local_path:
|
local_path:
|
||||||
type: str
|
type: str
|
||||||
|
@ -83,9 +94,10 @@ map:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
Any paths matching these patterns are included/excluded from backups. Globs are
|
Any paths matching these patterns are included/excluded from
|
||||||
expanded. (Tildes are not.) Note that Borg considers this option experimental.
|
backups. Globs are expanded. (Tildes are not.) Note that
|
||||||
See the output of "borg help patterns" for more details. Quote any value if it
|
Borg considers this option experimental. See the output of
|
||||||
|
"borg help patterns" for more details. Quote any value if it
|
||||||
contains leading punctuation, so it parses correctly.
|
contains leading punctuation, so it parses correctly.
|
||||||
example:
|
example:
|
||||||
- 'R /'
|
- 'R /'
|
||||||
|
@ -96,17 +108,19 @@ map:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
Read include/exclude patterns from one or more separate named files, one pattern
|
Read include/exclude patterns from one or more separate
|
||||||
per line. Note that Borg considers this option experimental. See the output of
|
named files, one pattern per line. Note that Borg considers
|
||||||
"borg help patterns" for more details.
|
this option experimental. See the output of "borg help
|
||||||
|
patterns" for more details.
|
||||||
example:
|
example:
|
||||||
- /etc/borgmatic/patterns
|
- /etc/borgmatic/patterns
|
||||||
exclude_patterns:
|
exclude_patterns:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
Any paths matching these patterns are excluded from backups. Globs and tildes
|
Any paths matching these patterns are excluded from backups.
|
||||||
are expanded. See the output of "borg help patterns" for more details.
|
Globs and tildes are expanded. See the output of "borg help
|
||||||
|
patterns" for more details.
|
||||||
example:
|
example:
|
||||||
- '*.pyc'
|
- '*.pyc'
|
||||||
- ~/*/.cache
|
- ~/*/.cache
|
||||||
|
@ -115,29 +129,32 @@ map:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
Read exclude patterns from one or more separate named files, one pattern per
|
Read exclude patterns from one or more separate named files,
|
||||||
line. See the output of "borg help patterns" for more details.
|
one pattern per line. See the output of "borg help patterns"
|
||||||
|
for more details.
|
||||||
example:
|
example:
|
||||||
- /etc/borgmatic/excludes
|
- /etc/borgmatic/excludes
|
||||||
exclude_caches:
|
exclude_caches:
|
||||||
type: bool
|
type: bool
|
||||||
desc: |
|
desc: |
|
||||||
Exclude directories that contain a CACHEDIR.TAG file. See
|
Exclude directories that contain a CACHEDIR.TAG file. See
|
||||||
http://www.brynosaurus.com/cachedir/spec.html for details. Defaults to false.
|
http://www.brynosaurus.com/cachedir/spec.html for details.
|
||||||
|
Defaults to false.
|
||||||
example: true
|
example: true
|
||||||
exclude_if_present:
|
exclude_if_present:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
Exclude directories that contain a file with the given filenames. Defaults to not
|
Exclude directories that contain a file with the given
|
||||||
set.
|
filenames. Defaults to not set.
|
||||||
example:
|
example:
|
||||||
- .nobackup
|
- .nobackup
|
||||||
keep_exclude_tags:
|
keep_exclude_tags:
|
||||||
type: bool
|
type: bool
|
||||||
desc: |
|
desc: |
|
||||||
If true, the exclude_if_present filename is included in backups. Defaults to
|
If true, the exclude_if_present filename is included in
|
||||||
false, meaning that the exclude_if_present filename is omitted from backups.
|
backups. Defaults to false, meaning that the
|
||||||
|
exclude_if_present filename is omitted from backups.
|
||||||
example: true
|
example: true
|
||||||
exclude_nodump:
|
exclude_nodump:
|
||||||
type: bool
|
type: bool
|
||||||
|
@ -147,90 +164,103 @@ map:
|
||||||
borgmatic_source_directory:
|
borgmatic_source_directory:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Path for additional source files used for temporary internal state like
|
Path for additional source files used for temporary internal
|
||||||
borgmatic database dumps. Note that changing this path prevents "borgmatic
|
state like borgmatic database dumps. Note that changing this
|
||||||
restore" from finding any database dumps created before the change. Defaults
|
path prevents "borgmatic restore" from finding any database
|
||||||
to ~/.borgmatic
|
dumps created before the change. Defaults to ~/.borgmatic
|
||||||
example: /tmp/borgmatic
|
example: /tmp/borgmatic
|
||||||
storage:
|
storage:
|
||||||
desc: |
|
desc: |
|
||||||
Repository storage options. See
|
Repository storage options. See
|
||||||
https://borgbackup.readthedocs.io/en/stable/usage.html#borg-create and
|
https://borgbackup.readthedocs.io/en/stable/usage/create.html and
|
||||||
https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables for
|
https://borgbackup.readthedocs.io/en/stable/usage/general.html for
|
||||||
details.
|
details.
|
||||||
map:
|
map:
|
||||||
encryption_passcommand:
|
encryption_passcommand:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
The standard output of this command is used to unlock the encryption key. Only
|
The standard output of this command is used to unlock the
|
||||||
use on repositories that were initialized with passcommand/repokey encryption.
|
encryption key. Only use on repositories that were
|
||||||
Note that if both encryption_passcommand and encryption_passphrase are set,
|
initialized with passcommand/repokey encryption. Note that
|
||||||
then encryption_passphrase takes precedence. Defaults to not set.
|
if both encryption_passcommand and encryption_passphrase are
|
||||||
|
set, then encryption_passphrase takes precedence. Defaults
|
||||||
|
to not set.
|
||||||
example: "secret-tool lookup borg-repository repo-name"
|
example: "secret-tool lookup borg-repository repo-name"
|
||||||
encryption_passphrase:
|
encryption_passphrase:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Passphrase to unlock the encryption key with. Only use on repositories that were
|
Passphrase to unlock the encryption key with. Only use on
|
||||||
initialized with passphrase/repokey encryption. Quote the value if it contains
|
repositories that were initialized with passphrase/repokey
|
||||||
punctuation, so it parses correctly. And backslash any quote or backslash
|
encryption. Quote the value if it contains punctuation, so
|
||||||
|
it parses correctly. And backslash any quote or backslash
|
||||||
literals as well. Defaults to not set.
|
literals as well. Defaults to not set.
|
||||||
example: "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"
|
example: "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"
|
||||||
checkpoint_interval:
|
checkpoint_interval:
|
||||||
type: int
|
type: int
|
||||||
desc: |
|
desc: |
|
||||||
Number of seconds between each checkpoint during a long-running backup. See
|
Number of seconds between each checkpoint during a
|
||||||
https://borgbackup.readthedocs.io/en/stable/faq.html#if-a-backup-stops-mid-way-does-the-already-backed-up-data-stay-there
|
long-running backup. See
|
||||||
for details. Defaults to checkpoints every 1800 seconds (30 minutes).
|
https://borgbackup.readthedocs.io/en/stable/faq.html
|
||||||
|
for details. Defaults to checkpoints every 1800 seconds (30
|
||||||
|
minutes).
|
||||||
example: 1800
|
example: 1800
|
||||||
chunker_params:
|
chunker_params:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Specify the parameters passed to then chunker (CHUNK_MIN_EXP, CHUNK_MAX_EXP,
|
Specify the parameters passed to then chunker
|
||||||
HASH_MASK_BITS, HASH_WINDOW_SIZE). See https://borgbackup.readthedocs.io/en/stable/internals.html
|
(CHUNK_MIN_EXP, CHUNK_MAX_EXP, HASH_MASK_BITS,
|
||||||
|
HASH_WINDOW_SIZE). See
|
||||||
|
https://borgbackup.readthedocs.io/en/stable/internals.html
|
||||||
for details. Defaults to "19,23,21,4095".
|
for details. Defaults to "19,23,21,4095".
|
||||||
example: 19,23,21,4095
|
example: 19,23,21,4095
|
||||||
compression:
|
compression:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Type of compression to use when creating archives. See
|
Type of compression to use when creating archives. See
|
||||||
https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create for details.
|
http://borgbackup.readthedocs.io/en/stable/usage/create.html
|
||||||
Defaults to "lz4".
|
for details. Defaults to "lz4".
|
||||||
example: lz4
|
example: lz4
|
||||||
remote_rate_limit:
|
remote_rate_limit:
|
||||||
type: int
|
type: int
|
||||||
desc: Remote network upload rate limit in kiBytes/second. Defaults to unlimited.
|
desc: |
|
||||||
|
Remote network upload rate limit in kiBytes/second. Defaults
|
||||||
|
to unlimited.
|
||||||
example: 100
|
example: 100
|
||||||
ssh_command:
|
ssh_command:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Command to use instead of "ssh". This can be used to specify ssh options.
|
Command to use instead of "ssh". This can be used to specify
|
||||||
Defaults to not set.
|
ssh options. Defaults to not set.
|
||||||
example: ssh -i /path/to/private/key
|
example: ssh -i /path/to/private/key
|
||||||
borg_base_directory:
|
borg_base_directory:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Base path used for various Borg directories. Defaults to $HOME, ~$USER, or ~.
|
Base path used for various Borg directories. Defaults to
|
||||||
See https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables for details.
|
$HOME, ~$USER, or ~.
|
||||||
example: /path/to/base
|
example: /path/to/base
|
||||||
borg_config_directory:
|
borg_config_directory:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Path for Borg configuration files. Defaults to $borg_base_directory/.config/borg
|
Path for Borg configuration files. Defaults to
|
||||||
|
$borg_base_directory/.config/borg
|
||||||
example: /path/to/base/config
|
example: /path/to/base/config
|
||||||
borg_cache_directory:
|
borg_cache_directory:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Path for Borg cache files. Defaults to $borg_base_directory/.cache/borg
|
Path for Borg cache files. Defaults to
|
||||||
|
$borg_base_directory/.cache/borg
|
||||||
example: /path/to/base/cache
|
example: /path/to/base/cache
|
||||||
borg_security_directory:
|
borg_security_directory:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Path for Borg security and encryption nonce files. Defaults to $borg_base_directory/.config/borg/security
|
Path for Borg security and encryption nonce files. Defaults
|
||||||
|
to $borg_base_directory/.config/borg/security
|
||||||
example: /path/to/base/config/security
|
example: /path/to/base/config/security
|
||||||
borg_keys_directory:
|
borg_keys_directory:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Path for Borg encryption key files. Defaults to $borg_base_directory/.config/borg/keys
|
Path for Borg encryption key files. Defaults to
|
||||||
|
$borg_base_directory/.config/borg/keys
|
||||||
example: /path/to/base/config/keys
|
example: /path/to/base/config/keys
|
||||||
umask:
|
umask:
|
||||||
type: scalar
|
type: scalar
|
||||||
|
@ -238,58 +268,69 @@ map:
|
||||||
example: 0077
|
example: 0077
|
||||||
lock_wait:
|
lock_wait:
|
||||||
type: int
|
type: int
|
||||||
desc: Maximum seconds to wait for acquiring a repository/cache lock. Defaults to 1.
|
desc: |
|
||||||
|
Maximum seconds to wait for acquiring a repository/cache
|
||||||
|
lock. Defaults to 1.
|
||||||
example: 5
|
example: 5
|
||||||
archive_name_format:
|
archive_name_format:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Name of the archive. Borg placeholders can be used. See the output of
|
Name of the archive. Borg placeholders can be used. See the
|
||||||
"borg help placeholders" for details. Defaults to
|
output of "borg help placeholders" for details. Defaults to
|
||||||
"{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}". If you specify this option, you must
|
"{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}". If you specify this
|
||||||
also specify a prefix in the retention section to avoid accidental pruning of
|
option, you must also specify a prefix in the retention
|
||||||
archives with a different archive name format. And you should also specify a
|
section to avoid accidental pruning of archives with a
|
||||||
|
different archive name format. And you should also specify a
|
||||||
prefix in the consistency section as well.
|
prefix in the consistency section as well.
|
||||||
example: "{hostname}-documents-{now}"
|
example: "{hostname}-documents-{now}"
|
||||||
relocated_repo_access_is_ok:
|
relocated_repo_access_is_ok:
|
||||||
type: bool
|
type: bool
|
||||||
desc: Bypass Borg error about a repository that has been moved. Defaults to false.
|
desc: |
|
||||||
|
Bypass Borg error about a repository that has been moved.
|
||||||
|
Defaults to false.
|
||||||
example: true
|
example: true
|
||||||
unknown_unencrypted_repo_access_is_ok:
|
unknown_unencrypted_repo_access_is_ok:
|
||||||
type: bool
|
type: bool
|
||||||
desc: |
|
desc: |
|
||||||
Bypass Borg error about a previously unknown unencrypted repository. Defaults to
|
Bypass Borg error about a previously unknown unencrypted
|
||||||
false.
|
repository. Defaults to false.
|
||||||
example: true
|
example: true
|
||||||
extra_borg_options:
|
extra_borg_options:
|
||||||
map:
|
map:
|
||||||
init:
|
init:
|
||||||
type: str
|
type: str
|
||||||
desc: Extra command-line options to pass to "borg init".
|
desc: |
|
||||||
|
Extra command-line options to pass to "borg init".
|
||||||
example: "--make-parent-dirs"
|
example: "--make-parent-dirs"
|
||||||
prune:
|
prune:
|
||||||
type: str
|
type: str
|
||||||
desc: Extra command-line options to pass to "borg prune".
|
desc: |
|
||||||
|
Extra command-line options to pass to "borg prune".
|
||||||
example: "--save-space"
|
example: "--save-space"
|
||||||
create:
|
create:
|
||||||
type: str
|
type: str
|
||||||
desc: Extra command-line options to pass to "borg create".
|
desc: |
|
||||||
|
Extra command-line options to pass to "borg create".
|
||||||
example: "--no-files-cache"
|
example: "--no-files-cache"
|
||||||
check:
|
check:
|
||||||
type: str
|
type: str
|
||||||
desc: Extra command-line options to pass to "borg check".
|
desc: |
|
||||||
|
Extra command-line options to pass to "borg check".
|
||||||
example: "--save-space"
|
example: "--save-space"
|
||||||
desc: |
|
desc: |
|
||||||
Additional options to pass directly to particular Borg commands, handy for Borg
|
Additional options to pass directly to particular Borg
|
||||||
options that borgmatic does not yet support natively. Note that borgmatic does
|
commands, handy for Borg options that borgmatic does not yet
|
||||||
not perform any validation on these options. Running borgmatic with
|
support natively. Note that borgmatic does not perform any
|
||||||
"--verbosity 2" shows the exact Borg command-line invocation.
|
validation on these options. Running borgmatic with
|
||||||
|
"--verbosity 2" shows the exact Borg command-line
|
||||||
|
invocation.
|
||||||
retention:
|
retention:
|
||||||
desc: |
|
desc: |
|
||||||
Retention policy for how many backups to keep in each category. See
|
Retention policy for how many backups to keep in each category. See
|
||||||
https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for details.
|
https://borgbackup.readthedocs.io/en/stable/usage/prune.html for
|
||||||
At least one of the "keep" options is required for pruning to work. See
|
details. At least one of the "keep" options is required for pruning
|
||||||
https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/
|
to work. See borgmatic documentation if you'd like to skip pruning
|
||||||
if you'd like to skip pruning entirely.
|
entirely.
|
||||||
map:
|
map:
|
||||||
keep_within:
|
keep_within:
|
||||||
type: str
|
type: str
|
||||||
|
@ -326,27 +367,37 @@ map:
|
||||||
prefix:
|
prefix:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
When pruning, only consider archive names starting with this prefix.
|
When pruning, only consider archive names starting with this
|
||||||
Borg placeholders can be used. See the output of "borg help placeholders" for
|
prefix. Borg placeholders can be used. See the output of
|
||||||
details. Defaults to "{hostname}-". Use an empty value to disable the default.
|
"borg help placeholders" for details. Defaults to
|
||||||
|
"{hostname}-". Use an empty value to disable the default.
|
||||||
example: sourcehostname
|
example: sourcehostname
|
||||||
consistency:
|
consistency:
|
||||||
desc: |
|
desc: |
|
||||||
Consistency checks to run after backups. See
|
Consistency checks to run after backups. See
|
||||||
https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check and
|
https://borgbackup.readthedocs.io/en/stable/usage/check.html and
|
||||||
https://borgbackup.readthedocs.org/en/stable/usage.html#borg-extract for details.
|
https://borgbackup.readthedocs.io/en/stable/usage/extract.html for
|
||||||
|
details.
|
||||||
map:
|
map:
|
||||||
checks:
|
checks:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
enum: ['repository', 'archives', 'data', 'extract', 'disabled']
|
enum: [
|
||||||
|
'repository',
|
||||||
|
'archives',
|
||||||
|
'data',
|
||||||
|
'extract',
|
||||||
|
'disabled'
|
||||||
|
]
|
||||||
unique: true
|
unique: true
|
||||||
desc: |
|
desc: |
|
||||||
List of one or more consistency checks to run: "repository", "archives", "data",
|
List of one or more consistency checks to run: "repository",
|
||||||
and/or "extract". Defaults to "repository" and "archives". Set to "disabled" to
|
"archives", "data", and/or "extract". Defaults to
|
||||||
disable all consistency checks. "repository" checks the consistency of the
|
"repository" and "archives". Set to "disabled" to disable
|
||||||
repository, "archives" checks all of the archives, "data" verifies the integrity
|
all consistency checks. "repository" checks the consistency
|
||||||
of the data within the archives, and "extract" does an extraction dry-run of the
|
of the repository, "archives" checks all of the archives,
|
||||||
|
"data" verifies the integrity of the data within the
|
||||||
|
archives, and "extract" does an extraction dry-run of the
|
||||||
most recent archive. Note that "data" implies "archives".
|
most recent archive. Note that "data" implies "archives".
|
||||||
example:
|
example:
|
||||||
- repository
|
- repository
|
||||||
|
@ -355,24 +406,29 @@ map:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
Paths to a subset of the repositories in the location section on which to run
|
Paths to a subset of the repositories in the location
|
||||||
consistency checks. Handy in case some of your repositories are very large, and
|
section on which to run consistency checks. Handy in case
|
||||||
so running consistency checks on them would take too long. Defaults to running
|
some of your repositories are very large, and so running
|
||||||
consistency checks on all repositories configured in the location section.
|
consistency checks on them would take too long. Defaults to
|
||||||
|
running consistency checks on all repositories configured in
|
||||||
|
the location section.
|
||||||
example:
|
example:
|
||||||
- user@backupserver:sourcehostname.borg
|
- user@backupserver:sourcehostname.borg
|
||||||
check_last:
|
check_last:
|
||||||
type: int
|
type: int
|
||||||
desc: Restrict the number of checked archives to the last n. Applies only to the
|
desc: |
|
||||||
"archives" check. Defaults to checking all archives.
|
Restrict the number of checked archives to the last n.
|
||||||
|
Applies only to the "archives" check. Defaults to checking
|
||||||
|
all archives.
|
||||||
example: 3
|
example: 3
|
||||||
prefix:
|
prefix:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
When performing the "archives" check, only consider archive names starting with
|
When performing the "archives" check, only consider archive
|
||||||
this prefix. Borg placeholders can be used. See the output of
|
names starting with this prefix. Borg placeholders can be
|
||||||
"borg help placeholders" for details. Defaults to "{hostname}-". Use an empty
|
used. See the output of "borg help placeholders" for
|
||||||
value to disable the default.
|
details. Defaults to "{hostname}-". Use an empty value to
|
||||||
|
disable the default.
|
||||||
example: sourcehostname
|
example: sourcehostname
|
||||||
output:
|
output:
|
||||||
desc: |
|
desc: |
|
||||||
|
@ -381,72 +437,73 @@ map:
|
||||||
color:
|
color:
|
||||||
type: bool
|
type: bool
|
||||||
desc: |
|
desc: |
|
||||||
Apply color to console output. Can be overridden with --no-color command-line
|
Apply color to console output. Can be overridden with
|
||||||
flag. Defaults to true.
|
--no-color command-line flag. Defaults to true.
|
||||||
example: false
|
example: false
|
||||||
hooks:
|
hooks:
|
||||||
desc: |
|
desc: |
|
||||||
Shell commands, scripts, or integrations to execute at various points during a borgmatic
|
Shell commands, scripts, or integrations to execute at various
|
||||||
run. IMPORTANT: All provided commands and scripts are executed with user permissions of
|
points during a borgmatic run. IMPORTANT: All provided commands and
|
||||||
borgmatic. Do not forget to set secure permissions on this configuration file (chmod
|
scripts are executed with user permissions of borgmatic. Do not
|
||||||
0600) as well as on any script called from a hook (chmod 0700) to prevent potential
|
forget to set secure permissions on this configuration file (chmod
|
||||||
shell injection or privilege escalation.
|
0600) as well as on any script called from a hook (chmod 0700) to
|
||||||
|
prevent potential shell injection or privilege escalation.
|
||||||
map:
|
map:
|
||||||
before_backup:
|
before_backup:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
List of one or more shell commands or scripts to execute before creating a
|
List of one or more shell commands or scripts to execute
|
||||||
backup, run once per configuration file.
|
before creating a backup, run once per configuration file.
|
||||||
example:
|
example:
|
||||||
- echo "Starting a backup."
|
- echo "Starting a backup."
|
||||||
before_prune:
|
before_prune:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
List of one or more shell commands or scripts to execute before pruning, run
|
List of one or more shell commands or scripts to execute
|
||||||
once per configuration file.
|
before pruning, run once per configuration file.
|
||||||
example:
|
example:
|
||||||
- echo "Starting pruning."
|
- echo "Starting pruning."
|
||||||
before_check:
|
before_check:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
List of one or more shell commands or scripts to execute before consistency
|
List of one or more shell commands or scripts to execute
|
||||||
checks, run once per configuration file.
|
before consistency checks, run once per configuration file.
|
||||||
example:
|
example:
|
||||||
- echo "Starting checks."
|
- echo "Starting checks."
|
||||||
after_backup:
|
after_backup:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
List of one or more shell commands or scripts to execute after creating a
|
List of one or more shell commands or scripts to execute
|
||||||
backup, run once per configuration file.
|
after creating a backup, run once per configuration file.
|
||||||
example:
|
example:
|
||||||
- echo "Finished a backup."
|
- echo "Finished a backup."
|
||||||
after_prune:
|
after_prune:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
List of one or more shell commands or scripts to execute after pruning, run once
|
List of one or more shell commands or scripts to execute
|
||||||
per configuration file.
|
after pruning, run once per configuration file.
|
||||||
example:
|
example:
|
||||||
- echo "Finished pruning."
|
- echo "Finished pruning."
|
||||||
after_check:
|
after_check:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
List of one or more shell commands or scripts to execute after consistency
|
List of one or more shell commands or scripts to execute
|
||||||
checks, run once per configuration file.
|
after consistency checks, run once per configuration file.
|
||||||
example:
|
example:
|
||||||
- echo "Finished checks."
|
- echo "Finished checks."
|
||||||
on_error:
|
on_error:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
List of one or more shell commands or scripts to execute when an exception
|
List of one or more shell commands or scripts to execute
|
||||||
occurs during a "prune", "create", or "check" action or an associated
|
when an exception occurs during a "prune", "create", or
|
||||||
before/after hook.
|
"check" action or an associated before/after hook.
|
||||||
example:
|
example:
|
||||||
- echo "Error during prune/create/check."
|
- echo "Error during prune/create/check."
|
||||||
postgresql_databases:
|
postgresql_databases:
|
||||||
|
@ -456,16 +513,17 @@ map:
|
||||||
required: true
|
required: true
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Database name (required if using this hook). Or "all" to dump all
|
Database name (required if using this hook). Or
|
||||||
databases on the host. Note that using this database hook implicitly
|
"all" to dump all databases on the host. Note
|
||||||
enables both read_special and one_file_system (see above) to support
|
that using this database hook implicitly enables
|
||||||
dump and restore streaming.
|
both read_special and one_file_system (see
|
||||||
|
above) to support dump and restore streaming.
|
||||||
example: users
|
example: users
|
||||||
hostname:
|
hostname:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Database hostname to connect to. Defaults to connecting via local
|
Database hostname to connect to. Defaults to
|
||||||
Unix socket.
|
connecting via local Unix socket.
|
||||||
example: database.example.org
|
example: database.example.org
|
||||||
port:
|
port:
|
||||||
type: int
|
type: int
|
||||||
|
@ -474,39 +532,46 @@ map:
|
||||||
username:
|
username:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Username with which to connect to the database. Defaults to the
|
Username with which to connect to the database.
|
||||||
username of the current user. You probably want to specify the
|
Defaults to the username of the current user.
|
||||||
"postgres" superuser here when the database name is "all".
|
You probably want to specify the "postgres"
|
||||||
|
superuser here when the database name is "all".
|
||||||
example: dbuser
|
example: dbuser
|
||||||
password:
|
password:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Password with which to connect to the database. Omitting a password
|
Password with which to connect to the database.
|
||||||
will only work if PostgreSQL is configured to trust the configured
|
Omitting a password will only work if PostgreSQL
|
||||||
username without a password, or you create a ~/.pgpass file.
|
is configured to trust the configured username
|
||||||
|
without a password, or you create a ~/.pgpass
|
||||||
|
file.
|
||||||
example: trustsome1
|
example: trustsome1
|
||||||
format:
|
format:
|
||||||
type: str
|
type: str
|
||||||
enum: ['plain', 'custom', 'directory', 'tar']
|
enum: ['plain', 'custom', 'directory', 'tar']
|
||||||
desc: |
|
desc: |
|
||||||
Database dump output format. One of "plain", "custom", "directory",
|
Database dump output format. One of "plain",
|
||||||
or "tar". Defaults to "custom" (unlike raw pg_dump). See
|
"custom", "directory", or "tar". Defaults to
|
||||||
https://www.postgresql.org/docs/current/app-pgdump.html for details.
|
"custom" (unlike raw pg_dump). See pg_dump
|
||||||
Note that format is ignored when the database name is "all".
|
documentation for details. Note that format is
|
||||||
|
ignored when the database name is "all".
|
||||||
example: directory
|
example: directory
|
||||||
options:
|
options:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Additional pg_dump/pg_dumpall options to pass directly to the dump
|
Additional pg_dump/pg_dumpall options to pass
|
||||||
command, without performing any validation on them. See
|
directly to the dump command, without performing
|
||||||
https://www.postgresql.org/docs/current/app-pgdump.html for details.
|
any validation on them. See pg_dump
|
||||||
|
documentation for details.
|
||||||
example: --role=someone
|
example: --role=someone
|
||||||
desc: |
|
desc: |
|
||||||
List of one or more PostgreSQL databases to dump before creating a backup,
|
List of one or more PostgreSQL databases to dump before
|
||||||
run once per configuration file. The database dumps are added to your source
|
creating a backup, run once per configuration file. The
|
||||||
directories at runtime, backed up, and then removed afterwards. Requires
|
database dumps are added to your source directories at
|
||||||
|
runtime, backed up, and removed afterwards. Requires
|
||||||
pg_dump/pg_dumpall/pg_restore commands. See
|
pg_dump/pg_dumpall/pg_restore commands. See
|
||||||
https://www.postgresql.org/docs/current/app-pgdump.html for details.
|
https://www.postgresql.org/docs/current/app-pgdump.html for
|
||||||
|
details.
|
||||||
mysql_databases:
|
mysql_databases:
|
||||||
seq:
|
seq:
|
||||||
- map:
|
- map:
|
||||||
|
@ -514,16 +579,17 @@ map:
|
||||||
required: true
|
required: true
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Database name (required if using this hook). Or "all" to dump all
|
Database name (required if using this hook). Or
|
||||||
databases on the host. Note that using this database hook implicitly
|
"all" to dump all databases on the host. Note
|
||||||
enables both read_special and one_file_system (see above) to support
|
that using this database hook implicitly enables
|
||||||
dump and restore streaming.
|
both read_special and one_file_system (see
|
||||||
|
above) to support dump and restore streaming.
|
||||||
example: users
|
example: users
|
||||||
hostname:
|
hostname:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Database hostname to connect to. Defaults to connecting via local
|
Database hostname to connect to. Defaults to
|
||||||
Unix socket.
|
connecting via local Unix socket.
|
||||||
example: database.example.org
|
example: database.example.org
|
||||||
port:
|
port:
|
||||||
type: int
|
type: int
|
||||||
|
@ -532,87 +598,92 @@ map:
|
||||||
username:
|
username:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Username with which to connect to the database. Defaults to the
|
Username with which to connect to the database.
|
||||||
username of the current user.
|
Defaults to the username of the current user.
|
||||||
example: dbuser
|
example: dbuser
|
||||||
password:
|
password:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Password with which to connect to the database. Omitting a password
|
Password with which to connect to the database.
|
||||||
will only work if MySQL is configured to trust the configured
|
Omitting a password will only work if MySQL is
|
||||||
username without a password.
|
configured to trust the configured username
|
||||||
|
without a password.
|
||||||
example: trustsome1
|
example: trustsome1
|
||||||
options:
|
options:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Additional mysqldump options to pass directly to the dump command,
|
Additional mysqldump options to pass directly to
|
||||||
without performing any validation on them. See
|
the dump command, without performing any
|
||||||
https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html or
|
validation on them. See mysqldump documentation
|
||||||
https://mariadb.com/kb/en/library/mysqldump/ for details.
|
for details.
|
||||||
example: --skip-comments
|
example: --skip-comments
|
||||||
desc: |
|
desc: |
|
||||||
List of one or more MySQL/MariaDB databases to dump before creating a backup,
|
List of one or more MySQL/MariaDB databases to dump before
|
||||||
run once per configuration file. The database dumps are added to your source
|
creating a backup, run once per configuration file. The
|
||||||
directories at runtime, backed up, and then removed afterwards. Requires
|
database dumps are added to your source directories at
|
||||||
|
runtime, backed up, and removed afterwards. Requires
|
||||||
mysqldump/mysql commands (from either MySQL or MariaDB). See
|
mysqldump/mysql commands (from either MySQL or MariaDB). See
|
||||||
https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html or
|
https://dev.mysql.com/doc/refman/8.0/en/mysqldump.html or
|
||||||
https://mariadb.com/kb/en/library/mysqldump/ for details.
|
https://mariadb.com/kb/en/library/mysqldump/ for details.
|
||||||
healthchecks:
|
healthchecks:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Healthchecks ping URL or UUID to notify when a backup begins, ends, or errors.
|
Healthchecks ping URL or UUID to notify when a backup
|
||||||
Create an account at https://healthchecks.io if you'd like to use this service.
|
begins, ends, or errors. Create an account at
|
||||||
See
|
https://healthchecks.io if you'd like to use this service.
|
||||||
https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#healthchecks-hook
|
See borgmatic monitoring documentation for details.
|
||||||
for details.
|
|
||||||
example:
|
example:
|
||||||
https://hc-ping.com/your-uuid-here
|
https://hc-ping.com/your-uuid-here
|
||||||
cronitor:
|
cronitor:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Cronitor ping URL to notify when a backup begins, ends, or errors. Create an
|
Cronitor ping URL to notify when a backup begins, ends, or
|
||||||
account at https://cronitor.io if you'd like to use this service. See
|
errors. Create an account at https://cronitor.io if you'd
|
||||||
https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronitor-hook
|
like to use this service. See borgmatic monitoring
|
||||||
for details.
|
documentation for details.
|
||||||
example:
|
example:
|
||||||
https://cronitor.link/d3x0c1
|
https://cronitor.link/d3x0c1
|
||||||
pagerduty:
|
pagerduty:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
PagerDuty integration key used to notify PagerDuty when a backup errors. Create
|
PagerDuty integration key used to notify PagerDuty when a
|
||||||
an account at https://www.pagerduty.com/ if you'd like to use this service. See
|
backup errors. Create an account at
|
||||||
https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#pagerduty-hook
|
https://www.pagerduty.com/ if you'd like to use this
|
||||||
for details.
|
service. See borgmatic monitoring documentation for details.
|
||||||
example:
|
example:
|
||||||
a177cad45bd374409f78906a810a3074
|
a177cad45bd374409f78906a810a3074
|
||||||
cronhub:
|
cronhub:
|
||||||
type: str
|
type: str
|
||||||
desc: |
|
desc: |
|
||||||
Cronhub ping URL to notify when a backup begins, ends, or errors. Create an
|
Cronhub ping URL to notify when a backup begins, ends, or
|
||||||
account at https://cronhub.io if you'd like to use this service. See
|
errors. Create an account at https://cronhub.io if you'd
|
||||||
https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/#cronhub-hook for
|
like to use this service. See borgmatic monitoring
|
||||||
details.
|
documentation for details.
|
||||||
example:
|
example:
|
||||||
https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d031
|
https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d01
|
||||||
before_everything:
|
before_everything:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
List of one or more shell commands or scripts to execute before running all
|
List of one or more shell commands or scripts to execute
|
||||||
actions (if one of them is "create"). These are collected from all configuration
|
before running all actions (if one of them is "create").
|
||||||
files and then run once before all of them (prior to all actions).
|
These are collected from all configuration files and then
|
||||||
|
run once before all of them (prior to all actions).
|
||||||
example:
|
example:
|
||||||
- echo "Starting actions."
|
- echo "Starting actions."
|
||||||
after_everything:
|
after_everything:
|
||||||
seq:
|
seq:
|
||||||
- type: str
|
- type: str
|
||||||
desc: |
|
desc: |
|
||||||
List of one or more shell commands or scripts to execute after running all
|
List of one or more shell commands or scripts to execute
|
||||||
actions (if one of them is "create"). These are collected from all configuration
|
after running all actions (if one of them is "create").
|
||||||
files and then run once before all of them (prior to all actions).
|
These are collected from all configuration files and then
|
||||||
|
run once before all of them (prior to all actions).
|
||||||
example:
|
example:
|
||||||
- echo "Completed actions."
|
- echo "Completed actions."
|
||||||
umask:
|
umask:
|
||||||
type: scalar
|
type: scalar
|
||||||
desc: Umask used when executing hooks. Defaults to the umask that borgmatic is run with.
|
desc: |
|
||||||
|
Umask used when executing hooks. Defaults to the umask that
|
||||||
|
borgmatic is run with.
|
||||||
example: 0077
|
example: 0077
|
||||||
|
|
8
tests/integration/config/test_schema.py
Normal file
8
tests/integration/config/test_schema.py
Normal file
|
@ -0,0 +1,8 @@
|
||||||
|
MAXIMUM_LINE_LENGTH = 80
|
||||||
|
|
||||||
|
|
||||||
|
def test_schema_line_length_stays_under_limit():
|
||||||
|
schema_file = open('borgmatic/config/schema.yaml')
|
||||||
|
|
||||||
|
for line in schema_file.readlines():
|
||||||
|
assert len(line.rstrip('\n')) <= MAXIMUM_LINE_LENGTH
|
Loading…
Reference in a new issue