Upgrade Firezone
Keep your Firezone deployment current. This guide covers upgrading the Gateway for each supported deployment method, as well as the Client on each platform. Gateways are designed to be upgraded with little or no planned downtime.
Version compatibility
Gateways are guaranteed to be compatible with Clients of the current and previous minor version. For example, Gateway version 1.4.X is compatible with all Client versions 1.3.X and 1.4.X but not with Clients from the 1.2.X version.
To ensure smooth access to all your Resources, we recommend updating your Clients and Gateways at least every 3 months. These updates do not have to happen in lock-step as the Firezone control plane automatically selects a compatible Gateway for each Client according to the compatibility described above.
To support Clients across multiple minor versions, you can deploy Gateways of different versions in the same site. For example, running Gateway 1.3.X, 1.4.X and 1.5.X within the same site will allow Clients from 1.2.X to 1.5.X to connect.
In order to safely upgrade your Gateways to a new version, you'll want to ensure that all of your Clients have upgraded at least to the prior minor version. For example, if you upgrade your Gateways to 1.5.X, all users should at least be using Client 1.4.0 of their respective platform.
Upgrade the Gateway
Upgrading a Gateway generally consists of simply replacing the binary or Docker image with the newer version and then restarting. See below for specific steps depending on how you've deployed your Gateway:
If you installed the Gateway from the artifacts.firezone.dev APT repository,
you can upgrade the Gateway via apt:
sudo apt update
sudo apt upgrade firezone-gateway
Copy-paste the following command to upgrade your Docker-based Gateway:
curl -fsSL \
https://raw.githubusercontent.com/firezone/firezone/main/scripts/gateway-docker-upgrade.sh \
| bash
If you deployed via the portal, your unit file should already contain logic necessary to upgrade the Gateway on service start. Simply move the old binary and restart the service to trigger the upgrade:
# Stop the Gateway service. WARNING: This will cause brief downtime for this Gateway.
sudo systemctl stop firezone-gateway
# Move the old binary to a backup location
sudo mv /opt/firezone/bin/firezone-gateway /opt/firezone/bin/firezone-gateway.bak
# Start the Gateway service to trigger the upgrade
sudo systemctl start firezone-gateway
Rollback in case of issues
If something goes wrong during the upgrade, you can always revert to the old binary by stopping the service and moving the backup binary back to its original location:
# Restore the old binary and restart the service
sudo systemctl stop firezone-gateway
sudo mv /usr/local/bin/firezone-gateway.bak /usr/local/bin/firezone-gateway
sudo systemctl start firezone-gateway
Please file a GitHub issue if you consistently encounter issues with the upgrade process.
If you deployed the Gateway with the NixOS module, upgrade by pointing the flake input at the new Gateway release tag and rebuilding.
Update the pinned tag in your flake.nix:
# flake.nix
inputs.firezone.url = "github:firezone/firezone/gateway-1.5.2";Then refresh the lock and rebuild:
nix flake update firezone
sudo nixos-rebuild switch
nixos-rebuild switch swaps in the new Gateway package and restarts the hardened
firezone-gateway service.
Rollback in case of issues
If something goes wrong, roll back to the previous generation and restart the service:
sudo nixos-rebuild switch --rollback
Alternatively, restore the previous gateway-<version> tag in your flake.nix,
run nix flake update firezone, and rebuild.
Verification
After running the upgrade, check that the version reported by the Gateway in the admin portal matches the latest published version on our changelog page to ensure it's up to date.
Downtime considerations
Gateways deployed within the same Site will automatically failover for each other. By upgrading Gateways one-by-one in a rolling update strategy, Clients connected to the Gateway being upgraded will automatically reconnect to an available Gateway.
Users may notice very brief interruptions to Resources for a few seconds as their Client reconnects to a healthy Gateway.
Upgrade the Clients
How you upgrade the Client depends on the platform and how it was installed.
The Windows Client automatically checks for updates on launch and prompts you to upgrade when a new version is available. To upgrade manually:
- Download the latest
.msiinstaller from the Windows install guide. - Quit the Client.
- Install the new
.msi.
App Store: use the App Store to update the Firezone Client. See Apple's "Use the App Store to update apps on Mac".
Standalone:
- Quit the Firezone Client if it's running.
- Download the latest version.
- Open the downloaded
.dmgfile. - Drag the Firezone icon to the Applications folder, replacing the existing version.
- Open the Applications folder and double-click the Firezone icon.
If you installed the Client via apt, upgrade it like any other package:
sudo apt update
sudo apt upgrade firezone-client-gui
If you installed the package manually, download the latest .deb or .rpm from
the Linux install guide, quit the Client,
install the new package, and restart it.
Updates are handled through the Google Play Store if you installed the app from there. See the Play Store documentation for how to update apps. If you installed from an APK directly, download and install the new APK manually.
Updates are handled through the Apple App Store. See Apple's documentation for how to update apps on your device.
Need help? See all support options.