More documentation updates based on section removal (#721).
This commit is contained in:
parent
cedf562a7e
commit
2453ecad42
12 changed files with 243 additions and 232 deletions
|
@ -1,5 +1,5 @@
|
||||||
<h2>Improve this documentation</h2>
|
<h2>Improve this documentation</h2>
|
||||||
|
|
||||||
<p>Have an idea on how to make this documentation even better? Use our <a
|
<p>Have an idea on how to make this documentation even better? Use our <a
|
||||||
href="https://projects.torsion.org/borgmatic-collective/borgmatic/issues">issue tracker</a> to send your
|
href="https://torsion.org/borgmatic/#support-and-contributing">issue
|
||||||
feedback!</p>
|
tracker</a> to send your feedback!</p>
|
||||||
|
|
|
@ -21,11 +21,10 @@ running backups, and specify `after_backup` hooks to perform cleanup steps
|
||||||
afterwards. Here's an example:
|
afterwards. Here's an example:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
before_backup:
|
||||||
before_backup:
|
- mount /some/filesystem
|
||||||
- mount /some/filesystem
|
after_backup:
|
||||||
after_backup:
|
- umount /some/filesystem
|
||||||
- umount /some/filesystem
|
|
||||||
```
|
```
|
||||||
|
|
||||||
If your command contains a special YAML character such as a colon, you may
|
If your command contains a special YAML character such as a colon, you may
|
||||||
|
@ -33,11 +32,23 @@ need to quote the entire string (or use a [multiline
|
||||||
string](https://yaml-multiline.info/)) to avoid an error:
|
string](https://yaml-multiline.info/)) to avoid an error:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
before_backup:
|
||||||
before_backup:
|
- "echo Backup: start"
|
||||||
- "echo Backup: start"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
There are additional hooks that run before/after other actions as well. For
|
||||||
|
instance, `before_prune` runs before a `prune` action for a repository, while
|
||||||
|
`after_prune` runs after it.
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
these options in the `hooks:` section of your configuration.
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">New in version 1.7.0</span> The
|
||||||
|
`before_actions` and `after_actions` hooks run before/after all the actions
|
||||||
|
(like `create`, `prune`, etc.) for each repository. These hooks are a good
|
||||||
|
place to run per-repository steps like mounting/unmounting a remote
|
||||||
|
filesystem.
|
||||||
|
|
||||||
<span class="minilink minilink-addedin">New in version 1.6.0</span> The
|
<span class="minilink minilink-addedin">New in version 1.6.0</span> The
|
||||||
`before_backup` and `after_backup` hooks each run once per repository in a
|
`before_backup` and `after_backup` hooks each run once per repository in a
|
||||||
configuration file. `before_backup` hooks runs right before the `create`
|
configuration file. `before_backup` hooks runs right before the `create`
|
||||||
|
@ -46,16 +57,6 @@ but not if an error occurs in a previous hook or in the backups themselves.
|
||||||
(Prior to borgmatic 1.6.0, these hooks instead ran once per configuration file
|
(Prior to borgmatic 1.6.0, these hooks instead ran once per configuration file
|
||||||
rather than once per repository.)
|
rather than once per repository.)
|
||||||
|
|
||||||
There are additional hooks that run before/after other actions as well. For
|
|
||||||
instance, `before_prune` runs before a `prune` action for a repository, while
|
|
||||||
`after_prune` runs after it.
|
|
||||||
|
|
||||||
<span class="minilink minilink-addedin">New in version 1.7.0</span> The
|
|
||||||
`before_actions` and `after_actions` hooks run before/after all the actions
|
|
||||||
(like `create`, `prune`, etc.) for each repository. These hooks are a good
|
|
||||||
place to run per-repository steps like mounting/unmounting a remote
|
|
||||||
filesystem.
|
|
||||||
|
|
||||||
|
|
||||||
## Variable interpolation
|
## Variable interpolation
|
||||||
|
|
||||||
|
@ -64,11 +65,13 @@ variables into the hook command. Here's an example that assumes you provide a
|
||||||
separate shell script:
|
separate shell script:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
after_prune:
|
||||||
after_prune:
|
- record-prune.sh "{configuration_filename}" "{repository}"
|
||||||
- record-prune.sh "{configuration_filename}" "{repository}"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
this option in the `hooks:` section of your configuration.
|
||||||
|
|
||||||
In this example, when the hook is triggered, borgmatic interpolates runtime
|
In this example, when the hook is triggered, borgmatic interpolates runtime
|
||||||
values into the hook command: the borgmatic configuration filename and the
|
values into the hook command: the borgmatic configuration filename and the
|
||||||
paths of the current Borg repository. Here's the full set of supported
|
paths of the current Borg repository. Here's the full set of supported
|
||||||
|
@ -92,13 +95,15 @@ You can also use `before_everything` and `after_everything` hooks to perform
|
||||||
global setup or cleanup:
|
global setup or cleanup:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
before_everything:
|
||||||
before_everything:
|
- set-up-stuff-globally
|
||||||
- set-up-stuff-globally
|
after_everything:
|
||||||
after_everything:
|
- clean-up-stuff-globally
|
||||||
- clean-up-stuff-globally
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
these options in the `hooks:` section of your configuration.
|
||||||
|
|
||||||
`before_everything` hooks collected from all borgmatic configuration files run
|
`before_everything` hooks collected from all borgmatic configuration files run
|
||||||
once before all configuration files (prior to all actions), but only if there
|
once before all configuration files (prior to all actions), but only if there
|
||||||
is a `create` action. An error encountered during a `before_everything` hook
|
is a `create` action. An error encountered during a `before_everything` hook
|
||||||
|
@ -109,6 +114,7 @@ but only if there is a `create` action. It runs even if an error occurs during
|
||||||
a backup or a backup hook, but not if an error occurs during a
|
a backup or a backup hook, but not if an error occurs during a
|
||||||
`before_everything` hook.
|
`before_everything` hook.
|
||||||
|
|
||||||
|
|
||||||
## Error hooks
|
## Error hooks
|
||||||
|
|
||||||
borgmatic also runs `on_error` hooks if an error occurs, either when creating
|
borgmatic also runs `on_error` hooks if an error occurs, either when creating
|
||||||
|
@ -116,6 +122,7 @@ a backup or running a backup hook. See the [monitoring and alerting
|
||||||
documentation](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/)
|
documentation](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/)
|
||||||
for more information.
|
for more information.
|
||||||
|
|
||||||
|
|
||||||
## Hook output
|
## Hook output
|
||||||
|
|
||||||
Any output produced by your hooks shows up both at the console and in syslog
|
Any output produced by your hooks shows up both at the console and in syslog
|
||||||
|
@ -123,6 +130,7 @@ Any output produced by your hooks shows up both at the console and in syslog
|
||||||
href="https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/">inspecting
|
href="https://torsion.org/borgmatic/docs/how-to/inspect-your-backups/">inspecting
|
||||||
your backups</a>.
|
your backups</a>.
|
||||||
|
|
||||||
|
|
||||||
## Security
|
## Security
|
||||||
|
|
||||||
An important security note about hooks: borgmatic executes all hook commands
|
An important security note about hooks: borgmatic executes all hook commands
|
||||||
|
|
|
@ -62,11 +62,13 @@ the external `findmnt` utility to see whether the drive is mounted before
|
||||||
proceeding.
|
proceeding.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
before_backup:
|
||||||
before_backup:
|
- findmnt /mnt/removable > /dev/null || exit 75
|
||||||
- findmnt /mnt/removable > /dev/null || exit 75
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put this
|
||||||
|
option in the `hooks:` section of your configuration.
|
||||||
|
|
||||||
What this does is check if the `findmnt` command errors when probing for a
|
What this does is check if the `findmnt` command errors when probing for a
|
||||||
particular mount point. If it does error, then it returns exit code 75 to
|
particular mount point. If it does error, then it returns exit code 75 to
|
||||||
borgmatic. borgmatic logs the soft failure, skips all further actions in that
|
borgmatic. borgmatic logs the soft failure, skips all further actions in that
|
||||||
|
@ -89,19 +91,11 @@ before_backup:
|
||||||
- ping -q -c 1 buddys-server.org > /dev/null || exit 75
|
- ping -q -c 1 buddys-server.org > /dev/null || exit 75
|
||||||
```
|
```
|
||||||
|
|
||||||
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put the
|
|
||||||
first two options in the `location:` section of your configuration and the
|
|
||||||
`before_backup` option within the `hooks:` section.
|
|
||||||
|
|
||||||
<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
|
|
||||||
the `path:` portion of the `repositories` list.
|
|
||||||
|
|
||||||
Or to only run backups if the battery level is high enough:
|
Or to only run backups if the battery level is high enough:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
before_backup:
|
||||||
before_backup:
|
- is_battery_percent_at_least.sh 25
|
||||||
- is_battery_percent_at_least.sh 25
|
|
||||||
```
|
```
|
||||||
|
|
||||||
(Writing the battery script is left as an exercise to the reader.)
|
(Writing the battery script is left as an exercise to the reader.)
|
||||||
|
|
|
@ -18,31 +18,32 @@ prior to running backups. For example, here is everything you need to dump and
|
||||||
backup a couple of local PostgreSQL databases and a MySQL/MariaDB database.
|
backup a couple of local PostgreSQL databases and a MySQL/MariaDB database.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
postgresql_databases:
|
||||||
postgresql_databases:
|
- name: users
|
||||||
- name: users
|
- name: orders
|
||||||
- name: orders
|
mysql_databases:
|
||||||
mysql_databases:
|
- name: posts
|
||||||
- name: posts
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
these and other database options in the `hooks:` section of your
|
||||||
|
configuration.
|
||||||
|
|
||||||
<span class="minilink minilink-addedin">New in version 1.5.22</span> You can
|
<span class="minilink minilink-addedin">New in version 1.5.22</span> You can
|
||||||
also dump MongoDB databases. For example:
|
also dump MongoDB databases. For example:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
mongodb_databases:
|
||||||
mongodb_databases:
|
- name: messages
|
||||||
- name: messages
|
|
||||||
```
|
```
|
||||||
|
|
||||||
<span class="minilink minilink-addedin">New in version 1.7.9</span>
|
<span class="minilink minilink-addedin">New in version 1.7.9</span>
|
||||||
Additionally, you can dump SQLite databases. For example:
|
Additionally, you can dump SQLite databases. For example:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
sqlite_databases:
|
||||||
sqlite_databases:
|
- name: mydb
|
||||||
- name: mydb
|
path: /var/lib/sqlite3/mydb.sqlite
|
||||||
path: /var/lib/sqlite3/mydb.sqlite
|
|
||||||
```
|
```
|
||||||
|
|
||||||
As part of each backup, borgmatic streams a database dump for each configured
|
As part of each backup, borgmatic streams a database dump for each configured
|
||||||
|
@ -54,7 +55,7 @@ temporary disk space.)
|
||||||
|
|
||||||
To support this, borgmatic creates temporary named pipes in `~/.borgmatic` by
|
To support this, borgmatic creates temporary named pipes in `~/.borgmatic` by
|
||||||
default. To customize this path, set the `borgmatic_source_directory` option
|
default. To customize this path, set the `borgmatic_source_directory` option
|
||||||
in the `location` section of borgmatic's configuration.
|
in borgmatic's configuration.
|
||||||
|
|
||||||
Also note that using a database hook implicitly enables both the
|
Also note that using a database hook implicitly enables both the
|
||||||
`read_special` and `one_file_system` configuration settings (even if they're
|
`read_special` and `one_file_system` configuration settings (even if they're
|
||||||
|
@ -64,35 +65,34 @@ See Limitations below for more on this.
|
||||||
Here's a more involved example that connects to remote databases:
|
Here's a more involved example that connects to remote databases:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
postgresql_databases:
|
||||||
postgresql_databases:
|
- name: users
|
||||||
- name: users
|
hostname: database1.example.org
|
||||||
hostname: database1.example.org
|
- name: orders
|
||||||
- name: orders
|
hostname: database2.example.org
|
||||||
hostname: database2.example.org
|
port: 5433
|
||||||
port: 5433
|
username: postgres
|
||||||
username: postgres
|
password: trustsome1
|
||||||
password: trustsome1
|
format: tar
|
||||||
format: tar
|
options: "--role=someone"
|
||||||
options: "--role=someone"
|
mysql_databases:
|
||||||
mysql_databases:
|
- name: posts
|
||||||
- name: posts
|
hostname: database3.example.org
|
||||||
hostname: database3.example.org
|
port: 3307
|
||||||
port: 3307
|
username: root
|
||||||
username: root
|
password: trustsome1
|
||||||
password: trustsome1
|
options: "--skip-comments"
|
||||||
options: "--skip-comments"
|
mongodb_databases:
|
||||||
mongodb_databases:
|
- name: messages
|
||||||
- name: messages
|
hostname: database4.example.org
|
||||||
hostname: database4.example.org
|
port: 27018
|
||||||
port: 27018
|
username: dbuser
|
||||||
username: dbuser
|
password: trustsome1
|
||||||
password: trustsome1
|
authentication_database: mongousers
|
||||||
authentication_database: mongousers
|
options: "--ssl"
|
||||||
options: "--ssl"
|
sqlite_databases:
|
||||||
sqlite_databases:
|
- name: mydb
|
||||||
- name: mydb
|
path: /var/lib/sqlite3/mydb.sqlite
|
||||||
path: /var/lib/sqlite3/mydb.sqlite
|
|
||||||
```
|
```
|
||||||
|
|
||||||
See your [borgmatic configuration
|
See your [borgmatic configuration
|
||||||
|
@ -106,13 +106,12 @@ listing databases, restoring databases, etc.).
|
||||||
If you want to dump all databases on a host, use `all` for the database name:
|
If you want to dump all databases on a host, use `all` for the database name:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
postgresql_databases:
|
||||||
postgresql_databases:
|
- name: all
|
||||||
- name: all
|
mysql_databases:
|
||||||
mysql_databases:
|
- name: all
|
||||||
- name: all
|
mongodb_databases:
|
||||||
mongodb_databases:
|
- name: all
|
||||||
- name: all
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Note that you may need to use a `username` of the `postgres` superuser for
|
Note that you may need to use a `username` of the `postgres` superuser for
|
||||||
|
@ -120,6 +119,9 @@ this to work with PostgreSQL.
|
||||||
|
|
||||||
The SQLite hook in particular does not consider "all" a special database name.
|
The SQLite hook in particular does not consider "all" a special database name.
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
these options in the `hooks:` section of your configuration.
|
||||||
|
|
||||||
<span class="minilink minilink-addedin">New in version 1.7.6</span> With
|
<span class="minilink minilink-addedin">New in version 1.7.6</span> With
|
||||||
PostgreSQL and MySQL, you can optionally dump "all" databases to separate
|
PostgreSQL and MySQL, you can optionally dump "all" databases to separate
|
||||||
files instead of one combined dump file, allowing more convenient restores of
|
files instead of one combined dump file, allowing more convenient restores of
|
||||||
|
@ -127,13 +129,12 @@ individual databases. Enable this by specifying your desired database dump
|
||||||
`format`:
|
`format`:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
postgresql_databases:
|
||||||
postgresql_databases:
|
- name: all
|
||||||
- name: all
|
format: custom
|
||||||
format: custom
|
mysql_databases:
|
||||||
mysql_databases:
|
- name: all
|
||||||
- name: all
|
format: sql
|
||||||
format: sql
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Containers
|
### Containers
|
||||||
|
@ -143,15 +144,17 @@ problem—configure borgmatic to connect to the container's name on its exposed
|
||||||
port. For instance:
|
port. For instance:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
postgresql_databases:
|
||||||
postgresql_databases:
|
- name: users
|
||||||
- name: users
|
hostname: your-database-container-name
|
||||||
hostname: your-database-container-name
|
port: 5433
|
||||||
port: 5433
|
username: postgres
|
||||||
username: postgres
|
password: trustsome1
|
||||||
password: trustsome1
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
these options in the `hooks:` section of your configuration.
|
||||||
|
|
||||||
But what if borgmatic is running on the host? You can still connect to a
|
But what if borgmatic is running on the host? You can still connect to a
|
||||||
database container if its ports are properly exposed to the host. For
|
database container if its ports are properly exposed to the host. For
|
||||||
instance, when running the database container, you can specify `--publish
|
instance, when running the database container, you can specify `--publish
|
||||||
|
@ -179,8 +182,7 @@ hooks:
|
||||||
password: trustsome1
|
password: trustsome1
|
||||||
```
|
```
|
||||||
|
|
||||||
You can alter the ports in these examples to suit your particular database
|
Alter the ports in these examples to suit your particular database system.
|
||||||
system.
|
|
||||||
|
|
||||||
|
|
||||||
### No source directories
|
### No source directories
|
||||||
|
@ -428,10 +430,9 @@ You can add any additional flags to the `options:` in your database
|
||||||
configuration. Here's an example:
|
configuration. Here's an example:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
mysql_databases:
|
||||||
mysql_databases:
|
- name: posts
|
||||||
- name: posts
|
options: "--single-transaction --quick"
|
||||||
options: "--single-transaction --quick"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### borgmatic hangs during backup
|
### borgmatic hangs during backup
|
||||||
|
|
|
@ -65,19 +65,20 @@ configure borgmatic to run repository checks only. Configure this in the
|
||||||
`consistency` section of borgmatic configuration:
|
`consistency` section of borgmatic configuration:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
consistency:
|
checks:
|
||||||
checks:
|
- name: repository
|
||||||
- name: repository
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
this option in the `consistency:` section of your configuration.
|
||||||
|
|
||||||
<span class="minilink minilink-addedin">Prior to version 1.6.2</span> The
|
<span class="minilink minilink-addedin">Prior to version 1.6.2</span> The
|
||||||
`checks` option was a plain list of strings without the `name:` part, and
|
`checks` option was a plain list of strings without the `name:` part, and
|
||||||
borgmatic ran each configured check every time checks were run. For example:
|
borgmatic ran each configured check every time checks were run. For example:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
consistency:
|
checks:
|
||||||
checks:
|
- repository
|
||||||
- repository
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
|
@ -103,14 +104,16 @@ optionally configure checks to run on a periodic basis rather than every time
|
||||||
borgmatic runs checks. For instance:
|
borgmatic runs checks. For instance:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
consistency:
|
checks:
|
||||||
checks:
|
- name: repository
|
||||||
- name: repository
|
frequency: 2 weeks
|
||||||
frequency: 2 weeks
|
- name: archives
|
||||||
- name: archives
|
frequency: 1 month
|
||||||
frequency: 1 month
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
this option in the `consistency:` section of your configuration.
|
||||||
|
|
||||||
This tells borgmatic to run the `repository` consistency check at most once
|
This tells borgmatic to run the `repository` consistency check at most once
|
||||||
every two weeks for a given repository and the `archives` check at most once a
|
every two weeks for a given repository and the `archives` check at most once a
|
||||||
month. The `frequency` value is a number followed by a unit of time, e.g. "3
|
month. The `frequency` value is a number followed by a unit of time, e.g. "3
|
||||||
|
@ -173,9 +176,8 @@ this option in the `consistency:` section of your configuration.
|
||||||
was a plain list of strings without the `name:` part. For instance:
|
was a plain list of strings without the `name:` part. For instance:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
consistency:
|
checks:
|
||||||
checks:
|
- disabled
|
||||||
- disabled
|
|
||||||
```
|
```
|
||||||
|
|
||||||
If you have multiple repositories in your borgmatic configuration file,
|
If you have multiple repositories in your borgmatic configuration file,
|
||||||
|
|
|
@ -7,7 +7,7 @@ eleventyNavigation:
|
||||||
---
|
---
|
||||||
## Source code
|
## Source code
|
||||||
|
|
||||||
To get set up to hack on borgmatic, first clone it via HTTPS or SSH:
|
To get set up to develop on borgmatic, first clone it via HTTPS or SSH:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
git clone https://projects.torsion.org/borgmatic-collective/borgmatic.git
|
git clone https://projects.torsion.org/borgmatic-collective/borgmatic.git
|
||||||
|
@ -21,8 +21,8 @@ git clone ssh://git@projects.torsion.org:3022/borgmatic-collective/borgmatic.git
|
||||||
|
|
||||||
Then, install borgmatic
|
Then, install borgmatic
|
||||||
"[editable](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs)"
|
"[editable](https://pip.pypa.io/en/stable/cli/pip_install/#editable-installs)"
|
||||||
so that you can run borgmatic commands while you're hacking on them to
|
so that you can run borgmatic actions during development to make sure your
|
||||||
make sure your changes work.
|
changes work.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
cd borgmatic
|
cd borgmatic
|
||||||
|
|
|
@ -60,7 +60,7 @@ with `--format`. Refer to the [borg list --format
|
||||||
documentation](https://borgbackup.readthedocs.io/en/stable/usage/list.html#the-format-specifier-syntax)
|
documentation](https://borgbackup.readthedocs.io/en/stable/usage/list.html#the-format-specifier-syntax)
|
||||||
for available values.
|
for available values.
|
||||||
|
|
||||||
*(No borgmatic `list` or `info` actions? Upgrade borgmatic!)*
|
(No borgmatic `list` or `info` actions? Upgrade borgmatic!)
|
||||||
|
|
||||||
<span class="minilink minilink-addedin">New in borgmatic version 1.7.0</span>
|
<span class="minilink minilink-addedin">New in borgmatic version 1.7.0</span>
|
||||||
There are also `rlist` and `rinfo` actions for displaying repository
|
There are also `rlist` and `rinfo` actions for displaying repository
|
||||||
|
|
|
@ -104,11 +104,12 @@ to filter archives when running supported actions.
|
||||||
For instance, let's say that you have this in your configuration:
|
For instance, let's say that you have this in your configuration:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
storage:
|
archive_name_format: {hostname}-user-data-{now}
|
||||||
...
|
|
||||||
archive_name_format: {hostname}-user-data-{now}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
this option in the `storage:` section of your configuration.
|
||||||
|
|
||||||
borgmatic considers `{now}` an emphemeral data placeholder that will probably
|
borgmatic considers `{now}` an emphemeral data placeholder that will probably
|
||||||
change per archive, while `{hostname}` won't. So it turns the example value
|
change per archive, while `{hostname}` won't. So it turns the example value
|
||||||
into `{hostname}-user-data-*` and applies it to filter down the set of
|
into `{hostname}-user-data-*` and applies it to filter down the set of
|
||||||
|
@ -124,10 +125,8 @@ If this behavior isn't quite smart enough for your needs, you can use the
|
||||||
filtering archives. For example:
|
filtering archives. For example:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
storage:
|
archive_name_format: {hostname}-user-data-{now}
|
||||||
...
|
match_archives: sh:myhost-user-data-*
|
||||||
archive_name_format: {hostname}-user-data-{now}
|
|
||||||
match_archives: sh:myhost-user-data-*
|
|
||||||
```
|
```
|
||||||
|
|
||||||
For Borg 1.x, use a shell pattern for the `match_archives` value and see the
|
For Borg 1.x, use a shell pattern for the `match_archives` value and see the
|
||||||
|
@ -190,7 +189,7 @@ When a configuration include is a relative path, borgmatic loads it from either
|
||||||
the current working directory or from the directory containing the file doing
|
the current working directory or from the directory containing the file doing
|
||||||
the including.
|
the including.
|
||||||
|
|
||||||
Note that this form of include must be a YAML value rather than a key. For
|
Note that this form of include must be a value rather than an option name. For
|
||||||
example, this will not work:
|
example, this will not work:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
|
@ -201,7 +200,7 @@ repositories:
|
||||||
!include /etc/borgmatic/common_checks.yaml
|
!include /etc/borgmatic/common_checks.yaml
|
||||||
```
|
```
|
||||||
|
|
||||||
But if you do want to merge in a YAML key *and* its values, keep reading!
|
But if you do want to merge in a option name *and* its values, keep reading!
|
||||||
|
|
||||||
|
|
||||||
## Include merging
|
## Include merging
|
||||||
|
@ -238,11 +237,6 @@ Once this include gets merged in, the resulting configuration would have all
|
||||||
of the options from the original configuration file *and* the options from the
|
of the options from the original configuration file *and* the options from the
|
||||||
include.
|
include.
|
||||||
|
|
||||||
<span class="minilink minilink-addedin">Prior to version 1.6.0</span> When the
|
|
||||||
same option appeared in both the local file and the merged include, the local
|
|
||||||
file's value took precedence—meaning the included value was ignored in favor
|
|
||||||
of the local one. But see below about deep merge in version 1.6.0+.
|
|
||||||
|
|
||||||
Note that this `<<` include merging syntax is only for merging in mappings
|
Note that this `<<` include merging syntax is only for merging in mappings
|
||||||
(configuration options and their values). But if you'd like to include a
|
(configuration options and their values). But if you'd like to include a
|
||||||
single value directly, please see the above about standard includes.
|
single value directly, please see the above about standard includes.
|
||||||
|
@ -261,29 +255,30 @@ at all levels in the two configuration files. This allows you to include
|
||||||
common configuration—up to full borgmatic configuration files—while overriding
|
common configuration—up to full borgmatic configuration files—while overriding
|
||||||
only the parts you want to customize.
|
only the parts you want to customize.
|
||||||
|
|
||||||
For instance, here's an example of a main configuration file that pulls in two
|
For instance, here's an example of a main configuration file that pulls in
|
||||||
retention options via an include and then overrides one of them locally:
|
options via an include and then overrides one of them locally:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
<<: !include /etc/borgmatic/common.yaml
|
<<: !include /etc/borgmatic/common.yaml
|
||||||
|
|
||||||
location:
|
constants:
|
||||||
...
|
hostname: myhostname
|
||||||
|
|
||||||
retention:
|
repositories:
|
||||||
keep_daily: 5
|
- path: repo.borg
|
||||||
```
|
```
|
||||||
|
|
||||||
This is what `common.yaml` might look like:
|
This is what `common.yaml` might look like:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
retention:
|
constants:
|
||||||
keep_hourly: 24
|
prefix: myprefix
|
||||||
keep_daily: 7
|
hostname: otherhost
|
||||||
```
|
```
|
||||||
|
|
||||||
Once this include gets merged in, the resulting configuration would have a
|
Once this include gets merged in, the resulting configuration would have a
|
||||||
`keep_hourly` value of `24` and an overridden `keep_daily` value of `5`.
|
`prefix` value of `myprefix` and an overridden `hostname` value of
|
||||||
|
`myhostname`.
|
||||||
|
|
||||||
When there's an option collision between the local file and the merged
|
When there's an option collision between the local file and the merged
|
||||||
include, the local file's option takes precedence.
|
include, the local file's option takes precedence.
|
||||||
|
@ -301,21 +296,22 @@ configuration file, you can omit it with an `!omit` tag. For instance:
|
||||||
```yaml
|
```yaml
|
||||||
<<: !include /etc/borgmatic/common.yaml
|
<<: !include /etc/borgmatic/common.yaml
|
||||||
|
|
||||||
location:
|
source_directories:
|
||||||
source_directories:
|
- !omit /home
|
||||||
- !omit /home
|
- /var
|
||||||
- /var
|
|
||||||
```
|
```
|
||||||
|
|
||||||
And `common.yaml` like this:
|
And `common.yaml` like this:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
location:
|
source_directories:
|
||||||
source_directories:
|
- /home
|
||||||
- /home
|
- /etc
|
||||||
- /etc
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
this option in the `location:` section of your configuration.
|
||||||
|
|
||||||
Once this include gets merged in, the resulting configuration will have a
|
Once this include gets merged in, the resulting configuration will have a
|
||||||
`source_directories` value of `/etc` and `/var`—with `/home` omitted.
|
`source_directories` value of `/etc` and `/var`—with `/home` omitted.
|
||||||
|
|
||||||
|
@ -328,16 +324,15 @@ an example of some things not to do:
|
||||||
```yaml
|
```yaml
|
||||||
<<: !include /etc/borgmatic/common.yaml
|
<<: !include /etc/borgmatic/common.yaml
|
||||||
|
|
||||||
location:
|
source_directories:
|
||||||
source_directories:
|
# Do not do this! It will not work. "!omit" belongs before "/home".
|
||||||
# Do not do this! It will not work. "!omit" belongs before "/home".
|
- /home !omit
|
||||||
- /home !omit
|
|
||||||
|
|
||||||
# Do not do this either! "!omit" only works on scalar list items.
|
# Do not do this either! "!omit" only works on scalar list items.
|
||||||
repositories: !omit
|
repositories: !omit
|
||||||
# Also do not do this for the same reason! This is a list item, but it's
|
# Also do not do this for the same reason! This is a list item, but it's
|
||||||
# not a scalar.
|
# not a scalar.
|
||||||
- !omit path: repo.borg
|
- !omit path: repo.borg
|
||||||
```
|
```
|
||||||
|
|
||||||
Additionally, the `!omit` tag only works in a configuration file that also
|
Additionally, the `!omit` tag only works in a configuration file that also
|
||||||
|
@ -451,9 +446,6 @@ What this does is load your configuration files, and for each one, disregard
|
||||||
the configured value for the `remote_path` option, and use the value of
|
the configured value for the `remote_path` option, and use the value of
|
||||||
`/usr/local/bin/borg1` instead.
|
`/usr/local/bin/borg1` instead.
|
||||||
|
|
||||||
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Don't
|
|
||||||
forget to specify the section (like `location:`) that any option is in.
|
|
||||||
|
|
||||||
You can even override nested values or multiple values at once. For instance:
|
You can even override nested values or multiple values at once. For instance:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
|
|
|
@ -89,19 +89,20 @@ notifications or take other actions, so you can get alerted as soon as
|
||||||
something goes wrong. Here's a not-so-useful example:
|
something goes wrong. Here's a not-so-useful example:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
on_error:
|
||||||
on_error:
|
- echo "Error while creating a backup or running a backup hook."
|
||||||
- echo "Error while creating a backup or running a backup hook."
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
this option in the `hooks:` section of your configuration.
|
||||||
|
|
||||||
The `on_error` hook supports interpolating particular runtime variables into
|
The `on_error` hook supports interpolating particular runtime variables into
|
||||||
the hook command. Here's an example that assumes you provide a separate shell
|
the hook command. Here's an example that assumes you provide a separate shell
|
||||||
script to handle the alerting:
|
script to handle the alerting:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
on_error:
|
||||||
on_error:
|
- send-text-message.sh "{configuration_filename}" "{repository}"
|
||||||
- send-text-message.sh "{configuration_filename}" "{repository}"
|
|
||||||
```
|
```
|
||||||
|
|
||||||
In this example, when the error occurs, borgmatic interpolates runtime values
|
In this example, when the error occurs, borgmatic interpolates runtime values
|
||||||
|
@ -135,11 +136,13 @@ URL" for your project. Here's an example:
|
||||||
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
healthchecks:
|
||||||
healthchecks:
|
ping_url: https://hc-ping.com/addffa72-da17-40ae-be9c-ff591afb942a
|
||||||
ping_url: https://hc-ping.com/addffa72-da17-40ae-be9c-ff591afb942a
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
this option in the `hooks:` section of your configuration.
|
||||||
|
|
||||||
With this hook in place, borgmatic pings your Healthchecks project when a
|
With this hook in place, borgmatic pings your Healthchecks project when a
|
||||||
backup begins, ends, or errors. Specifically, after the <a
|
backup begins, ends, or errors. Specifically, after the <a
|
||||||
href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
|
href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
|
||||||
|
@ -179,11 +182,13 @@ API URL" for your monitor. Here's an example:
|
||||||
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
cronitor:
|
||||||
cronitor:
|
ping_url: https://cronitor.link/d3x0c1
|
||||||
ping_url: https://cronitor.link/d3x0c1
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
this option in the `hooks:` section of your configuration.
|
||||||
|
|
||||||
With this hook in place, borgmatic pings your Cronitor monitor when a backup
|
With this hook in place, borgmatic pings your Cronitor monitor when a backup
|
||||||
begins, ends, or errors. Specifically, after the <a
|
begins, ends, or errors. Specifically, after the <a
|
||||||
href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
|
href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
|
||||||
|
@ -208,11 +213,13 @@ URL" for your monitor. Here's an example:
|
||||||
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
cronhub:
|
||||||
cronhub:
|
ping_url: https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d031
|
||||||
ping_url: https://cronhub.io/start/1f5e3410-254c-11e8-b61d-55875966d031
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
this option in the `hooks:` section of your configuration.
|
||||||
|
|
||||||
With this hook in place, borgmatic pings your Cronhub monitor when a backup
|
With this hook in place, borgmatic pings your Cronhub monitor when a backup
|
||||||
begins, ends, or errors. Specifically, after the <a
|
begins, ends, or errors. Specifically, after the <a
|
||||||
href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
|
href="https://torsion.org/borgmatic/docs/how-to/add-preparation-and-cleanup-steps-to-backups/">`before_backup`
|
||||||
|
@ -251,11 +258,13 @@ Here's an example:
|
||||||
|
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
pagerduty:
|
||||||
pagerduty:
|
integration_key: a177cad45bd374409f78906a810a3074
|
||||||
integration_key: a177cad45bd374409f78906a810a3074
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
this option in the `hooks:` section of your configuration.
|
||||||
|
|
||||||
With this hook in place, borgmatic creates a PagerDuty event for your service
|
With this hook in place, borgmatic creates a PagerDuty event for your service
|
||||||
whenever backups fail. Specifically, if an error occurs during a `create`,
|
whenever backups fail. Specifically, if an error occurs during a `create`,
|
||||||
`prune`, `compact`, or `check` action, borgmatic sends an event to PagerDuty
|
`prune`, `compact`, or `check` action, borgmatic sends an event to PagerDuty
|
||||||
|
@ -291,31 +300,34 @@ An example configuration is shown here, with all the available options, includin
|
||||||
[tags](https://ntfy.sh/docs/publish/#tags-emojis):
|
[tags](https://ntfy.sh/docs/publish/#tags-emojis):
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
ntfy:
|
||||||
ntfy:
|
topic: my-unique-topic
|
||||||
topic: my-unique-topic
|
server: https://ntfy.my-domain.com
|
||||||
server: https://ntfy.my-domain.com
|
start:
|
||||||
start:
|
title: A Borgmatic backup started
|
||||||
title: A Borgmatic backup started
|
message: Watch this space...
|
||||||
message: Watch this space...
|
tags: borgmatic
|
||||||
tags: borgmatic
|
priority: min
|
||||||
priority: min
|
finish:
|
||||||
finish:
|
title: A Borgmatic backup completed successfully
|
||||||
title: A Borgmatic backup completed successfully
|
message: Nice!
|
||||||
message: Nice!
|
tags: borgmatic,+1
|
||||||
tags: borgmatic,+1
|
priority: min
|
||||||
priority: min
|
fail:
|
||||||
fail:
|
title: A Borgmatic backup failed
|
||||||
title: A Borgmatic backup failed
|
message: You should probably fix it
|
||||||
message: You should probably fix it
|
tags: borgmatic,-1,skull
|
||||||
tags: borgmatic,-1,skull
|
priority: max
|
||||||
priority: max
|
states:
|
||||||
states:
|
- start
|
||||||
- start
|
- finish
|
||||||
- finish
|
- fail
|
||||||
- fail
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
the `ntfy:` option in the `hooks:` section of your configuration.
|
||||||
|
|
||||||
|
|
||||||
## Scripting borgmatic
|
## Scripting borgmatic
|
||||||
|
|
||||||
To consume the output of borgmatic in other software, you can include an
|
To consume the output of borgmatic in other software, you can include an
|
||||||
|
|
|
@ -20,10 +20,12 @@ pull your repository passphrase, your database passwords, or any other option
|
||||||
values from environment variables. For instance:
|
values from environment variables. For instance:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
storage:
|
encryption_passphrase: ${MY_PASSPHRASE}
|
||||||
encryption_passphrase: ${MY_PASSPHRASE}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
this option in the `storage:` section of your configuration.
|
||||||
|
|
||||||
This uses the `MY_PASSPHRASE` environment variable as your encryption
|
This uses the `MY_PASSPHRASE` environment variable as your encryption
|
||||||
passphrase. Note that the `{` `}` brackets are required. `$MY_PASSPHRASE` by
|
passphrase. Note that the `{` `}` brackets are required. `$MY_PASSPHRASE` by
|
||||||
itself will not work.
|
itself will not work.
|
||||||
|
@ -38,12 +40,14 @@ configuration](https://torsion.org/borgmatic/docs/how-to/backup-your-databases/)
|
||||||
the same approach applies. For example:
|
the same approach applies. For example:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
postgresql_databases:
|
||||||
postgresql_databases:
|
- name: users
|
||||||
- name: users
|
password: ${MY_DATABASE_PASSWORD}
|
||||||
password: ${MY_DATABASE_PASSWORD}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
|
||||||
|
this option in the `hooks:` section of your configuration.
|
||||||
|
|
||||||
This uses the `MY_DATABASE_PASSWORD` environment variable as your database
|
This uses the `MY_DATABASE_PASSWORD` environment variable as your database
|
||||||
password.
|
password.
|
||||||
|
|
||||||
|
@ -53,8 +57,7 @@ password.
|
||||||
If you'd like to set a default for your environment variables, you can do so with the following syntax:
|
If you'd like to set a default for your environment variables, you can do so with the following syntax:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
storage:
|
encryption_passphrase: ${MY_PASSPHRASE:-defaultpass}
|
||||||
encryption_passphrase: ${MY_PASSPHRASE:-defaultpass}
|
|
||||||
```
|
```
|
||||||
|
|
||||||
Here, "`defaultpass`" is the default passphrase if the `MY_PASSPHRASE`
|
Here, "`defaultpass`" is the default passphrase if the `MY_PASSPHRASE`
|
||||||
|
@ -72,8 +75,7 @@ can escape it with a backslash. For instance, if your password is literally
|
||||||
`${A}@!`:
|
`${A}@!`:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
storage:
|
encryption_passphrase: \${A}@!
|
||||||
encryption_passphrase: \${A}@!
|
|
||||||
```
|
```
|
||||||
|
|
||||||
### Related features
|
### Related features
|
||||||
|
|
|
@ -135,12 +135,6 @@ repositories:
|
||||||
- path: original.borg
|
- path: original.borg
|
||||||
```
|
```
|
||||||
|
|
||||||
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> This
|
|
||||||
option was found in the `location:` section of your configuration.
|
|
||||||
|
|
||||||
<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
|
|
||||||
the `path:` portion of the `repositories` list.
|
|
||||||
|
|
||||||
Change it to a new (not yet created) repository path:
|
Change it to a new (not yet created) repository path:
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
|
@ -148,6 +142,12 @@ repositories:
|
||||||
- path: upgraded.borg
|
- path: upgraded.borg
|
||||||
```
|
```
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> This
|
||||||
|
option was found in the `location:` section of your configuration.
|
||||||
|
|
||||||
|
<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
|
||||||
|
the `path:` portion of the `repositories` list.
|
||||||
|
|
||||||
Then, run the `rcreate` action (formerly `init`) to create that new Borg 2
|
Then, run the `rcreate` action (formerly `init`) to create that new Borg 2
|
||||||
repository:
|
repository:
|
||||||
|
|
||||||
|
|
|
@ -15,7 +15,7 @@ listed here do not have equivalents in borgmatic's [configuration
|
||||||
file](https://torsion.org/borgmatic/docs/reference/configuration/).
|
file](https://torsion.org/borgmatic/docs/reference/configuration/).
|
||||||
|
|
||||||
If you're using an older version of borgmatic, some of these flags may not be
|
If you're using an older version of borgmatic, some of these flags may not be
|
||||||
present in that version, and you should instead use `borgmatic --help` or
|
present in that version and you should instead use `borgmatic --help` or
|
||||||
`borgmatic [action name] --help` (where `[action name]` is the name of an
|
`borgmatic [action name] --help` (where `[action name]` is the name of an
|
||||||
action like `list`, `create`, etc.).
|
action like `list`, `create`, etc.).
|
||||||
|
|
||||||
|
|
Loading…
Reference in a new issue