Document "repositories" context to for "before_*" and "after_*" command action hooks (#469).
This commit is contained in:
parent
6b500c2a8b
commit
db7499db82
5 changed files with 33 additions and 7 deletions
1
NEWS
1
NEWS
|
@ -3,6 +3,7 @@
|
||||||
* #444: When loading a configuration file that is unreadable due to file permissions, warn instead
|
* #444: When loading a configuration file that is unreadable due to file permissions, warn instead
|
||||||
of erroring. This supports running borgmatic as a non-root user with configuration in ~/.config
|
of erroring. This supports running borgmatic as a non-root user with configuration in ~/.config
|
||||||
even if there is an unreadable global configuration file in /etc.
|
even if there is an unreadable global configuration file in /etc.
|
||||||
|
* #469: Add "repositories" context to "before_*" and "after_*" command action hooks.
|
||||||
* #486: Fix handling of "patterns_from" and "exclude_from" options to error instead of warning when
|
* #486: Fix handling of "patterns_from" and "exclude_from" options to error instead of warning when
|
||||||
referencing unreadable files and "create" action is run.
|
referencing unreadable files and "create" action is run.
|
||||||
* #507: Fix Borg usage error in the "compact" action when running "borgmatic --dry-run". Now, skip
|
* #507: Fix Borg usage error in the "compact" action when running "borgmatic --dry-run". Now, skip
|
||||||
|
|
|
@ -66,7 +66,7 @@ def run_configuration(config_filename, config, arguments):
|
||||||
monitoring_log_level = verbosity_to_log_level(global_arguments.monitoring_verbosity)
|
monitoring_log_level = verbosity_to_log_level(global_arguments.monitoring_verbosity)
|
||||||
|
|
||||||
hook_context = {
|
hook_context = {
|
||||||
'repository': ','.join(location['repositories']),
|
'repositories': ','.join(location['repositories']),
|
||||||
}
|
}
|
||||||
|
|
||||||
try:
|
try:
|
||||||
|
|
|
@ -37,9 +37,33 @@ There are additional hooks that run before/after other actions as well. For
|
||||||
instance, `before_prune` runs before a `prune` action, while `after_prune`
|
instance, `before_prune` runs before a `prune` action, while `after_prune`
|
||||||
runs after it.
|
runs after it.
|
||||||
|
|
||||||
|
## Variable interpolation
|
||||||
|
|
||||||
|
The before and after action hooks support interpolating particular runtime
|
||||||
|
variables into the hook command. Here's an example that assumes you provide a
|
||||||
|
separate shell script:
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
hooks:
|
||||||
|
after_prune:
|
||||||
|
- record-prune.sh "{configuration_filename}" "{repositories}"
|
||||||
|
```
|
||||||
|
|
||||||
|
In this example, when the hook is triggered, borgmatic interpolates runtime
|
||||||
|
values into the hook command: the borgmatic configuration filename and the
|
||||||
|
paths of all configured repositories. Here's the full set of supported
|
||||||
|
variables you can use here:
|
||||||
|
|
||||||
|
* `configuration_filename`: borgmatic configuration filename in which the
|
||||||
|
hook was defined
|
||||||
|
* `repositories`: comma-separated paths of all repositories configured in the
|
||||||
|
current borgmatic configuration file
|
||||||
|
|
||||||
You can also use `before_everything` and `after_everything` hooks to perform
|
You can also use `before_everything` and `after_everything` hooks to perform
|
||||||
global setup or cleanup:
|
global setup or cleanup:
|
||||||
|
|
||||||
|
## Global hooks
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
hooks:
|
hooks:
|
||||||
before_everything:
|
before_everything:
|
||||||
|
@ -58,6 +82,8 @@ 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
|
||||||
|
|
||||||
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
|
||||||
a backup or running a backup hook. See the [monitoring and alerting
|
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/)
|
||||||
|
|
|
@ -244,8 +244,8 @@ hooks:
|
||||||
### borgmatic hangs during backup
|
### borgmatic hangs during backup
|
||||||
|
|
||||||
See Limitations above about `read_special`. You may need to exclude certain
|
See Limitations above about `read_special`. You may need to exclude certain
|
||||||
paths with named pipes, block devices, or character devices on which borgmatic
|
paths with named pipes, block devices, character devices, or sockets on which
|
||||||
is hanging.
|
borgmatic is hanging.
|
||||||
|
|
||||||
Alternatively, if excluding special files is too onerous, you can create two
|
Alternatively, if excluding special files is too onerous, you can create two
|
||||||
separate borgmatic configuration files—one for your source files and a
|
separate borgmatic configuration files—one for your source files and a
|
||||||
|
|
|
@ -104,10 +104,9 @@ hooks:
|
||||||
- send-text-message.sh "{configuration_filename}" "{repository}"
|
- send-text-message.sh "{configuration_filename}" "{repository}"
|
||||||
```
|
```
|
||||||
|
|
||||||
In this example, when the error occurs, borgmatic interpolates a few runtime
|
In this example, when the error occurs, borgmatic interpolates runtime values
|
||||||
values into the hook command: the borgmatic configuration filename, and the
|
into the hook command: the borgmatic configuration filename, and the path of
|
||||||
path of the repository. Here's the full set of supported variables you can use
|
the repository. Here's the full set of supported variables you can use here:
|
||||||
here:
|
|
||||||
|
|
||||||
* `configuration_filename`: borgmatic configuration filename in which the
|
* `configuration_filename`: borgmatic configuration filename in which the
|
||||||
error occurred
|
error occurred
|
||||||
|
|
Loading…
Reference in a new issue