Files
firezone/www/docs/reference/configuration-file.mdx
Jamil 643330fcbe Merge blog site into docs, serve at subpaths (#1419)
- [x] Move all docs to be served under `/docs` prefix
- [x] Merge blog articles and serve under `/blog` prefix
- [x] Remove docs side bar for blog content
- [x] Remake marketing site pages in markdown/react
- [x] Serve marketing site under root path
- [x] Update all old links and paths to use new prefixes
2023-02-15 16:52:16 -08:00

187 lines
151 KiB
Plaintext

---
title: Configuration File
sidebar_position: 2
---
# Omnibus configuration options
:::warning
This reference is written for Omnibus-based deployments of Firezone. For
Docker-based deployments visit the [Environment Variables](../env-vars) page.
:::
To configure Omnibus-based deployments of Firezone:
1. Edit `/etc/firezone/firezone.rb` with your changes.
1. Run `sudo firezone-ctl reconfigure` to process the changes and restart affected services.
Read more about configuring Firezone in the [configure guide](/docs/deploy/configure).
## Configuration file reference
Shown below is a complete listing of the configuration options available in
`/etc/firezone/firezone.rb`.
<!-- markdownlint-disable MD033 -->
<!-- markdownlint-disable MD034 -->
| Option | Description | Default Value |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `default['firezone']['external_url']` | URL used to access the web portal of this Firezone instance. | <code>"https://#{node['fqdn'] &vert;&vert; node['hostname']}"</code> |
| `default['firezone']['config_directory']` | Top-level directory for Firezone configuration. | `'/etc/firezone'` |
| `default['firezone']['install_directory']` | Top-level directory to install Firezone to. | `'/opt/firezone'` |
| `default['firezone']['app_directory']` | Top-level directory to install the Firezone web application. | `"#{node['firezone']['install_directory']}/embedded/service/firezone"` |
| `default['firezone']['log_directory']` | Top-level directory for Firezone logs. | `'/var/log/firezone'` |
| `default['firezone']['var_directory']` | Top-level directory for Firezone runtime files. | `'/var/opt/firezone'` |
| `default['firezone']['user']` | Name of unprivileged Linux user most services and files will belong to. | `'firezone'` |
| `default['firezone']['group']` | Name of Linux group most services and files will belong to. | `'firezone'` |
| `default['firezone']['admin_email']` | Email address for initial Firezone user. | `"firezone@localhost"` |
| `default['firezone']['max_devices_per_user']` | Maximum number of devices a user can have. | `10` |
| `default['firezone']['allow_unprivileged_device_management']` | Allows non-admin users to create and delete devices. | `true` |
| `default['firezone']['allow_unprivileged_device_configuration']` | Allows non-admin users to modify device configurations. When disabled, prevents unprivileged users from changing all device fields except for `name` and `description`. | `true` |
| `default['firezone']['egress_interface']` | Interface name where tunneled traffic will exit. If nil, the default route interface will be used. | `nil` |
| `default['firezone']['fips_enabled']` | Enable or disable OpenSSL FIPs mode. | `nil` |
| `default['firezone']['logging']['enabled']` | Enable or disable logging across Firezone. Set to `false` to disable logging entirely. | `true` |
| `default['enterprise']['name']` | Name used by the Chef 'enterprise' cookbook. | `'firezone'` |
| `default['firezone']['install_path']` | Install path used by Chef 'enterprise' cookbook. Should be set to the same as the `install_directory` above. | `node['firezone']['install_directory']` |
| `default['firezone']['sysvinit_id']` | An identifier used in `/etc/inittab`. Must be a unique sequence of 1-4 characters. | `'SUP'` |
| `default['firezone']['authentication']['local']['enabled']` | Enable or disable local email/password authentication. | `true` |
| `default['firezone']['authentication']['disable_vpn_on_oidc_error']` | Disable a user's VPN if an error is detected trying to refresh their OIDC token. | `false` |
| `default['firezone']['authentication']['oidc']` | OpenID Connect config, in the format of `{"provider" => [config...]}` - See [OpenIDConnect documentation](https://hexdocs.pm/openid_connect/readme.html) for config examples. | `{}` |
| `default['firezone']['nginx']['enabled']` | Enable or disable the bundled nginx server. | `true` |
| `default['firezone']['nginx']['ssl_port']` | HTTPS listen port. | `443` |
| `default['firezone']['nginx']['directory']` | Directory to store Firezone-related nginx virtual host configuration. | `"#{node['firezone']['var_directory']}/nginx/etc"` |
| `default['firezone']['nginx']['log_directory']` | Directory to store Firezone-related nginx log files. | `"#{node['firezone']['log_directory']}/nginx"` |
| `default['firezone']['nginx']['log_rotation']['file_maxbytes']` | File size at which to rotate Nginx log files. | `104857600` |
| `default['firezone']['nginx']['log_rotation']['num_to_keep']` | Number of Firezone nginx log files to keep before discarding. | `10` |
| `default['firezone']['nginx']['log_x_forwarded_for']` | Whether to log Firezone nginx `x-forwarded-for` header. | `true` |
| `default['firezone']['nginx']['hsts_header']['enabled']` | Enable or disable [HSTS](https://www.nginx.com/blog/http-strict-transport-security-hsts-and-nginx/). | `true` |
| `default['firezone']['nginx']['hsts_header']['include_subdomains']` | Enable or disable `includeSubDomains` for the HSTS header. | `true` |
| `default['firezone']['nginx']['hsts_header']['max_age']` | Max age for the HSTS header. | `31536000` |
| `default['firezone']['nginx']['redirect_to_canonical']` | Whether to redirect URLs to the canonical FQDN specified above | `false` |
| `default['firezone']['nginx']['cache']['enabled']` | Enable or disable the Firezone nginx cache. | `false` |
| `default['firezone']['nginx']['cache']['directory']` | Directory for Firezone nginx cache. | `"#{node['firezone']['var_directory']}/nginx/cache"` |
| `default['firezone']['nginx']['user']` | Firezone nginx user. | `node['firezone']['user']` |
| `default['firezone']['nginx']['group']` | Firezone nginx group. | `node['firezone']['group']` |
| `default['firezone']['nginx']['dir']` | Top-level nginx configuration directory. | `node['firezone']['nginx']['directory']` |
| `default['firezone']['nginx']['log_dir']` | Top-level nginx log directory. | `node['firezone']['nginx']['log_directory']` |
| `default['firezone']['nginx']['pid']` | Location for nginx pid file. | `"#{node['firezone']['nginx']['directory']}/nginx.pid"` |
| `default['firezone']['nginx']['daemon_disable']` | Disable nginx daemon mode so we can monitor it instead. | `true` |
| `default['firezone']['nginx']['gzip']` | Turn nginx gzip compression on or off. | `'on'` |
| `default['firezone']['nginx']['gzip_static']` | Turn nginx gzip compression on or off for static files. | `'off'` |
| `default['firezone']['nginx']['gzip_http_version']` | HTTP version to use for serving static files. | `'1.0'` |
| `default['firezone']['nginx']['gzip_comp_level']` | nginx gzip compression level. | `'2'` |
| `default['firezone']['nginx']['gzip_proxied']` | Enables or disables gzipping of responses for proxied requests depending on the request and response. | `'any'` |
| `default['firezone']['nginx']['gzip_vary']` | Enables or disables inserting the “Vary: Accept-Encoding” response header. | `'off'` |
| `default['firezone']['nginx']['gzip_buffers']` | Sets the number and size of buffers used to compress a response. If `nil`, nginx default is used. | `nil` |
| `default['firezone']['nginx']['gzip_types']` | MIME types to enable gzip compression for. | `['text/plain', 'text/css','application/x-javascript', 'text/xml', 'application/xml', 'application/rss+xml', 'application/atom+xml', 'text/javascript', 'application/javascript', 'application/json']` |
| `default['firezone']['nginx']['gzip_min_length']` | Minimum file length to enable file gzip compression for. | `1000` |
| `default['firezone']['nginx']['gzip_disable']` | User-agent matcher to disable gzip compression for. | `'MSIE [1-6]\.'` |
| `default['firezone']['nginx']['keepalive']` | Activates cache for connection to upstream servers. | `'on'` |
| `default['firezone']['nginx']['keepalive_timeout']` | Timeout in seconds for keepalive connection to upstream servers. | `65` |
| `default['firezone']['nginx']['worker_processes']` | Number of nginx worker processes. | `node['cpu'] && node['cpu']['total'] ? node['cpu']['total'] : 1` |
| `default['firezone']['nginx']['worker_connections']` | Max number of simultaneous connections that can be opened by a worker process. | `1024` |
| `default['firezone']['nginx']['worker_rlimit_nofile']` | Changes the limit on the maximum number of open files for worker processes. Uses nginx default if nil. | `nil` |
| `default['firezone']['nginx']['multi_accept']` | Whether workers should accept one connection at a time or multiple. | `true` |
| `default['firezone']['nginx']['event']` | Specifies the connection processing method to use inside nginx events context. | `'epoll'` |
| `default['firezone']['nginx']['server_tokens']` | Enables or disables emitting nginx version on error pages and in the “Server” response header field. | `nil` |
| `default['firezone']['nginx']['server_names_hash_bucket_size']` | Sets the bucket size for the server names hash tables. | `64` |
| `default['firezone']['nginx']['sendfile']` | Enables or disables the use of nginx's `sendfile()`. | `'on'` |
| `default['firezone']['nginx']['access_log_options']` | Sets nginx access log options. | `nil` |
| `default['firezone']['nginx']['error_log_options']` | Sets nginx error log options. | `nil` |
| `default['firezone']['nginx']['disable_access_log']` | Disables nginx access log. | `false` |
| `default['firezone']['nginx']['types_hash_max_size']` | nginx types hash max size. | `2048` |
| `default['firezone']['nginx']['types_hash_bucket_size']` | nginx types hash bucket size. | `64` |
| `default['firezone']['nginx']['proxy_read_timeout']` | nginx proxy read timeout. Set to `nil` to use nginx default. | `nil` |
| `default['firezone']['nginx']['client_body_buffer_size']` | nginx client body buffer size. Set to `nil` to use nginx default. | `nil` |
| `default['firezone']['nginx']['client_max_body_size']` | nginx client max body size. | `'250m'` |
| `default['firezone']['nginx']['default']['modules']` | Specify additional nginx modules. | `[]` |
| `default['firezone']['nginx']['enable_rate_limiting']` | Enable or disable nginx rate limiting. | `true` |
| `default['firezone']['nginx']['rate_limiting_zone_name']` | Nginx rate limiting zone name. | `'firezone'` |
| `default['firezone']['nginx']['rate_limiting_backoff']` | Nginx rate limiting backoff. | `'10m'` |
| `default['firezone']['nginx']['rate_limit']` | Nginx rate limit. | `'10r/s'` |
| `default['firezone']['nginx']['ipv6']` | Allow nginx to listen for HTTP requests for IPv6 in addition to IPv4. | `true` |
| `default['firezone']['postgresql']['enabled']` | Enable or disable bundled Postgresql. Set to `false` and fill in the `database` options below to use your own Postgresql instance. | `true` |
| `default['firezone']['postgresql']['username']` | Username for Postgresql. | `node['firezone']['user']` |
| `default['firezone']['postgresql']['data_directory']` | Postgresql data directory. | `"#{node['firezone']['var_directory']}/postgresql/13.3/data"` |
| `default['firezone']['postgresql']['log_directory']` | Postgresql log directory. | `"#{node['firezone']['log_directory']}/postgresql"` |
| `default['firezone']['postgresql']['log_rotation']['file_maxbytes']` | Postgresql log file maximum size before it's rotated. | `104857600` |
| `default['firezone']['postgresql']['log_rotation']['num_to_keep']` | Number of Postgresql log files to keep. | `10` |
| `default['firezone']['postgresql']['checkpoint_completion_target']` | Postgresql checkpoint completion target. | `0.5` |
| `default['firezone']['postgresql']['checkpoint_segments']` | Number of Postgresql checkpoint segments. | `3` |
| `default['firezone']['postgresql']['checkpoint_timeout']` | Postgresql checkpoint timeout. | `'5min'` |
| `default['firezone']['postgresql']['checkpoint_warning']` | Postgresql checkpoint warning time in seconds. | `'30s'` |
| `default['firezone']['postgresql']['effective_cache_size']` | Postgresql effective cache size. | `'128MB'` |
| `default['firezone']['postgresql']['listen_address']` | Postgresql listen address. | `'127.0.0.1'` |
| `default['firezone']['postgresql']['max_connections']` | Postgresql max connections. | `350` |
| `default['firezone']['postgresql']['md5_auth_cidr_addresses']` | Postgresql CIDRs to allow for md5 auth. | `['127.0.0.1/32', '::1/128']` |
| `default['firezone']['postgresql']['port']` | Postgresql listen port. | `15432` |
| `default['firezone']['postgresql']['shared_buffers']` | Postgresql shared buffers size. | `"#{(node['memory']['total'].to_i / 4) / 1024}MB"` |
| `default['firezone']['postgresql']['shmmax']` | Postgresql shmmax in bytes. | `17179869184` |
| `default['firezone']['postgresql']['shmall']` | Postgresql shmall in bytes. | `4194304` |
| `default['firezone']['postgresql']['work_mem']` | Postgresql working memory size. | `'8MB'` |
| `default['firezone']['database']['user']` | Specifies the username Firezone will use to connect to the DB. | `node['firezone']['postgresql']['username']` |
| `default['firezone']['database']['password']` | If using an external DB, specifies the password Firezone will use to connect to the DB. | `'change_me'` |
| `default['firezone']['database']['name']` | Database that Firezone will use. Will be created if it doesn't exist. | `'firezone'` |
| `default['firezone']['database']['host']` | Database host that Firezone will connect to. | `node['firezone']['postgresql']['listen_address']` |
| `default['firezone']['database']['port']` | Database port that Firezone will connect to. | `node['firezone']['postgresql']['port']` |
| `default['firezone']['database']['pool']` | Database pool size Firezone will use. | `[10, Etc.nprocessors].max` |
| `default['firezone']['database']['ssl']` | Whether to connect to the database over SSL. | `false` |
| `default['firezone']['database']['ssl_opts']` | Hash of options to send to the `:ssl_opts` option when connecting over SSL. See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options). | `{}` |
| `default['firezone']['database']['parameters']` | Hash of parameters to send to the `:parameters` option when connecting to the database. See [Ecto.Adapters.Postgres documentation](https://hexdocs.pm/ecto_sql/Ecto.Adapters.Postgres.html#module-connection-options). | `{}` |
| `default['firezone']['database']['extensions']` | Database extensions to enable. | `{ 'plpgsql' => true, 'pg_trgm' => true }` |
| `default['firezone']['phoenix']['enabled']` | Enable or disable the Firezone web application. | `true` |
| `default['firezone']['phoenix']['listen_address']` | Firezone web application listen address. This will be the upstream listen address that nginx proxies. | `'127.0.0.1'` |
| `default['firezone']['phoenix']['port']` | Firezone web application listen port. This will be the upstream port that nginx proxies. | `13000` |
| `default['firezone']['phoenix']['log_directory']` | Firezone web application log directory. | `"#{node['firezone']['log_directory']}/phoenix"` |
| `default['firezone']['phoenix']['log_rotation']['file_maxbytes']` | Firezone web application log file size. | `104857600` |
| `default['firezone']['phoenix']['log_rotation']['num_to_keep']` | Number of Firezone web application log files to keep. | `10` |
| `default['firezone']['phoenix']['crash_detection']['enabled']` | Enable or disable bringing down the Firezone web application when a crash is detected. | `true` |
| `default['firezone']['phoenix']['external_trusted_proxies']` | List of trusted reverse proxies formatted as an Array of IPs and/or CIDRs. | `[]` |
| `default['firezone']['phoenix']['private_clients']` | List of private network HTTP clients, formatted an Array of IPs and/or CIDRs. | `[]` |
| `default['firezone']['wireguard']['enabled']` | Enable or disable bundled WireGuard management. | `true` |
| `default['firezone']['wireguard']['log_directory']` | Log directory for bundled WireGuard management. | `"#{node['firezone']['log_directory']}/wireguard"` |
| `default['firezone']['wireguard']['log_rotation']['file_maxbytes']` | WireGuard log file max size. | `104857600` |
| `default['firezone']['wireguard']['log_rotation']['num_to_keep']` | Number of WireGuard log files to keep. | `10` |
| `default['firezone']['wireguard']['interface_name']` | WireGuard interface name. **Changing this parameter may cause a temporary loss in VPN connectivity**. | `'wg-firezone'` |
| `default['firezone']['wireguard']['port']` | WireGuard listen port. | `51820` |
| `default['firezone']['wireguard']['persistent_keepalive']` | Default PersistentKeepalive setting for generated device configurations. A value of 0 disables. | `0` |
| `default['firezone']['wireguard']['ipv4']['enabled']` | Enable or disable IPv4 for WireGuard network. | `true` |
| `default['firezone']['wireguard']['ipv4']['masquerade']` | Enable or disable masquerade for packets leaving the IPv4 tunnel. | `true` |
| `default['firezone']['wireguard']['ipv4']['network']` | WireGuard network IPv4 address pool. | `'10.3.2.0/24'` |
| `default['firezone']['wireguard']['ipv4']['address']` | WireGuard interface IPv4 address. Must be within WireGuard address pool. | `'10.3.2.1'` |
| `default['firezone']['wireguard']['ipv6']['enabled']` | Enable or disable IPv6 for WireGuard network. | `true` |
| `default['firezone']['wireguard']['ipv6']['masquerade']` | Enable or disable masquerade for packets leaving the IPv6 tunnel. | `true` |
| `default['firezone']['wireguard']['ipv6']['network']` | WireGuard network IPv6 address pool. | `'fd00::3:2:0/120'` |
| `default['firezone']['wireguard']['ipv6']['address']` | WireGuard interface IPv6 address. Must be within IPv6 address pool. | `'fd00::3:2:1'` |
| `default['firezone']['runit']['svlogd_bin']` | Runit svlogd bin location. | `"#{node['firezone']['install_directory']}/embedded/bin/svlogd"` |
| `default['firezone']['ssl']['directory']` | SSL directory for storing generated certs. | `'/var/opt/firezone/ssl'` |
| `default['firezone']['ssl']['email_address']` | Email address to use for self-signed certs and ACME protocol renewal notices. | `'you@example.com'` |
| `default['firezone']['ssl']['acme']['enabled']` | Enable ACME for automatic SSL cert provisioning. | `false` |
| `default['firezone']['ssl']['acme']['server']` | ACME server to use for certificate issuance/renewal. Can be any [valid acme.sh server](https://github.com/acmesh-official/acme.sh/wiki/Server) | `letsencrypt` |
| `default['firezone']['ssl']['acme']['keylength']` | Specify the key type and length for SSL certificates. See [here](https://github.com/acmesh-official/acme.sh#10-issue-ecc-certificates) | `ec-256` |
| `default['firezone']['ssl']['certificate']` | Path to the certificate file for your FQDN. Overrides ACME setting above if specified. If both ACME and this are `nil` a self-signed cert will be generated. | `nil` |
| `default['firezone']['ssl']['certificate_key']` | Path to the certificate file. | `nil` |
| `default['firezone']['ssl']['ssl_dhparam']` | nginx ssl dh_param. | `nil` |
| `default['firezone']['ssl']['country_name']` | Country name for self-signed cert. | `'US'` |
| `default['firezone']['ssl']['state_name']` | State name for self-signed cert. | `'CA'` |
| `default['firezone']['ssl']['locality_name']` | Locality name for self-signed cert. | `'San Francisco'` |
| `default['firezone']['ssl']['company_name']` | Company name self-signed cert. | `'My Company'` |
| `default['firezone']['ssl']['organizational_unit_name']` | Organizational unit name for self-signed cert. | `'Operations'` |
| `default['firezone']['ssl']['ciphers']` | SSL ciphers for nginx to use. | `'ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-DSS-AES128-GCM-SHA256:kEDH+AESGCM:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA384:ECDHE-RSA-AES256-SHA:ECDHE-ECDSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-DSS-AES128-SHA256:DHE-RSA-AES256-SHA256:DHE-DSS-AES256-SHA:DHE-RSA-AES256-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA:AES256-SHA:AES:CAMELLIA:DES-CBC3-SHA:!aNULL:!eNULL:!EXPORT:!DES:!RC4:!MD5:!PSK:!aECDH:!EDH-DSS-DES-CBC3-SHA:!EDH-RSA-DES-CBC3-SHA:!KRB5-DES-CBC3-SHA'` |
| `default['firezone']['ssl']['fips_ciphers']` | SSL ciphers for FIPs mode. | `'FIPS@STRENGTH:!aNULL:!eNULL'` |
| `default['firezone']['ssl']['protocols']` | TLS protocols to use. | `'TLSv1 TLSv1.1 TLSv1.2'` |
| `default['firezone']['ssl']['session_cache']` | SSL session cache. | `'shared:SSL:4m'` |
| `default['firezone']['ssl']['session_timeout']` | SSL session timeout. | `'5m'` |
| `default['firezone']['robots_allow']` | nginx robots allow. | `'/'` |
| `default['firezone']['robots_disallow']` | nginx robots disallow. | `nil` |
| `default['firezone']['outbound_email']['from']` | Outbound email from address. | `nil` |
| `default['firezone']['outbound_email']['provider']` | Outbound email service provider. | `nil` |
| `default['firezone']['outbound_email']['configs']` | Outbound email provider configs. | see `omnibus/cookbooks/firezone/attributes/default.rb` |
| `default['firezone']['telemetry']['enabled']` | Enable or disable anonymized product telemetry. | `true` |
| `default['firezone']['connectivity_checks']['enabled']` | Enable or disable the Firezone connectivity checks service. | `true` |
| `default['firezone']['connectivity_checks']['interval']` | Interval between connectivity checks in seconds. | `3_600` |
<!-- markdownlint-enable MD033 -->
<!-- markdownlint-enable MD034 -->