# 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](/docs/deploy/configure).

## 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 Key                          | Description                                                                                                                                                                                                                                                                                                                                                                                      | Format            | Default |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------- | ------- |
| **EXTERNAL_URL**                 | The external URL the web UI will be accessible at.<br /> <br />Must be a valid and public FQDN for ACME SSL issuance to function.<br /> <br />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.<br /> <br />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.<br /> <br />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.<br /> <br />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.<br /> <br />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](https://www.erlang.org/doc/man/ssl.html).<br />. 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.<br /> <br />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.<br /> <br />Typically, to enabled SSL you want following options: <br /> - `cacertfile` - path to the CA certificate file;<br /> - `verify` - set to `verify_peer` to verify the server certificate;<br /> - `fail_if_no_peer_cert` - set to `true` to require the server to present a certificate;<br /> - `server_name_indication` - specify the hostname to be used in TLS Server Name Indication extension.<br /> <br />See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options). For list of all supported options, see the [`ssl`](http://erlang.org/doc/man/ssl.html#type-tls_client_option) module documentation. | JSON-encoded map | `{}`      |

### Admin Setup

Options responsible for initial admin provisioning and resetting the admin
password.

For more details see
[troubleshooting guide](/docs/administer/troubleshoot/#admin-login-isnt-working).

| 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.<br /> <br />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](https://www.wireguard.com/quickstart/#nat-and-firewall-traversal-persistence).<br /> <br />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.<br /> <br />It can be either an IP address or a FQDN if you intend to use a DNS-over-TLS server.<br /> <br />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.<br /> <br />AllowedIPs determines which destination IPs get routed through Firezone.<br /> <br />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.<br /> <br />For example:<br /> <br />`[ { "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" } ]`<br /> <br />For more details see https://docs.firezone.dev/authenticate/oidc/. | JSON-encoded list | `"[]"`                        |
| SAML_IDENTITY_PROVIDERS   | List of SAML identity providers configurations.<br /> <br />For example:<br /> <br />`[ { "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 } ]`<br /> <br />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](https://github.com/swoosh/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.<br /> <br />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}` | ``      |
