Omnibus configuration options

This reference is written for Omnibus-based deployments of Firezone. For Docker-based deployments visit the Environment Variables page.

To configure Omnibus-based deployments of Firezone:

  1. Edit /etc/firezone/firezone.rb with your changes.
  2. Run sudo firezone-ctl reconfigure to process the changes and restart affected services.

Read more about configuring Firezone in the configure guide.

Configuration file reference

Shown below is a complete listing of the configuration options available in /etc/firezone/firezone.rb.

OptionDescriptionDefault Value
default['firezone']['external_url']URL used to access the web portal of this Firezone instance."https://#{node['fqdn'] || node['hostname']}"
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 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.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 abovefalse
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.{}
default['firezone']['database']['parameters']Hash of parameters to send to the :parameters option when connecting to the database. See Ecto.Adapters.Postgres documentation.{}
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 serverletsencrypt
default['firezone']['ssl']['acme']['keylength']Specify the key type and length for SSL certificates. See hereec-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