borgmatic/docs/how-to/inspect-your-backups.md at b1941bcce9c50df7aac5dfd6185f33e63709a47d

Dan Helfman 7b3b28616d Add "borgmatic list --successful" flag to only list successful (non-checkpoint) archives (#86 ).

2019-10-13 15:58:11 -07:00

5.3 KiB

Raw Blame History

title
How to inspect your backups

Backup progress

By default, borgmatic runs proceed silently except in the case of errors. But if you'd like to to get additional information about the progress of the backup as it proceeds, use the verbosity option:

borgmatic --verbosity 1

This lists the files that borgmatic is archiving, which are those that are new or changed since the last backup.

Or, for even more progress and debug spew:

borgmatic --verbosity 2

Backup summary

If you're less concerned with progress during a backup, and you just want to see the summary of archive statistics at the end, you can use the stats option when performing a backup:

borgmatic --stats

Existing backups

borgmatic provides convenient actions for Borg's list and info functionality:

borgmatic list
borgmatic info

(No borgmatic list or info actions? Try the old-style --list or --info. Or upgrade borgmatic!)

Logging

By default, borgmatic logs to a local syslog-compatible daemon if one is present and borgmatic is running in a non-interactive console. Where those logs show up depends on your particular system. If you're using systemd, try running journalctl -xe. Otherwise, try viewing /var/log/syslog or similiar.

You can customize the log level used for syslog logging with the --syslog-verbosity flag, and this is independent from the console logging --verbosity flag described above. For instance, to get additional information about the progress of the backup as it proceeds:

borgmatic --syslog-verbosity 1

Or to increase syslog logging to include debug spew:

borgmatic --syslog-verbosity 2

systemd journal

If your local syslog daemon is systemd's journal, be aware that journald by default throttles the rate at which a particular program can log. So you may need to change the journald rate limit in /etc/systemd/journald.conf if you're finding that borgmatic journald logs are missing.

Note that the sample borgmatic systemd service file already has this rate limit disabled.

Error alerting

When an error occurs during a backup, borgmatic can run configurable shell commands to fire off custom error notifications or take other actions, so you can get alerted as soon as something goes wrong. Here's a not-so-useful example:

hooks:
    on_error:
        - echo "Error while creating a backup or running a backup hook."

The on_error hook supports interpolating particular runtime variables into the hook command. Here's an example that assumes you provide a separate shell script to handle the alerting:

hooks:
    on_error:
        - 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:

configuration_filename: borgmatic configuration filename in which the error occurred
repository: path of the repository in which the error occurred (may be blank if the error occurs in a hook)
error: the error message itself
output: output of the command that failed (may be blank if an error occurred without running a command)

Note that borgmatic does not run on_error hooks if an error occurs within a before_everything or after_everything hook. For more about hooks, see the borgmatic hooks documentation, especially the security information.

Scripting borgmatic

To consume the output of borgmatic in other software, you can include an optional --json flag with create, list, or info to get the output formatted as JSON.

Note that when you specify the --json flag, Borg's other non-JSON output is suppressed so as not to interfere with the captured JSON. Also note that JSON output only shows up at the console, and not in syslog.

Successful backups

borgmatic list includes support for a --successful flag that only lists successful (non-checkpoint) backups. Combined with a built-in Borg flag like --last, you can list the last successful backup for use in your monitoring scripts. Here's an example combined with --json:

borgmatic list --successful --last 1 --json

Note that this particular combination will only work if you've got a single backup "series" in your repository. If you're instead backing up, say, from multiple different hosts into a single repository, then you'll need to get fancier with your archive listing. See borg list --help for more flags.

5.3 KiB Raw Blame History