Environment Variables Reference

Environment Variables Reference

This is the complete reference for all environment variables you can configure on a Broch server deployment.

Core Configuration

BROCH_MASTER_KEY and a database connection are required to start — the server will not boot without them. Your identity provider is also a boot input: the server starts without it, but no one can sign in until it’s set. The license is not a boot input — it’s activated in the app on first sign-in. See First-Run Setup.

Variable	Description	Default	Secret
ASPNETCORE_ENVIRONMENT	ASP.NET Core environment name	Production	No
ASPNETCORE_URLS	HTTP listener binding (TLS terminated at ingress)	http://+:8080	No
BROCH_MASTER_KEY	At-rest encryption root. Wraps the Data Protection key ring. Generated at provision time or by you, depending on platform — see below	—	Yes
API__WILDCARDHOSTNAME	Wildcard hostname for tunnel subdomains (e.g., tunnels.company.com)	—	No

At-Rest Encryption (BROCH_MASTER_KEY)

BROCH_MASTER_KEY is the customer-owned root of Broch’s at-rest encryption. It derives the key-encryption key that wraps the ASP.NET Data Protection key ring, which in turn protects the encrypted IdP refresh tokens, the persisted license token, and usage counters stored in your database. The server will not start without it.

• Generated in your environment. The broch-deploy Terraform modules (AWS, Azure, DigitalOcean) generate the value at provision time and store it in your platform’s secret store (Secrets Manager, Key Vault, the droplet’s root-only .env). On Docker Compose and the Azure Bicep template, you generate it once — openssl rand -base64 48 — and keep it in your env file or deployment parameters. Either way it stays in your environment, and Broch never receives a copy — see Security.
• Treat it like a database master password. Keep it in your secret store and back it up there. Together with your database connection, these are the secrets the server strictly requires to start.
• Rotation / loss is recoverable, not catastrophic. If the key is changed or lost, previously wrapped state becomes unreadable; Broch detects this, mints a fresh key ring, and the affected paths self-heal — users re-authenticate, the license token re-activates on the next refresh, and usage counters reset. No instance is ever bricked. Rotating the key therefore forces a one-time re-authentication for active users.
• Unchanged across upgrades. Supply the same BROCH_MASTER_KEY when you upgrade — it lives in your secret store, so this is automatic. The key ring stays readable and nobody re-authenticates. Changing it during an upgrade is what triggers the one-time re-auth above, not the upgrade itself. See Upgrading.

Database

Required — The application will not start without a database connection.

Variable	Description	Default	Secret
DATABASE__PROVIDER	Database provider (only PostgreSQL is supported)	PostgreSQL	No
ConnectionStrings__DefaultConnection	PostgreSQL connection string	—	Yes

Example: Host=localhost;Database=broch;Username=postgres;Password=secret

Authentication

Part of the boot floor. Configure your identity provider here. The server starts without it, but no one can sign in until it’s set — there is no in-app bootstrap; the first admin authenticates through the IdP, and admin access is granted by a role in AUTHENTICATION__ADMINROLES. Once AUTHENTICATION__PROVIDER is set, the provider-specific values below are required for that provider.

Variable	Description	Default	Secret
AUTHENTICATION__PROVIDER	Identity provider type: AzureAd, EntraExternalId, Auth0, Okta, or Oidc (any standards-compliant OIDC issuer — set AUTHENTICATION__AUTHORITY)	—	No
AUTHENTICATION__CLIENTID	OAuth client ID from your IdP	—	No
AUTHENTICATION__CLIENTSECRET	OAuth client secret from your IdP	—	Yes
AUTHENTICATION__ADMINROLES	Comma-separated role names that grant admin access	—	No
BROCH_AUTH_CONFIG_RESET	Break-glass: clears the persisted in-app IdP configuration at boot so the environment values above apply again. Set, restart, recover, then remove — see Recovering From a Broken IdP Configuration	—	No

Provider-Specific Variables

Azure Entra ID:

Variable	Description	Default
AUTHENTICATION__TENANTID	Azure tenant ID	—
AUTHENTICATION__INSTANCE	Azure login endpoint	https://login.microsoftonline.com/

Auth0:

Variable	Description	Default
AUTHENTICATION__DOMAIN	Auth0 domain (e.g., contoso.auth0.com)	—
AUTHENTICATION__AUDIENCE	OAuth audience identifier	Falls back to Client ID
AUTHENTICATION__SCOPES	Additional OAuth scopes, appended to the always-requested openid,profile,email,offline_access	—

Okta:

Variable	Description	Default
AUTHENTICATION__DOMAIN	Okta organization domain (e.g., contoso.okta.com)	—
AUTHENTICATION__AUDIENCE	OAuth audience identifier	Falls back to Client ID
AUTHENTICATION__SCOPES	Additional OAuth scopes, appended to the always-requested openid,profile,email,offline_access	—

Generic OIDC (Oidc): for any standards-compliant issuer not listed above.

Variable	Description	Default
AUTHENTICATION__AUTHORITY	Issuer URL — the base that serves /.well-known/openid-configuration. Required for Oidc.	—
AUTHENTICATION__SCOPES	Additional OAuth scopes, appended to the always-requested openid,profile,email,offline_access	—

API & Networking

Variable	Description	Default	Required
API__URLSEPARATOR	Separator between tunnel name and hostname: . (dot) or - (hyphen)	.	No

Licensing & Central Server

The license itself is not configured here — it’s activated in-app (see Licensing). The SSH host key for tunnel transport is generated by the server and stored encrypted in your database; it needs no configuration.

Variable	Description	Default	Required
CENTRALSERVER__VALIDATIONTIMEOUTSECONDS	Timeout for license activation/refresh requests (seconds)	30	No

Logging (Optional)

Structured JSON always goes to stdout — collect it with your container platform’s log driver. A provider is an additional off-box sink, never a replacement for stdout.

Variable	Description	Default	Required
BROCHLOGGING__PROVIDER	Additional log sink: DataDog, Seq, OpenTelemetry	(stdout only)	No
BROCHLOGGING__MINIMUMLEVEL	Minimum log level: Verbose, Debug, Information, Warning, Error, Fatal	Information	No

DataDog Logging

Variable	Description	Default
BROCHLOGGING__DATADOG__APIKEY	DataDog API key	—
BROCHLOGGING__DATADOG__SERVICENAME	DataDog service name tag	broch-server
BROCHLOGGING__DATADOG__ENVIRONMENT	DataDog environment tag	production
BROCHLOGGING__DATADOG__SITE	DataDog site: datadoghq.com (US) or datadoghq.eu (EU)	datadoghq.com

Seq Logging

Variable	Description	Default
BROCHLOGGING__SEQ__SERVERURL	Seq server URL	http://localhost:5341

OpenTelemetry (OTLP) Logging

Routes structured logs to any OTLP-compatible collector — the vendor-neutral path into your SIEM or observability stack.

Variable	Description	Default
BROCHLOGGING__OTLP__ENDPOINT	OTLP collector endpoint (e.g., http://collector:4317 for gRPC, http://collector:4318/v1/logs for HTTP)	—
BROCHLOGGING__OTLP__PROTOCOL	OTLP transport: grpc or httpprotobuf	grpc
BROCHLOGGING__OTLP__HEADERS	Comma-separated Key=Value headers sent with every export, for collectors that require authentication (e.g., Authorization=Bearer <token>). Treat as a secret	—

Health Check Endpoints

Use these endpoints to monitor server health and readiness in your deployment:

Endpoint	Purpose	Returns
GET /healthz	Liveness probe — is the process running?	Always 200 if running
GET /healthz/ready	Readiness probe — are the license and auth config valid?	200 when valid, 503 otherwise
GET /api/configuration	Client version policy (for CLI/app version compatibility)	JSON with version requirements

Gate orchestrator and load-balancer health checks on /healthz (liveness). /healthz/ready is license-gated — a fresh server returns 503 until an admin activates a license, so gating traffic on it would deadlock first-run setup. Reserve /healthz/ready for observability and the broch status / broch doctor commands. See Health Checks for response bodies and the full readiness lifecycle.

Common Configuration Examples

Minimal Docker Compose (Embedded Database)

ASPNETCORE_ENVIRONMENT=Production
ASPNETCORE_URLS=http://+:8080
BROCH_MASTER_KEY=<generated-value>
API__WILDCARDHOSTNAME=tunnels.company.com
DATABASE__PROVIDER=PostgreSQL
ConnectionStrings__DefaultConnection=Host=postgres;Database=broch;Username=postgres;Password=<secure-password>
AUTHENTICATION__PROVIDER=AzureAd
AUTHENTICATION__CLIENTID=<your-client-id>
AUTHENTICATION__CLIENTSECRET=<your-client-secret>
AUTHENTICATION__TENANTID=<your-tenant-id>
AUTHENTICATION__INSTANCE=https://login.microsoftonline.com/
AUTHENTICATION__ADMINROLES=Admin

Production with Logging & Monitoring

# Core
ASPNETCORE_ENVIRONMENT=Production
ASPNETCORE_URLS=http://+:8080
BROCH_MASTER_KEY=<generated-value>
API__WILDCARDHOSTNAME=tunnels.company.com

# Database (Managed)
DATABASE__PROVIDER=PostgreSQL
ConnectionStrings__DefaultConnection=postgres://user:pass@rds-endpoint:5432/broch

# Auth
AUTHENTICATION__PROVIDER=Okta
AUTHENTICATION__DOMAIN=company.okta.com
AUTHENTICATION__CLIENTID=<your-client-id>
AUTHENTICATION__CLIENTSECRET=<your-client-secret>
AUTHENTICATION__ADMINROLES=broch_admin

# Logging
BROCHLOGGING__PROVIDER=DataDog
BROCHLOGGING__DATADOG__APIKEY=<your-api-key>
BROCHLOGGING__DATADOG__SERVICENAME=broch-prod
BROCHLOGGING__DATADOG__ENVIRONMENT=production

Secrets Management

Never commit secrets (license keys, client secrets, connection strings, API keys) to version control. Use your platform’s secure secret storage:

• Docker: Docker secrets or environment files excluded from git
• Kubernetes: Kubernetes secrets
• Azure: Azure Key Vault
• AWS: AWS Secrets Manager
• DigitalOcean: App Platform encrypted environment variables

Questions?

Contact Broch at [email protected] for configuration questions or deployment guidance.