Upgrading Firezone
Upgrading Firezone consists of upgrading the Clients and Gateways. Read more below to understand how our versioning system works, how you can auto-update these components, and suggestions for an upgrade strategy in high-availability deployments.
How versioning works in Firezone
Firezone uses a semantic version scheme in the following format:
MAJOR.MINOR.PATCH
Firezone is changing rapidly, so we currently recommend staying as up-to-date as possible to make sure you have the latest bug fixes and performance improvements in place.
All components currently have a major version of 1 -- this is not expected to
change for some time.
Client application auto-updates
In general we recommend keeping Clients and Gateways as up-to-date as possible. See below for auto-update details for each platform.
Enable auto-updates in Settings.app.
A UI alert is shown upon launch if the Windows Client has an update available.
Auto-updates depend on your package manager configuration and deployment method.
Upgrading Gateways
Upgrading a Gateway generally consists of simply replacing the binary or Docker image and then restarting. See below for specific steps depending on how you've deployed your Gateway:
Run the following upgrade script which pulls the latest image, stops the running Gateway, and then restarts it using the newer image with the same configuration.
curl -s https://raw.githubusercontent.com/firezone/firezone/main/scripts/gateway-docker-upgrade.sh | bash
Verification
After running the upgrade, you can verify the Gateway is running the latest version by ensuring the sha256 hash of the pulled image matches the latest artifact published on GitHub:
# Get the sha256 hash of the gateway image running on your system
> docker inspect ghcr.io/firezone/gateway:1.0 --format='{{index .RepoDigests 0}}'
# Ensure this hash matches the latest available image above
ghcr.io/firezone/gateway@sha256:0516fa4a305fac10571238db2b7bf02e6adeda0fb5afc1fe7e8d0c4d0a93ebc6
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:
sudo mv /usr/local/bin/firezone-gateway /usr/local/bin/firezone-gateway.bak
sudo systemctl restart firezone-gateway
Downtime considerations
Gateways deployed within the same Site will automatically failover for each other. By upgrading Gateways one-by-one, Clients connected to the Gateway being upgraded will automatically reconnect to an available Gateway.
Upgrades should be performed during a scheduled maintenance window to ensure minimal disruption. Other than a possible short-term connection interruption to in-use Resources, users won't otherwise be impacted by upgrading Gateways within the same Site.