Backups and restore
The Airgate appliance backs itself up into one encrypted file. A backup restores the whole appliance, including its certificate authorities, so you can rebuild a lost or broken appliance on a new VM and have laptops, phones and switches keep connecting. This page is for platform administrators of an appliance. Airgate Cloud is backed up by Airowire.
What a backup contains
Section titled “What a backup contains”A backup is one file, airgate-backup-<host>-<UTC date>-<UTC time>-<version>.agbk, with:
- the database: configuration, policies, users, devices, guests, logs and audit records, and the certificate authorities (root, onboarding, RadSec) with their keys, every issued certificate and the server certificates (console, Wi-Fi, RadSec), generated or uploaded;
- the appliance’s settings and secrets (
/opt/airgate/deploy/.env), among them the master key that encrypts the CA keys and other secrets stored in the database; - the version it was made with.
It does not contain:
- the network settings and the host name (they belong to the VM);
- the appliance login password;
- the backup schedule and backup server settings;
- the Active Directory domain join of the appliance.
Encryption
Section titled “Encryption”The file is encrypted with AES-256-GCM. The key is derived from your backup passphrase with scrypt. Every chunk is authenticated, so a wrong passphrase, a modified header, or a changed, reordered or truncated part of the file makes it fail to open.
Before you begin
Section titled “Before you begin”- The platform administrator role (Settings › Backups is under Settings › Platform).
- A passphrase of at least 12 characters.
- Optional: an SFTP server with a directory the backup user can write to.
Step 1: Set the schedule and passphrase
Section titled “Step 1: Set the schedule and passphrase”- Go to Settings › Backups › Schedule and passphrase.
- Daily backup: on by default at
00:00in the appliance’s time zone. Choose another time, or turn it off to back up by hand only. - Keep on the appliance: how many of the newest backups to keep in
/var/lib/airgate/backups(default14, from 1 to 365). - Passphrase and Repeat: at least 12 characters.
- Select Save.
No backup is made until a passphrase is set; the page shows Set a backup passphrase until then. The passphrase is stored on the appliance, readable by root only, so scheduled backups run unattended. Changing it applies to new backups; existing backups keep the passphrase they were made with.
Step 2: Copy backups to a backup server (recommended)
Section titled “Step 2: Copy backups to a backup server (recommended)”A backup kept only on the appliance is lost with the appliance. Copy every backup to an SFTP server:
- In Backup server (SFTP), turn on Copy backups to a backup server.
- Enter the Host (for example
backup.contoso.com), Port, User, Directory (for example/backups/airgate) and Keep on the server (how many to keep there;0keeps all). - Sign in with a Password, or a Private key (PEM, without a passphrase).
- Select Save, then Test. Airgate connects, checks that the directory is writable, and pins the server’s key: it shows Connected; the directory is writable and the pinned key. The settings then show Server key pinned with the key.
Later copies to a server that presents another key are refused, which protects the backups from being sent to an impostor. A failed copy shows in the list; the backup stays on the appliance.
Step 3: Back up now
Section titled “Step 3: Back up now”Select Back up now to make a backup at once, for example before an update. The list shows each backup with its size and whether it was copied to the backup server; Download saves it to your computer, Delete removes it from the appliance.
Over SSH:
| Command | Does |
|---|---|
sudo airgate-backup |
Back up now with the stored passphrase |
sudo airgate-backup -passphrase-file FILE |
Back up with the passphrase in FILE |
sudo airgate-backup list |
List the backups on the appliance |
Restore a backup
Section titled “Restore a backup”A restore replaces everything on the appliance with the backup’s content: the database, settings, secrets and certificates.
- On Settings › Backups, select Restore next to a backup in the list, or choose a file under Restore a backup from a file to upload one.
- Enter the Passphrase of the backup.
- Airgate opens the backup and shows what it is: Appliance, Made, Version, Console address and Wi-Fi server name. Check that it is the backup you expect.
- Type
RESTOREin Type RESTORE to confirm and confirm.
Airgate restarts with the backup. Sign-ins pause for a few minutes and everyone is signed out of the console. Sign in again with the administrators of the backup. If the restore fails, the appliance’s previous database and settings are put back.
Over SSH: sudo airgate-restore FILE asks for the passphrase and a confirmation; sudo airgate-restore -passphrase-file FILE -yes BACKUP runs it without questions.
Which versions can restore a backup
Section titled “Which versions can restore a backup”A backup restores on the same or a newer Airgate version: Airgate brings the database up to date when it starts. A backup from a newer version than the one installed is refused with the backup is from Airgate <version>, newer than the installed <version>: update this appliance to <version> or later first. Update the appliance first (Software updates), then restore.
When the versions cannot be compared (for example a development build), the restore is refused unless you turn on Restore anyway.
Rebuild an appliance from a backup
Section titled “Rebuild an appliance from a backup”Laptops, phones and network devices trust the appliance’s certificate authorities and its Wi-Fi certificate. A newly deployed appliance creates new ones that devices do not trust. To replace an appliance (a rebuild, a new host, a broken VM), restore its backup on the new one: it comes back with the same certificate authorities, certificates, settings and secrets, and devices keep connecting.
- Get a recent backup and its passphrase. If the old appliance is gone, take the copy from the backup server.
- Deploy the OVA as in Install the appliance on VMware ESXi. To take the old appliance’s place, give the new one the same IP address and host name. Otherwise point DNS for the console and the Wi-Fi certificate name, and the network devices’ RADIUS and TACACS+ settings, at the new address.
- In the first-boot wizard, after the host name, answer
yto Restore from a backup of an Airgate appliance (rebuild)? The wizard sets the network, NTP and the login password, then asks for the backup:- copy it over SSH from your computer:
scp airgate-backup-….agbk airgate@<new appliance>:and enter/home/airgate/airgate-backup-….agbk; or - enter the backup server’s address,
sftp://user@backup.contoso.com/backups/airgate/airgate-backup-….agbk. The wizard shows the server’s key for you to confirm and asks for the password.
- copy it over SSH from your computer:
- Enter the passphrase and confirm the restore.
- Airgate starts with the backup. Sign in with the old appliance’s administrators.
Then on the new appliance:
- set the backup schedule, passphrase and backup server again (Settings › Backups);
- if the old appliance was joined to Active Directory, join again with the same computer name: Access › Directories › the Active Directory directory › Domain join.
The new appliance must run the same or a newer version than the backup’s.
Verify
Section titled “Verify”- Settings › Backups shows the last scheduled backup with today’s date, and no The last scheduled backup did not run banner.
- Backups appear on the SFTP server.
- Once a quarter, restore a backup on a test VM to prove that it and its passphrase work.
Troubleshooting
Section titled “Troubleshooting”| Symptom | Cause | Fix |
|---|---|---|
| Set a backup passphrase banner, no backups | No passphrase set | Set one in Schedule and passphrase |
| The last scheduled backup did not run | The appliance was off or the backup failed at the scheduled time | Open Last log; select Back up now |
| Copy to the backup server failed | Server unreachable, wrong credentials or directory not writable | Select Test and fix what it reports |
the backup server's host key does not match the pinned one |
The SFTP server presents a different key than the one pinned at the first test: the server was rebuilt, or something is impersonating it | Check the server’s key fingerprint with its administrator before you trust it |
| Restore says the passphrase is wrong | Wrong passphrase, or the file is damaged | Use the passphrase the backup was made with; download the file again |
| Restore refused: backup is newer | The backup was made by a newer Airgate | Update the appliance first |
| Devices stop trusting Airgate after a rebuild | The new appliance was set up fresh instead of restored | Restore the old appliance’s backup on it |