borg
Installation
SKILL.md
Identity
- Binary:
borg(borgbackup package) - No daemon: borg runs on-demand; no persistent service for local use
- Wrapper:
borgmatic— YAML-driven automation layer over raw borg commands - Remote hosting: Borgbase (borgbase.com), rsync.net (both offer borg-specific plans)
- Key env vars:
BORG_REPO— default repository path; avoids repeating it in every commandBORG_PASSPHRASE— repository encryption passphrase; set for unattended backupsBORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=yes— required to access unencrypted repos without interactive prompt
- Install:
apt install borgbackup/dnf install borgbackup/pip install borgbackup
Key Operations
| Operation | Command |
|---|---|
| Initialize repo (repokey, passphrase in env) | borg init --encryption=repokey /path/to/repo |
| Initialize repo (keyfile, key stored locally) | borg init --encryption=keyfile /path/to/repo |
| Initialize unencrypted repo | borg init --encryption=none /path/to/repo |
| Create archive | borg create /path/to/repo::archive-name /source/path |
| Create with compression and progress | borg create --compression lz4 --progress /repo::archive-name /source |
| Create with exclusions | borg create --exclude '/home/*/.cache' /repo::archive-name /home |
| List all archives in repo | borg list /path/to/repo |
| List contents of a specific archive | borg list /path/to/repo::archive-name |
| Extract full archive | borg extract /path/to/repo::archive-name |
| Extract single file or directory | borg extract /path/to/repo::archive-name path/to/file |
| Mount repository as filesystem (FUSE) | borg mount /path/to/repo /mnt/borgmount |
| Mount single archive | borg mount /path/to/repo::archive-name /mnt/borgmount |
| Unmount | borg umount /mnt/borgmount |
| Prune old archives (keep schedule) | borg prune --keep-daily=7 --keep-weekly=4 --keep-monthly=6 /repo |
| Prune with dry run | borg prune --dry-run --keep-daily=7 --list /repo |
| Compact repo (free space after prune) | borg compact /path/to/repo |
| Check repository integrity | borg check /path/to/repo |
| Check with archive verification | borg check --archives-only /path/to/repo |
| Repository info and stats | borg info /path/to/repo |
| Archive info | borg info /path/to/repo::archive-name |
| Delete a specific archive | borg delete /path/to/repo::archive-name |
| Benchmark I/O performance | borg benchmark crud /path/to/repo /source/path |
| Transfer archives between repos | borg transfer --from-repo /old/repo /new/repo |
| Serve over SSH (remote access restriction) | borg serve --restrict-to-path /backups/client |
| Export repo key (repokey) | borg key export /path/to/repo /safe/location/key.txt |
| Export key as base64 (paste-safe) | borg key export --paper /path/to/repo |
| Import key | borg key import /path/to/repo /safe/location/key.txt |
Expected State
borg check /repoexits 0 with no errors printed- Prune running on a schedule (cron or borgmatic timer) with verified archive rotation
- Repository key and passphrase stored securely and separately (not only on the backed-up machine)
Health Checks
borg list /repo 2>&1 | head -5— lists archives; confirms repo is accessible and passphrase is correctborg check --last 1 /repo 2>&1— verifies the most recent archive is intact (faster than full check)borg info /repo 2>&1 | grep -E 'Unique|Total'— shows dedup stats and confirms repo is not corrupted
Common Failures
| Symptom | Likely cause | Check/Fix |
|---|---|---|
Repository has been manually modified |
.borg internal files were edited or corrupted |
Never touch files inside the repo dir; restore from a known-good copy |
passphrase supplied in BORG_PASSPHRASE is incorrect |
Wrong passphrase or env var not set | Verify echo $BORG_PASSPHRASE; passphrase cannot be recovered if lost |
Failed to create/acquire the lock |
Stale lock from a crashed/killed borg process | Confirm no other borg is running, then borg break-lock /repo |
Encryption method not supported |
Borg version on client is older than the repo's encryption format | Upgrade borg: pip install --upgrade borgbackup |
| Disk full error during backup | Backup partially written; repo may be in inconsistent state | Free space, then borg check /repo; compact if check passes |
Permission denied (publickey) for SSH remote |
SSH key not in authorized_keys or borg command restriction wrong | Check ~/.ssh/authorized_keys on remote; verify command= restriction points to correct borg binary |
| Archives exist but prune not reducing count | borg prune keeps archives but does not free disk space |
Run borg compact /repo after pruning; compact is always a separate step |
Unknown archive when extracting |
Archive name typo or wrong repo | Run borg list /repo to see exact names; names are case-sensitive |
Pain Points
- Passphrase loss = data loss: There is no recovery path if the passphrase is lost. Store it in a password manager or secrets vault, separate from the machine being backed up.
- Repository key must be backed up separately: For
repokeymode,borg key exportembeds the key in the repo — but if the repo is lost, the key is too. Forkeyfilemode, the key lives in~/.config/borg/keys/and must be backed up independently. Runborg key export --paper /repoto get a printable base64 representation. borg break-lockis dangerous if another borg is running: It removes the lock unconditionally. Confirm withps aux | grep borgbefore breaking; breaking a live lock causes repository corruption.- Prune and compact are separate operations:
borg prunemarks archives for deletion but does not free disk space.borg compactis the second step that actually reclaims space. Easy to forget compact and then wonder why the repo is still full. borg checkis slow on large repositories: Checking data integrity reads all chunks. Use--last Nto verify only recent archives, or--archives-onlyto skip the segment-level check during routine runs.- borgmatic simplifies all of this: A single
borgmatic.ymlreplaces manual borg invocations for init, create, prune, compact, and check. Prefer borgmatic for any recurring backup job. - Unencrypted repo requires opt-in: Accessing an unencrypted repo interactively prompts a warning. In scripts, set
BORG_UNKNOWN_UNENCRYPTED_REPO_ACCESS_IS_OK=yesto suppress the prompt.
References
See references/ for:
cheatsheet.md— task-organized command reference covering init, backup, restore, prune, compact, check, SSH, borgmatic, and key managementdocs.md— official documentation and hosting service links
Related skills