Unimus Backup Exporter

Tomas Kirnak -

Unimus allows you to backup all of your device configurations into a convenient and accessible platform. However, you may want to keep copies of your backups stored offsite in the case of a catastrophic failure that removes your ability to use your Unimus server.

To solve this problem, we created the Unimus Backup Exporter. This script will allow you to download all backups from your Unimus server. Once you download them, you may want to export them offsite, for example to AWS S3 using the AWS CLI, or possibly to a local NFS share. We provide built-in GIT functionality in the Exporter script as another alternative solution if desired.

Let us show you how you can use the Exporter in a few steps.

Step 1 - Preparing Unimus and creating an API token

The First step we need to take is to create an API token for the Exporter script. After you log into your Unimus system, you will find a User management section on the sidebar. After opening this section, at the bottom of the page, you will see API tokens. Click add to create a new token, and keep this page open for a later step.

Step 2 - Downloading the Unimus Backup Exporter

Navigate to the directory where you would like to install the script from your command line, and we can use wget to download it. Then we will need to unzip the script and make it executable. For example:

[~] $ mkdir unimus-exporter
[~] $ cd unimus-backups
[~/unimus-exporter] $ wget https://github.com/netcore-jsa/unimus-backup-exporter/releases/latest/download/unimus-backup-exporter.zip
[~/unimus-exporter] $ unzip -x unimus-backup-exporter.zip
[~/unimus-exporter] $ chmod +x unimus-backup-exporter.sh

Step 3 - Setting up your config file.

Now that we have our script downloaded, we need to configure an env file to tell it how to access our server. We will do this in the following two parts.

Part 1 - Local backups

Provided is a sample env file called unimus-backup-exporter.env. In this file, you will find examples of all options you can use to configure your script.

The following settings will export all of your backups to your local filesystem in a backups directory in the same directory as the script. In Step 1, we kept open the page with the Unimus API key. We will use that here in the API key section. Please note, everything should be in double quotes. Any options not being used can be removed or commented out with a preceding #.

unimus_server_address="http://foo.bar:8085"
unimus_api_key="insert api key here"
backup_type="latest"
export_type="fs"

backup_type has two options:

  • latest - pulls the most recent backups from Unimus
  • all - pulls all backups from Unimus

Any options not used can be removed or commented out with a preceding #, as shown below. 

#git_username=”foo”

After running the script, you will see all of your backups in the backups directory, listed by IP address and the Unimus device ID. 

[~/unimus-exporter/backups] $ ls -l
total 2
drwxr-xr-x 1 user group 4096 Jan 18 09:38 '192.168.4.1 - 6'
drwxr-xr-x 1 user group 4096 Jan 13 23:47 '192.168.3.1 - 2'
[~/unimus-exporter/backups] $

If you only want to export to your local file system, you can skip part 2 of this step and go to Step 4.

Part 2 - Pushing to Git

Some users will want to have the option to move the backups offsite. We have included GIT functionality into the script to make this easier. Inside of your unimus-backup-exporter.env file, you need to add some additional settings. These options are going to be dependent on your GIT server / repo. The most common options are going to be the following.

git_username="foo"
git_email="foo@bar.org"
git_server_protocal="http"
git_server_address="192.168.4.5"
git_port="22"
git_repo_name="User/unimus-backup-exporter"
git_branch="master"

You may also need to set the git_password option if you use password authentication.

git_password="password"

git_server_protocal has three options:

  • http - pushes to GIT using HTTP
  • https - pushes to GIT using HTTPS
  • ssh - pushes to git using SSH

Please note that you must add the private SSH key to use to authenticate to the server before running the script if you are using SSH key authentication.

Once you have these set correctly, we are ready to run the script!

Step 4 - Running the Exporter

Now that you have a working configuration file, we can execute the script by running the following command in the script directory. 

[~/unimus-exporter] $ ./unimus-backup-exporter.sh
Getting device data
Getting Device Information
Exporting latest backups
2 backups exported
Export successful
Script finished
[~/unimus-exporter] $

After running the script, you will see the following directory structure in the backups directory. 

[~/unimus-exporter/backups] $ ls -l
total 2
drwxr-xr-x 1 user group 4096 Jan 18 09:38 '192.168.4.1 - 6'
drwxr-xr-x 1 user group 4096 Jan 13 23:47 '192.168.3.1 - 2'
[~/unimus-exporter/backups] $

If you are exporting to Git, you will see something similar to the following output.

[~/unimus-exporter] $ ./unimus-backup-exporter.sh
Getting device data
Getting Device Information
Exporting latest backups
2 backups exported
Export successful
Pushing to git
Initialized empty Git repository in /home/user/unimus-exporter/backups/.git/
[master (root-commit) 5fabcf7] Initial Commit
 2 files changed, 878 insertions(+)
 create mode 100644 192.168.3.1 - 2/Backup 192.168.3.1 2021-02-16-03:00:43-EST 2.txt
 create mode 100644 192.168.4.1 - 6/Backup 192.168.4.1 2021-11-01-03:00:27-EDT 6.txt
Enumerating objects: 6, done.
Counting objects: 100% (6/6), done.
Delta compression using up to 32 threads
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 7.61 KiB | 3.80 MiB/s, done.
Total 6 (delta 0), reused 0 (delta 0)
remote:
remote: The private project user/test_unimus_git was successfully created.
remote:
To ssh://192.168.4.5/user/test_unimus_git.git
 * [new branch]      master -> master
Everything up-to-date
Push successful
Script finished
[~/unimus-exporter] $

If using GitHub or GitLab, you should be able to see the backups in the web interface.

Step 5 - Automating the exporter

Typically, you will want to run the Exporter script periodically to ensure you have the latest backups. To do this, you can schedule a cron job. Given the script shouldn’t need any elevated privileges, adding the following line to your user’s crontab -e will set up the script to run every night at 3 AM. You should schedule the script to run after Unimus is done backing up your devices.

0 3 * * * /path-to-script/unimus-backup-exporter.sh

A log is generated in the script’s directory. Your output should look like this.

Log File - 2021-11-04 21:46:16
2021-11-04 21:46:16 Getting device data
2021-11-04 21:46:16 Getting Device Information
2021-11-04 21:46:17 Exporting latest backups
2021-11-04 21:46:17 20 backups exported
2021-11-04 21:46:17 Export successful
2021-11-04 21:46:17 Pushing to git
2021-11-04 21:46:19 Push successful
2021-11-04 21:46:19 Script finished

You can use the log to monitor results and create alarms and notifications if the export fails for any reason. If the script fails to finish, you will receive an error message. 

Log File - 2021-11-04 21:49:40
ERROR: 2021-11-04 21:50:01 Unable to connect to unimus server

That’s all that is needed to set up our exporter and automate it to run daily.