Borgbackup - friends call him Borg - is an extremely powerful and versatile backup program.
Borg can be used in two modes:
- local backup
- remote backup over SSH
You’re probably here because you want to backup data to another server - either in your LAN or over the Internet using SSH. In this scenario Borg must be installed on the other end, which can be whatever OS supported by Borg.
The goal of this guide is to describe a simple Borg setup in remote mode using the borgbackup plugin. The official Borg documentation will help if you need more information and is the source for lot of the content in this guide.
Exposing your server’s SSH port over the Internet can be extremely dangerous if not done correctly. This guide will not cover this aspect, only proceed with this if you know what you are doing.
You need to know how to setup SSH authentication and test it first to verify this part is correct.
You should know some terms before working with Borg. Don’t worry, it’s only the very basics to go through this guide.
- repository: a directory where your backups will go. By default Borg creates this folder under the user’s home. A server can host infinite repositories. They are independent from each other, you could use one for each user or server.
- archive: is the result of a single backup. An archive stores a snapshot of the data of the files “inside” it.
- client: the actual OMV server you want to backup.
- server: your backup destination server. Just install Borg and set up SSH properly.
- passphrase: the password used to encrypt your key that encrypts your data.
- Borg installed on your server, Borg plugin installed on your OMV client
- client-server connection with SSH key authentication
Borg (client) needs to know what SSH private key should be used when connecting to the server. Locate your key and execute
NOTE: This environment variable only applies to Borg, but if you want to do the same for standard SSH connections, create this file nano ~/.ssh/config and enter IdentityFile /etc/ssh/my_secure_server_key
You can try the Borg connection to your server by running a command that would check a repo
- omv is the user on the backup server
- acme.com is the server address
- 7290 is the SSH port - ALWAYS use a custom port!
- /./ tells Borg it’s a relative path inside the user’s home folder.
- check is the backup repository - it does not exist but it’s needed to validate the SSH connection.
You should get a message like:
Repository ssh://firstname.lastname@example.org:7290/check does not exist.
If this is the case the configuration is ready for Borg, otherwise there’s something wrong with your SSH/key configuration.
Add a new repository by browsing to Services > BorgBackup > Repos > Add
What you need to know:
- Name: the repo identifier in OMV. No spaces are allowed
- Type: Local or Remote - the latter since we’re backing up on another server
- Remote path: the same command you typed above
- To create a repository under your user’s home folder, use ssh://email@example.com:7290/./mybackup. To create a repository somewhere else, use the absolute path like ssh://firstname.lastname@example.org:7290/volume1/backups/mybackup.
- NOTE: If you receive an error message about incorrect permissions, try without ssh://
- Either way, the destination folder must not exist, Borg will create it upon initialization
- More information about repositories paths can be found here
- Passphrase: it is used for encryption. Use a password generator for this one, it should be very strong and stored in a safe place.
- Encryption: enable this, you’ll want to use it
- Skip init: if you were to add an already initialized repository
Click Save and Borg will initialize your first repository with the provided settings.
NOTE: If the plugin shows an error there is an issue with the remote path or you haven't configured your SSH key correctly.
The key for this repo will be stored in /root/.config/borg/keys/. Make a copy and store it safely! It's the only way to access your backup.
Once initialization is completed, you will see the repo and a lot of options.
Here’s a brief description:
- Check: verifies the consistency of a repository, archives or the actual data
- Export: exports the repository config so it can be used on another Borg client to mount/restore/continue a backup
- Extract: restore a backup on OMV
- List: lists all archives in a repository
- Mount: mounts a backup in your local filesystem with minimal network usage, only using the metadata. Files will be transferred only when they are opened or copied.
To know more about these options, the Borg official documentation can be found here.
It’s finally time to create an archive to actually tell Borg what to backup.
Navigate to Archives tab and click Add:
What you need to know:
- Name/Prefix: the archive name. No spaces are allowed
- Repo: the repository we configured a minute ago
- Compression Type: lz4 is the default compression method, but you might consider zstd. More info about compression can be found here
- Compression ratio: applies to the type of compression you have chosen, more info at the same link above
- One Filesystem: stay in the same file system and do not store mount points of other file systems
- No atime: don’t store atime (last access time)
- Includes: paths of the folders you want to backup. In this example I’ve added my UnionFS path.
- Excludes: paths of the file/folders you want to exclude
- Hourly, Daily, Weekly, Monthly, Yearly: How many archives you want to keep. They depend on your needs, more info can be found here. It also doubles down as scheduling.
- Rate Limit: in case you want to limit the upload speed.
Click Save and your backup is ready to go. Click Run to start it immediatelly.
NOTE Every archive/backup execution is scheduled as frequently as the first non-zero retention policy. In this example it will run every day because Hourly is set to 0.
This setting is baked into the plugin and not in Borg, which is not scheduled by design.
The first backup will take a long time: this is expected, but the following ones will be much quicker.
If the SSH connection is being dropped during the initial backup, it is likely that your client is compressing a lot of data and the receiving server is closing the connection due to inactivity.
You can increase the timeout on your receiving server. Edit /etc/ssh/sshd_config and add the following
This will increase the maximum timeout to 30 minutes. It should not be needed after the first backup.
You have two options to restore files: restore essentially restores everything to a defined path, while mount is great to browse your backup and pick a particular folder or file.
Thanks to ryecoaaron for making this plugin and answering my questions.