Upgrading Firezone will pause all VPN sessions and temporarily bring down the web UI.
Automatic rollbacks are still under development. We recommend backing up relevant files and folders before upgrading in case anything goes wrong.
Follow the steps below to upgrade Firezone:
- Change to your Firezone installation directory, by default
- If your
.envfile has a
VERSIONvariable, update it to the desired version. By default
latestis assumed if not set. This variable is read in newer versions of the docker-compose.yml template to populate the
image:key for the
- Update service images:
docker compose pull
- Re-up the services (warning: this will restart updated services):
docker compose up -d
If you hit any issues, please let us know by filing an issue.
Upgrading to 0.7.x
Firezone 0.7.0 introduces a new REST API that allows administrators to automate much of the day to day configuration of Firezone.
The REST API
/v0/configuration endpoint supersedes some of the previous environment
variables used for WireGuard server configuration.
If you're running Firezone < 0.6, we recommend updating to the latest
0.6.x release before upgrading to 0.7. This will ensure any environment variables
are properly parsed and migrated into the DB as runtime
Note: Omnibus deployments are deprecated in 0.7.x and will be removed in Firezone 0.8 and above. We recommend migrating your installation to Docker if you haven't done so already.
Upgrading to >= 0.6.12
WIREGUARD_* env vars
Firezone 0.6.12 moves the
WIREGUARD_DNS environment variables to the database to be configured in the
/settings/client_defaults. If the corresponding value at
/settings/client_defaults was empty, the environment variable's value was used to
populate the field.
This is a small step in our quest to move more runtime configuration from environment variables to the DB.
Similar to the
WIREGUARD_* env vars above, the
AUTH_OIDC_JSON env var has similarly
been moved to the database and can be configured at
0.6.12 fixes IPv6 routing within Docker networks.
To enable, add IPv6 addresses to your
$HOME/.firezone/docker-compose.yml by setting the following fields:
- subnet: 2001:3990:3990::/64
- gateway: 2001:3990:3990::1
You also need to update the Docker daemon to enable IPv6. See our IPv6 guide for more info.
Upgrading from 0.5.x to 0.6.x
Firezone 0.6 introduces Docker support, SAML 2.0 authentication, more granular user provisioning options, and a slew of minor improvements and bugfixes.
Migrate to Docker
Docker is now the preferred way to deploy and manage Firezone. See the migration guide to migrate today. In most cases this can be done in a few minutes using our automatic migration script.
Some configuration variables have recently moved to the DB in order to be configurable at runtime. Check the configure guide for more information.
Upgrading from < 0.5.0 to >= 0.5.0
0.5.0 introduces a few breaking changes and configuration updates that will need to be addressed. Read more below.
Bundled Nginx non_ssl_port (HTTP) requests removed
0.5.0 and above removes the
non_ssl_port settings for
Nginx. SSL is required for Firezone to function; if you're using (or would like
to use) your own reverse proxy, we recommend disabling the bundle Nginx service
default['firezone']['nginx']['enabled'] = false and pointing your
reverse proxy directly to the Phoenix app on port 13000 (by default).
Read more about setting up a custom reverse proxy here.
ACME protocol support
0.5.0 introduces ACME protocol support for automatically renewing SSL certificates with the bundled Nginx service. To enable,
default['firezone']['external_url']contains a valid FQDN that resolves to your server's public IP address.
Enable ACME protocol support with
default['firezone']['ssl']['acme']['enabled'] = truein your config file.
Overlapping egress rule destinations
Firezone 0.5.0 removes the ability to add rules with overlapping destinations. When upgrading to 0.5.0, our migration script will automatically detect these cases and keep only the rules whose destination encompasses the other rule. If this is OK, there is nothing you need to do.
Otherwise, we recommend modifying your ruleset to eliminate these cases before upgrading.
Preconfigured Okta and Google SSO
Firezone 0.5.0 removes support for the old-style Okta and Google SSO
configuration in favor of the new, more flexible OIDC-based configuration.
If you have any configuration under the
default['firezone']['authentication']['google'] keys, you need to migrate
these to our OIDC-based configuration using the guide below.
Existing Google OAuth configuration
Remove these lines containing the old Google OAuth configs from your configuration
file located at
Then, follow the instructions here to configure Google as an OIDC provider.
Existing Okta OAuth configuration
Remove these lines containing the old Okta OAuth configs from your configuration
file located at
Then, follow the instructions here to configure Okta as an OIDC provider.
Upgrading from 0.3.x to >= 0.3.16
Follow the instructions below based on your current version and setup:
I have an existing OIDC integration
Upgrading to >= 0.3.16 requires the
offline_access scope for some OIDC providers
to obtain a refresh token.
This ensures Firezone syncs with the identity provider and VPN access is terminated
once the user is removed. Previous versions of Firezone do not have this capability.
Users who are removed from your identity provider will still have active VPN sessions
in some cases.
For OIDC providers that support the
offline_access scope, you will need to add
offline_access to the
scope parameter of your OIDC config. The
Firezone configuration file can be found at
/etc/firezone/firezone.rb and requires
firezone-ctl reconfigure to pick up the changes.
If Firezone is able to successfully retrieve the refresh token, you will see the OIDC Connections heading in the user details page of the web UI for users authenticated through your OIDC provider.
If this does not work, you will need to delete your existing OAuth app and repeat the OIDC setup steps to create a new app integration .
I have an existing OAuth integration
Prior to 0.3.11, Firezone used pre-configured OAuth2 providers. Follow the instructions here to migrate to OIDC.
I have not integrated an identity provider
No action needed. You can follow the instructions here to enable SSO through an OIDC provider.
Upgrading from 0.3.1 to >= 0.3.2
The configuration option
default['firezone']['fqdn'] has been removed in favor
default['firezone']['external_url']. Please set this to the
publicly-accessible URL of your Firezone web portal. If left unspecified it will
https:// + the FQDN of your server.
Reminder, the configuration file can be found at
For an exhaustive list of configuration variables and their descriptions, see the
configuration file reference.
Upgrading from 0.2.x to 0.3.x
Starting with version 0.3.0, Firezone no longer stores device private keys on the Firezone server. Any existing devices should continue to function as-is, but you will not be able to re-download or view these configurations in the Firezone Web UI.
Upgrading from 0.1.x to 0.2.x
Firezone 0.2.x contains some configuration file changes that will need to be
handled manually if you're upgrading from 0.1.x. Run the commands below as root
to perform the needed changes to your
cp /etc/firezone/firezone.rb /etc/firezone/firezone.rb.bak
sed -i "s/\['enable'\]/\['enabled'\]/" /etc/firezone/firezone.rb
echo "default['firezone']['connectivity_checks']['enabled'] = true" >> /etc/firezone/firezone.rb
echo "default['firezone']['connectivity_checks']['interval'] = 3_600" >> /etc/firezone/firezone.rb