diff --git a/NEWS b/NEWS index 0707a3c..7eaa051 100644 --- a/NEWS +++ b/NEWS @@ -3,6 +3,7 @@ * #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 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 referencing unreadable files and "create" action is run. * #507: Fix Borg usage error in the "compact" action when running "borgmatic --dry-run". Now, skip diff --git a/borgmatic/commands/borgmatic.py b/borgmatic/commands/borgmatic.py index a027e39..b8efb86 100644 --- a/borgmatic/commands/borgmatic.py +++ b/borgmatic/commands/borgmatic.py @@ -66,7 +66,7 @@ def run_configuration(config_filename, config, arguments): monitoring_log_level = verbosity_to_log_level(global_arguments.monitoring_verbosity) hook_context = { - 'repository': ','.join(location['repositories']), + 'repositories': ','.join(location['repositories']), } try: diff --git a/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md b/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md index 45bbfbe..abf293d 100644 --- a/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md +++ b/docs/how-to/add-preparation-and-cleanup-steps-to-backups.md @@ -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` 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 global setup or cleanup: +## Global hooks + ```yaml hooks: 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 `before_everything` hook. +## Error hooks + 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 documentation](https://torsion.org/borgmatic/docs/how-to/monitor-your-backups/) diff --git a/docs/how-to/backup-your-databases.md b/docs/how-to/backup-your-databases.md index 0d1abb3..297cf40 100644 --- a/docs/how-to/backup-your-databases.md +++ b/docs/how-to/backup-your-databases.md @@ -244,8 +244,8 @@ hooks: ### borgmatic hangs during backup See Limitations above about `read_special`. You may need to exclude certain -paths with named pipes, block devices, or character devices on which borgmatic -is hanging. +paths with named pipes, block devices, character devices, or sockets on which +borgmatic is hanging. Alternatively, if excluding special files is too onerous, you can create two separate borgmatic configuration files—one for your source files and a diff --git a/docs/how-to/monitor-your-backups.md b/docs/how-to/monitor-your-backups.md index e616a29..501e98f 100644 --- a/docs/how-to/monitor-your-backups.md +++ b/docs/how-to/monitor-your-backups.md @@ -104,10 +104,9 @@ hooks: - send-text-message.sh "{configuration_filename}" "{repository}" ``` -In this example, when the error occurs, borgmatic interpolates a few runtime -values into the hook command: the borgmatic configuration filename, and the -path of the repository. Here's the full set of supported variables you can use -here: +In this example, when the error occurs, borgmatic interpolates runtime values +into the hook command: the borgmatic configuration filename, and the path of +the repository. Here's the full set of supported variables you can use here: * `configuration_filename`: borgmatic configuration filename in which the error occurred