psw/borgmatic
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Improve configuration reference documentation readability via more aggressive word-wrapping in configuration schema descriptions.

Browse source
This commit is contained in:
Dan Helfman 2020-06-17 23:15:12 -07:00
parent b320e74ad5
commit 7fb4061759
3 changed files with 274 additions and 193 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
NEWS
View file

@ -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

457
borgmatic/config/schema.yaml
View file

@ -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
View 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