borgmatic

How to backup to a removable drive or an intermittent server

Occasional backups

A common situation is backing up to a repository that's only sometimes online. For instance, you might send most of your backups to the cloud, but occasionally you want to plug in an external hard drive or backup to your buddy's sometimes-online server for that extra level of redundancy.

But if you run borgmatic and your hard drive isn't plugged in, or your buddy's server is offline, then you'll get an annoying error message and the overall borgmatic run will fail (even if individual repositories still complete).

So what if you want borgmatic to swallow the error of a missing drive or an offline server, and continue trucking along? That's where the concept of "soft failure" come in.

Soft failure command hooks

This feature leverages borgmatic command hooks, so first familiarize yourself with them. The idea is that you write a simple test in the form of a borgmatic hook to see if backups should proceed or not.

The way the test works is that 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 that configuration file. If you return any other status, then it's a standard success or error. (Zero is success; anything else other than 75 is an error).

So for instance, if you have an external drive that's only sometimes mounted, declare its repository in its own separate configuration file, say at /etc/borgmatic.d/removable.yaml:

location:
source_directories:
- /home

repositories:
- /mnt/removable/backup.borg

Then, write a before_backup hook in that same configuration file that uses the external findmnt utility to see whether the drive is mounted before proceeding.

hooks:
before_backup:
- findmnt /mnt/removable > /dev/null || exit 75

What this does is check if the findmnt command errors when probing for a particular mount point. If it does error, then it returns exit code 75 to borgmatic. borgmatic logs the soft failure, skips all further actions in that configurable file, and proceeds onward to any other borgmatic configuration files you may have.

You can imagine a similar check for the sometimes-online server case:

location:
source_directories:
- /home

repositories:
- me@buddys-server.org:backup.borg

hooks:
before_backup:
- ping -q -c 1 buddys-server.org > /dev/null || exit 75

Caveats and details

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

Improve this documentation

Have an idea on how to make this documentation even better? Send your feedback below! But if you need help with borgmatic, or have an idea for a borgmatic feature, please use our issue tracker instead.