Borgup: Convenience wrapper for borg backups

Borgup is a series of short, opinionated Bash scripts that simplify the task of using Borg to back up files.

Simplify how? Compare the following Borgup invocation:

$ borgup-backup home.dir rsync-net.repo

to the equivalent command line required when using plain Borg:

$ BORG_KEYS_DIR=keys.borg borg create --remote-path borg1 \
 --verbose --progress --stats --compression zstd,10 \
 --checkpoint-interval 600 --exclude-from /tmp/excluded-files.list \
 ssh://me@z2.rsync.net/~/backup/home/myhost::myhost-20230621-1687365006 /home

Key design features of Borgup

• Configuration files: Borgup keeps all configuration data in key-value files.
• Reuse of configuration: The same source directory can be backed up in multiple repositories. The same repository can be used to back up multiple source directories.
• Comprehensibility: Borgup is a set of Bash scripts that use standard Borg commands and options. Its operations can be easily inspected and understood by Borg users.
• Clear key management: All keys needed to recover a backup are stored, in a secure way, alongside the configuration files, simplifying their management and backup.

Quick start guide

1. Create a directory where to store the configuration files and the keys:

$ mkdir ~/backup
$ cd ~/backup

2. Add configuration files for a source directory and for a repository:

$ echo "SOURCE_DIR=/etc" > etc.dir # Absolute path of the directory to back up
$ echo "BACKUP_ROOT=ssh://me@server.example.net/srv/bk" > server.repo

3. Initialize the Borg repository:

$ borgup-init etc.dir server.repo
TODO: output of borgup-init

Notice that the generate Borg key has been stored in the same directory as the configuration files:

$ tree
.
├── borg.keys
│  └── backup_server__etc_myhost
├── etc.dir
└── server.dir

4. Create the first archive:

$ borgup-backup etc.dir server.repo
TODO: output of borgup-backup

5. Bonus: mount the remote archive locally:

$ mkdir /tmp/etc-old/
$ borgup-mount etc.dir server.repo --at-date=2022年08月12日 /tmp/etc-old/
TODO: output of borgup-mount

Borgup commands

• borgup-init: Initializes a Borg repository and encryption keys for a specific source directory.

• borgup-backup: Backs up a source directory into a repository, creating a new Borg archive.

• borgup-mount: Mount a (possibly remote) archive onto a local directory.

• borgup-borg: Generic wrapper to run any valid Borg command, but using the settings gathered from the directory and repository configuration files.

borgup-borg: Generic Borg wrapper

borgup-borg is used to run any valid Borg command. This wrapper adds to the passed Borg command the right options for the directory and repository specified in the configuration files. In addition, all placeholders in the form @VARIABLE@ are replaced with the value of that variable.

The following example show the use of check to verify the consistency of all archives created in August 2020 in the repository described in r.repo for the source directory specified in d.dir:

$ borgup-borg d.dir r.repo check -a '*-202208*' @REPO_DIR@

Design

Configuration in files

In Borgup, information about the source directories and the repositories is read from key-value configuration files.

$ cat home.dir
SOURCE_DIR=$HOME
KIND=home
EXCLUDE_FILES="
.cache
Photos
"

$ cat rsync-net.repo
BACKUP_ROOT=ssh://me@e2.rsync.net/~/backup/home

$ cat usb.repo
BACKUP_ROOT=/media/myuser/backup-disk

This allows mixing and matching source directories and repositories at one's pleasure.

Key management

By default Borg stores the keys it needs to access and decrypt the repositories in ~/.config/borg/keys. Many users do not realize TODO

TODO: What is the path on the remote host?

Usage examples

Backing up a directory onto multiple repositores:

$ cd ~/Backup/
$ borgup-backup home.dir rsync-net.repo
TODO
$ borgup-backup home.dir usb-disk.repo
TODO

Mounting an archive from a remote repository as a local directory:

$ borgup-mount home.dir rsync-net.repo --at-date=2022年08月12日 /tmp/home-old/
TODO

Why Borgup? Why aren't Borg and Borgmatic enough?

Borg is a great backup tool, but it is also complex to use because it does not (by design) use any kind of configuration file: all configuration must be specified as command line options.

Because typing so many options is not feasible, users often rely on scrappy, ad-hoc scripts, or use more complex, compliled frontends like Borgmatic, that make it hard to understand how Borg is used.

Also, by default Borg store the encryption keys in ~/.config/borg/keys, a directory away from the attention of user and rarely backed up. Many users realize that they did not have a copy of those keys only once they try to retrieve some of their backed up data.

Borgup is a set of hackable short Bash scripts, where all the settings are kept in small configuration files, and that simplifies the management of configuration files and encryption keys.

Alternatives

• borgmatic: https://torsion.org/borgmatic/

Authors

• Gioele Barabucci https://gioele.io

License

This is free software released under the terms of the ISC license.

See the LICENCE.txt file for more details.