diff --git a/features/setting-up-your-instance/configuration.md b/features/setting-up-your-instance/configuration.md index da7faa8..e71df57 100644 --- a/features/setting-up-your-instance/configuration.md +++ b/features/setting-up-your-instance/configuration.md @@ -16,26 +16,42 @@ You can generate random strings for secrets with e.g.: `openssl rand -base64 55 | tr -d "=+/" | tr -d '\n' | cut -c1-64` {% endhint %} -* `DEFGUARD_LOG_LEVEL` - [Logger](https://crates.io/crates/log) log level, default: `info` -* `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 `http://localhost:8000`, Needed for OpenID discovery endpoint to work correctly. +* `DEFGUARD_LOG_LEVEL`: [Logger](https://crates.io/crates/log) 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](https://docs.rs/humantime/latest/humantime/struct.Duration.html)) +* `DEFGUARD_MFA_CODE_TIMEOUT`: Email code lifetime period, default: `60s` ([Humantime documentation](https://docs.rs/humantime/latest/humantime/struct.Duration.html)) +* `DEFGUARD_SESSION_TIMEOUT`: Session lifetime period, default: `7d` ([Humantime documentation](https://docs.rs/humantime/latest/humantime/struct.Duration.html)) +* `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](https://docs.rs/humantime/latest/humantime/struct.Duration.html)) * `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). - {% hint style="warning" %} `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.` {% endhint %} -* `DEFGUARD_OPENID_KEY` : Path to a private key file used for OAuth2/OpenID, [more here](https://defguard.gitbook.io/defguard/features/setting-up-your-instance/docker-compose#openid-rsa-setup) +* `DEFGUARD_OPENID_KEY`: Path to a private key file used for OAuth2/OpenID, [more here](https://defguard.gitbook.io/defguard/features/setting-up-your-instance/docker-compose#openid-rsa-setup) * `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 {% hint style="warning" %} @@ -44,32 +60,32 @@ If you want to access your defguard instance without TLS (using an `http://` URL This is of course not recommended in production but can be useful when testing without a full reverse proxy setup. {% endhint %} -* `DEFGUARD_COOKIE_INSECURE` : set cookies without the `Secure` flag; use only in dev environments when serving defguard without HTTPS +* `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](../forward-auth.md). ### 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 threshold for stats removal, default `30d` +* `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](https://docs.rs/humantime/latest/humantime/struct.Duration.html)) +* `DEFGUARD_STATS_PURGE_THRESHOLD`: age threshold for stats removal, default `30d` ([Humantime documentation](https://docs.rs/humantime/latest/humantime/struct.Duration.html)) ### 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 a user uses the token to start the enrollment process, default: `10m` +* `DEFGUARD_ENROLLMENT_TOKEN_TIMEOUT`: how long is the enrollment token valid for use, default: `24h` ([Humantime documentation](https://docs.rs/humantime/latest/humantime/struct.Duration.html)) +* `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](https://docs.rs/humantime/latest/humantime/struct.Duration.html)) ### Password reset configuration -* `DEFGUARD_PASSWORD_RESET_TOKEN_TIMEOUT` : how long is the password reset token valid for use, default: `24h` -* `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` +* `DEFGUARD_PASSWORD_RESET_TOKEN_TIMEOUT`: how long is the password reset token valid for use, default: `24h` ([Humantime documentation](https://docs.rs/humantime/latest/humantime/struct.Duration.html)) +* `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](https://docs.rs/humantime/latest/humantime/struct.Duration.html)) ### gRPC server configuration -* `DEFGUARD_GRPC_PORT` : gRPC server port, default `50055` +* `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 +* `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 @@ -80,8 +96,8 @@ This is of course not recommended in production but can be useful when testing w ### Environmental variables -* `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_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 @@ -89,23 +105,23 @@ This is of course not recommended in production but can be useful when testing w ### 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` +* `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 `, `--grpc ` : Connect to gRPC server at the given URL -* `-i ` , `--id ` : WorkerID, default `YubiBridge` -* `-d` , `--debug` : Enable debug mode -* `-t ` , `--tmpdir ` : GnuPG home directory, default: `tmp` -* `-p ` , `--provision ` : Provision YubiKey with the following data -* `-w ` , `--worker-token ` : Secret worker token to secure gRPC communication, available on provisioners page -* `-c ` , `--command ` : Run command after provisioning and pass created keys as arguments +* `-h` , `--help`: Display help message +* `-g `, `--grpc `: Connect to gRPC server at the given URL +* `-i ` , `--id `: WorkerID, default `YubiBridge` +* `-d` , `--debug`: Enable debug mode +* `-t ` , `--tmpdir `: GnuPG home directory, default: `tmp` +* `-p ` , `--provision `: Provision YubiKey with the following data +* `-w ` , `--worker-token `: Secret worker token to secure gRPC communication, available on provisioners page +* `-c ` , `--command `: Run command after provisioning and pass created keys as arguments ## Gateway Configuration