Skip to content
Menu

Configuration#

This page lists the environment variables Drawbridge reads and shows how the environment and the config file fit together.

Environment variables#

The table below is generated from the code: every DRAWBRIDGE_ variable a file under src/ or bin/ reads, with its meaning, its default and the first file that reads it.

Variable Meaning Default Read in
DRAWBRIDGE_CONFIG the per-app config file /etc/drawbridge/drawbridge.yaml src/Command/Env.php
DRAWBRIDGE_COOKIE_SECURE Secure session cookie; false only for a plain-HTTP local rig true src/Command/Env.php
DRAWBRIDGE_METRICS_ALLOW comma list of client IPs/CIDRs allowed to read /metrics; empty trusts no address none src/Command/Env.php
DRAWBRIDGE_METRICS_DIR the shared file-backed metrics store: the signer and the /metrics endpoint keep their counters in this directory, one JSON file per metric family /tmp/drawbridge-metrics src/Metrics/FileStorage.php
DRAWBRIDGE_METRICS_TOKEN bearer token that may read /metrics; empty turns the endpoint off unless an allow list is set none src/Command/Env.php
DRAWBRIDGE_OIDC_CLIENT_SECRET the OpenID Connect client secret; or set DRAWBRIDGE_OIDC_CLIENT_SECRET_FILE to a mounted secret file (the plain variable wins when both are set) none, required src/Config/ClientSecretExpiry.php
DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES the day the client secret expires (YYYY-MM-DD, from Entra); config:validate prints the days left, /metrics serves drawbridge_oidc_client_secret_days_left, and render warns in the container log at 30 days or fewer; never refuses a request, but a value that is not a real date is refused when the config is rendered unset src/Command/Env.php
DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE encrypts state cookies and sessions; 32+ characters; with the default shm store, changing it signs everyone out (the rotation rig run documents why a previous passphrase cannot keep them); with gateway.session_store: redis, setting the old value as DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS keeps everyone signed in, proven by rig/run.sh redis-rotation none, required src/Render/RenderOptions.php
DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS an old passphrase, rendered as the second value (new first, old second); mod_auth_openidc accepts it, but with the default shm store every reload or restart empties the sessions, so it keeps nobody signed in (see the rotation rig run); with gateway.session_store: redis (0.2.1) it keeps the sessions sealed under the old value working while new ones use the new value, proven by rig/run.sh redis-rotation; remove it after session_seconds (8 hours by default), when those sessions have run out anyway; any still left are sent to sign in again unset src/Command/Env.php
DRAWBRIDGE_PORT port Apache listens on (non-root, so above 1024) 8080 src/Command/Env.php
DRAWBRIDGE_PUBLIC_PORT public port when it is not the scheme default empty src/Command/Env.php
DRAWBRIDGE_PUBLIC_SCHEME how browsers reach the gateway; feeds ServerName, X-Forwarded-Proto, the redirect URI https src/Command/Env.php
DRAWBRIDGE_REDIS_PASSWORD the password of the Redis that holds the gateway sessions when gateway.session_store is redis; rendered as a reference to this variable, never as a value, and only when it is set unset src/Command/Env.php
DRAWBRIDGE_REVOCATION_FILE the revocation list drawbridge revoke writes and the gateway reads on every signed-in request; several gateway instances must share one mounted file /tmp/drawbridge/revoked.txt src/Command/Env.php
DRAWBRIDGE_SESSION_CACHE_ENTRIES entries in the shared-memory cache: sessions, nonces, provider metadata (minimum 10; a smaller value or a non-number is refused when the config is rendered) 1000 src/Command/Env.php
DRAWBRIDGE_SIGNING_KEY_FILE ES256 private key for assertions (mounted) /run/drawbridge/signing.key src/Command/Env.php
DRAWBRIDGE_SIGNING_KEY_ID kid in each token header; change it when the key changes drawbridge-1 src/Command/Env.php
DRAWBRIDGE_TRUSTED_PROXIES comma-separated CIDRs allowed to set X-Forwarded-For; empty trusts nobody empty src/Command/Env.php

Example environment#

Every variable from the table, plus the three from .env.example, with placeholder values:

DRAWBRIDGE_CONFIG=/etc/drawbridge/drawbridge.yaml
DRAWBRIDGE_PORT=8080
DRAWBRIDGE_PUBLIC_SCHEME=https
DRAWBRIDGE_PUBLIC_PORT=
DRAWBRIDGE_COOKIE_SECURE=true
DRAWBRIDGE_TRUSTED_PROXIES=
DRAWBRIDGE_OIDC_CLIENT_SECRET=change-me
DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES=2028-11-01
DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE=change-me
DRAWBRIDGE_OIDC_CRYPTO_PASSPHRASE_PREVIOUS=
DRAWBRIDGE_SIGNING_KEY_FILE=/run/drawbridge/signing.key
DRAWBRIDGE_SIGNING_KEY_ID=drawbridge-1
DRAWBRIDGE_SESSION_CACHE_ENTRIES=1000
DRAWBRIDGE_REVOCATION_FILE=/tmp/drawbridge/revoked.txt
DRAWBRIDGE_RUN_DIR=/tmp/drawbridge
DRAWBRIDGE_LOG_LEVEL=warn
DRAWBRIDGE_EVENT_LOG=/dev/stdout
DRAWBRIDGE_METRICS_TOKEN=change-me
DRAWBRIDGE_METRICS_ALLOW=

Client secret expiry#

An Entra client secret expires on a date, and on that date nobody can sign in to any app behind the gateway. Set DRAWBRIDGE_OIDC_CLIENT_SECRET_EXPIRES to the date Entra shows beside the secret (YYYY-MM-DD; it is not a secret) and the gateway counts down to it in whole days from today's UTC date:

State Days left
ok more than 30
soon 30 or fewer
urgent 7 or fewer, the day itself included
expired below 0

It shows in three places, and none of them refuses a request:

  • config:validate prints the date, the days left and the state, then how to rotate: add a new client secret in Entra, set it and its new date, restart the gateway, delete the old secret.
  • /metrics serves drawbridge_oidc_client_secret_days_left, a gauge that goes negative once the date has passed (see Metrics); alert on it at 30 and 7.
  • render, which the entrypoint runs once at each container start, writes one drawbridge: warning: ... line to the container log when the state is soon, urgent or expired.

Unset, nothing changes. A value that is not a real date (12/01/2026, 2026-02-30) is refused by config:validate and by render, so the container does not start with a reminder that would never fire. The owner is whoever owns the app registration in Entra and set the secret; update the date with the secret at every rotation.

The config file#

One YAML (or PHP array) file declares the gateway, the OpenID Connect provider and each app. config/drawbridge.example.yaml is annotated. The Protecting paths guide walks through it: each app's id, host, upstream, mode and default, its public, protected, api and deny paths, and the groups a rule can name (with oidc.groups_claim, the ID token claim that lists them).