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:
- If not setup already, install our package repository based on your distro's package format:
- Upgrade the
firezonepackage using your distro's package manager.
firezone-ctl reconfigureto pick up the new changes.
firezone-ctl restartto 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
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