Software updates
Airgate appliances are updated in place with a signed update file. The update replaces Airgate’s container images, deployment files and appliance scripts; the database, settings, secrets and certificates stay. This page is for platform administrators of an appliance. Airgate Cloud is updated by Airowire.
Before you begin
Section titled “Before you begin”- The platform administrator role (the Software update page is under Settings › Platform).
- The update file
airgate-update-<version>.tarand its checksum fileairgate-update-<version>.tar.sha256for the new version. See Release notes for what changed. - A recent backup: on Settings › Backups select Back up now first. See Backups and restore.
- Optional but recommended: a VM snapshot of the appliance, taken just before the update.
- A maintenance window. Installing restarts Airgate’s services: for a minute or two the console is unavailable and sign-ins (RADIUS, TACACS+) pause.
What an update contains
Section titled “What an update contains”An update file is an uncompressed tar archive:
| Entry | Content |
|---|---|
manifest.json |
Product, version, build time, and the SHA-256 and size of every file in the update |
manifest.sig |
Ed25519 signature of the manifest by Airgate’s release key |
images.tar.gz |
The Airgate container images (when the update brings new ones) |
deploy/… |
Deployment files |
scripts/…, rootfs/… |
Appliance scripts and files |
bin/airgate-agent |
The update agent itself |
The appliance accepts only updates signed with Airgate’s release key. Because the signature covers the manifest and the manifest lists the SHA-256 of every file, it covers every byte that gets installed. A file that is not listed, or whose checksum differs, is refused.
Step 1: Check the download
Section titled “Step 1: Check the download”On your workstation:
sha256sum -c airgate-update-<version>.tar.sha256On Windows PowerShell, compare Get-FileHash airgate-update-<version>.tar -Algorithm SHA256 with the value in the .sha256 file. The appliance checks the signature again in Step 3; this step catches a damaged download before you upload it.
Step 2: Upload the update
Section titled “Step 2: Upload the update”- Go to Settings › Software update. The Installed card shows the Appliance version, the Console build, the Previous version kept for rollback, and Updates accepted (normally Signed by the Airgate release key only).
- Under Install an update, choose
airgate-update-<version>.tar. - Select Upload. The file is uploaded in chunks with a progress bar.
Step 3: Check the file
Section titled “Step 3: Check the file”After the upload the appliance checks the signature and the checksum of every file. When it passes, a banner shows Airgate <version>, signature verified, with the build date, the size, whether it brings new container images, and the version installed now.
If the check fails, This file cannot be installed shows the reason. Select Choose another file.
If the file is the version already installed, turn on This version is already installed: reinstall it to install it again.
Step 4: Install
Section titled “Step 4: Install”- Select Install
<version>and confirm. - The page follows the progress and shows the log. The update:
- saves the current release’s deployment files for a rollback;
- loads the new container images;
- installs the files;
- restarts Airgate’s services;
- waits up to 3 minutes for Airgate to answer its health check.
- While the services restart, the console is briefly unavailable; the page keeps checking and comes back by itself.
When it is done, the History table shows the update with the result done, and the Installed card shows the new version. The previous version is kept for a rollback. Container images other than the current and previous versions are removed to save disk space.
Installing, verifying and rolling back are written to the platform audit log.
Install over SSH
Section titled “Install over SSH”You can do the same from the appliance’s shell:
scp airgate-update-<version>.tar airgate@nac.contoso.com:ssh airgate@nac.contoso.comsudo airgate-update airgate-update-<version>.tar| Command | Does |
|---|---|
sudo airgate-update FILE |
Verify and install FILE (signed updates only) |
sudo airgate-update -force FILE |
Reinstall the version already installed |
sudo airgate-update rollback |
Return to the previous version |
sudo airgate-update status |
Show the installed and previous versions and the last operation |
The log of the last operation is in /var/lib/airgate/updater/operation.log. Only one update or rollback runs at a time, and none runs while a backup is being restored.
First update of an older appliance
Section titled “First update of an older appliance”An appliance built before in-place updates existed has no airgate-update command yet. Copy the file over, then run:
mkdir /tmp/u && tar -xf airgate-update-<version>.tar -C /tmp/u bin/airgate-agentsudo /tmp/u/bin/airgate-agent apply airgate-update-<version>.tarThis also installs the update agent; later updates work from the console.
Roll back
Section titled “Roll back”The previous version is kept. To return to it:
- in the console, Settings › Software update › Installed › Roll back, then confirm; or
- over SSH,
sudo airgate-update rollback.
A rollback restores the previous version’s deployment files and container images and restarts Airgate. The appliance scripts keep their newer copies.
If an update fails
Section titled “If an update fails”The History table shows the update as failed with the reason, and Show the last log opens the full log.
| Symptom | Cause | Fix |
|---|---|---|
the update is not signed by Airgate's release key |
The file is not signed with Airgate’s release key, or it was modified | Download it again and check the .sha256; use only files from Airowire |
…: checksum mismatch, … is not in the signed manifest, not an Airgate update bundle |
Damaged, altered or wrong file | Download it again |
version … is already installed |
The file is the running version | Turn on reinstall it, or use -force |
an update or rollback is already running |
An update or rollback is in progress, or a backup restore holds the updater | Wait for it to finish |
Airgate did not answer on … within 3m0s |
Airgate did not become healthy after the restart | sudo airgate-compose ps and sudo airgate-compose logs nacd; roll back if needed |
there is no previous version to return to |
Nothing to roll back to (first install) | Restore a backup instead |
| Updates are off on this host | The installation has no update agent (for example Airgate Cloud) | Nothing to do; Airowire updates Airgate Cloud |
Site connectors
Section titled “Site connectors”The Airgate Edge appliance has no update file. The Version column on Network › Sites shows each connector’s version. To move a site to a newer connector, deploy the new Edge appliance (or install the new nac-edge program), issue a new enrollment token and enroll it; see Replace or re-enroll a connector.