IT/Software/Backup Programs/Borg Backup
About
Borg Backup is a backup program that features compression deduplication, data compression and runs nicely over SSH.
This page is incomplete.
Setup
BorgBackup must be installed on both a client and server machine to perform remote backups. This is a good thing because it requires much much less bandwidth to perform backups and is much less latency dependent.
To setup the client, simply install borgbackup. It is in the ubuntu repositories. It's a little bit out of date in 22.04 (version 1.2.0, latest stable at time of writing is 1.2.7 and 23.04 on all have development version 2.0), but not an issue.
To setup the server, there are a few more steps.
It is recommended to create a dedicated user for borg for security. Then setup passwordless ssh login for that user using a key file with the client machine. Not necessary but makes things much easier.
For security again, add the following to the beginning of the authorized_keys entry that contains the client public key.
command="borg serve --restrict-to-repository /path/to/repo",restrict
It should look like this:
command="borg serve --restrict-to-repository /path/to/repo",restrict ssh-rsa AbCgnbiuorgurigt743GREG4r43d...B3= username@clienthostname
This forces any login using that private key to run the command borg serve, which disallows any other commands.
See the borg serve docs and the borg Hosting repositories docs for more possible configurations.
Finally, run one of the following to initialize the repository.
# On the server borg init -e=none /path/to/repo # On the client borg init -e=none ssh://username@serverhostname/path/to/repo
The repo is setup and connection is established between the server and client. Now you just need to setup a cronjob to perform a backup.
TODO: cronjob to backup
Terms
- Repository: A place backup archives can be stored. From a lowlevel perspective, it's a folder on a server. Contains one archive per backup, but not one file per archive. Understanding the structure of the repository folder is done only through borg.
- Actually each file is a chunk of deduplicated data.
- Archive: A single full backup. Can be thought of as a snapshot of a point in time. Use borg list to see archives in a repository. An archive's name is often something of the form "msgcnxfiles 2024-05-01 12:00".
- A single repo can contain archives of completely different folders. It's not a bad idea to do so either, because borg's deduplication can save space between them.
Usage
There are several important commands to understand borg. Note that all options (arguments with a - like -s or --progress) MUST come before or after positional arguments such as a repo URL, and not between.
init
This command is used to create a new borg repository. This repository can be created anywhere you have access, such as on a local mounted disk, or on a remote borg instance over ssh. The syntax is simple, but requires the -e flag for encryption settings. Choose none for no encryption, or repokey for standard SHA-256 encryption. The examples will all be no encryption as we don't require it.
# At-a-glance syntax borg init -e=none <repository-location> # To create a repository in a directory on the local machine. # The directory should already exist, or supply --make-parent-dirs to borg borg init -e=none /path/to/repo # To create a repository on a remote machine borg init -e=none ssh://username@hostname/path/to/repo # To create a repository on a remote machine relative to the user's home directory borg init -e=none ssh://user@hostname/~/Documents/repository
Creating a local repository from machine A is equivalent to creating a remote repository on machine A from machine B over ssh.
create
This command is used to create a new backup inside an existing repository. Specify the intended compression level, the target repository, and the source location. Paths are stored in the repository archive exactly as they are written in the create command. This means that the command
borg create ssh://user@hostname/~/borgrepository::backup-name ./Documents/backupfolder
will take the relative folder Documents/backupfolder and store it in the repository with the name "backup-name" under the path Documents/backupfolder. This means thought should be put into what working directory borg is run from.
# At-a-glance syntax
borg create ssh://user@hostname/~/Documents/repository::backupfolder-{now} backupfolder
# Options:
# --list Print out each file as it is processed
# --exclude Exclude a glob. Ex. Do not backup .vdi files: --exclude '*.vdi'
# -C | --compression <compalg>,<level> Compression. Possible compression algorithms are given by `borg help compression`. Essentially lz4 is high speed low compression, zstd is variable and has a different compression level based on the level you give it, zlib is medium (and also has levels), lzma is low speed high compression, auto chooses for each chunk whether to compress, obfuscate is useful when using encryption. In our experience lzma is the most efficient for our internet speeds and CPU usage.
# --progress Print progress
# --stats Print stats after running on the repository
# --paths-from-stdin Not usually useful but allows specifying specific files to backup. Can be useful with find. See borg docs for info.
# -n | --dry-run Performs all steps except for actually making the archive. Useful for testing.
# Typical backup. Prints progress information and afterwards statistics regarding how the size of your backup changed
borg create -C auto,lzma --progress --stats ssh://user@hostname/~/Documents/repository ./foldertobackup
You can fill in several placeholders in the archive name (the part after the ::) that borg will fill in.
{hostname} - the hostname of the source server
{user} - username of the source server
{now} - Current time and date
{now:%Y-%m-%dT%H:%M:%S} - Current time and date in format 2024-05-01T12:38:15
There are further options for backing up raw devices, for backing up the other direction using an sshfs, etc. See borg docs for this information.
extract
Extract extracts the contents of an archive to a target directory.
list
prune
compact
mount
serve
Creating a backup
When creating a backup we need to specify what kind of compression we want to use, where the repo we want to backup to is, and where the source files we want to backup are located.
borg create -C auto,lzma --progress repo/location/::name-of-backup location/to/be/backed/up
LZMA compression uses more CPU and less storage space.
Name of backup must be unique so using the date command instead of a static name is desirable when automating backups.
... repo/location/::`date '+%Y-%m-%d-%H.%M.%S'` location/to/be/backed/up
Backing up over SSH
In all Borg commands we can use ssh://ip.of.server/repo/location/on/server.
borg create -C auto,lzma --progress ssh://my.backup.server/repo/location/::name-of-backup location/to/be/backed/up
Viewing a repos backups
To list all the backups in a repo we can run the following:
borg list /path/to/repo
Restoring from a backup
We can mount a Borg backup as if it was a regular drive anywhere in the filesystem.
borg mount /path/to/repo/::backupName mountPoint/
We can pull files from the backup as if it were a regular drive.
To unmount the backup we can run:
umount mountpoint/
Pruning old backups
By default Borg will keep backups forever.
We can prune backups by running borg prune.
borg prune -v --list --keep-hourly=48 --keep-daily=30 --keep-monthly=12 /path/to/repo/
In this example we will assume a backup job is running hourly.
In this example we will keep 1 backup per hour for the past 48 hours, 1 backup per day for the past 30 days, and 1 backup per month for the past 12 months.
Borg will keep the most recent backup from the time period it is pruning.
In the example we would keep the backup ran at 23:00 for the past 30 days and the last backup of the month for the monthly.
Backup Scripting
Example:
#!/bin/bash
cd /location/to/be/backed/up
borg create -C auto,lzma --progress /path/to/repo/::`date '+%Y-%m-%d-%H.%M.%S'` .
borg prune -v --list --keep-hourly=48 --keep-daily=30 --keep-monthly=12 /path/to/repo/