import { HiCheck, HiCommandLine } from "react-icons/hi2"; import { FaDocker, FaUbuntu } from "react-icons/fa"; import Link from "next/link"; import { TabsItem, TabsGroup } from "@/components/Tabs"; import Image from "next/image"; import Alert from "@/components/DocsAlert"; import SupportOptions from "@/components/SupportOptions";

Upgrade Gateways

Firezone Gateways are designed to be easily upgraded with little or no planned downtime for your organization. This guide will walk you through the steps to upgrade your Gateway for both Docker and systemd deployments.

<Alert color="info"> This guide covers Gateway upgrades only. For details on upgrading Clients, refer to the appropriate [client app guide](/kb/client-apps) for your platform. </Alert>

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 process

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:

bash

sudo apt update
sudo apt upgrade firezone-gateway

</TabsItem> <TabsItem title="Docker" icon={FaDocker}>

Copy-paste the following command to upgrade your Docker-based Gateway:

bash

curl -fsSL \
  https://raw.githubusercontent.com/firezone/firezone/main/scripts/gateway-docker-upgrade.sh \
  | bash

{(<div className="flex justify-end">

<Link className="text-sm" href="https://github.com/firezone/firezone/blob/main/scripts/gateway-docker-upgrade.sh" > View script source </Link> </div>)} </TabsItem> <TabsItem title="systemd" icon={HiCommandLine}>

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:

bash

# 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:

bash

# 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.

</TabsItem> </TabsGroup>

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.