Environment Variables
Most day-to-day config of Firezone can be done via the Firezone Web UI, but for zero-touch deployments we allow to override most of configuration options using environment variables.
Read more about configuring Firezone in our configure guide.
Errors
Firezone will not boot if the configuration is invalid, providing a detailed error message and a link to the documentation for the configuration key with samples how to set it.
Naming
If environment variables are used, the configuration key must be in uppercase. The database variables are the same as the configuration keys.
Precedence
The configuration precedence is as follows:
- Environment variables
- Database values
- Default values
It means that if environment variable is set, it will be used, regardless of the database value, and UI to edit database value will be disabled.
Environment Variable Listing
We recommend setting these in your Docker ENV file ($HOME/.firezone/.env by
default). Required fields in bold.
WebServer
| Env Key | Description | Format | Default |
|---|---|---|---|
| EXTERNAL_URL | The external URL the web UI will be accessible at. Must be a valid and public FQDN for ACME SSL issuance to function. You can add a path suffix if you want to serve firezone from a non-root path, eg: https://firezone.mycorp.com/vpn/. | string | |
| PHOENIX_SECURE_COOKIES | Enable or disable requiring secure cookies. Required for HTTPS. | boolean | true |
| PHOENIX_HTTP_PORT | Internal port to listen on for the Phoenix web server. | integer | 13000 |
| PHOENIX_HTTP_PROTOCOL_OPTIONS | Allows to override Cowboy HTTP server options. Keep in mind though changing those limits can pose a security risk. Other times, browsers and proxies along the way may have equally strict limits, which means the request will still fail or the URL will be pruned. You can see all supported options at https://ninenines.eu/docs/en/cowboy/2.5/manual/cowboy\_http/. | JSON-encoded map | {} |
| PHOENIX_EXTERNAL_TRUSTED_PROXIES | List of trusted reverse proxies. This is used to determine the correct IP address of the client when the application is behind a reverse proxy by skipping a trusted proxy IP from a list of possible source IPs. | JSON-encoded list | "[]" |
| PHOENIX_PRIVATE_CLIENTS | List of trusted clients. This is used to determine the correct IP address of the client when the application is behind a reverse proxy by picking a trusted client IP from a list of possible source IPs. | JSON-encoded list | "[]" |
| HTTP_CLIENT_SSL_OPTS | JSON-encoded ssl options to pass to Erlang's ssl module.. Most users don't need to override many, if any, SSL opts. Most commonly this is to use custom cacert files and TLS versions for self-hosted OIDC providers. | JSON-encoded map | {} |
Database
| Env Key | Description | Format | Default |
|---|---|---|---|
| DATABASE_HOST | PostgreSQL host. | string | postgres |
| DATABASE_PORT | PostgreSQL port. | integer | 5432 |
| DATABASE_NAME | Name of the PostgreSQL database. | string | firezone |
| DATABASE_USER | User that will be used to access the PostgreSQL database. | string | postgres |
| DATABASE_PASSWORD | Password that will be used to access the PostgreSQL database. | string | |
| DATABASE_POOL_SIZE | Size of the connection pool to the PostgreSQL database. | integer | generated |
| DATABASE_SSL_ENABLED | Whether to connect to the database over SSL. If this field is set to true, the database_ssl_opts config must be set too with at least cacertfile option present. | boolean | false |
| DATABASE_SSL_OPTS | SSL options for connecting to the PostgreSQL database. Typically, to enabled SSL you want following options: - cacertfile - path to the CA certificate file;- verify - set to verify_peer to verify the server certificate;- fail_if_no_peer_cert - set to true to require the server to present a certificate;- server_name_indication - specify the hostname to be used in TLS Server Name Indication extension.See Ecto.Adapters.Postgres documentation. For list of all supported options, see the ssl module documentation. | JSON-encoded map | {} |
Admin Setup
Options responsible for initial admin provisioning and resetting the admin password.
For more details see troubleshooting guide.
| Env Key | Description | Format | Default |
|---|---|---|---|
| RESET_ADMIN_ON_BOOT | Set this variable to true to create or reset the admin password every time Firezone starts. By default, the admin password is only set when Firezone is installed.Note: This will not change the status of local authentication. | boolean | false |
| DEFAULT_ADMIN_EMAIL | Primary administrator email. | string | |
| DEFAULT_ADMIN_PASSWORD | Default password that will be used for creating or resetting the primary administrator account. | string |
Secrets and Encryption
Your secrets should be generated during installation automatically and persisted
to .env file.
All secrets should be a base64-encoded string.
| Env Key | Description | Format | Default |
|---|---|---|---|
| GUARDIAN_SECRET_KEY | Secret key used for signing JWTs. | string | |
| DATABASE_ENCRYPTION_KEY | Secret key used for encrypting sensitive data in the database. | string | |
| SECRET_KEY_BASE | Primary secret key base for the Phoenix application. | string | |
| LIVE_VIEW_SIGNING_SALT | Signing salt for Phoenix LiveView connection tokens. | string | |
| COOKIE_SIGNING_SALT | Signing salt for cookies issued by the Phoenix web application. | string | |
| COOKIE_ENCRYPTION_SALT | Encryption salt for cookies issued by the Phoenix web application. | string |
Devices
| Env Key | Description | Format | Default |
|---|---|---|---|
| ALLOW_UNPRIVILEGED_DEVICE_MANAGEMENT | Enable or disable management of devices on unprivileged accounts. | boolean | true |
| ALLOW_UNPRIVILEGED_DEVICE_CONFIGURATION | Enable or disable configuration of device network settings for unprivileged users. | boolean | true |
| VPN_SESSION_DURATION | Optionally require users to periodically authenticate to the Firezone web UI in order to keep their VPN sessions active. | integer | 0 |
| DEFAULT_CLIENT_PERSISTENT_KEEPALIVE | Interval for WireGuard persistent keepalive. If you experience NAT or firewall traversal problems, you can enable this to send a keepalive packet every 25 seconds. Otherwise, keep it disabled with a 0 default value. | integer | 25 |
| DEFAULT_CLIENT_MTU | WireGuard interface MTU for devices. 1280 is a safe bet for most networks. Leave this blank to omit this field from generated configs. | integer | 1280 |
| DEFAULT_CLIENT_ENDPOINT | IPv4, IPv6 address, or FQDN that devices will be configured to connect to. Defaults to this server's FQDN. | one of IP with port, string | generated |
| DEFAULT_CLIENT_DNS | Comma-separated list of DNS servers to use for devices. It can be either an IP address or a FQDN if you intend to use a DNS-over-TLS server. Leave this blank to omit the DNS section from generated configs. | {:array, ",", {:one_of, \[FzHttp.Types.IP, :string]}, \[validate_unique: true]} | [] |
| DEFAULT_CLIENT_ALLOWED_IPS | Configures the default AllowedIPs setting for devices. AllowedIPs determines which destination IPs get routed through Firezone. Specify a comma-separated list of IPs or CIDRs here to achieve split tunneling, or use 0.0.0.0/0, ::/0 to route all device traffic through this Firezone server. | {:array, ",", {:one_of, \[FzHttp.Types.CIDR, FzHttp.Types.IP]}, \[validate_unique: true]} | 0.0.0.0/0, ::/0 |
Limits
| Env Key | Description | Format | Default |
|---|---|---|---|
| MAX_DEVICES_PER_USER | Changes how many devices a user can have at a time. | integer | 10 |
Authentication
| Env Key | Description | Format | Default |
|---|---|---|---|
| LOCAL_AUTH_ENABLED | Enable or disable the local authentication method for all users. | boolean | true |
| DISABLE_VPN_ON_OIDC_ERROR | Enable or disable auto disabling VPN connection on OIDC refresh error. | boolean | false |
| SAML_ENTITY_ID | Entity ID for SAML authentication. | string | urn:firezone.dev:firezone-app |
| SAML_KEYFILE_PATH | Path to the SAML keyfile inside the container. Should be either a PEM or DER-encoded private key, with file extension .pem or .key. | string | /var/firezone/saml.key |
| SAML_CERTFILE_PATH | Path to the SAML certificate file inside the container. Should be either a PEM or DER-encoded certificate, with file extension .crt or .pem. | string | /var/firezone/saml.crt |
| OPENID_CONNECT_PROVIDERS | List of OpenID Connect identity providers configurations. For example: [ { "auto_create_users": false, "id": "google", "label": "google", "client_id": "test-id", "client_secret": "test-secret", "discovery_document_uri": "https://accounts.google.com/.well-known/openid-configuration", "redirect_uri": "https://invalid", "response_type": "response-type", "scope": "oauth email profile" } ]For more details see https://docs.firezone.dev/authenticate/oidc/. | JSON-encoded list | "[]" |
| SAML_IDENTITY_PROVIDERS | List of SAML identity providers configurations. For example: [ { "auto_create_users": false, "base_url": "https://saml", "id": "okta", "label": "okta", "metadata": "<?xml version="1.0"?>...", "sign_metadata": false, "sign_requests": false, "signed_assertion_in_resp": false, "signed_envelopes_in_resp": false } ]For more details see https://docs.firezone.dev/authenticate/saml/. | JSON-encoded list | "[]" |
WireGuard
| Env Key | Description | Format | Default |
|---|---|---|---|
| WIREGUARD_PORT | A port on which WireGuard will listen for incoming connections. | integer | 51820 |
| WIREGUARD_IPV4_ENABLED | Enable or disable IPv4 support for WireGuard. | boolean | true |
| WIREGUARD_IPV4_MASQUERADE | Enable or disable IPv4 masqeurading. | boolean | true |
| WIREGUARD_IPV6_ENABLED | Enable or disable IPv6 support for WireGuard. | boolean | true |
| WIREGUARD_IPV6_MASQUERADE | Enable or disable IPv6 masqeurading. | boolean | true |
Outbound Emails
| Env Key | Description | Format | Default |
|---|---|---|---|
| OUTBOUND_EMAIL_FROM | From address to use for sending outbound emails. If not set, sending email will be disabled (default). | string | generated |
| OUTBOUND_EMAIL_ADAPTER | Method to use for sending outbound email. | One of Elixir.Swoosh.Adapters.AmazonSES, Elixir.Swoosh.Adapters.CustomerIO, Elixir.Swoosh.Adapters.Dyn, Elixir.Swoosh.Adapters.ExAwsAmazonSES, Elixir.Swoosh.Adapters.Gmail, Elixir.Swoosh.Adapters.MailPace, Elixir.Swoosh.Adapters.Mailgun, Elixir.Swoosh.Adapters.Mailjet, Elixir.Swoosh.Adapters.Mandrill, Elixir.Swoosh.Adapters.Postmark, Elixir.Swoosh.Adapters.ProtonBridge, Elixir.Swoosh.Adapters.SMTP, Elixir.Swoosh.Adapters.SMTP2GO, Elixir.Swoosh.Adapters.Sendgrid, Elixir.Swoosh.Adapters.Sendinblue, Elixir.Swoosh.Adapters.Sendmail, Elixir.Swoosh.Adapters.SocketLabs, Elixir.Swoosh.Adapters.SparkPost, Elixir.FzHttpWeb.Mailer.NoopAdapter | Elixir.FzHttpWeb.Mailer.NoopAdapter |
| OUTBOUND_EMAIL_ADAPTER_OPTS | Adapter configuration, for list of options see Swoosh Adapters. | JSON-encoded map | {} |
Connectivity Checks
| Env Key | Description | Format | Default |
|---|---|---|---|
| CONNECTIVITY_CHECKS_ENABLED | Enable / disable periodic checking for egress connectivity. Determines the instance's public IP to populate Endpoint fields. | boolean | true |
| CONNECTIVITY_CHECKS_INTERVAL | Periodicity in seconds to check for egress connectivity. | integer | 43200 |
Telemetry
| Env Key | Description | Format | Default |
|---|---|---|---|
| TELEMETRY_ENABLED | Enable or disable the Firezone telemetry collection. For more details see https://docs.firezone.dev/reference/telemetry/. | boolean | true |
Other
| Env Key | Description | Format | Default |
|---|---|---|---|
| LOGO | The path to a logo image file to replace default Firezone logo. | {:embed, FzHttp.Config.Logo} | `` |