Borgmatic: Configuration-Driven Backups Without the Shell Script Sprawl

You've got a backup script somewhere. It's probably called backup.sh, it's probably got a dozen lines commented out from experiments gone wrong, and you're not entirely sure it still runs correctly at 3 AM. Borgmatic is an attempt to replace that script with a YAML file.

It's backup software for servers and workstations, built on top of Borg Backup, and it takes the "declare what you want, not how to do it" approach to protecting your data.

What It Does

Borgmatic is a configuration-driven wrapper around Borg Backup, the deduplicating archiver that handles the actual client-side encryption and storage. Where Borg gives you a powerful command-line interface with a lot of flags, borgmatic gives you a single config file that describes your entire backup strategy, then runs it consistently.

The core of it is straightforward: you list your source directories, list your repositories (local or remote — the example shows both an SSH path to BorgBase and a local path), and define a retention policy using keep_daily, keep_weekly, and keep_monthly values. Borgmatic handles the pruning according to those rules. You can also define checks to validate repositories and archives, optionally at different frequencies — the README shows repository checks running on the default schedule and archive checks running every two weeks.

What elevates it beyond a Borg wrapper is everything else in that config file. You can dump databases (PostgreSQL, MySQL, MariaDB, MongoDB, SQLite, InfluxDB) and include those dumps in the backup automatically. You can run preparation scripts before an action using the commands block — the example runs prepare-for-backup.sh before a create operation. And you can wire in healthchecks so you find out when backups aren't happening, which is the failure mode that actually matters.

Why It's Cool

• The config file is the documentation. A single YAML file tells you what's being backed up, where it's going, how long it's kept, what databases are involved, and who gets pinged if it breaks. Six months from now, when you've forgotten everything, that file is still readable. Compare that to reverse-engineering a shell script at 2 AM.

• Database dumps are first-class citizens. This is the part that usually turns into a mess of pg_dump invocations, timestamped filenames, and cleanup logic bolted onto your backup script. Borgmatic treats postgresql_databases and friends as config entries. It handles the dump and folds it into the backup, which means your database and your filesystem are captured in the same archive.

• Healthchecks integration is the honest feature. Most backup tools tell you when a backup succeeds. That's the easy part. Borgmatic's healthchecks integration (via ping_url) tells you when it doesn't run — dead man's switch style. If the ping doesn't arrive, you get alerted. That's the difference between a backup system and a backup system you can trust.

• Hooks before actions, not just around them. The commands block with before: action and when: [create] lets you scope preparation scripts to specific operations. You're not stuck with a monolithic pre-backup script — you can attach the right setup to the right step.

• Broad storage and data integration surface. The README lists integrations across PostgreSQL, MySQL, MariaDB, MongoDB, SQLite, InfluxDB, OpenZFS, Btrfs, LVM, OpenLDAP, rclone, and BorgBase on the data side, plus Healthchecks and Uptime Kuma on monitoring. That's a lot of "yes, we handle that" for a tool this focused.

How to Try It

1. Head to the canonical project home at torsion.org/borgmatic or the repository at github.com/borgmatic-collective/borgmatic.

2. Install borgmatic using whatever package manager or installation method the project documentation specifies for your platform. You'll also need Borg Backup itself installed, since borgmatic is powered by it.

3. Create a configuration file. Start from the example in the README and trim it down to what you actually need:

source_directories:
    - /home
    - /etc

repositories:
    - path: ssh://user@host/./repo
      label: remote
    - path: /var/lib/backups/local.borg
      label: local

keep_daily: 7
keep_weekly: 4
keep_monthly: 6

checks:
    - name: repository
    - name: archives
      frequency: 2 weeks

1. Add database dumps if you need them:

postgresql_databases:
    - name: users

1. Add a healthcheck ping URL if you want to know when things go wrong:

healthchecks:
    ping_url: https://hc-ping.com/your-uuid-here

1. Run it. Schedule it with cron or a systemd timer once you've confirmed it works interactively.

Final Thoughts

Borgmatic isn't trying to be a backup platform or a hosted service — it's a configuration layer that makes Borg usable without memorizing flags. If you're already using Borg and maintaining a homegrown wrapper script, this is a straightforward upgrade. If you're not using Borg yet, borgmatic is a reasonable entry point, though you'll still want to understand Borg's model of repositories and archives.

The real value is in the parts that prevent silent failure: retention policies that don't require you to remember borg prune syntax, database dumps that don't live in a separate script, and healthchecks that alert you when the whole thing stops running. Backups only count if they happen, and borgmatic seems designed around that reality.

Follow @githubprojects for more developer tools and open source projects.