BorgBackup

Borg is a deduplicating, compressing, authenticated-encryption backup program. Repositories hold many archives, and each archive is a point-in-time backup. This sheet uses the Borg 1.4 syntax (REPO::ARCHIVE), which is what most distributions and the borgmatic Docker image ship. Borg 2 is still beta and changes the syntax (see the end of this sheet). Day-to-day scheduling is easier with borgmatic.

Documentation: Borg docs · Quick start · Usage

Verification: The Borg 2 renames and its beta status were checked against the Borg changelog. The Borg 1.4 command syntax below is standard and long-stable but was not re-checked against the docs this session, and neither was the authorized_keys form. No command was executed.

See also: Backup Strategy · borgmatic · restic · rsync · OpenSSH Cheat-Sheet · Linux

Environment Variables #

Repository forms: /path/to/repo, ssh://<USER>@<HOST>:<PORT>/./path/to/repo (relative to the home), ssh://<USER>@<HOST>/path/to/repo (absolute), or the older <USER>@<HOST>:path.

Create a Repository #

With repokey, losing the passphrase loses the data, and anybody with repo write access and the passphrase can read it. Export the key anyway.

Create Backups #

Archive name placeholders: {hostname}, {user}, {now}, {utcnow}, {fqdn}. Example:

export BORG_REPO=ssh://<USER>@<HOST>/./borg-repo
export BORG_PASSCOMMAND='cat /etc/borg/passphrase'

borg create --stats --compression auto,zstd \
  --exclude-caches --exclude '/home/*/.cache' \
  '::{hostname}-{now:%Y-%m-%dT%H:%M:%S}' /etc /home /srv

With BORG_REPO set, ::NAME refers to that repo.

Prune and Compact #

prune removes archives per a retention policy. In Borg 1.2 and later the space is only returned by compact.

Other --keep-* options: --keep-within 3d, --keep-last N, --keep-hourly N.

Inspect, Verify, Browse #

Restore #

extract writes into the current directory, so cd to the target first. Paths are stored without the leading slash.

mkdir /tmp/restore && cd /tmp/restore
borg extract --list <REPO>::<NAME> home/<USER>/documents
borg extract --dry-run --list <REPO>::<NAME>          # preview a full restore
borg extract --strip-components 2 <REPO>::<NAME> srv/app/data
borg export-tar <REPO>::<NAME> - | tar -tf -          # stream an archive as tar

Quick verification after a restore: compare with diff -r /tmp/restore/home/<USER>/documents /home/<USER>/documents.

Remote Repository over SSH #

• Install the same major Borg version on both ends.
• Use a dedicated SSH key and restrict it on the server in ~/.ssh/authorized_keys:

command="borg serve --restrict-to-path /srv/borg/<HOST> --append-only",restrict ssh-ed25519 AAAA... backup@<HOST>

--append-only stops a compromised client from deleting history. Run prune and compact from a trusted admin machine with a different key. Without --append-only, a client can destroy its own backups.

Hook-style Wrapper Script #

For anything beyond a one-off, use borgmatic. A minimal script if you want plain Borg:

#!/usr/bin/env bash
set -euo pipefail
export BORG_REPO=ssh://<USER>@<HOST>/./borg-repo
export BORG_PASSCOMMAND='cat /etc/borg/passphrase'

borg create --stats --compression auto,zstd '::{hostname}-{now:%Y-%m-%dT%H:%M:%S}' /etc /srv
borg prune --list --glob-archives '{hostname}-*' --keep-daily 7 --keep-weekly 4 --keep-monthly 6
borg compact
borg check --repository-only
curl -fsS -m 10 --retry 5 https://hc-ping.com/<UUID> >/dev/null

Borg 2 Differences (beta at the time of writing) #

Borg 2 is beta and its documentation says not to use it for production. Borg 1.4 repositories are not compatible and need borg transfer.