You're viewing documentation for the legacy version of Firezone, now End-of-Life. View the latest docs here.

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:

  1. Environment variables
  2. Database values
  3. 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 KeyDescriptionFormatDefault
EXTERNAL_URLThe 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_COOKIESEnable or disable requiring secure cookies. Required for HTTPS.booleantrue
PHOENIX_HTTP_PORTInternal port to listen on for the Phoenix web server.integer13000
PHOENIX_HTTP_PROTOCOL_OPTIONSAllows 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.12/manual/cowboy_http2/.
JSON-encoded map{}
PHOENIX_EXTERNAL_TRUSTED_PROXIESList 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_CLIENTSList 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_OPTSJSON-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 KeyDescriptionFormatDefault
DATABASE_HOSTPostgreSQL host.stringpostgres
DATABASE_PORTPostgreSQL port.integer5432
DATABASE_NAMEName of the PostgreSQL database.stringfirezone
DATABASE_USERUser that will be used to access the PostgreSQL database.stringpostgres
DATABASE_PASSWORDPassword that will be used to access the PostgreSQL database.string
DATABASE_POOL_SIZESize of the connection pool to the PostgreSQL database.integergenerated
DATABASE_SSL_ENABLEDWhether 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.
booleanfalse
DATABASE_SSL_OPTSSSL 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 KeyDescriptionFormatDefault
RESET_ADMIN_ON_BOOTSet 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.
booleanfalse
DEFAULT_ADMIN_EMAILPrimary administrator email.string
DEFAULT_ADMIN_PASSWORDDefault 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 KeyDescriptionFormatDefault
GUARDIAN_SECRET_KEYSecret key used for signing JWTs.string
DATABASE_ENCRYPTION_KEYSecret key used for encrypting sensitive data in the database.string
SECRET_KEY_BASEPrimary secret key base for the Phoenix application.string
LIVE_VIEW_SIGNING_SALTSigning salt for Phoenix LiveView connection tokens.string
COOKIE_SIGNING_SALTSigning salt for cookies issued by the Phoenix web application.string
COOKIE_ENCRYPTION_SALTEncryption salt for cookies issued by the Phoenix web application.string

Devices

Env KeyDescriptionFormatDefault
ALLOW_UNPRIVILEGED_DEVICE_MANAGEMENTEnable or disable management of devices on unprivileged accounts.booleantrue
ALLOW_UNPRIVILEGED_DEVICE_CONFIGURATIONEnable or disable configuration of device network settings for unprivileged users.booleantrue
VPN_SESSION_DURATIONOptionally require users to periodically authenticate to the Firezone web UI in order to keep their VPN sessions active.integer0
DEFAULT_CLIENT_PERSISTENT_KEEPALIVEInterval 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.
integer25
DEFAULT_CLIENT_MTUWireGuard interface MTU for devices. 1280 is a safe bet for most networks. Leave this blank to omit this field from generated configs.integer1280
DEFAULT_CLIENT_ENDPOINTIPv4, IPv6 address, or FQDN that devices will be configured to connect to. Defaults to this server's FQDN.one of IP with port, stringgenerated
DEFAULT_CLIENT_DNSComma-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_IPSConfigures 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 KeyDescriptionFormatDefault
MAX_DEVICES_PER_USERChanges how many devices a user can have at a time.integer10

Authentication

Env KeyDescriptionFormatDefault
LOCAL_AUTH_ENABLEDEnable or disable the local authentication method for all users.booleantrue
DISABLE_VPN_ON_OIDC_ERROREnable or disable auto disabling VPN connection on OIDC refresh error.booleanfalse
SAML_ENTITY_IDEntity ID for SAML authentication.stringurn:firezone.dev:firezone-app
SAML_KEYFILE_PATHPath 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_PATHPath 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_PROVIDERSList 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_PROVIDERSList 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 KeyDescriptionFormatDefault
WIREGUARD_PORTA port on which WireGuard will listen for incoming connections.integer51820
WIREGUARD_IPV4_ENABLEDEnable or disable IPv4 support for WireGuard.booleantrue
WIREGUARD_IPV4_MASQUERADEEnable or disable IPv4 masqeurading.booleantrue
WIREGUARD_IPV6_ENABLEDEnable or disable IPv6 support for WireGuard.booleantrue
WIREGUARD_IPV6_MASQUERADEEnable or disable IPv6 masqeurading.booleantrue

Outbound Emails

Env KeyDescriptionFormatDefault
OUTBOUND_EMAIL_FROMFrom address to use for sending outbound emails. If not set, sending email will be disabled (default).stringgenerated
OUTBOUND_EMAIL_ADAPTERMethod 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.NoopAdapterElixir.FzHttpWeb.Mailer.NoopAdapter
OUTBOUND_EMAIL_ADAPTER_OPTSAdapter configuration, for list of options see Swoosh Adapters.JSON-encoded map{}

Connectivity Checks

Env KeyDescriptionFormatDefault
CONNECTIVITY_CHECKS_ENABLEDEnable / disable periodic checking for egress connectivity. Determines the instance's public IP to populate Endpoint fields.booleantrue
CONNECTIVITY_CHECKS_INTERVALPeriodicity in seconds to check for egress connectivity.integer43200

Telemetry

Env KeyDescriptionFormatDefault
TELEMETRY_ENABLEDEnable or disable the Firezone telemetry collection.

For more details see https://docs.firezone.dev/reference/telemetry/.
booleantrue

Other

Env KeyDescriptionFormatDefault
LOGOThe path to a logo image file to replace default Firezone logo.{:embed, FzHttp.Config.Logo}``
Last updated: April 16, 2024