Configuration

Here you can find a list of all configurable things through environmental variables, options or configuration files for all Defguard components (each top-level section for a specific component):

If you are using one-line installation, everything is generated and configured automatically.

Core

Secrets configuration

Defguard core requires a random secret strings to properly generate tokens for authentication or generating JWT tokens.

You can generate random strings for secrets with e.g.:

openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-64

  • DEFGUARD_AUTH_SECRET: JWT secret key for encrypting user tokens, default: DEFGUARD_AUTH_SECRET

  • DEFGUARD_SECRET_KEY: JWT secret key for encrypting private cookies; must be at least 64 characters long

  • DEFGUARD_GATEWAY_SECRET: JWT secret key for encrypting Gateway tokens, default: DEFGUARD_GATEWAY_SECRET

  • DEFGUARD_YUBIBRIDGE_SECRET: JWT secret key for encrypting YubiBridge tokens, default: DEFGUARD_YUBIBRIDGE_SECRET

  • DEFGUARD_OPENID_KEY: this is optional if you want to use HMAC algorithm for OIDC token validation, if you want to use RSA please provide a path to a private key file used for OAuth2/OpenID, more here.

General configuration

  • DEFGUARD_URL: URL of your server instance, default http://localhost:8000. This is the address at which the Web UI you use to administer your instance and the REST API endpoints are available (both of those are served by Defguard core on port 8000 by default; port can be configured with DEFGUARD_HTTP_PORT env variable).This URL is needed to be exact since it's needed for OpenID discovery endpoint to work correctly, so if you have a reverse-proxy, custom domain, please provide an actual URL for Defguard core.

  • DEFGUARD_GATEWAY_DISCONNECTION_NOTIFICATION_TIMEOUT: If gateway is disconnected for this long, send email notification, default: 10m (Humantime documentation)

  • DEFGUARD_WEBAUTHN_RP_ID (optional): Relying party ID and relying party origin for WebAuthn used for MFA. By default, it's generated by using a base domain of DEFGUARD_URL (for example https://defguard.example.com is converted to defguard.example.com).

DEFGUARD_WEBAUTHN_RP_IDmust be an effective domain of DEFGUARD_URL (for example if hosting at https://idm.example.com, rp_id must be idm.example.com, example.com or com). Changing DEFGUARD_WEBAUTHN_RP_ID will potentially break all your existing Webauthn credentials.

  • DEFGUARD_ADMIN_GROUPNAME: Name of the administrator group, default: admin

  • DEFGUARD_USERADMIN_GROUPNAME: Name of the user administrator group, default: useradmin

  • DEFGUARD_VPN_GROUPNAME: Name of the vpn group, default: vpn

  • DEFGUARD_DEFAULT_ADMIN_PASSWORD: Password for the default admin user, default: pass123

  • DEFGUARD_LOG_LEVEL: Logger log level, default: info, supported: debug, warn, error

  • DEFGUARD_HTTP_PORT: Core server port, default: 8000

  • DEFGUARD_LOG_FILE: Log file path

  • DEFGUARD_AUTH_COOKIE_TIMEOUT: Cookie lifetime period, default: 7d (Humantime documentation)

  • DEFGUARD_MFA_CODE_TIMEOUT: Email code lifetime period, default: 60s (Humantime documentation)

  • DEFGUARD_SESSION_TIMEOUT: Session lifetime period, default: 7d (Humantime documentation)

  • HTTP_BIND_ADDRESS: The IP address that the HTTP should bind to (available since version 1.5.0)

  • GRPC_BIND_ADDRESS: The IP address that the gRPC should bind to (available since version 1.5.0)

Database configuration

Following env variables can be used to setup your database access:

  • DEFGUARD_DB_HOST

  • DEFGUARD_DB_PORT

  • DEFGUARD_DB_NAME

  • DEFGUARD_DB_USER

  • DEFGUARD_DB_PASSWORD

Auth cookies configuration

If you want to access your Defguard instance without TLS (using an http:// URL) you MUST enable insecure cookies by setting DEFGUARD_COOKIE_INSECURE to true.

This is of course not recommended in production but can be useful when testing without a full reverse proxy setup.

  • DEFGUARD_COOKIE_INSECURE: set cookies without the Secure flag; use only in dev environments when serving Defguard without HTTPS

  • DEFGUARD_COOKIE_DOMAIN (optional): set the domain for auth cookies. By default, it's the domain from DEFGUARD_URL. Must be changed to base URL if you want to use forward auth.

Stats cleanup configuration

  • DEFGUARD_DISABLE_STATS_PURGE: disable periodic cleanup of old Wireguard stats

  • DEFGUARD_STATS_PURGE_FREQUENCY: how often should the cleanup process be performed, default 24h (Humantime documentation)

  • DEFGUARD_STATS_PURGE_THRESHOLD: age threshold for stats removal, default 30d (Humantime documentation)

Enrollment configuration

  • DEFGUARD_ENROLLMENT_URL: external URL of the enrollment proxy server, default http://localhost:8080 - this URL is sent in enrollment emails as well as displayed when configuring the desktop client - thus must be to the actual URL you have configured the proxy Web UI to be accessible at, otherwise the enrollment or desktop client configuration will not work.

  • DEFGUARD_ENROLLMENT_TOKEN_TIMEOUT: how long is the enrollment token valid for use, default: 24h (Humantime documentation)

  • DEFGUARD_ENROLLMENT_SESSION_TIMEOUT: how long in the enrollment session valid after a user uses the token to start the enrollment process, default: 10m (Humantime documentation)

Password reset configuration

  • DEFGUARD_PASSWORD_RESET_TOKEN_TIMEOUT: how long is the password reset token valid for use, default: 24h (Humantime documentation)

  • DEFGUARD_PASSWORD_RESET_SESSION_TIMEOUT: how long in the password reset session valid after a user uses the token to start the enrollment process, default: 10m (Humantime documentation)

gRPC server configuration

More on that in this help page.

  • DEFGUARD_GRPC_PORT: the port on which the gRPC server should listen, default is 50055. This port is used by Defguard Gateways to connect to your Core instance.

  • DEFGUARD_GRPC_CERT (optional): path to TLS certificate file

  • DEFGUARD_GRPC_KEY(optional): path to TLS key file

  • DEFGUARD_GRPC_URL: external URL of your instance's gRPC server, default http://localhost:50055; used for generating example VPN gateway startup command in Web UI

Proxy connection configuration

  • DEFGUARD_PROXY_URL (optional): proxy service gRPC endpoint URL

  • DEFGUARD_PROXY_GRPC_CA(optional): path to TLS root certificate file, required if connecting to proxy gRPC service with a custom CA (More on that in this help page.)

Proxy service

Here are proxy ENV variables. gRPC configuration is described more on this help page.

  • DEFGUARD_PROXY_HTTP_PORT: port the proxy API server and Web UI will listen on, default 8080

  • DEFGUARD_PROXY_GRPC_PORT: port the gRPCS server will listen on, default 50051

  • DEFGUARD_PROXY_GRPC_CERT (optional): path to TLS certificate file

  • DEFGUARD_PROXY_GRPC_KEY(optional): path to TLS key file. More on that in this help page.

  • DEFGUARD_PROXY_URL - if you wish to use External OIDC enrollment/desktop client configuration, please set this value to the same as DEFGUARD_ENROLLMENT_URL in core. This is the address at which the proxy Web UI is available.

  • DEFGUARD_PROXY_LOG_LEVEL : Logger log level, default: info, supported: debug, warn, error

  • HTTP_BIND_ADDRESS: The IP address that the HTTP should bind to (available since version 1.5.0)

  • GRPC_BIND_ADDRESS: The IP address that the gRPC should bind to (available since version 1.5.0)

Gateway Configuration

Environmental variables / Arguments

If you're using docker image you can pass this value as environmental variables or on binary you can pass them as arguments

  • DEFGUARD_GRPC_URL , -g <URL> - Defguard Core gRPC endpoint URL. This is used by the gateway to connect to your Defguard Core instance. If you configured the DEFGUARD_GRPC_URL variable on your Core instance before (as described in the gRPC server configuration section), use the same value here. Otherwise, provide an URL that will allow the Gateway to reach your Core instance, e.g. http://localhost:50055 if both Core and Gateway are running on the same host.

  • DEFGUARD_TOKEN ,-t <TOKEN> - Token displayed in the Defguard Core web UI after completing the network wizard. It can be copied from the "Authentication Token" section on the Location Settings page.

  • DEFGUARD_USERSPACE , -u - Use userspace wireguard implementation, useful on systems without native wireguard support

  • DEFGUARD_GRPC_CA - path to ca file more on this topic on this help page.

  • DEFGUARD_STATS_PERIOD ,-p <SECONDS> - Defines how often (seconds) should interface statistics be sent to the Defguard server

  • DEFGUARD_GATEWAY_NAME, --name <NAME> - (optional) human-readable gateway name that will be displayed in Defguard webapp

  • -s, --use-syslog - enable logging to syslog

  • RUST_LOG : Logger log level, default: info, supported: debug, warn, error

  • DEFGUARD_MASQUERADE - controls whether the gateway automatically applies masquerade NAT firewall rule; defaults to false

  • DEFGUARD_DISABLE_FW_MGMT - disables all firewall management by the gateway; this overrides DEFGUARD_MASQUERADE setting; defaults to false

DEFGUARD_DISABLE_FW_MGMT is meant as a workaround for running in incompatible environments, where our default firewall integration is not supported.

As a consequence, enabling this option disables ACL functionality on a given gateway.

  • HTTP_BIND_ADDRESS: The IP address that the HTTP should bind to (available since version 1.5.0)

Executing custom commands on VPN up/down

The following env variables or gateway arguments define which commands gateway will run before / after it wil bring up / down the VPN.

It's usfull for exaple to use those commands to launch custom firewall commands or scripts that do various operations needed to be done on those ocasions.

Defguard is built with highest security standards in mind, thus the options below accept only a full path to one command and it's arguments.

If you would like to have multiple commands run, you can create a shell script which will define the acceptable and preferred shell you would like to use and then all the commands you like to execute.

PRE_UP , --pre-up, - Command to run before bringing up the interface. If you want to run a shell script, you should pass it's path to your shell, for example: /bin/sh -c /path/to/script

POST_UP , --post-up, - Command to run after bringing up the interface.

PRE_DOWN , --pre-down, - Command to run before bringing down the interface.

POST_DOWN , --post-down, - Command to run after bringing down the interface.

If logging to syslog please remember to configure your syslog deamon accordingly, so that a dedicated logfile is created or the messages are included in the main system log.

Config file

Gateway configuration can also be read from a file by using a --config CLI option. Example file contents:

# This is an example config file for Defguard VPN gateway
# To use it fill in actual values for your deployment below

# Required: secret token generated by Defguard
# NOTE: must replace default with actual value
token = "<your_gateway_token>"
# Required: Defguard server gRPC endpoint URL
# NOTE: must replace default with actual value
grpc_url = "<defguard_grpc_url>"
# Optional: gateway name which will be displayed in Defguard web UI
name = "Gateway on server X"
# Required: use userspace Wireguard implementation (e.g. wireguard-go)
userspace = false
# Optional: path to TLS cert file - more in gRPC SSL communication help page
# in our documentation.
# grpc_ca = cert.pem
# Required: how often should interface stat updates be sent to Defguard server (in seconds)
stats_period = 60
# Required: name of Wireguard interface
ifname = "wg0"
# Optional: write PID to this file
# pidfile = defguard-gateway.pid
# Required: enable logging to syslog
use_syslog = false
# Required: which syslog facility to use
syslog_facility = "LOG_USER"
# Required: which socket to use for logging
syslog_socket = "/var/run/log"

# Optional: Command which will be run before bringing interface up
#pre_up = "/path/to/script.sh"

# Optional: Command which will be run after bringing interface up
#post_up = "ip route add default via 192.168.1.1 dev wg0

# Optional: Command which will be run before bringing interface down
# Example: Remove WireGuard-related firewall rules before interface is taken down:
#pre_down = "iptables -D INPUT -i wg0 -j ACCEPT"

# Optional: Command which will be run after bringing interface down
# Example: Remove the default route after WireGuard interface is down:
#post_down = "ip route del default via 192.168.1.1 dev wg0"

YubiBridge configuration

Environmental variables

  • LOG_LEVEL: Log messages level, default: INFO, available levels: CRITICAL, ERROR, WARNIG, INFO, DEBUG

  • WORKER_ID: Name of your YubiBridge displayed on Defguard website, default: YubiBridge

  • DEFGUARD_TOKEN: - Secret worker token to secure gRPC communication, available on provisioners page

  • SMARTCARD_RETRIES: Number of retries in case provisioning failed, default: 1

  • JOB_INTERVAL: Defines how often(seconds) YubiBridge checks Defguard for new jobs, default: 2

  • SMARTCARD_RETRY_INTERVAL: Defines the number of seconds between trying to provision YubiKey again, default 15

CLI arguments:

  • -h , --help: Display help message

  • -g <URL>, --grpc <URL>: Connect to gRPC server at the given URL

  • -i <ID> , --id <ID>: WorkerID, default YubiBridge

  • -d , --debug: Enable debug mode

  • -t <TMPDIR> , --tmpdir <TMPDIR>: GnuPG home directory, default: tmp

  • -p <first_name> <last_name> <email> , --provision <first_name> <last_name> <email>: Provision YubiKey with the following data

  • -w <token> , --worker-token <token>: Secret worker token to secure gRPC communication, available on provisioners page

  • -c <command> , --command <command>: Run command after provisioning and pass created keys as arguments

PreviousHealth checkNextLicense

Last updated

Was this helpful?