Database Backup

TunnelHound uses a built-in PostgreSQL database server to store configuration data. This database contains information necessary to form secure connections between the computers in your network. This database needs to be backed up periodically, in case your appliance data is lost. It’s best to store this data encrypted and on a trustworthy medium.

Note: If you are using an older version of TunnelHound from before the name change, then replace ‘tunnelhound’ with ‘wirehound’ in all the commands below.

Backing up the database

In order to backup your database, you will need SSH access into your appliance. Run the tunnelhound-backup command on your appliance.

For a cloud appliance:

ssh vpn@<you.ip.or.domain.name> -C tunnelhound-backup > tunnelhound.backup

If you need to use a particular SSH private key to backup, pass that in using the -i flag.

ssh -i <path to key.pem> vpn@<your.ip.or.domain.name> -C tunnelhound-backup > tunnelhound.backup

For a Docker appliance:

docker exec -it <name-of-tunnelhound-container> tunnelhound-backup > tunnelhound.backup

By default, the dump will occur unencrypted which means that the dump file you receive can be read by anyone (although the transfer is protected by SSH). It is highly recommended that you store your dump encrypted. See the encryption section for more

Restoration

To restore a TunnelHound instance, run the following command (include the -i option if you need another SSH identity). Note that this will erase any information you may already have on the target Tunnelhound instance, without prompting you.

For a cloud appliance:

cat tunnelhound.backup | ssh vpn@<your.ip.or.domain.name> -C tunnelhound-restore

For a Docker appliance:

cat tunnelhound.backup | docker exec -it <name-of-tunnelhound-container> tunnelhound-restore

If the backup you’re restoring contains a previous TunnelHound license, you will be given some information that you can use to transfer the license ownership to the new appliance. Due to the way licensure works, this is currently a manual process. The restoration process will erase any existing license keys before activating the new database.

Note that restoration may result in a few minutes of downtime while the new network structure is created.

Encryption

TunnelHound can automatically encrypt your database backups and decrypt your backups for restoration. To set up encryption, run the tunnelhound-backup-passwd command.

For a cloud appliance:

ssh vpn@<your.ip.or.domain.name> -t -C tunnelhound-backup-passwd

For a Docker appliance:

docker exec -it <name-of-tunnelhound-container> tunnelhound-backup-passwd

This command will prompt you for a password which will be saved to encrypt future backups.

The database backup will now be unreadable without this password. Make sure to write down your password somewhere safe and delete the file from your computer.

To restore from an encrypted backup, copy the password file to your new appliance and run the restoration command as before.

Automation

Sometimes you want to set up encryption without having to run an interactive command. You can set the backup password automatically by invoking the tunnelhound-backup-passwd script on a non-interactive terminal.

For a cloud appliance, run

echo "new password" | ssh vpn@<your.ip.or.domain.name> -C tunnelhound-backup-passwd

Or you can use cat to set the password to the contents of a file.

cat <password/file> | ssh vpn@<your.ip.or.domain.name> -C tunnelhound-backup-passwd

Or for a Docker appliance, run

echo "new password" | docker exec -it <name-of-tunnelhound-container> tunnelhound-backup-passwd

or using a file

cat <password/file> | docker exec -it <name-of-tunnelhound-container> tunnelhound-backup-passwd

Note that the password must be contained on only one line.

Recommendations

For most purposes, it’s good enough to back up your databases daily, and retain them for about one month. These files are small and unlikely to cause space shortages.