Table of Contents
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
Restoring Backups - extract borg backup
The first step in restoring your data is extracting it from your borg archive that the backup script created for you. Let’s go through that process.
Reminder: Run your entire restore process as ROOT!
First, why are we extracting the data locally instead of pulling it directly from our remote server? Well, a few reasons:
- Downloading it locally does not require any additional programs to be installed. The restore script uses tar which is installed on pretty much every Linux distro by default. Restoring directly from a remote repo would require something like rsync which is an excellent tool but I wanted to focus on staying as POSIX-compliant as possible. If you’d like to see rsync support, please file an issue requesting it and I’ll add it based on interest.
- Restoring data doesn’t always go smoothly the first time around. By having a local copy, you do not have to re-run lengthy and potentially costly downloads multiple times. Remember, many backup storage services charge you for downloading your data!
- Of course, the downside is that you require twice the storage space available - space for the downloaded backup and space to copy it to mailcow.
Set up borg
Obviously, you need to have borg installed and functional before going any further. To access your remote borg repository, you’ll probably also need your SSH key and likely your borg repository key (unless you set up a repokey type repository in which case your key is stored in the repo itself and you only need your password). Once you have those things, you need to set some environment variables to get borg to work.
If you have access to the backup.details file used by backup.sh from your previous set up then this step is really easy. Just ‘source’ the file to import the environment variables into your working environment. I am assuming your borg set up is the same as your old system and you are already running as root.
# assuming the old backup.details file is in your home directory
source /root/backup.details
If you don’t have that file, we can still do things manually.
# assuming your borg base directory is /var/borgbackup
export BORG_BASE_DIR='/var/borgbackup'
export BORG_REMOTE_PATH=borg1
export BORG_RSH='ssh -i /path/to/your/ssh.key'
export BORG_REPO='user@remote.server.tld:repoName'
export BORG_PASSPHRASE='repository_password'
# if you are using a keyfile style repo, export this variable also
export BORG_KEY_FILE='/path/to/borg/key.file'
Extract backup archive
Let’s see what our options are first – get a list of available archives in our borg repository:
borg list
If you get any errors running this command, double-check your environment variables in the previous step and reset them as necessary.
Each of your archives should be listed in the first column with their names being numerical date stamps. Review your options and choose the one you want to restore. Remember that borg extracts archives to the current directory, so we’ll make a directory first and switch to it.
# create directory for our files and switch to it
mkdir /var/mcRestore
cd /var/mcRestore
# extract borg archive from repository
borg extract --list ::archiveName
I’m using the --list parameter to output each file name to the console. This is optional but I like seeing what’s going on.
N.B. If you do not run as root, borg cannot restore file permissions and ownership! If you run as a regular user, you’ll notice that all your files are restored with that user as the owner. This will not work since mailcow requires particular files to have particular owners within its various containers.
Bottom line: RUN BORG EXTRACT AS ROOT!
Assuming the extraction is successful, you’re ready for the next step.