Configuration

Here you can find a list of all configurable things through environmental variables in Defguard core server, YubiBridge client and Gateway client.

Core

Environment files

Environment variables that are not already set are loaded from .env files by dotenvy crate. Default .env file can be overwritten by creating .env.local which is not tracked by git.

Core configuration

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

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

  • DEFGUARD_LOG_LEVEL: Logger log level, default: info

  • 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)

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

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

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

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

  • DEFGUARD_WG_SERVICE_URL: WireGuard service instance to connect to, default: http://wireguard:50051

  • DEFGUARD_URL: URL of your server instance, default http://localhost:8000, Needed for OpenID discovery endpoint to work correctly.

  • 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_OPENID_KEY: Path to a private key file used for OAuth2/OpenID, more here

  • 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

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

  • 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: gRPC server port, default 50055

  • 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 HTTPS

Proxy service

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

  • DEFGUARD_PROXY_HTTP_PORT: port the API server 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

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

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_USERSPACE , -u - Use userspace wireguard implementation, useful on systems without native wireguard support

DEFGUARD_GRPC_URL , -g <URL> - defguard server gRPC endpoint URL default is https://localhost:50055

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_TOKEN ,-t <TOKEN> - Token received on defguard after completing network wizard

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

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

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"
PreviousSecuring gRPC communicationNextDocker images and tags

Last updated