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

More documentation updates based on section removal (#721).

Browse source
This commit is contained in:
Dan Helfman 2023-07-11 22:10:57 -07:00
parent cedf562a7e
commit 2453ecad42
12 changed files with 243 additions and 232 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

4
docs/_includes/components/suggestion-link.html
View file

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

60
docs/how-to/add-preparation-and-cleanup-steps-to-backups.md
View file

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

20
docs/how-to/backup-to-a-removable-drive-or-an-intermittent-server.md
View file

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

141
docs/how-to/backup-your-databases.md
View file

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

32
docs/how-to/deal-with-very-large-backups.md
View file

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

6
docs/how-to/develop-on-borgmatic.md
View 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

2
docs/how-to/inspect-your-backups.md
View file

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

80
docs/how-to/make-per-application-backups.md
View file

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

94
docs/how-to/monitor-your-backups.md
View file

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

22
docs/how-to/provide-your-passwords.md
View file

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

12
docs/how-to/upgrade.md
View file

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

2
docs/reference/command-line.md
View file

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