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):
Core
Secrets configuration
Defguard core requires a random secret strings to properly generate tokens for authentication or generating JWT tokens.
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 longDEFGUARD_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
General configuration
DEFGUARD_URL
: URL of your server instance, defaulthttp://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 ofDEFGUARD_URL
(for example https://defguard.example.com is converted to defguard.example.com).
DEFGUARD_WEBAUTHN_RP_ID
must 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 defaultadmin
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 pathDEFGUARD_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)
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 theSecure
flag; use only in dev environments when serving defguard without HTTPSDEFGUARD_COOKIE_DOMAIN
(optional): set the domain for auth cookies. By default, it's the domain fromDEFGUARD_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 statsDEFGUARD_STATS_PURGE_FREQUENCY
: how often should the cleanup process be performed, default24h
(Humantime documentation)DEFGUARD_STATS_PURGE_THRESHOLD
: age threshold for stats removal, default30d
(Humantime documentation)
Enrollment configuration
DEFGUARD_ENROLLMENT_URL
: external URL of the enrollment proxy server, defaulthttp://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
: gRPC server port, default50055
DEFGUARD_GRPC_CERT
(optional): path to TLS certificate fileDEFGUARD_GRPC_KEY
(optional): path to TLS key fileDEFGUARD_GRPC_URL
: external URL of your instance's gRPC server, defaulthttp://localhost:50055
; used for generating example VPN gateway startup command in Web UI
Proxy connection configuration
DEFGUARD_PROXY_URL
(optional): proxy service gRPC endpoint URLDEFGUARD_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, default8080
DEFGUARD_PROXY_GRPC_PORT
: port the gRPCS server will listen on, default50051
DEFGUARD_PROXY_GRPC_CERT
(optional): path to TLS certificate fileDEFGUARD_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 asDEFGUARD_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
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 supportDEFGUARD_GRPC_URL
,-g <URL>
- defguard server gRPC endpoint URL default is https://localhost:50055DEFGUARD_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 serverDEFGUARD_TOKEN
,-t <TOKEN>
- Token received on defguard after completing network wizardDEFGUARD_GATEWAY_NAME
,--name <NAME>
- (optional) human-readable gateway name that will be displayed in defguard webapp-s, --use-syslog
- enable logging to syslogRUST_LOG
: Logger log level, default:info
, supported:debug
,warn
,error
DEFGUARD_MASQUERADE
- controls whether the gateway automatically applies masquerade NAT firewall rule; defaults tofalse
DEFGUARD_DISABLE_FW_MGMT
- disables all firewall management by the gateway; this overridesDEFGUARD_MASQUERADE
setting; defaults tofalse
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.
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.
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 pageSMARTCARD_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, default15
CLI arguments:
-h
,--help
: Display help message-g <URL>
,--grpc <URL>
: Connect to gRPC server at the given URL-i <ID>
,--id <ID>
: WorkerID, defaultYubiBridge
-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
Last updated
Was this helpful?