LLI Wiki — My Digital Knowledge Base

BorgBackup to a remote SSH storage box: useful commands

Repository creation, backup, restore, prune and compact with BorgBackup on a remote storage box.

This note collects the BorgBackup commands used to back up Linux hosts and directories to a remote storage box over SSH (Hetzner Storage Box style, SSH on port 23): repository creation, backup, listing, mounting, searching, restoring, pruning and compacting.

References: Backup and restore files with Borg and Install and configure BorgBackup (Hetzner community).

In the examples, user@example.com is the storage box account and myrepo is a repository name.

Prepare SSH access

Copy your public key to the storage box, then test with SFTP/SSH (adapt the port to your provider):

ssh-copy-id -p 23 -s user@example.com
sftp -P 23 user@example.com
ssh -p 23 user@example.com

Initialise a repository and export its key

borg init --encryption=repokey ssh://user@example.com:23/./backups/myrepo
borg key export --paper ssh://user@example.com:23/./backups/myrepo

Keep the exported key (and the passphrase) outside the repository, in a password manager or on paper. Without them an encrypted repository cannot be restored.

Save the key to a file:

borg key export ssh://user@example.com:23/./backups/myrepo > encrypted-key-backup
borg key export --paper ssh://user@example.com:23/./backups/myrepo > encrypted-key-backup.txt

List and mount

borg list ssh://user@example.com:23/./backups/myrepo
borg mount ssh://user@example.com:23/./backups/myrepo mnt/borg/

Search inside an archive (dry run)

Patterns can be shell style (sh:), fnmatch (fm:) or regular expressions (re:):

borg extract --dry-run -v --list ssh://user@example.com:23/./backups/myrepo::archive-name "sh:**/report.jpg"
borg extract --dry-run -v --list ssh://user@example.com:23/./backups/myrepo::archive-name "sh:**/*.jpg"
borg extract --dry-run -v --list ssh://user@example.com:23/./backups/myrepo::archive-name "fm:*.jpg"
borg extract --dry-run -v --list ssh://user@example.com:23/./backups/myrepo::archive-name "fm:*report*"
borg extract --dry-run -v --list ssh://user@example.com:23/./backups/myrepo::archive-name "re:.*report.*"
borg extract --dry-run -v --list ssh://user@example.com:23/./backups/myrepo::archive-name "sh:home/user/**/*.sh"
borg extract --dry-run -v --list ssh://user@example.com:23/./backups/myrepo::archive-name "sh:var**/*.log"

Restore

Remove --dry-run to extract. When the remote Borg binary is not in the default path (for example on a NAS), pass --remote-path:

borg extract -v --list ssh://user@example.com:23/./backups/myrepo::archive-name "re:home\/.*app.log"
borg extract -v --list --remote-path /usr/local/bin/borg ssh://user@example.com:222/volume1/backups/myrepo::archive-name "path/to/file.jpg"

Create a backup

Mount a remote directory through SSHFS and back it up:

sshfs -o allow_other,default_permissions user@example.com:~/ mnt/website
sudo chmod 777 mnt/website

borg create --stats --progress ssh://user@example.com:23/./backups/website::website-$(date +"%Y-%m-%d-%H%M%S"-${USER}) /home/user/mnt/website/public_html/

Back up a local disk, with the passphrase supplied through the environment:

export BORG_PASSPHRASE='<PASSWORD>'
borg create --stats --progress ssh://user@example.com:23/./backups/myrepo::data-{now:%Y-%m-%d} /mnt/disk/backup_data/
borg create --stats --progress ssh://user@example.com:23/./backups/myrepo::data-$(date +"%Y-%m-%d-%H%M%S"-${USER}) /mnt/disk/backup_data/

Back up a cloud drive mounted with rclone:

rclone mount remote: mnt/cloud/ --daemon
export BORG_PASSPHRASE='<PASSWORD>'
borg create --stats --progress ssh://user@example.com:23/./backups/myrepo::cloud-$(date +"%Y-%m-%d-%H%M%S"-${USER}) ~/mnt/cloud/

Back up a whole VPS (root filesystem minus pseudo filesystems):

export BORG_PASSPHRASE='<PASSWORD>'
export REPOSITORY='ssh://user@example.com:23/./backups/myrepo'

borg create -v --stats                   \
$REPOSITORY::'myhost-{now:%Y-%m-%d}'     \
/                                        \
--exclude /dev                           \
--exclude /proc                          \
--exclude /sys                           \
--exclude /var/run                       \
--exclude /run                           \
--exclude /lost+found                    \
--exclude /mnt                           \
--exclude /var/lib/lxcfs ;

Prune

Warning: retention applies to the archive date, not to the dates of the files inside. Always run with --dry-run first.

borg prune --keep-daily=7 --keep-monthly=6 --keep-yearly=2 -v --list --dry-run ssh://user@example.com:23/./backups/myrepo
borg prune --keep-within=7d --keep-monthly=6 --keep-yearly=2 -v --list --dry-run ssh://user@example.com:23/./backups/myrepo
borg prune --keep-within=7d --keep-monthly=3 --keep-yearly=1 -v --list --dry-run ssh://user@example.com:23/./backups/myrepo

Delete archives

borg delete --progress --save-space --stats --list --info --glob-archives 'myhost*' ssh://user@example.com:23/./backups/myrepo

Compact

borg compact --progress --verbose --cleanup-commits ssh://user@example.com:23/./backups/myrepo

Information

borg info ssh://user@example.com:23/./backups/myrepo
borg version ssh://user@example.com:23/./backups/myrepo

Performance tuning

See Borg backup and compression: performance comparison. Two knobs used here:

export BORG_FILES_CACHE_TTL=50
# add to borg create:
--compression=zstd,3

Notes

Mastodon LLIMastodon SocialFosstodon