Backing up data with Borg

This note was created on 2020-11-03
This note was last edited on 2023-01-31

"borg" is a deduplicating backup program. Optionally, it supports compression and authenticated encryption.
The main goal of Borg is to provide an efficient and secure way to backup data. The data deduplication technique used makes Borg suitable for daily backups since only changes are stored. The authenticated encryption technique makes it suitable for backups to not fully trusted targets.
Source code available at GitHub: https://github.com/borgbackup/borg

=== Create a backup ===
Initialize a new NOT encrypted backup repository:
$ borg init -e none /path/to/repo

Initialize a new encrypted (with password) backup repository:
$ borg init -e keyfile /path/to/repo
Note: encrypted keys stored in "~/.config/borg/keys/"

Initialize a new encrypted (with key file) backup repository:
$ borg init -e repokey /path/to/repo

Create a backup archive with your documents:
$ borg create /path/to/repo::docs_4nov20 ~/Dokumente

Create a backup archive with your documents, but excluding "scans" subfolder:
$ borg create /path/to/repo::docs_4nov20 ~/Dokumente --exclude ~/Dokumente/scans

Create a compressed (with zstd) backup archive with your documents, show progress and statistic:
$ borg create --stats --progress --compression zstd /path/to/repo::docs_4nov20 ~/Dokumente
Following compression methods available: "none", "lz4", "zstd", "zlib", "lzma", "auto".

=== Restore a backup ===
There are two ways to restore files from a borg backup repository:
1. "borg mount" - use this if:
   - you don’t precisely know what files you want to restore
   - you don’t know which archive contains the files (in the state) you want
   - you need to look into files / directories before deciding what you want
   - you need a relatively low volume of data restored
   - you don’t care for restoring stuff that the FUSE mount is not implementing yet (like special fs flags, ACLs)
   - you have a client with good resources (RAM, CPU, temp. disk space)
   - you want to rather use some filemanager to restore (copy) files than borg extract shell commands
2. "borg extract" - use this if:
   - you precisely know what you want (repo, archive, path)
   - you need a high volume of files restored (best speed)
   - you want a as-complete-as-it-gets reproduction of file metadata (like special fs flags, ACLs)
   - you have a client with low resources (RAM, CPU, temp. disk space)

Mount an archive:
$ borg mount /path/to/repo::docs_4nov20 /path/to/mountpoint

Mount remote archive:
$ borg mount ssh://borg@example.org:2222/path/to/repo::docs_4nov20 /path/to/mountpoint

Unmount archive:
$ borg umount /path/to/mountpoint

Extract an archive:
$ borg extract /path/to/repo::docs_4nov20 path/to/extract
Note: Borg always extracts into current directory and that directory should be empty (borg does not support transforming a non-empty dir to the state as present in your backup archive).

Extract remote archive:
$ borg extract ssh://borg@example.org:2222/path/to/repo::docs_4nov20

=== Repository maintenance ===
List archives in repository:
$ borg list /path/to/repo

Display information about the specified repository:
$ borg info /path/to/repo

Display information about the specified archive (backup):
$ borg info /path/to/repo::docs_4nov20

Rename archive in repository:
$ borg rename /path/to/repo::archivename newname

Delete archive from repository:
$ borg delete /path/to/repo::docs_4nov20

Find differences (file contents, user/group/mode) between archives:
$ borg diff testrepo::archive1 archive2

Create a tarball from an archive:
$ borg export-tar /path/to/repo::docs_4nov20 docs_4nov20.tar.gz

Verify the consistency of a repository:
$ borg check --repository-only -v /path/to/repo

Verify the consistency of all archives:
$ borg check --archives-only -v /path/to/repo

Attempt to repair any inconsistencies found:
$ borg check --repair -v /path/to/repo

Upgrade local Borg repository to newer version:
$ borg upgrade -v /path/to/repo

=== Key maintenance ===
If repository encryption is used, the repository is inaccessible without the key. This command allows to backup this essential key. Note that the backup produced does not include the passphrase itself (i.e. the exported key stays encrypted). In order to regain access to a repository, one needs both the exported key and the original passphrase.
There are two backup formats. The normal backup format is suitable for digital storage as a file. The "--paper" backup format is optimized for printing and typing in while importing, with per line checks to reduce problems with manual input.
For repositories using keyfile encryption the key is saved locally on the system that is capable of doing backups. To guard against loss of this key, the key needs to be backed up independently of the main data backup.
For repositories using the repokey encryption the key is saved in the repository in the config file. A backup is thus not strictly needed, but guards against the repository becoming inaccessible if the file is damaged for some reason.

Export a key:
$ borg key export /path/to/repo /path/to/key

Import a key:
$ borg key import /path/to/repo /path/to/key

Change a passphrase for key:
$ borg key change-passphrase /path/to/repo
Please note that this command only changes the passphrase, but not any secret protected by it.

=== Read more ===
Documentation available on the official website: https://borgbackup.readthedocs.io/en/stable.