Backups with Borg / BorgBase

Backups with Borg / BorgBase

BorgBackup (Borg) is a deduplicating, compressing, authenticated-encryption backup program. Its killer feature is content-defined chunking: identical data is stored once across all backups, so daily snapshots cost only the changed blocks. A month of dailies can take barely more space than one.

BorgBase is a hosted, append-only Borg repository — a convenient off-site target so a compromised server can’t delete its own backups.

Tip

A backup you have never restored is a hypothesis, not a backup. Schedule restore drills (below) the same way you schedule the backups themselves.

Why Borg

• Deduplication across the whole repository — only new chunks are stored.
• Authenticated encryption (client-side) — the server, including BorgBase, never sees plaintext or the encryption key.
• Compression (zstd, lz4) on top of dedup.
• Append-only mode — protects backups from a compromised client deleting history.

Initializing an encrypted repository

Choose repokey (key stored in the repo, protected by your passphrase) or keyfile (key stored only on the client). Either way, back up the key and passphrase separately — lose them and the backups are unrecoverable by design.

# Local or SSH target
borg init --encryption=repokey-blake2 user@host:/path/to/repo

# Export and safely store the key material (do this once, keep offline)
borg key export user@host:/path/to/repo borg-key.txt

Creating backups and retention

Create a named archive, then prune old archives on a retention schedule so the repo doesn’t grow forever:

# Create a timestamped archive of /etc and /srv
borg create --stats --compression zstd \
  user@host:/path/to/repo::'{hostname}-{now}' \
  /etc /srv

# Keep 7 daily, 4 weekly, 6 monthly; prune the rest
borg prune --list user@host:/path/to/repo \
  --keep-daily=7 --keep-weekly=4 --keep-monthly=6

# Reclaim space after pruning (Borg 2.x)
borg compact user@host:/path/to/repo

Borgmatic wraps these steps in a single YAML config plus a systemd timer — recommended over hand-written cron for anything real.

BorgBase as an off-site target

BorgBase gives you a Borg-native SSH endpoint with append-only access keys:

1. Create a repository in BorgBase and add your server’s SSH public key as an append-only key.
2. borg init --encryption=repokey-blake2 <your-repo>@<your-repo>.repo.borgbase.com:repo
3. Run borg create/borg prune as above against that URL.

Because the key is append-only, a compromised server can write new backups but cannot delete or overwrite old ones — pruning is performed by BorgBase on a schedule you set, not by the client. This defeats ransomware that tries to wipe your backups.

Restore drills

borg list user@host:/path/to/repo                 # list archives
borg list user@host:/path/to/repo::archive-name   # list files in one archive

# Extract into the current directory
borg extract user@host:/path/to/repo::archive-name etc/

# Or mount the archive and browse it like a filesystem
borg mount user@host:/path/to/repo::archive-name /mnt/restore

Test a real restore to a scratch location on a fixed cadence (monthly is a good default). Verify the data is complete and that you actually have the passphrase/key needed — the worst time to discover a missing key is during a real incident. Fold this into your Disaster Recovery plan.

The 3-2-1 rule

Keep 3 copies of important data, on 2 different media, with 1 off-site. Borg on local disk + BorgBase off-site satisfies this for most self-hosters.

Related

• Backups with Restic — alternative with first-class S3/object-storage backends
• Disaster Recovery — the plan that backups feed into
• Authentik Backup — backing up your identity provider specifically
• Linux Server Storage — where backups live and how to size it