diff --git a/NEWS b/NEWS index 3cc473c97..a00e8835f 100644 --- a/NEWS +++ b/NEWS @@ -7,6 +7,7 @@ * #38, #76: Upgrade ruamel.yaml compatibility version range and fix support for Python 3.7. * #77: Skip non-"*.yaml" config filenames in /etc/borgmatic.d/ so as not to parse backup files, editor swap files, etc. + * #81: Document user-defined hooks run before/after backup, or on error. * Add code style guidelines to the documention. 1.2.0 diff --git a/README.md b/README.md index ce60fc260..ab95e0165 100644 --- a/README.md +++ b/README.md @@ -138,6 +138,31 @@ configuration paths on the command-line with borgmatic's `--config` option. See `borgmatic --help` for more information. +### Hooks + +If you find yourself performing prepraration tasks before your backup runs, or +cleanup work afterwards, borgmatic hooks may be of interest. They're simply +shell commands that borgmatic executes for you at various points, and they're +configured in the `hooks` section of your configuration file. + +For instance, you can specify `before_backup` hooks to dump a database to file +before backing it up, and specify `after_backup` hooks to delete the temporary +file afterwards. + +borgmatic hooks run once per configuration file. `before_backup` hooks run +prior to backups of all repositories. `after_backup` hooks run afterwards, but +not if an error occurs in previous hook or in the backups themselves. And +borgmatic runs `on_error` hooks if an error occurs. + +An important security note about hooks: borgmatic executes all hook commands +with the user permissions of borgmatic itself. So to prevent potential shell +injection or privilege escalation, do not forget to set secure permissions +(chmod 0700) on borgmatic configuration files and scripts invoked by hooks. + +See the sample generated configuration file mentioned above for specifics +about hook configuration syntax. + + ## Upgrading In general, all you should need to do to upgrade borgmatic is run the @@ -329,7 +354,7 @@ your thing. In general, contributions are very welcome. We don't bite! ### Code style Start with [PEP 8](https://www.python.org/dev/peps/pep-0008/). But then, apply -the following deviations from PEP 8: +the following deviations from it: * For strings, prefer single quotes over double quotes. * Limit all lines to a maximum of 100 characters.