453 lines
22 KiB
YAML
453 lines
22 KiB
YAML
name: Borgmatic configuration file schema
|
|
version: 1
|
|
map:
|
|
location:
|
|
desc: |
|
|
Where to look for files to backup, and where to store those backups. See
|
|
https://borgbackup.readthedocs.io/en/stable/quickstart.html and
|
|
https://borgbackup.readthedocs.io/en/stable/usage.html#borg-create for details.
|
|
required: true
|
|
map:
|
|
source_directories:
|
|
required: true
|
|
seq:
|
|
- type: str
|
|
desc: |
|
|
List of source directories to backup (required). Globs and tildes are expanded.
|
|
example:
|
|
- /home
|
|
- /etc
|
|
- /var/log/syslog*
|
|
repositories:
|
|
required: true
|
|
seq:
|
|
- type: str
|
|
desc: |
|
|
Paths to local or remote repositories (required). Tildes are expanded. Multiple
|
|
repositories are backed up to in sequence. See ssh_command for SSH options like
|
|
identity file or port.
|
|
example:
|
|
- user@backupserver:sourcehostname.borg
|
|
one_file_system:
|
|
type: bool
|
|
desc: Stay in same file system (do not cross mount points). Defaults to false.
|
|
example: true
|
|
numeric_owner:
|
|
type: bool
|
|
desc: Only store/extract numeric user and group identifiers. Defaults to false.
|
|
example: true
|
|
atime:
|
|
type: bool
|
|
desc: Store atime into archive. Defaults to true.
|
|
example: false
|
|
ctime:
|
|
type: bool
|
|
desc: Store ctime into archive. Defaults to true.
|
|
example: false
|
|
birthtime:
|
|
type: bool
|
|
desc: Store birthtime (creation date) into archive. Defaults to true.
|
|
example: false
|
|
read_special:
|
|
type: bool
|
|
desc: |
|
|
Use Borg's --read-special flag to allow backup of block and other special
|
|
devices. Use with caution, as it will lead to problems if used when
|
|
backing up special devices such as /dev/zero. Defaults to false.
|
|
example: false
|
|
bsd_flags:
|
|
type: bool
|
|
desc: Record bsdflags (e.g. NODUMP, IMMUTABLE) in archive. Defaults to true.
|
|
example: true
|
|
files_cache:
|
|
type: str
|
|
desc: |
|
|
Mode in which to operate the files cache. See
|
|
https://borgbackup.readthedocs.io/en/stable/usage/create.html#description for
|
|
details. Defaults to "ctime,size,inode".
|
|
example: ctime,size,inode
|
|
local_path:
|
|
type: str
|
|
desc: Alternate Borg local executable. Defaults to "borg".
|
|
example: borg1
|
|
remote_path:
|
|
type: str
|
|
desc: Alternate Borg remote executable. Defaults to "borg".
|
|
example: borg1
|
|
patterns:
|
|
seq:
|
|
- type: str
|
|
desc: |
|
|
Any paths matching these patterns are included/excluded from backups. Globs are
|
|
expanded. (Tildes are not.) Note that 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.
|
|
example:
|
|
- 'R /'
|
|
- '- /home/*/.cache'
|
|
- '+ /home/susan'
|
|
- '- /home/*'
|
|
patterns_from:
|
|
seq:
|
|
- type: str
|
|
desc: |
|
|
Read include/exclude patterns from one or more separate named files, one pattern
|
|
per line. Note that Borg considers this option experimental. See the output of
|
|
"borg help patterns" for more details.
|
|
example:
|
|
- /etc/borgmatic/patterns
|
|
exclude_patterns:
|
|
seq:
|
|
- type: str
|
|
desc: |
|
|
Any paths matching these patterns are excluded from backups. Globs and tildes
|
|
are expanded. See the output of "borg help patterns" for more details.
|
|
example:
|
|
- '*.pyc'
|
|
- ~/*/.cache
|
|
- /etc/ssl
|
|
exclude_from:
|
|
seq:
|
|
- type: str
|
|
desc: |
|
|
Read exclude patterns from one or more separate named files, one pattern per
|
|
line. See the output of "borg help patterns" for more details.
|
|
example:
|
|
- /etc/borgmatic/excludes
|
|
exclude_caches:
|
|
type: bool
|
|
desc: |
|
|
Exclude directories that contain a CACHEDIR.TAG file. See
|
|
http://www.brynosaurus.com/cachedir/spec.html for details. Defaults to false.
|
|
example: true
|
|
exclude_if_present:
|
|
type: str
|
|
desc: |
|
|
Exclude directories that contain a file with the given filename. Defaults to not
|
|
set.
|
|
example: .nobackup
|
|
storage:
|
|
desc: |
|
|
Repository storage options. See
|
|
https://borgbackup.readthedocs.io/en/stable/usage.html#borg-create and
|
|
https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables for
|
|
details.
|
|
map:
|
|
encryption_passcommand:
|
|
type: str
|
|
desc: |
|
|
The standard output of this command is used to unlock the encryption key. Only
|
|
use on repositories that were initialized with passcommand/repokey encryption.
|
|
Note that 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"
|
|
encryption_passphrase:
|
|
type: str
|
|
desc: |
|
|
Passphrase to unlock the encryption key with. Only use on repositories that were
|
|
initialized with passphrase/repokey 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.
|
|
example: "!\"#$%&'()*+,-./:;<=>?@[\\]^_`{|}~"
|
|
checkpoint_interval:
|
|
type: int
|
|
desc: |
|
|
Number of seconds between each checkpoint during a long-running backup. See
|
|
https://borgbackup.readthedocs.io/en/stable/faq.html#if-a-backup-stops-mid-way-does-the-already-backed-up-data-stay-there
|
|
for details. Defaults to checkpoints every 1800 seconds (30 minutes).
|
|
example: 1800
|
|
chunker_params:
|
|
type: str
|
|
desc: |
|
|
Specify the parameters passed to then chunker (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".
|
|
example: 19,23,21,4095
|
|
compression:
|
|
type: str
|
|
desc: |
|
|
Type of compression to use when creating archives. See
|
|
https://borgbackup.readthedocs.org/en/stable/usage.html#borg-create for details.
|
|
Defaults to "lz4".
|
|
example: lz4
|
|
remote_rate_limit:
|
|
type: int
|
|
desc: Remote network upload rate limit in kiBytes/second. Defaults to unlimited.
|
|
example: 100
|
|
ssh_command:
|
|
type: str
|
|
desc: |
|
|
Command to use instead of "ssh". This can be used to specify ssh options.
|
|
Defaults to not set.
|
|
example: ssh -i /path/to/private/key
|
|
borg_base_directory:
|
|
type: str
|
|
desc: |
|
|
Base path used for various Borg directories. Defaults to $HOME, ~$USER, or ~.
|
|
See https://borgbackup.readthedocs.io/en/stable/usage/general.html#environment-variables for details.
|
|
example: /path/to/base
|
|
borg_config_directory:
|
|
type: str
|
|
desc: |
|
|
Path for Borg configuration files. Defaults to $borg_base_directory/.config/borg
|
|
example: /path/to/base/config
|
|
borg_cache_directory:
|
|
type: str
|
|
desc: |
|
|
Path for Borg cache files. Defaults to $borg_base_directory/.cache/borg
|
|
example: /path/to/base/cache
|
|
borg_security_directory:
|
|
type: str
|
|
desc: |
|
|
Path for Borg security and encryption nonce files. Defaults to $borg_base_directory/.config/borg/security
|
|
example: /path/to/base/config/security
|
|
borg_keys_directory:
|
|
type: str
|
|
desc: |
|
|
Path for Borg encryption key files. Defaults to $borg_base_directory/.config/borg/keys
|
|
example: /path/to/base/config/keys
|
|
umask:
|
|
type: scalar
|
|
desc: Umask to be used for borg create. Defaults to 0077.
|
|
example: 0077
|
|
lock_wait:
|
|
type: int
|
|
desc: Maximum seconds to wait for acquiring a repository/cache lock. Defaults to 1.
|
|
example: 5
|
|
archive_name_format:
|
|
type: str
|
|
desc: |
|
|
Name of the archive. Borg placeholders can be used. See the 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
|
|
also specify a prefix in the retention 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.
|
|
example: "{hostname}-documents-{now}"
|
|
relocated_repo_access_is_ok:
|
|
type: bool
|
|
desc: Bypass Borg error about a repository that has been moved. Defaults to false.
|
|
example: true
|
|
unknown_unencrypted_repo_access_is_ok:
|
|
type: bool
|
|
desc: |
|
|
Bypass Borg error about a previously unknown unencrypted repository. Defaults to
|
|
false.
|
|
example: true
|
|
retention:
|
|
desc: |
|
|
Retention policy for how many backups to keep in each category. See
|
|
https://borgbackup.readthedocs.org/en/stable/usage.html#borg-prune for details.
|
|
At least one of the "keep" options is required for pruning to work. See
|
|
https://torsion.org/borgmatic/docs/how-to/deal-with-very-large-backups/
|
|
if you'd like to skip pruning entirely.
|
|
map:
|
|
keep_within:
|
|
type: str
|
|
desc: Keep all archives within this time interval.
|
|
example: 3H
|
|
keep_secondly:
|
|
type: int
|
|
desc: Number of secondly archives to keep.
|
|
example: 60
|
|
keep_minutely:
|
|
type: int
|
|
desc: Number of minutely archives to keep.
|
|
example: 60
|
|
keep_hourly:
|
|
type: int
|
|
desc: Number of hourly archives to keep.
|
|
example: 24
|
|
keep_daily:
|
|
type: int
|
|
desc: Number of daily archives to keep.
|
|
example: 7
|
|
keep_weekly:
|
|
type: int
|
|
desc: Number of weekly archives to keep.
|
|
example: 4
|
|
keep_monthly:
|
|
type: int
|
|
desc: Number of monthly archives to keep.
|
|
example: 6
|
|
keep_yearly:
|
|
type: int
|
|
desc: Number of yearly archives to keep.
|
|
example: 1
|
|
prefix:
|
|
type: str
|
|
desc: |
|
|
When pruning, only consider archive names starting with this prefix.
|
|
Borg placeholders can be used. See the output of "borg help placeholders" for
|
|
details. Defaults to "{hostname}-". Use an empty value to disable the default.
|
|
example: sourcehostname
|
|
consistency:
|
|
desc: |
|
|
Consistency checks to run after backups. See
|
|
https://borgbackup.readthedocs.org/en/stable/usage.html#borg-check and
|
|
https://borgbackup.readthedocs.org/en/stable/usage.html#borg-extract for details.
|
|
map:
|
|
checks:
|
|
seq:
|
|
- type: str
|
|
enum: ['repository', 'archives', 'data', 'extract', 'disabled']
|
|
unique: true
|
|
desc: |
|
|
List of one or more consistency checks to run: "repository", "archives", "data",
|
|
and/or "extract". Defaults to "repository" and "archives". Set to "disabled" to
|
|
disable all consistency checks. "repository" checks the consistency 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".
|
|
example:
|
|
- repository
|
|
- archives
|
|
check_repositories:
|
|
seq:
|
|
- type: str
|
|
desc: |
|
|
Paths to a subset of the repositories in the location section on which to run
|
|
consistency checks. Handy in case some of your repositories are very large, and
|
|
so running consistency checks on them would take too long. Defaults to running
|
|
consistency checks on all repositories configured in the location section.
|
|
example:
|
|
- user@backupserver:sourcehostname.borg
|
|
check_last:
|
|
type: int
|
|
desc: Restrict the number of checked archives to the last n. Applies only to the
|
|
"archives" check. Defaults to checking all archives.
|
|
example: 3
|
|
prefix:
|
|
type: str
|
|
desc: |
|
|
When performing the "archives" check, only consider archive names starting with
|
|
this prefix. Borg placeholders can be used. See the output of
|
|
"borg help placeholders" for details. Defaults to "{hostname}-". Use an empty
|
|
value to disable the default.
|
|
example: sourcehostname
|
|
output:
|
|
desc: |
|
|
Options for customizing borgmatic's own output and logging.
|
|
map:
|
|
color:
|
|
type: bool
|
|
desc: |
|
|
Apply color to console output. Can be overridden with --no-color command-line
|
|
flag. Defaults to true.
|
|
example: false
|
|
hooks:
|
|
desc: |
|
|
Shell commands, scripts, or integrations to execute at various points during a borgmatic
|
|
run. IMPORTANT: All provided commands and scripts are executed with user permissions of
|
|
borgmatic. Do not forget to set secure permissions on this configuration file (chmod
|
|
0600) as well as on any script called from a hook (chmod 0700) to prevent potential
|
|
shell injection or privilege escalation.
|
|
map:
|
|
before_backup:
|
|
seq:
|
|
- type: str
|
|
desc: |
|
|
List of one or more shell commands or scripts to execute before creating a
|
|
backup, run once per configuration file.
|
|
example:
|
|
- echo "Starting a backup."
|
|
after_backup:
|
|
seq:
|
|
- type: str
|
|
desc: |
|
|
List of one or more shell commands or scripts to execute after creating a
|
|
backup, run once per configuration file.
|
|
example:
|
|
- echo "Created a backup."
|
|
on_error:
|
|
seq:
|
|
- type: str
|
|
desc: |
|
|
List of one or more shell commands or scripts to execute when an exception
|
|
occurs during a backup or when running a before_backup or after_backup hook.
|
|
example:
|
|
- echo "Error while creating a backup or running a backup hook."
|
|
postgresql_databases:
|
|
seq:
|
|
- map:
|
|
name:
|
|
required: true
|
|
type: str
|
|
desc: |
|
|
Database name (required if using this hook). Or "all" to dump all
|
|
databases on the host.
|
|
example: users
|
|
hostname:
|
|
type: str
|
|
desc: |
|
|
Database hostname to connect to. Defaults to connecting via local
|
|
Unix socket.
|
|
example: database.example.org
|
|
port:
|
|
type: int
|
|
desc: Port to connect to. Defaults to 5432.
|
|
example: 5433
|
|
username:
|
|
type: str
|
|
desc: |
|
|
Username with which to connect to the database. Defaults to the
|
|
username of the current user. You probably want to specify the
|
|
"postgres" superuser here when the database name is "all".
|
|
example: dbuser
|
|
password:
|
|
type: str
|
|
desc: |
|
|
Password with which to connect to the database. Omitting a password
|
|
will only work if PostgreSQL is configured to trust the configured
|
|
username without a password, or you create a ~/.pgpass file.
|
|
example: trustsome1
|
|
format:
|
|
type: str
|
|
enum: ['plain', 'custom', 'directory', 'tar']
|
|
desc: |
|
|
Database dump output format. One of "plain", "custom", "directory",
|
|
or "tar". Defaults to "custom" (unlike raw pg_dump). See
|
|
https://www.postgresql.org/docs/current/app-pgdump.html for details.
|
|
Note that format is ignored when the database name is "all".
|
|
example: directory
|
|
options:
|
|
type: str
|
|
desc: |
|
|
Additional pg_dump/pg_dumpall options to pass directly to the dump
|
|
command, without performing any validation on them. See
|
|
https://www.postgresql.org/docs/current/app-pgdump.html for details.
|
|
example: --role=someone
|
|
desc: |
|
|
List of one or more PostgreSQL databases to dump before creating a backup,
|
|
run once per configuration file. The database dumps are added to your source
|
|
directories at runtime, backed up, and then removed afterwards. Requires
|
|
pg_dump/pg_dumpall/pg_restore commands. See
|
|
https://www.postgresql.org/docs/current/app-pgdump.html for details.
|
|
healthchecks:
|
|
type: str
|
|
desc: |
|
|
Healthchecks ping URL or UUID to notify when a backup begins, ends, or errors.
|
|
Create an account at https://healthchecks.io if you'd like to use this service.
|
|
example:
|
|
https://hc-ping.com/your-uuid-here
|
|
before_everything:
|
|
seq:
|
|
- type: str
|
|
desc: |
|
|
List of one or more shell commands or scripts to execute before running all
|
|
actions (if one of them is "create"), run once before all configuration files.
|
|
example:
|
|
- echo "Starting actions."
|
|
after_everything:
|
|
seq:
|
|
- type: str
|
|
desc: |
|
|
List of one or more shell commands or scripts to execute after running all
|
|
actions (if one of them is "create"), run once after all configuration files.
|
|
example:
|
|
- echo "Completed actions."
|
|
umask:
|
|
type: scalar
|
|
desc: Umask used when executing hooks. Defaults to the umask that borgmatic is run with.
|
|
example: 0077
|