Skip to main content

Upgrade

Upgrading Firezone will disconnect all VPN sessions and require shutting down the Web UI. We recommend a maintenance window of about an hour in case anything goes wrong during the upgrade.

To upgrade Firezone, follow these steps:

  1. If not setup already, install our package repository based on your distro's package format:
  2. Upgrade the firezone package using your distro's package manager.
  3. Run firezone-ctl reconfigure to pick up the new changes.
  4. Run firezone-ctl restart to restart services.

Occasionally problems arise. If you hit any, please let us know by filing an issue.

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.

OIDC Connections

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