borgmatic

πŸͺ Command hooks

πŸ”

New in version 2.0.0 Command hooks allow you to run arbitrary prepration and cleanup commands (or external scripts) at various points in borgmatic's execution. You configure them via a list of commands: in your borgmatic configuration file. For example:

commands:
    - before: action
      when: [create]
      run:
          - echo "Before create!"
    - after: action
      when:
          - create
          - prune
      run:
          - echo "After create or prune!"
    - after: error
      run:
          - echo "Something went wrong!"

Each command in the commands: list has the following options:

When command hooks run, they respect the working_directory option if it is configured, meaning that the hook commands are run in that directory.

New in version 2.0.4If the exact same everything command hook is present in multiple configuration files, borgmatic only runs it once.

borgmatic's --repository flag does not impact which command hooks get run. But you can use the --config flag to limit the configuration files (and thus command hooks) used.

Order of execution

Here's a way of visualizing how all of these command hooks slot into borgmatic's execution.

Let's say you've got a borgmatic configuration file with a configured repository. And suppose you configure several command hooks and then run borgmatic for the create and prune actions. Here's the order of execution:

This same order of execution extends to multiple repositories and/or configuration files.

Based on the above, you can see the difference between, say, an after: action hook with states: [fail] and an after: error hook. The after: action hook runs immediately after the create action fails for a particular repositoryβ€”so before any subsequent actions for that repository or other repositories even have a chance to run. Whereas the after: error hook doesn't run until all actions forβ€”and repositories inβ€”a configuration file have had a chance to execute.

And if there are multiple hooks defined for a particular step (e.g. before: action for create), then those hooks are run in the order they're defined in configuration.

Variable interpolation

The command action hooks support interpolating particular runtime variables into the commands that are run. Here's are a couple examples that assume you provide separate shell scripts:

commands:
    - after: action
      when: [prune]
      run:
          - record-prune.sh {configuration_filename} {repository}
    - after: error
      when: [create]
      run:
          - send-text-message.sh {configuration_filename} {repository}

In this example, when the hook is triggered, borgmatic interpolates runtime values into each hook command: the borgmatic configuration filename and the paths of the current Borg repository.

Here's the full set of supported variables you can use here:

Not all command hooks support all variables. For instance, the everything and configuration hooks don't support repository variables because those hooks don't run in the context of a single repository. But the deprecated command hooks (before_backup, on_error, etc.) do generally support variable interpolation.

borgmatic automatically escapes these interpolated values to prevent shell injection attacks. One implication is that you shouldn't wrap the interpolated values in your own quotes, as that will interfere with the quoting performed by borgmatic and result in your command receiving incorrect arguments. For instance, this won't work:

commands:
    - after: error
      run:
          # Don't do this! It won't work, as the {error} value is already quoted.
          - send-text-message.sh "Uh oh: {error}"

Do this instead:

commands:
    - after: error
      run:
          - send-text-message.sh {error}

Note that you can also interpolate arbitrary environment variables.

Soft failure

If any of your hook commands return a special exit status of 75, that indicates to borgmatic that it's a temporary failure and borgmatic should skip all subsequent actions for the current repository.

If you return any status besides 75, then it's a standard success or error. (Zero is success; anything else other than 75 is an error).

Example of a soft failure command:

commands:
    - before: repository
      run:
          - findmnt /mnt/removable > /dev/null || exit 75

Caveats and details

There are some caveats you should be aware of with this feature.

Full configuration

# List of one or more command hooks to execute, triggered at
# particular points during borgmatic's execution. For each command
# hook, specify one of "before" or "after", not both.
commands:
    # Name for the point in borgmatic's execution that
    # the commands should be run before (required if
    # "after" isn't set):
    #  * "action" runs before each action for each
    # repository.
    #  * "repository" runs before all actions for each
    # repository.
    #  * "configuration" runs before all actions and
    # repositories in the current configuration file.
    #  * "everything" runs before all configuration
    # files.
    - before: action

      # Name for the point in borgmatic's execution that
      # the commands should be run after (required if
      # "before" isn't set):
      #  * "action" runs after each action for each
      # repository.
      #  * "repository" runs after all actions for each
      # repository.
      #  * "configuration" runs after all actions and
      # repositories in the current configuration file.
      #  * "everything" runs after all configuration
      # files.
      #  * "error" runs after an error occurs.
      after: action

      # Only trigger the hook when borgmatic is run with
      # particular actions listed here. Defaults to
      # running for all actions.
      when:
          - create
          - prune
          - compact
          - check

      # List of one or more shell commands or scripts to
      # run when this command hook is triggered. Required.
      run:
          - echo Doing stuff.

      # Only trigger the hook if borgmatic encounters one
      # of the states (execution results) listed here,
      # where:
      #  * "finish": No errors occurred.
      #  * "fail": An error occurred.
      # This state is evaluated only for the scope of the
      # configured "action", "repository", etc., rather
      # than for the entire borgmatic run. Only available
      # for "after" hooks. Defaults to running the hook
      # for all states.
      states:
          - finish

Improve this documentation

Have an idea on how to make this documentation even better? Use our issue tracker to send your feedback!