Acasă Explorează Ajutor
Autentificare
mirrors
/
borgmatic
oglindă de https://github.com/witten/borgmatic
2
0
Bifurcare 0
Fisiere Probleme 0 Wiki
Arbore: ec88bb2e9c
Ramuri Etichete
borgmatic
/
docs
/
how-to
/
add-preparation-and-cleanup-steps-to-backups.md

add-preparation-and-cleanup-steps-to-backups.md 8.6 KB
Istoric Crud

title: How to add preparation and cleanup steps to backups eleventyNavigation: key: 🧹 Add preparation and cleanup steps parent: How-to guides

order: 10

Preparation and cleanup hooks

If you find yourself performing preparation tasks before your backup runs or cleanup work afterwards, borgmatic command hooks may be of interest. These are custom shell commands you can configure borgmatic to execute at various points as it runs.

But if you're looking to backup a database, it's probably easier to use the database backup feature instead.

New in version 1.9.14 You can configure command hooks 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 and/or prune!"

If A run: command contains a special YAML character such as a colon, you may need to quote the entire string (or use a multiline string) to avoid an error:

commands:
    - before: action
      when:
          - create
      run:
    - "echo Backup: start"

Each command has the following options:

  • before or after: Name for the point in borgmatic's execution that the commands should be run before/after, one of:
    • action runs before each action for each repository. (Replaces the deprecated before_create, after_prune, etc.)
    • repository runs before/after all actions for each repository. (Replaces the deprecated before_actions/after_actions.)
    • configuration runs before/after all actions and repositories in the current configuration file.
    • everything runs before/after all configuration files. (Replaces the deprecated before_everything/after_everything.)
  • when: List of actions for which the commands will be run. Defaults to running for all actions.
  • run: List of one or more shell commands or scripts to run when this command hook is triggered.

There's also another command hook that works a little differently:

commands:
    - before: dump_data_sources
      hooks:
          - postgresql
      run:
          - echo "Right before the PostgreSQL database dump!"

This command hook has the following options:

  • before or after: dump_data_sources
  • hooks: List of names of other hooks that this command hook applies to. Defaults to all hooks of the relevant type.
  • run: List of one or more shell commands or scripts to run when this command hook is triggered.

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:

  • Trigger before: everything (from all configuration files).
    • Trigger before: configuration (from the first configuration file).
      • Trigger before: repository (for the first repository).
        • Trigger before: action for create.
        • Run the create action.
        • Trigger after: action for create.
        • Trigger before: action for prune.
        • Run the prune action.
        • Trigger after: action for prune.
      • Trigger after: repository (for the first repository).
    • Trigger after: configuration (from the first configuration file).
  • Trigger after: everything (from all configuration files).

You can imagine how this would be extended to multiple repositories and/or configuration files.

Deprecated command hooks

Prior to version 1.9.14 The command hooks worked a little differently. In these older versions of borgmatic, you can specify before_backup hooks to perform preparation steps before running backups and specify after_backup hooks to perform cleanup steps afterwards. Here's an example:

before_backup:
    - mount /some/filesystem
after_backup:
    - umount /some/filesystem

If your command contains a special YAML character such as a colon, you may need to quote the entire string (or use a multiline string) to avoid an error:

before_backup:
    - "echo Backup: start"

There are additional hooks that run before/after other actions as well. For instance, before_prune runs before a prune action for a repository, while after_prune runs after it.

Prior to version 1.8.0 Put these options in the hooks: section of your configuration.

New in version 1.7.0 The before_actions and after_actions hooks run before/after all the actions (like create, prune, etc.) for each repository. These hooks are a good place to run per-repository steps like mounting/unmounting a remote filesystem.

New in version 1.6.0 The before_backup and after_backup hooks each run once per repository in a configuration file. before_backup hooks runs right before the create action for a particular repository, and after_backup hooks run afterwards, but not if an error occurs in a previous hook or in the backups themselves. (Prior to borgmatic 1.6.0, these hooks instead ran once per configuration file rather than once per repository.)

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:

after_prune:
    - record-prune.sh "{configuration_filename}" "{repository}"

Prior to version 1.8.0 Put this option in the hooks: section of your configuration.

In this example, when the hook is triggered, borgmatic interpolates runtime values into the 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:

  • configuration_filename: borgmatic configuration filename in which the hook was defined
  • log_file New in version 1.7.12: path of the borgmatic log file, only set when the --log-file flag is used
  • repository: path of the current repository as configured in the current borgmatic configuration file
  • repository_label New in version 1.8.12: label of the current repository as configured in the current borgmatic configuration file

Note that you can also interpolate in arbitrary environment variables.

Global hooks

You can also use before_everything and after_everything hooks to perform global setup or cleanup:

before_everything:
    - set-up-stuff-globally
after_everything:
    - clean-up-stuff-globally

Prior to version 1.8.0 Put these options in the hooks: section of your configuration.

before_everything hooks collected from all borgmatic configuration files run once before all configuration files (prior to all actions), but only if there is a create action. An error encountered during a before_everything hook causes borgmatic to exit without creating backups.

after_everything hooks run once after all configuration files and actions, 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 for more information.

Hook output

Any output produced by your hooks shows up both at the console and in syslog (when enabled). For more information, read about inspecting your backups.

Security

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 on borgmatic configuration files (chmod 0600) and scripts (chmod 0700) invoked by hooks.