Follow our deploy guide to install your self-hosted instance of Firezone.
Or, if you’re on a supported platform, try our one-line install script :
sudo -E bash -c “$(curl -fsSL https://github.com/firezone/firezone/raw/master/scripts/install.sh)”
Firezone is not:
Firezone can be self-hosted on a server running a supported Linux distribution in a few minutes. This guide will walk you through the steps to get started.
Start by checking if your environment is listed on supported platforms. A kernel upgrade may be required to ensure WireGuard® is available.
Ensure port forwarding is enabled on your firewall. The default Firezone configuration requires the following ports to be open:
443/tcp: To access the web UI.51820/udp: The VPN traffic listen-port.NOTE
Firezone modifies the kernel netfilter and routing tables. Other programs that modify the Linux routing table or firewall may interfere with Firezone’s operation. For help troubleshooting connectivity issues, see the troubleshooting guide.
Firezone requires the setup of a DNS record and matching SSL certificate for production deployments. See instructions here.
The easiest way to get started using Firezone is via the automatic installation script below.
sudo -E bash -c “$(curl -fsSL https://github.com/firezone/firezone/raw/master/scripts/install.sh)”
This will ask you a few questions regarding your install, install the latest release for your platform, then create an administrator user and print to the console instructions for logging in to the web UI.
By default, the web UI can be reached at the IP or domain name of your server. You can regenerate the admin credentials using the firezone-ctl create-or-reset-admin command.
If the script fails, follow instructions for manual installation.
Once successfully deployed, users and devices can be added to connect to the VPN server:
Congrats! You have completed the setup, but there’s a lot more you can do with Firezone.
Support us by:
Firezone currently supports the following platforms:
| OS | Architectures | Status | Notes |
|---|---|---|---|
| AmazonLinux 2 | amd64 arm64 | Fully-supported | See AmazonLinux 2 Notes |
| CentOS 7 | amd64 | Fully-supported | See CentOS 7 Notes |
| CentOS 8 | amd64 arm64 | Fully-supported | See CentOS 8 Notes |
| CentOS Stream 9 | amd64 arm64 | Fully-supported | Works as-is |
| Red Hat Enterprise Linux 7 | amd64 | Fully-supported | See RHEL 7 Notes |
| Red Hat Enterprise Linux 8 | amd64 arm64 | Fully-supported | See RHEL 8 Notes |
| Red Hat Enterprise Linux 9 | amd64 arm64 | Fully-supported | See RHEL 9 Notes |
| Debian 10 | amd64 arm64 | Fully-supported | See Debian 10 Notes |
| Debian 11 | amd64 arm64 | Fully-supported | Works as-is |
| Fedora 33 | amd64 arm64 | Fully-supported | See Fedora Notes |
| Fedora 34 | amd64 arm64 | Fully-supported | See Fedora Notes |
| Fedora 35 | amd64 arm64 | Fully-supported | See Fedora Notes |
| Ubuntu 18.04 | amd64 arm64 | Fully-supported | See Ubuntu 18.04 Notes |
| Ubuntu 20.04 | amd64 arm64 | Fully-supported | Works as-is |
| Ubuntu 22.04 | amd64 arm64 | Fully-supported | Works as-is |
| openSUSE Leap 15.3 | amd64 | Fully-supported | See openSUSE Notes |
If your distro isn’t listed here please try using a package for the closest distro first. For example, since Raspberry Pi OS is based on Debian, try using the Debian Firezone package.
If that doesn’t work, please open an issue and let us know. New distros are being supported on a regular basis and there’s a good chance yours will be added soon.
Note that we only support RPM and DEB based packaging systems. Others, like Arch Linux are currently being investigated in this issue.
Kernel upgrade required:
sudo amazon-linux-extras install -y kernel-5.10
Kernel upgrade to 5.6+ required. To upgrade to the latest mainline kernel and select it as the default boot kernel:
sudo rpm –import https://www.elrepo.org/RPM-GPG-KEY-elrepo.org
sudo yum install -y https://www.elrepo.org/elrepo-release-7.el7.elrepo.noarch.rpm
sudo yum install -y elrepo-release
sudo yum –enablerepo=elrepo-kernel install -y kernel-ml
sudo grub2-set-default 0
sudo grub2-mkconfig -o /boot/grub2/grub.cfg
sudo reboot
The WireGuard kernel module needs to be installed:
yum install elrepo-release epel-release
yum install kmod-wireguard
Red Hat Enterprise Linux is binary compatible with CentOS, so the Firezone package for CentOS 7 should work just fine for RHEL 7. You’ll still need to upgrade your kernel to 5.6+ however. To do so, follow the steps for CentOS 7 Notes above.
Red Hat Enterprise Linux is binary compatible with CentOS, so the Firezone package for CentOS 8 should work just fine for RHEL 8. You’ll still need to install the WireGuard kernel module, however. See CentOS 8 Notes above.
Use the package for CentOS 9.
On fresh Fedora installations you’ll probably need to install a cron implementation to support the logrotate functionality, otherwise you may receive errors about a missing /etc/cron.hourly directory.
yum install cronie-anacron
Kernel upgrade to 5.4+ required:
sudo apt install linux-image-generic-hwe-18.04
Kernel upgrade to 5.6+ required. See this guide for an example.
Firezone requires the setcap utility, but some recent openSUSE releases may not have it installed by default. To fix, ensure libcap-progs is installed:
sudo zypper install libcap-progs
Firezone requires the setup of a DNS record and matching SSL certificate for production deployments.
Firezone requires a fully-qualified domain name (e.g. firezone.company.com) for production use. You’ll need to create the appropriate DNS record at your registrar to achieve this. Typically this is either an A, CNAME, or AAAA record depending on your requirements.
While Firezone generates a self-signed SSL certificate for you on install, you’ll need a valid SSL certificate to use Firezone in a production capacity.
We recommend using Let’s Encrypt to generate a free SSL cert for your domain. Starting with Firezone 0.5.0 you have the option to auto-provision Let’s Encrypt SSL certificates for your instance using the ACME protocol. This is disabled by default to maintain backwards compatibility for existing installations.
To enable this, you must ensure the following conditions are met:
80/tcp is allow inboundnginx service is enabled and functioningdefault['firezone']['external_url']: The FQDN for the server.default['firezone']['ssl']['email_address']: The email that will be used for the issued certificates.default['firezone']['ssl']['acme']['enabled']: Set this to true to enable it.By default, Firezone requires ports 443/tcp and 51820/udp to be accessible for HTTPS and WireGuard traffic respectively. These ports can change based on what you’ve configured in the configuration file. See the configuration file reference for details.
We recommend starting with 1 vCPU and 1 GB of RAM and scaling up as the number of users and devices grows.
For Omnibus-based deployments on servers with less than 1GB of memory, we recommend turning on swap to prevent the Linux kernel from killing Firezone processes unexpectedly. When this happens, it’s often difficult to debug and results in strange, unpredictable failure modes.
For the VPN tunnels themselves, Firezone uses in-kernel WireGuard, so its performance should be very good. 1 vCPU should be more than enough to saturate a 1 Gbps network link.
Important: Ensure you’ve satisfied the prerequisites before following this guide.
Assuming you’re running a supported Linux kernel on one of the supported platforms, use one of the methods below to get started:
The easiest way to get started using Firezone is via the automatic installation script:
sudo -E bash -c “$(curl -fsSL https://github.com/firezone/firezone/raw/master/scripts/install.sh)”
This will ask you a few questions regarding your install, install the latest release for your platform, then create an administrator user and print to the console instructions for logging in to the web UI.
If the automatic install script fails, try these steps to install Firezone from our Cloudsmith repository.
curl -1sLf \
‘https://dl.cloudsmith.io/public/firezone/firezone/setup.deb.sh’ \
| sudo -E bash
See the Debian setup docs for more options if the script fails to setup the repo.
curl -1sLf \
‘https://dl.cloudsmith.io/public/firezone/firezone/setup.rpm.sh’ \
| sudo -E bash
Using apt
sudo apt install firezone
Using dnf
sudo dnf install firezone
Using yum
sudo yum install firezone
Using zypper
sudo zypper install firezone
If all else fails, try these steps to install Firezone manually.
sudo rpm -i firezone*.rpm or sudo dpkg -i firezone*.deb depending on your distro.sudo firezone-ctl reconfigure. This will initialize config files, set up needed services and generate the default configuration./etc/firezone/firezone.rb. We’ve chosen sensible defaults that should be a good starting point for most installations. For production installations, you’ll want to specify a valid external URL and enable ACME for certificate issuance and renewal:sudo firezone-ctl reconfigure.sudo firezone-ctl create-or-reset-admin. The login credentials will be printed to the console output.https://firezone.example.comFirezone comes with a bundled Nginx reverse proxy, however, in some cases you might want to deploy your own server such as when using behind your own load balancer.
Below you will find the requirements in order to setup Firezone with a custom reverse proxy.
default['firezone']['nginx']['enabled'] to false in the config file.default['firezone']['phoenix']['external_trusted_proxies']. Because of the way the X-Forwarded-For header works, this is needed to parse the actual client’s IP address to prevent IP spoofing.X-Forwarded-For header as explained hereX-Forwarded-Proto to https.Connection: upgradeUpgrade: websocketIn addition to the headers above, we recommend adding the following headers for security purposes:
X-XSS-Protection: 1; mode=blockX-Content-Type-Options nosniffReferrer-Policy no-referrer-when-downgradeContent-Security-Policy: default-src 'self' ws: wss: http: https: data: blob: 'unsafe-inline'; frame-ancestors 'self';Permissions-Policy: interest-cohort=()Since the upstream Firezone web app expects plain HTTP traffic, any requests the proxy forwards is sent over HTTP and thus is not encrypted. In most cases, the reverse proxy is installed in a trusted network, and this is not an issue. But the connection between your trusted proxy and the Firezone web app spans an untrusted network (such as the Internet), you may want to leave the bundled nginx proxy enabled for SSL termination, and set up your custom reverse proxy to proxy to that instead.
These configurations are written to be as simple as possible. They’re designed to function as a simple template which you can customize further to suit your needs.
If you have a working configuration for a different reverse proxy or a different version of an existing one we appreciate any contribution to expand the examples for the community.
The following are example apache configurations with and without SSL termination.
These expect the apache to be running on the same host as Firezone and default['firezone']['phoenix']['port'] to be 13000.
Since Firezone requires HTTPS for the web portal, please bear in mind a downstream proxy will need to terminate SSL connections in this scenario.
<server-name> needs to be replaced with your domain name.
This configuration needs to be placed in /etc/sites-available/<server-name>.conf
and activated with a2ensite <server-name>
LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so
LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
LoadModule proxy_http_module /usr/lib/apache2/modules/mod_proxy_http.so
LoadModule proxy_wstunnel_module /usr/lib/apache2/modules/mod_proxy_wstunnel.so
ServerName ProxyPassReverse “/” “http://127.0.0.1:13000/” ProxyPass “/” “http://127.0.0.1:13000/” RewriteEngine on RewriteCond %{HTTP:Upgrade} websocket [NC] RewriteCond %{HTTP:Connection} upgrade [NC] RewriteRule ^/?(.*) “ws://127.0.0.1:13000/$1” [P,L]
This configuration builds on the one above and uses Firezone’s auto-generated self-signed certificates.
LoadModule rewrite_module /usr/lib/apache2/modules/mod_rewrite.so
LoadModule proxy_module /usr/lib/apache2/modules/mod_proxy.so
LoadModule proxy_http_module /usr/lib/apache2/modules/mod_proxy_http.so
LoadModule proxy_wstunnel_module /usr/lib/apache2/modules/mod_proxy_wstunnel.so
LoadModule ssl_module /usr/lib/apache2/modules/mod_ssl.so
LoadModule headers_module /usr/lib/apache2/modules/mod_headers.so
Listen 443
ServerName RequestHeader set X-Forwarded-Proto “https” ProxyPassReverse “/” “http://127.0.0.1:13000/” ProxyPass “/” “http://127.0.0.1:13000/” RewriteEngine on RewriteCond %{HTTP:Upgrade} websocket [NC] RewriteCond %{HTTP:Connection} upgrade [NC] RewriteRule ^/?(.*) “ws://127.0.0.1:13000/$1” [P,L] SSLEngine On SSLCertificateFile “/var/opt/firezone/ssl/ca/acme-test.firez.one.crt” SSLCertificateKeyFile “/var/opt/firezone/ssl/ca/acme-test.firez.one.key”
The following are examples for configuring the Traefik proxy as a reverse proxy for Firezone.
In these examples, we assume Traefik is deployed using Docker on the same host as Firezone. For this to work, you’ll need to make sure Firezone’s phoenix app is bound to port 13000 on the Docker interface address and external_trusted_proxies is set properly:
Since Firezone requires HTTPS for the web portal, please bear in mind a downstream proxy will need to terminate SSL connections in this scenario.
Use the following docker-compose.yml and rules.yml files to configure Traefik:
docker-compose.ymlversion: ‘3’
services:
reverse-proxy:
#network_mode: “host”
# The official v2 Traefik docker image
image: traefik:v2.8
# Enables the web UI and tells Traefik to listen to docker
command:
– “–providers.docker”
– “–providers.file.filename=rules.yml”
– “–entrypoints.web.address=:80”
– “–entrypoints.web.forwardedHeaders.insecure”
– “–log.level=DEBUG”
extra_hosts:
– “host.docker.internal:host-gateway”
ports:
# The HTTP port
– “80:80”
volumes:
# So that Traefik can listen to the Docker events
– /var/run/docker.sock:/var/run/docker.sock
– “./rules.yml:/rules.yml”
rules.yml
http:
routers:
test:
entryPoints:
– “web”
service: test
rule: “Host(44.200.42.78)”
services:
test:
loadBalancer:
servers:
– url: “http://host.docker.internal:13000”
Now you should be able to start the Traefik proxy with docker compose up.
This configuration uses Firezone’s auto-generated self-signed certificates.
docker-compose.ymlservices:
reverse-proxy:
#network_mode: “host”
# The official v2 Traefik docker image
image: traefik:v2.8
# Enables the web UI and tells Traefik to listen to docker
command:
– “–providers.docker”
– “–providers.file.filename=rules.yml”
– “–entrypoints.web.address=:443”
– “–entrypoints.web.forwardedHeaders.insecure”
– “–log.level=DEBUG”
extra_hosts:
– “host.docker.internal:host-gateway”
ports:
# The HTTP port
– “443:443”
volumes:
# So that Traefik can listen to the Docker events
– /var/run/docker.sock:/var/run/docker.sock
– “./rules.yml:/rules.yml”
– /var/opt/firezone/ssl/ca:/ssl:ro
The following is an example reverse proxy configuration for HAProxy proxy. We assume default['firezone']['phoenix']['port'] to be 13000 and the proxy running on the same host as the Firezone app.
Since Firezone requires HTTPS for the web portal, please bear in mind a downstream proxy will need to terminate SSL connections in this scenario.
You can also configure HAProxy to handle the SSL termination as explained here but take into account that the pem file expected by ssl crt option needs to contain both the crt and key file.
Firezone can be configured to require authentication before users can generate or download device configuration files. Optionally, periodic re-authentication can also be required for users to maintain their VPN session.
Firezone supports the following authentication methods:
We’ve included instructions on how to set up Firezone with several popular identity providers:
If your identity provider is not listed above, but has a generic OIDC connector, please consult their documentation to find instructions on obtaining the config settings required. Instructions on setting up Firezone with a generic OIDC provider can be found here.
Open a Github Issue to request documentation or submit a pull request to add documentation for your provider. If you require assistance in setting up your OIDC provider, please join the Firezone Slack group.
For each OIDC provider a corresponding URL is created for redirecting to the configured provider’s sign-in URL. The URL format is https://firezone.example.com/auth/oidc/PROVIDER where PROVIDER is the OIDC key for that particular provider.
For example, the OIDC config below
default[‘firezone’][‘authentication’][‘oidc’] = {
google: {
# …
},
okta: {
# …
}
would generate the following URLs:
https://firezone.example.com/auth/oidc/googlehttps://firezone.example.com/auth/oidc/oktaThese URLs could then be distributed by an Admin directly to end users to navigate to the appropriate identity provider login page to authenticate to Firezone.
Periodic re-authentication can be enforced by changing the setting in settings/security. This can be used to ensure a user must sign in to Firezone periodically in order to maintain their VPN session.
You can set the session length to a minimum of 1 hour and maximum of 90 days. Setting this to Never disables this setting, allowing VPN sessions indefinitely. This is the default.
To re-authenticate an expired VPN session, a user will need to turn off their VPN session and sign in to the Firezone portal (URL specified during deployment ).
See detailed Client Instructions on how to re-authenticate your session here.
A user’s connection status is shown on the Users page under the table column VPN Connection. The connection statuses are:
By default, Firezone will use local email / password for authenticating users to the Firezone portal. Administrators can add users and assign their passwords on /users page.
Multi-factor authentication (MFA) can be added directly through Firezone or by adding an additional factor directly through your identity provider.
Firezone currently supports using a time-based one time password (TOTP) as an additional factor. This is supported with the local authentication method only; for SSO authentication we recommend enabling your provider’s MFA functionality as described below.
Admins can visit /settings/account/register_mfa in the admin portal to generate a QR code to be scanned by your authenticator app.
Unprivileged users can visit /user_account/register_mfa after logging into the user portal.
Most identity providers support additional authentication factors in addition to email/password. Consult your provider’s documentation to enforce an additional factor. We have included links to a few common providers below:
Firezone supports Single Sign-On (SSO) using Okta through the generic OIDC connector. This guide will walk you through how to obtain the following config settings required for the integration:
discovery_document_uri: The OpenID Connect provider configuration URI which returns a JSON document used to construct subsequent requests to this OIDC provider.client_id: The client ID of the application.client_secret: The client secret of the application.redirect_uri: Instructs OIDC provider where to redirect after authentication. This should be your Firezone EXTERNAL_URL + /auth/oidc/<provider_key>/callback/ (e.g. https://firezone.example.com/auth/oidc/okta/callback/).response_type: Set to code.scope: OIDC scopes to obtain from your OIDC provider. This should be set to openid email profile offline_access to provide Firezone with the user’s email in the returned claims.label: The button label text that shows up on your Firezone login screen.This section of the guide is based on Okta’s documentation.
In the Admin Console, go to Applications > Applications and click Create App Integration. Set Sign-in method to OICD – OpenID Connect and Application type to Web application.
On the following screen, configure the following settings:
FirezoneEXTERNAL_URL + /auth/oidc/okta/callback/ (e.g. https://firezone.example.com/auth/oidc/okta/callback/) as an entry to Authorized redirect URIs.Once settings are saved, you will be given a Client ID, Client Secret, and Okta Domain. These 3 values will be used in Step 2 to configure Firezone.
Edit /etc/firezone/firezone.rb to include the options below. Your discovery_document_url will be /.well-known/openid-configuration appended to the end of your okta_domain.
default[‘firezone’][‘authentication’][‘oidc’] = {
okta: {
discovery_document_uri: “https:///.well-known/openid-configuration”,
client_id: “”,
client_secret: “”,
redirect_uri: “https://firezone.example.com/auth/oidc/okta/callback/”,
response_type: “code”,
scope: “openid email profile offline_access”,
label: “Okta”
}
}
Run firezone-ctl reconfigure to update the application. You should now see a Sign in with Okta button at the root Firezone URL.
Okta can limit the users with access to the Firezone app. To do this, go to the Assignments tab of the Firezone App Integration in your Okta Admin Console.
Firezone supports Single Sign-On (SSO) using Azure Active Directory through the generic OIDC connector. This guide will walk you through how to obtain the following config settings required for the integration:
discovery_document_uri: The OpenID Connect provider configuration URI which returns a JSON document used to construct subsequent requests to this OIDC provider.client_id: The client ID of the application.client_secret: The client secret of the application.redirect_uri: Instructs OIDC provider where to redirect after authentication. This should be your Firezone EXTERNAL_URL + /auth/oidc/<provider_key>/callback/ (e.g. https://firezone.example.com/auth/oidc/azure/callback/).response_type: Set to code.scope: OIDC scopes to obtain from your OIDC provider. This should be set to openid email profile offline_access to provide Firezone with the user’s email in the returned claims.label: The button label text that shows up on your Firezone login screen.This guide is adapted from the Azure Active Directory documentation.
Navigate to the Azure Active Directory page on the Azure portal. Select the App registrations link under the Manage menu, click New Registration, and register after entering the following:
Name: FirezoneSupported account types: (Default Directory only - Single tenant)Redirect URI: This should be your firezone EXTERNAL_URL + /auth/oidc/azure/callback/ (e.g. https://firezone.example.com/auth/oidc/azure/callback/). Make sure you include the trailing slash. This will be the redirect_uri value.After registering, open the details view of the application and copy the Application (client) ID. This will be the client_id value. Next, open the endpoints menu to retrieve the OpenID Connect metadata document. This will be the discovery_document_uri value.
Next, select the Certificates & secrets link under the Manage menu and create a new client secret. Copy the client secret – this will be the client_secret value.
Lastly, select the API permissions link under the Manage menu, click Add a permission, and select Microsoft Graph. Add email, openid, offline_access and profile to the required permissions.
Edit /etc/firezone/firezone.rb to include the options below.
default[‘firezone’][‘authentication’][‘oidc’] = {
azure: {
discovery_document_uri: “https://login.microsoftonline.com//v2.0/.well-known/openid-configuration”,
client_id: “”,
client_secret: “”,
redirect_uri: “https://firezone.example.com/auth/oidc/azure/callback/”,
response_type: “code”,
scope: “openid email profile offline_access”,
label: “Azure”
}
}
Run firezone-ctl reconfigure to update the application. You should now see a Sign in with Azure button at the root Firezone URL.
Azure AD allows admins to restrict app access to a subset of users within your organization. See Microsoft’s documentation for more information on how to do this.
Firezone supports Single Sign-On (SSO) using Google Workspace and Cloud Identity through the generic OIDC connector. This guide will walk you through how to obtain the following config settings required for the integration:
discovery_document_uri: The OpenID Connect provider configuration URI which returns a JSON document used to construct subsequent requests to this OIDC provider.client_id: The client ID of the application.client_secret: The client secret of the application.redirect_uri: Instructs OIDC provider where to redirect after authentication. This should be your Firezone EXTERNAL_URL + /auth/oidc/<provider_key>/callback/ (e.g. https://firezone.example.com/auth/oidc/google/callback/).response_type: Set to code.scope: OIDC scopes to obtain from your OIDC provider. This should be set to openid email profile to provide Firezone with the user’s email in the returned claims.label: The button label text that shows up on your Firezone login screenIf this is the first time you are creating a new OAuth client ID, you will be asked to configure a consent screen.
IMPORTANT: Select Internal for user type. This ensures only accounts belonging to users in your Google Workspace Organization can create device configs. DO NOT select External unless you want to enable anyone with a valid Google Account to create device configs.
On the App information screen:
FirezoneThis section is based off Google’s own documentation on setting up OAuth 2.0.
Visit the Google Cloud Console Credentials page page, click + Create Credentials and select OAuth client ID.
On the OAuth client ID creation screen:
Application Type to Web applicationEXTERNAL_URL + /auth/oidc/google/callback/ (e.g. https://firezone.example.com/auth/oidc/google/callback/) as an entry to Authorized redirect URIs.After creating the OAuth client ID, you will be given a Client ID and Client Secret. These will be used together with the redirect URI in the next step.
Firezone supports Single Sign-On (SSO) using OneLogin through the generic OIDC connector. This guide will walk you through how to obtain the following config settings required for the integration:
discovery_document_uri: The OpenID Connect provider configuration URI which returns a JSON document used to construct subsequent requests to this OIDC provider.client_id: The client ID of the application.client_secret: The client secret of the application.redirect_uri: Instructs OIDC provider where to redirect after authentication. This should be your Firezone EXTERNAL_URL + /auth/oidc/<provider_key>/callback/ (e.g. https://firezone.example.com/auth/oidc/onelogin/callback/).response_type: Set to code.scope: OIDC scopes to obtain from your OIDC provider. This should be set to openid email profile to provide Firezone with the user’s email in the returned claims.label: The button label text that shows up on your Firezone login screen.Create a new OIDC connector by visiting Appliances > Custom Connectors.
Firezone<EXTERNAL_URL> + /auth/oidc/onelogin/callback/ (e.g. https://firezone.example.com/auth/oidc/onelogin/callback/Next, click Add App to Connector to create an OIDC application. Visit the SSO tab, then change the token endpoint authentication method to POST.
You will find the values for the config settings required by Firezone on this page as well.
The example below details the config settings required by Firezone to enable SSO through a generic OIDC provider. The configuration file can be found at /etc/firezone/firezone.rb. To pick up changes, run firezone-ctl reconfigure to update the application.
The following config settings are required for the integration:
discovery_document_uri: The OpenID Connect provider configuration URI which returns a JSON document used to construct subsequent requests to this OIDC provider.client_id: The client ID of the application.client_secret: The client secret of the application.redirect_uri: Instructs OIDC provider where to redirect after authentication. This should be your Firezone EXTERNAL_URL + /auth/oidc/<provider_key>/callback/ (e.g. https://firezone.example.com/auth/oidc/google/callback/).response_type: Set to code.scope: OIDC scopes to obtain from your OIDC provider. This should be set to openid email profile or openid email profile offline_access depending on the provider.label: The button label text that shows up on your Firezone login screen.Firezone leverages Chef Omnibus to handle release packaging, process supervision, log management, and more.
The main configuration file is written in Ruby and can be found at /etc/firezone/firezone.rb. Changing this file requires re-running sudo firezone-ctl reconfigure which triggers Chef to pick up the changes and apply them to the running system.
For an exhaustive list of configuration variables and their descriptions, see the configuration file reference.
Your Firezone installation can be managed via the firezone-ctl command, as shown below. Most subcommands require prefixing with sudo.
root@demo:~# firezone-ctl
I don’t know that command.
omnibus-ctl: command (subcommand)
General Commands:
cleanse
Delete all firezone data, and start from scratch.
create-or-reset-admin
Resets the password for admin with email specified by default[‘firezone’][‘admin_email’] or creates a new admin if that email doesn’t exist.
help
Print this help message.
reconfigure
Reconfigure the application.
reset-network
Resets nftables, WireGuard interface, and routing table back to Firezone defaults.
show-config
Show the configuration that would be generated by reconfigure.
teardown-network
Removes WireGuard interface and firezone nftables table.
force-cert-renewal
Force certificate renewal now even if it hasn\’t expired.
stop-cert-renewal
Removes cronjob that renews certificates.
uninstall
Kill all processes and uninstall the process supervisor (data will be preserved).
version
Display current version of Firezone
Service Management Commands:
graceful-kill
Attempt a graceful stop, then SIGKILL the entire process group.
hup
Send the services a HUP.
int
Send the services an INT.
kill
Send the services a KILL.
once
Start the services if they are down. Do not restart them if they stop.
restart
Stop the services if they are running, then start them again.
service-list
List all the services (enabled services appear with a *.)
start
Start services if they are down, and restart them if they stop.
status
Show the status of all the services.
stop
Stop the services, and do not restart them.
tail
Watch the service logs of all enabled services.
term
Send the services a TERM.
usr1
Send the services a USR1.
usr2
Send the services a USR2.
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:
firezone package using your distro’s package manager.firezone-ctl reconfigure to pick up the new changes.firezone-ctl restart to restart services.Occasionally problems arise. If you hit any, please let us know by filing an issue.
0.5.0 introduces a few breaking changes and configuration updates that will need to be addressed. Read more below.
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.
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.80/tcp is reachabledefault['firezone']['ssl']['acme']['enabled'] = true in your config file.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.
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.
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.
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.
Follow the instructions below based on your current version and setup:
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 .
Prior to 0.3.11, Firezone used pre-configured OAuth2 providers. Follow the instructions here to migrate to OIDC.
No action needed. You can follow the instructions here to enable SSO through an OIDC provider.
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.
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.
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.
To completely remove Firezone and its configuration files, run the uninstall.sh script:
sudo /bin/bash -c “$(curl -fsSL https://github.com/firezone/firezone/raw/master/scripts/uninstall.sh)”
Kali Linux 2024.4, the final release of 2024, brings a wide range of updates and…
This Go program applies a lifetime patch to PowerShell to disable ETW (Event Tracing for…
GPOHunter is a comprehensive tool designed to analyze and identify security misconfigurations in Active Directory…
Across small-to-medium enterprises (SMEs) and managed service providers (MSPs), the top priority for cybersecurity leaders…
The free and open-source security platform SecHub, provides a central API to test software with…
Don't worry if there are any bugs in the tool, we will try to fix…