Borg - Deduplicating Archiver

Description from the Borg Documentation website:

BorgBackup (short: Borg) is a deduplicating backup program. Optionally, it supports compression and authenticated encryption.

Borg is an program under development and the authors have made it clear that there may be problems handling archives created with different major versions. This should only be able to be an issue when creating new backups, restoring them should always work. Using stable versions you should be save. If you want guaranteed backward and forward compatibility, you may want to get a look att Attic. Attic is the project Borg was forked from. They are very similar, but Borg has more options and much faster development pase.


Follow the instructions from the Documentation. I would suggest not installing the git (developer) version.

Using Borg

Initializing a repository

Before a backup can be made a repository has to be initialized. (Be advised that encryption has to be enabled at initialization to be used)

To use borg on a remote server, borg and ssh have to be installed on both the remote server and the host you want to backup.

$ borg init

Repository encryption

If you want your backups to be encrypted, you have to enable encryption at initialization. We can enable encryption with --encryption=keyfile. The default keyfile location is ~/.borg/keys. With the keyword BORG_PASSPHRASE you can define the password to be used. This is useful when borg is automated.

$ BORG_PASSPHRASE=MyPassword1234 borg init --encryption=keyfile

Creating a backup

Now we can backup the /home directory into an archive called BackupName, excluding /home/*/.cache\ :

$ borg create /home -e /home/*/.cache

Now we will create another archive, called AnotherBackup. The --stats or -s option causes Borg to output statistics about the newly created archive such as the amount of unique data (not shared with other archives).

With -C you can define a compression method and level. I mostly use lz4.

$ borg create -C lz4 --stats /home -e home/*/.cache

Prune archives

If we do not want to keep all created backups, we can prune the repository. Use --keep- and then the time you want to select (hourly, daily, weekly, monthly or yearly)

In the example we want to keep 4 hourly and 7 daily backups.

$ borg prune --keep-hourly=4 --keep-daily=7

Restore a backup

To restore a file, you can mount specific archives or entire repositories. This is done with help of FUSE.

Mounting an Repository

$ borg mount -v /home/Mountpoint

Mounting an Archive

$ borg mount -v /home/Mountpoint

Automating my backup


For convenience I created a special user on the storage system and enabled passwordless login with keyfile


My backupscript

echo "***** setting variables *****"
EXCLUDE='-e /home/*/.cache/'

#echo "***** init *****"
## (this section was uncommented at the fist run)
## Create Repository:
#BORG_PASSPHRASE=$PASSWORD borg init -v --encryption=keyfile $REPOSITORY

echo "***** list *****"

echo "***** create *****"
# Create a new backup
BORG_PASSPHRASE=$PASSWORD borg create -C lz4 -v -s $REPOSITORY::User_Computer_A-`date +%Y-%m-%d__%H:%M` $SOURCE $EXCLUDE

echo "***** prune *****"
# Use the `prune` subcommand to maintain 4 hourly, 7 daily, 4 weekly,
# 6 monthly and 2 yearly archives.
BORG_PASSPHRASE=$PASSWORD borg prune -v -s $REPOSITORY --keep-hourly=4 --keep-daily=7 --keep-weekly=4 --keep-monthly=6 --keep-yearly=2

echo "***** list *****"

echo "***** unsetting variables *****"
unset SOURCE

# echo "***** mount repository *****"
# BORG_PASSPHRASE=$PASSWORD $Borg mount -v $REPOSITORY /home/nils/borg

Last words

These are the main concepts of using Borg. You should play around with the prune, compression and encryption options, before automating your backups. If you get stuck you allways can use borg’s excellent build in help function (for example borg init -h if you want to know all the specific options you can use att inititialisation) or take a look at the Documentation.