Update documentation for section removal (#721).

This commit is contained in:
Dan Helfman 2023-07-11 19:42:14 -07:00
parent ecd9e62147
commit d2fa205476
8 changed files with 184 additions and 162 deletions

View file

@ -16,7 +16,6 @@ The canonical home of borgmatic is at <a href="https://torsion.org/borgmatic">ht
Here's an example configuration file: Here's an example configuration file:
```yaml ```yaml
location:
# List of source directories to backup. # List of source directories to backup.
source_directories: source_directories:
- /home - /home
@ -29,20 +28,17 @@ location:
- path: /var/lib/backups/local.borg - path: /var/lib/backups/local.borg
label: local label: local
retention:
# Retention policy for how many backups to keep. # Retention policy for how many backups to keep.
keep_daily: 7 keep_daily: 7
keep_weekly: 4 keep_weekly: 4
keep_monthly: 6 keep_monthly: 6
consistency:
# List of checks to run to validate your backups. # List of checks to run to validate your backups.
checks: checks:
- name: repository - name: repository
- name: archives - name: archives
frequency: 2 weeks frequency: 2 weeks
hooks:
# Custom preparation scripts to run. # Custom preparation scripts to run.
before_backup: before_backup:
- prepare-for-backup.sh - prepare-for-backup.sh
@ -55,11 +51,6 @@ hooks:
healthchecks: https://hc-ping.com/be067061-cf96-4412-8eae-62b0c50d6a8c healthchecks: https://hc-ping.com/be067061-cf96-4412-8eae-62b0c50d6a8c
``` ```
Want to see borgmatic in action? Check out the <a
href="https://asciinema.org/a/203761?autoplay=1" target="_blank">screencast</a>.
<a href="https://asciinema.org/a/203761?autoplay=1" target="_blank"><img src="https://asciinema.org/a/203761.png" width="480"></a>
borgmatic is powered by [Borg Backup](https://www.borgbackup.org/). borgmatic is powered by [Borg Backup](https://www.borgbackup.org/).
## Integrations ## Integrations

View file

@ -44,7 +44,6 @@ file](https://torsion.org/borgmatic/docs/how-to/make-per-application-backups/),
say at `/etc/borgmatic.d/removable.yaml`: say at `/etc/borgmatic.d/removable.yaml`:
```yaml ```yaml
location:
source_directories: source_directories:
- /home - /home
@ -52,6 +51,9 @@ location:
- path: /mnt/removable/backup.borg - path: /mnt/removable/backup.borg
``` ```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
these options in the `location:` section of your configuration.
<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit <span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
the `path:` portion of the `repositories` list. the `path:` portion of the `repositories` list.
@ -77,18 +79,20 @@ optionally using `before_actions` instead.
You can imagine a similar check for the sometimes-online server case: You can imagine a similar check for the sometimes-online server case:
```yaml ```yaml
location:
source_directories: source_directories:
- /home - /home
repositories: repositories:
- path: ssh://me@buddys-server.org/./backup.borg - path: ssh://me@buddys-server.org/./backup.borg
hooks:
before_backup: 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 <span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
the `path:` portion of the `repositories` list. the `path:` portion of the `repositories` list.

View file

@ -196,6 +196,7 @@ it is a mandatory option there:
```yaml ```yaml
location: location:
source_directories: [] source_directories: []
hooks: hooks:
mysql_databases: mysql_databases:
- name: all - name: all

View file

@ -162,11 +162,13 @@ either for a single repository or for all repositories.
Disabling all consistency checks looks like this: Disabling all consistency checks looks like this:
```yaml ```yaml
consistency:
checks: checks:
- name: disabled - name: disabled
``` ```
<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> `checks` <span class="minilink minilink-addedin">Prior to version 1.6.2</span> `checks`
was a plain list of strings without the `name:` part. For instance: was a plain list of strings without the `name:` part. For instance:
@ -181,7 +183,6 @@ you can keep running consistency checks, but only against a subset of the
repositories: repositories:
```yaml ```yaml
consistency:
check_repositories: check_repositories:
- path/of/repository_to_check.borg - path/of/repository_to_check.borg
``` ```

View file

@ -12,7 +12,6 @@ it. borgmatic supports this in its configuration by specifying multiple backup
repositories. Here's an example: repositories. Here's an example:
```yaml ```yaml
location:
# List of source directories to backup. # List of source directories to backup.
source_directories: source_directories:
- /home - /home
@ -24,6 +23,9 @@ location:
- path: /var/lib/backups/local.borg - path: /var/lib/backups/local.borg
``` ```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
these options in the `location:` section of your configuration.
<span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit <span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
the `path:` portion of the `repositories` list. the `path:` portion of the `repositories` list.

View file

@ -74,14 +74,15 @@ and borgmatic uses that format to name any new archive it creates. For
instance: instance:
```yaml ```yaml
storage:
...
archive_name_format: home-directories-{now} archive_name_format: home-directories-{now}
``` ```
This means that when borgmatic creates an archive, its name will start with <span class="minilink minilink-addedin">Prior to version 1.8.0</span> Put
the string `home-directories-` and end with a timestamp for its creation time. this option in the `storage:` section of your configuration.
If `archive_name_format` is unspecified, the default is
This example means that when borgmatic creates an archive, its name will start
with the string `home-directories-` and end with a timestamp for its creation
time. If `archive_name_format` is unspecified, the default is
`{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}`, meaning your system hostname plus a `{hostname}-{now:%Y-%m-%dT%H:%M:%S.%f}`, meaning your system hostname plus a
timestamp in a particular format. timestamp in a particular format.
@ -156,23 +157,28 @@ them. To achieve this, you can put fragments of common configuration options
into a file, and then include or inline that file into one or more borgmatic into a file, and then include or inline that file into one or more borgmatic
configuration files. configuration files.
Let's say that you want to include common retention configuration across all Let's say that you want to include common consistency check configuration across all
of your configuration files. You could do that in each configuration file with of your configuration files. You could do that in each configuration file with
the following: the following:
```yaml ```yaml
location: repositories:
... - path: repo.borg
retention: checks:
!include /etc/borgmatic/common_retention.yaml !include /etc/borgmatic/common_checks.yaml
``` ```
And then the contents of `common_retention.yaml` could be: <span class="minilink minilink-addedin">Prior to version 1.8.0</span> These
options were organized into sections like `location:` and `consistency:`.
The contents of `common_checks.yaml` could be:
```yaml ```yaml
keep_hourly: 24 - name: repository
keep_daily: 7 frequency: 3 weeks
- name: archives
frequency: 2 weeks
``` ```
To prevent borgmatic from trying to load these configuration fragments by To prevent borgmatic from trying to load these configuration fragments by
@ -188,11 +194,11 @@ Note that this form of include must be a YAML value rather than a key. For
example, this will not work: example, this will not work:
```yaml ```yaml
location: repositories:
... - path: repo.borg
# Don't do this. It won't work! # Don't do this. It won't work!
!include /etc/borgmatic/common_retention.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 YAML key *and* its values, keep reading!
@ -203,45 +209,48 @@ But if you do want to merge in a YAML key *and* its values, keep reading!
If you need to get even fancier and merge in common configuration options, you If you need to get even fancier and merge in common configuration options, you
can perform a YAML merge of included configuration using the YAML `<<` key. can perform a YAML merge of included configuration using the YAML `<<` key.
For instance, here's an example of a main configuration file that pulls in For instance, here's an example of a main configuration file that pulls in
retention and consistency options via a single include: retention and consistency checks options via a single include:
```yaml ```yaml
<<: !include /etc/borgmatic/common.yaml repositories:
- path: repo.borg
location: <<: !include /etc/borgmatic/common.yaml
...
``` ```
This is what `common.yaml` might look like: This is what `common.yaml` might look like:
```yaml ```yaml
retention:
keep_hourly: 24 keep_hourly: 24
keep_daily: 7 keep_daily: 7
consistency:
checks: checks:
- name: repository - name: repository
frequency: 3 weeks
- name: archives
frequency: 2 weeks
``` ```
Once this include gets merged in, the resulting configuration would have all <span class="minilink minilink-addedin">Prior to version 1.8.0</span> These
of the `location` options from the original configuration file *and* the options were organized into sections like `retention:` and `consistency:`.
`retention` and `consistency` options from the include.
Prior to borgmatic version 1.6.0, when there's a section collision between the Once this include gets merged in, the resulting configuration would have all
local file and the merged include, the local file's section takes precedence. of the options from the original configuration file *and* the options from the
So if the `retention` section appears in both the local file and the include include.
file, the included `retention` is ignored in favor of the local `retention`.
But see below about deep merge in version 1.6.0+. <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 section above about standard includes. single value directly, please see the above about standard includes.
Additionally, there is a limitation preventing multiple `<<` include merges Additionally, there is a limitation preventing multiple `<<` include merges
per section. So for instance, that means you can do one `<<` merge at the per file or option value. So for instance, that means you can do one `<<`
global level, another `<<` within each configuration section, etc. (This is a merge at the global level, another `<<` within each nested option value, etc.
YAML limitation.) (This is a YAML limitation.)
### Deep merge ### Deep merge
@ -342,8 +351,8 @@ includes.
### Shallow merge ### Shallow merge
Even though deep merging is generally pretty handy for included files, Even though deep merging is generally pretty handy for included files,
sometimes you want specific sections in the local file to take precedence over sometimes you want specific options in the local file to take precedence over
included sections—without any merging occurring for them. included options—without any merging occurring for them.
<span class="minilink minilink-addedin">New in version 1.7.12</span> That's <span class="minilink minilink-addedin">New in version 1.7.12</span> That's
where the `!retain` tag comes in. Whenever you're merging an included file where the `!retain` tag comes in. Whenever you're merging an included file
@ -357,37 +366,38 @@ on the `retention` mapping:
```yaml ```yaml
<<: !include /etc/borgmatic/common.yaml <<: !include /etc/borgmatic/common.yaml
location:
repositories: repositories:
- path: repo.borg - path: repo.borg
retention: !retain checks: !retain
keep_daily: 5 - name: repository
``` ```
And `common.yaml` like this: And `common.yaml` like this:
```yaml ```yaml
location:
repositories: repositories:
- path: common.borg - path: common.borg
retention: checks:
keep_hourly: 24 - name: archives
keep_daily: 7
``` ```
Once this include gets merged in, the resulting configuration will have a <span class="minilink minilink-addedin">Prior to version 1.8.0</span> These
`keep_daily` value of `5` and nothing else in the `retention` section. That's options were organized into sections like `location:` and `consistency:`.
because the `!retain` tag says to retain the local version of `retention` and
ignore any values coming in from the include. But because the `repositories`
list doesn't have a `!retain` tag, it still gets merged together to contain
both `common.borg` and `repo.borg`.
The `!retain` tag can only be placed on mappings and lists, and it goes right Once this include gets merged in, the resulting configuration will have a
after the name of the option (and its colon) on the same line. The effects of `checks` value with a name of `repository` and no other values. That's because
`!retain` are recursive, meaning that if you place a `!retain` tag on a the `!retain` tag says to retain the local version of `checks` and ignore any
top-level mapping, even deeply nested values within it will not be merged. values coming in from the include. But because the `repositories` list doesn't
have a `!retain` tag, it still gets merged together to contain both
`common.borg` and `repo.borg`.
The `!retain` tag can only be placed on mappings (keys/values) and lists, and
it goes right after the name of the option (and its colon) on the same line.
The effects of `!retain` are recursive, meaning that if you place a `!retain`
tag on a top-level mapping, even deeply nested values within it will not be
merged.
Additionally, the `!retain` tag only works in a configuration file that also Additionally, the `!retain` tag only works in a configuration file that also
performs a merge include with `<<: !include`. It doesn't make sense within, performs a merge include with `<<: !include`. It doesn't make sense within,
@ -434,43 +444,50 @@ Whatever the reason, you can override borgmatic configuration options at the
command-line via the `--override` flag. Here's an example: command-line via the `--override` flag. Here's an example:
```bash ```bash
borgmatic create --override location.remote_path=/usr/local/bin/borg1 borgmatic create --override remote_path=/usr/local/bin/borg1
``` ```
What this does is load your configuration files, and for each one, disregard What this does is load your configuration files, and for each one, disregard
the configured value for the `remote_path` option in the `location` section, the configured value for the `remote_path` option, and use the value of
and use the value of `/usr/local/bin/borg1` instead. `/usr/local/bin/borg1` instead.
You can even override multiple values at once. For instance: <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:
```bash ```bash
borgmatic create --override section.option1=value1 section.option2=value2 borgmatic create --override parent_option.option1=value1 parent_option.option2=value2
``` ```
This will accomplish the same thing: This will accomplish the same thing:
```bash ```bash
borgmatic create --override section.option1=value1 --override section.option2=value2 borgmatic create --override parent_option.option1=value1 --override parent_option.option2=value2
``` ```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Don't
forget to specify the section that an option is in. That looks like a prefix
on the option name, e.g. `location.repositories`.
Note that each value is parsed as an actual YAML string, so you can even set Note that each value is parsed as an actual YAML string, so you can even set
list values by using brackets. For instance: list values by using brackets. For instance:
```bash ```bash
borgmatic create --override location.repositories=[test1.borg,test2.borg] borgmatic create --override repositories=[test1.borg,test2.borg]
``` ```
Or even a single list element: Or even a single list element:
```bash ```bash
borgmatic create --override location.repositories=[/root/test.borg] borgmatic create --override repositories=[/root/test.borg]
``` ```
If your override value contains special YAML characters like colons, then If your override value contains special YAML characters like colons, then
you'll need quotes for it to parse correctly: you'll need quotes for it to parse correctly:
```bash ```bash
borgmatic create --override location.repositories="['user@server:test.borg']" borgmatic create --override repositories="['user@server:test.borg']"
``` ```
There is not currently a way to override a single element of a list without There is not currently a way to override a single element of a list without
@ -486,7 +503,9 @@ indentation and a leading dash.)
Be sure to quote your overrides if they contain spaces or other characters Be sure to quote your overrides if they contain spaces or other characters
that your shell may interpret. that your shell may interpret.
An alternate to command-line overrides is passing in your values via [environment variables](https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/). An alternate to command-line overrides is passing in your values via
[environment
variables](https://torsion.org/borgmatic/docs/how-to/provide-your-passwords/).
## Constant interpolation ## Constant interpolation
@ -506,16 +525,19 @@ constants:
user: foo user: foo
archive_prefix: bar archive_prefix: bar
location:
source_directories: source_directories:
- /home/{user}/.config - /home/{user}/.config
- /home/{user}/.ssh - /home/{user}/.ssh
... ...
storage:
archive_name_format: '{archive_prefix}-{now}' archive_name_format: '{archive_prefix}-{now}'
``` ```
<span class="minilink minilink-addedin">Prior to version 1.8.0</span> Don't
forget to specify the section (like `location:` or `storage:`) that any option
is in.
In this example, when borgmatic runs, all instances of `{user}` get replaced In this example, when borgmatic runs, all instances of `{user}` get replaced
with `foo` and all instances of `{archive-prefix}` get replaced with `bar-`. with `foo` and all instances of `{archive-prefix}` get replaced with `bar-`.
(And in this particular example, `{now}` doesn't get replaced with anything, (And in this particular example, `{now}` doesn't get replaced with anything,
@ -523,13 +545,12 @@ but gets passed directly to Borg.) After substitution, the logical result
looks something like this: looks something like this:
```yaml ```yaml
location:
source_directories: source_directories:
- /home/foo/.config - /home/foo/.config
- /home/foo/.ssh - /home/foo/.ssh
... ...
storage:
archive_name_format: 'bar-{now}' archive_name_format: 'bar-{now}'
``` ```

View file

@ -140,13 +140,14 @@ use the `--destination` flag, for instance: `--destination
You should edit the configuration file to suit your needs, as the generated You should edit the configuration file to suit your needs, as the generated
values are only representative. All options are optional except where values are only representative. All options are optional except where
indicated, so feel free to ignore anything you don't need. indicated, so feel free to ignore anything you don't need. Be sure to use
spaces rather than tabs for indentation; YAML does not allow tabs.
Note that the configuration file is organized into distinct sections, each <span class="minilink minilink-addedin">Prior to version 1.8.0</span> The
with a section name like `location:` or `storage:`. So take care that if you configuration file was organized into distinct sections, each with a section
uncomment a particular option, also uncomment its containing section name, or name like `location:` or `storage:`. So in older versions of borgmatic, take
else borgmatic won't recognize the option. Also be sure to use spaces rather care that if you uncomment a particular option, also uncomment its containing
than tabs for indentation; YAML does not allow tabs. section name—or else borgmatic won't recognize the option.
You can get the same sample configuration file from the [configuration You can get the same sample configuration file from the [configuration
reference](https://torsion.org/borgmatic/docs/reference/configuration/), the reference](https://torsion.org/borgmatic/docs/reference/configuration/), the

View file

@ -131,18 +131,19 @@ Let's say your original borgmatic repository configuration file looks something
like this: like this:
```yaml ```yaml
location:
repositories: 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 <span class="minilink minilink-addedin">Prior to version 1.7.10</span> Omit
the `path:` portion of the `repositories` list. 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
location:
repositories: repositories:
- path: upgraded.borg - path: upgraded.borg
``` ```