Borg & Borgmatic

Borg stores encrypted, deduplicated archives. Borgmatic wraps Borg with YAML config, schedules, and hooks so backups stay consistent and repeatable.

If you only remember six things

Treat the repo passphrase or key export like production credentials: loss means unreadable backups.
Run application-consistent dumps for databases; use Borg for files and those dumps, not raw DB data dirs unless you know the trade-offs.
Define retention with borg prune (or Borgmatic retention) and monitor repo growth, not just job success.
Schedule restore drills: list an archive, extract to a temp path, verify checksums or app start.
Off-site copies mean a second failure domain (another host, bucket, or account), not only a second path on the same machine.
Pair this page with Backup & restore for 3-2-1 strategy and Postgres / MySQL for engine-native backup patterns.

On this page

When to use Borg vs other tools
Install
Repository layout and remotes
Encryption and key handling
Borgmatic configuration
Retention and pruning
Restore drill
See also

When to use Borg vs other tools

Borg fits Linux/BSD hosts where you want deduplication, strong encryption, and efficient daily incrementals over SSH or local disk. Backup & restore covers RPO/RTO and 3-2-1; this page is the tool path.

Need	Pointer
Postgres physical backup, WAL, PITR, `pgbackrest`	Postgres backup
MySQL / MariaDB logical or physical + binlogs	MySQL backup
Strategy, drills, immutability, runbook shape	Backup & restore and DR runbook template
Single binary, many cloud object backends, no Borg on the target	Consider Restic instead; SysRef standardizes on one file-level page here—Borg + Borgmatic.

Install

Package names differ by distribution. You want borgbackup and borgmatic (or borg-backup on some distros). Example on Debian/Ubuntu:

sudo apt update && sudo apt install -y borgbackup borgmatic
borgmatic --version

Run Borg as a dedicated user (e.g. borg or the service user) with least privilege; only that user needs read access to the paths you back up.

Repository layout and remotes

Initialize a repository once. Path can be local (block storage), SSH to another host, or a rclone remote (with caveats: locking and performance). Example local encrypted repo:

export BORG_PASSPHRASE='(use a long random secret; store in a secrets manager)'
borg init --encryption=repokey-blake2 /var/lib/borg-backup/reponame

SSH form (repo lives on the backup server): borg init [email protected]:/var/borg/myclient. Keep one repo per client or per site as fits your threat model; split repos to contain blast radius.

Encryption and key handling

With repokey modes, the key is stored in the repository (encrypted by your passphrase). You must still export a key backup and store it separately:

borg key export /var/lib/borg-backup/reponame /secure/offsite/borg-repokey-myclient.txt

Document who can access BORG_PASSPHRASE during incidents. If you only have the files on the backup server and it is lost, you need both exported key and passphrase to recover. Never commit passphrases to git; use environment files or your orchestrator’s secret store (see Secrets patterns).

Borgmatic configuration

Borgmatic’s config is usually /etc/borgmatic/config.yaml (or a .d drop-in directory). A minimal example backs up a directory and runs database dumps only if you add before_backup hooks:

source_directories:
  - /srv
  - /etc

repositories:
  - path: ssh://backup.example/./repos/myhost
    label: offsite

keep_daily: 7
keep_weekly: 4
keep_monthly: 6

hooks:
  before_backup:
    - echo "pre-backup: flush app caches or snapshot if needed"
  # Example: run pg_dump into a file under /srv/backup/ before borg create
  # after_backup:
  #   - find /tmp -name 'dump-*' -mtime +1 -delete

Wire Borgmatic to systemd timers or cron on a predictable schedule. Prefer timers with systemd for logging and on-failure behavior.

Retention and pruning

Without pruning, repositories grow until disks fail. Borgmatic’s keep_* keys map to borg prune rules. Prune with care on shared repos: use per-archive prefixes and understand that prune affects all matching archives. After policy changes, verify with borg compact when supported by your Borg version.

# Manual prune example (Borg 1.2+ style) — prefer Borgmatic in production
borg prune --list --keep-daily=7 --keep-weekly=4 --keep-monthly=6 /var/lib/borg-backup/reponame

Restore drill

At least quarterly, perform a real restore to a non-production path and validate checksums or application boot.

borg list REPO — confirm archive names and dates.
borg mount REPO::archive /mnt/restore — browse without extracting everything.
borg extract --dry-run then extract to a temp directory; compare a sample of files or re-import a test DB dump.

If extraction fails, fix keys, path, and permissions before an incident. See Backup & restore for freshness checks and SLOs & on-call if backup failures page the same team as user-visible errors.