12.3. Borgbackup tutorial


12.3.1. Get help

borg help

Borg official documentation

12.3.2. How to install

The easiest way to install the stable version of Borg is by using the APT package manager method, so you stick to the stable package for your distribution, in our case we use Debian.

# apt install borgbackup

12.3.3. Useful command list to use remotely

Initiate remote repository. This is somehow really similar of doing a “git init”. Borg will create the necessary files and structure, for storing your future backups.

$ mkdir -p /path/to/repo
$ borg init -e=none usr@srv:/path/to/repo
$ borg init --encryption=repokey usr@srv:/path/to/repo

Send data from your computer to a specif repository

$ borg create --stats --progress --compression lz4 usr@dest:/path/to/repo::name /path/from/origin

List available backups of specific borg repository (a folder):

borg list usr@dest:/path/to/repo
borg list backups@sam.gnunet.org:/home/backups/$folder

Extract the content to your computer of specific backup:

borg extract --progress  backups@sam.gnunet.org:/home/backups/weblate::2024-04-09T02:00:00

List the content of a specific backup-name

borg list usr@dest:/path/to/repo::backup-name

Find spefic stuff within a backup without the need of downloading and extracting it

borg list usr@dest:/path/to/repo::backup-name | grep $keyword

12.3.4. Restoring data


Note: For restoring, it is always better to do it from origin, and not in the backup server itself. Please remember this.

$ mkdir $folder
$ cd $folder
$ # Find the concrete backup to restore:
$ borg list usr@dest:/path/repo
$ # Once you have the "name" of the repo
$ # You can check the content, to makes sure it has what you are looking for
$ borg list usr@dest::/remote/path/backupX
$ # Fully extract the backup to destination folder
$ borg extract usr@dest::/remote/path/backupX
$ # Just extract "some" data
$ borg extract usr@dest::/remote/path/backupX path/to/extract/only
$ borg extract --progress backups@sam.gnunet.org:/home/backups/weblate::2023-11-13T11:29:30

12.3.5. Free remote disk space

Be careful, prune is a potentially dangerous command, it will remove backup archives.

The default of prune is to apply to all archives in the repository unless you restrict its operation to a subset of the archives using –prefix. When using –prefix, be careful to choose a good prefix - e.g. do not use a prefix “foo” if you do not also want to match “foobar”.

It is strongly recommended to always run prune -v –list –dry-run before, so you will see what it would do without it actually doing anything.


# Keep 7 end of day and 4 additional end of week archives.

borg prune -v –list –dry-run –keep-daily=7 –keep-weekly=4 /path/to/repo

# Real (without dry-run, this will remove data)

borg prune -v –list –keep-daily=7 –keep-weekly=4 /path/to/repo

12.3.6. Full example of how to apply borgbackup in a server, to backup specific data

You will find quite a few useful scripts to apply borgbackup in the migration-exercise-stable.git private repository, and within under the path /taler.net/borgbackup.

The best way and most secure way to use borg is with systemd timers, but it can also be used with a cronjob as usual. Locations that we use:

Local folder to gather your files temporarily: /home/user/borgbackup

  • borgbackup.sh # to send the data, to the borgbackup server

  • data.sh # to create .tar files, or dump databases

  • borgbackup.service # to execute the borgbackup.sh file

  • borgbackup.timer # to execute the .service file periodically

Once you have tested that the data.sh, and the borgbackup.sh are working properly, copy them to /opt/bin/borgbackup.

For the borgbackup.service and borgbackup.timer files, copy them to: /etc/systemd/system/

$ cp borgbackup.service borgbackup.timer /etc/systemd/system/
$ systemctl daemon-reload
$ # Check before the .service file works okay
$ systemctl start borgbackup.service
$ # Use journalctl -u borgbackup to fix any issue
$ systemctl enable --now borgbackup.timer


Once you have finished applying borg in server,it is mandatory in the following days, to check that the system is working properly. Just do a “borg list usr@dest::/remote/path/backupX”, to check if a few backups of the previous days, are listed.