Upgrade Firezone

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 $HOME/.firezone:

cd $HOME/.firezone

If your .env file has a VERSION variable, update it to the desired version. By default latest is assumed if not set. This variable is read in newer versions of the docker-compose.yml template to populate the image: key for the firezone service.
Update service images:

docker compose pull

Re-up the services (warning: this will restart updated services):

docker compose up -d

If not setup already, install our package repository based on your distro's package format:

Upgrade the firezone package using your distro's package manager.
Run firezone-ctl reconfigure to pick up the new changes.
Run firezone-ctl restart to restart services.

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

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_ALLOWED_IPS, WIREGUARD_PERSISTENT_KEEPALIVE, and WIREGUARD_DNS environment variables to the database to be configured in the UI at /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.

`AUTH_OIDC_JSON` config

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 /settings/site. In Firezone 0.7 this is now configurable via the REST API as well.

Fix IPv6

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:

services:
  firezone:
    networks:
      firezone-network:
        ipv6_address: fcff:3990:3990::99

# ...
networks:
  firezone-network:
    ipam:
      config:
        - subnet: fcff:3990:3990::/64
        - gateway: fcff: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.

Update Configuration

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 force_ssl and 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 by setting 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,

Make sure default['firezone']['external_url'] contains a valid FQDN that resolves to your server's public IP address.
Ensure port 80/tcp is reachable
Enable ACME protocol support with default['firezone']['ssl']['acme']['enabled'] = true in 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']['okta'] or 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 /etc/firezone/firezone.rb

default['firezone']['authentication']['google']['enabled']
default['firezone']['authentication']['google']['client_id']
default['firezone']['authentication']['google']['client_secret']
default['firezone']['authentication']['google']['redirect_uri']

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 /etc/firezone/firezone.rb

default['firezone']['authentication']['okta']['enabled']
default['firezone']['authentication']['okta']['client_id']
default['firezone']['authentication']['okta']['client_secret']
default['firezone']['authentication']['okta']['site']

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 running 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 of default['firezone']['external_url']. Please set this to the publicly-accessible URL of your Firezone web portal. If left unspecified it will default to https:// + the FQDN of your server.

Reminder, the configuration file can be found at /etc/firezone/firezone.rb. 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 /etc/firezone/firezone.rb file.

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
firezone-ctl reconfigure
firezone-ctl restart