Defguard
Search
⌃K
Comment on page

Configuration

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

Core server

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_SECRET_KEY - Rocket secret_key.
  • DEFGUARD_DATABASE_URL : Your database URL, default: sqlite::memory
  • DEFGUARD_HTTP_PORT : Core server port, default: 8000
  • 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 localhost:8000, Needed for OpenID discovery endpoint to work correctly.
  • DEFGUARD_WEBAUTHN_RP_ID (optional): Relying on party ID and relying on 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_DEFAULT_ADMIN_PASSWORD: Password for the default admin user, default: pass123

Auth cookies configuration

  • 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
  • DEFGUARD_STATS_PURGE_THRESHOLD : age treshold for stats removal, default 30d

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
  • DEFGUARD_ENROLLMENT_SESSION_TIMEOUT : how long in the enrollment session valid after user uses the token to start the enrollment process, default: 10m

gRPC configuration

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

Enrollment service

Environmental variables

  • DEFGUARD_PROXY_HTTP_PORT : port the API server will listen on, default 8080
  • DEFGUARD_PROXY_UPSTREAM_GRPC_URL : core server gRPC endpoint URL, default http://localhost:50055/
  • DEFGUARD_PROXY_GRPC_CA (optional): path to TLS certificate file, required if connecting to core gRPC service with HTTPS

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_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
# 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
# Example: Allow all traffic through WireGuard interface:
#pre_up = "iptables -A INPUT -i wg0 -j ACCEPT; iptables -A FORWARD -i wg0 -j ACCEPT; iptables -A OUTPUT -o wg0 -j ACCEPT"
​
# Optional: Command which will be run after bringing interface up
# Example: Add a default route after WireGuard interface is 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; iptables -D FORWARD -i wg0 -j ACCEPT; iptables -D OUTPUT -o 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"
Previous
One-line install script
Next
Docker Compose
Last modified 17h ago