Server config file reference
Every key a connect server config file can set, generated from the structs the server loads its config into. For what the settings do and how they fit together, see the server configuration guide. An editor can check a config file as you type with the JSON Schema at https://dioad.github.io/connect/schema/server.schema.json; "connect server config validate" also checks the rules the schema cannot express.
Top level
Config is the top-level configuration for the server.
| Key | Type | Default | Description |
|---|---|---|---|
log |
object | ||
management-listen-address |
string | management-listen-address is the host:port of the management listener that serves health, /metrics and, with enable-debug, pprof. Empty disables it. |
|
management-allow-unauthenticated-non-loopback |
boolean | management-allow-unauthenticated-non-loopback confirms that the management listener may bind beyond loopback with nothing in front of it to authenticate callers. Check accepts a non-loopback address without it only when ManagementTLSServer requires client certificates. |
|
management-enable-proxy-protocol |
boolean | management-enable-proxy-protocol accepts a PROXY protocol header on the management listener, for one a proxy forwards to. Leave it off for a platform check or scraper that connects directly. |
|
management-tls-server |
object | management-tls-server serves the management listener over TLS. With client-auth-type RequireAndVerifyClientCert and a client-ca-file it also authenticates callers, which lets the listener bind beyond loopback without the acknowledgement. Convert it with tls.NewServerTLSConfig and set the result as OperationalConfig.TLSConfig. |
|
enable-prometheus-metrics |
boolean | enable-prometheus-metrics serves /metrics on the management listener. Unset means on: the listener exists for health and metrics, and a service has to set it false to turn them off. |
|
enable-debug |
boolean | enable-debug should only be true in development environments. Set to false in production to avoid exposing sensitive information. |
|
shutdown-drain-delay |
duration | shutdown-drain-delay is how long shutdown waits, after /health/ready starts reporting not-ready and before listeners close, so a load balancer stops routing new requests first. Set it to at least one probe interval. Zero (the default) closes listeners immediately. |
|
enable-search |
boolean | enable-search serves forward-target search on the management listener. |
|
control |
object | control defines the settings for the control plane interface. |
|
identity |
object | identity defines the OIDC client settings for server identity. |
|
connect |
object | connect defines the core connection and service settings. |
|
events |
object | events defines how the server handles and routes events. |
|
agent-registry |
object | agent-registry locates the agent registry, which tunnel hosts search for forward targets served by other servers. |
log
Config contains all configuration options for logging behavior.
Fields support struct tags for configuration file unmarshaling:
YAML Example:
| Key | Type | Default | Description |
|---|---|---|---|
level |
string | level specifies the logging level: trace, debug, info, warn, error, fatal, panic. Empty string defaults to application-configured level or zerolog.WarnLevel. |
|
file |
string | file specifies the path to the log file. Supports home directory expansion (~). Empty string disables file logging (logs to stdout only). |
|
max-size |
integer | max-size is the maximum size of the log file in MB before rotation occurs. Default is 100 MB. |
|
max-age |
integer | max-age is the maximum number of days to keep old log files. Default is 0 (no limit). |
|
max-backups |
integer | max-backups is the maximum number of old log files to retain. Default is 0 (keep all). |
|
use-local-time |
boolean | use-local-time determines if rotated filenames use local time instead of UTC. Default is false. |
|
compress |
boolean | compress determines if old log files are gzip-compressed after rotation. Default is false. |
|
mode |
string | mode is reserved for future use. |
management-tls-server
ServerConfig specifies TLS configuration for a server.
| Key | Type | Default | Description |
|---|---|---|---|
server-name |
string | ||
acme |
object | ||
self-signed |
object | ||
local |
object | ||
client-auth-type |
string | ||
client-ca-file |
string | ||
next-protos |
list of string | ||
tls-min-version |
string |
control
ControlConfig configures the control listener that agents connect to.
| Key | Type | Default | Description |
|---|---|---|---|
listen-address |
string | ||
enable-proxy-protocol |
boolean | ||
tls-server |
object | ||
allow-unauthenticated-non-loopback |
boolean | allow-unauthenticated-non-loopback acknowledges that a service sets allow-unauthenticated while this listener is reachable from other hosts, so anyone who can reach it can open tunnels. Without it that combination is rejected. |
|
registration-url |
string | registration-url is the URL where new users can register an account. When set, the server root page displays a "Create a free account" link. |
identity
ClientConfig captures client credentials and token acquisition options for an OIDC provider.
| Key | Type | Default | Description |
|---|---|---|---|
type |
string | type selects a provider-specific behaviour. Accepted values are "github", "githubactions", "keycloak", "flyio" and "aws". Leave empty for a generic OIDC provider discovered from URL. |
|
url |
string | url is the OIDC issuer URL, for example "https://accounts.example.com". Provider metadata and signing keys are discovered from it. |
|
keycloak-realm |
string | keycloak-realm is the Keycloak realm name. It is only used when Type is "keycloak". |
|
client-id |
string | client-id is the OAuth 2.0 client identifier registered with the provider. |
|
client-secret |
string | client-secret is the OAuth 2.0 client secret, used for the client credentials flow. Set at most one of ClientSecret and ClientSecretFile. |
|
client-secret-file |
string | client-secret-file is the path to a file containing the client secret, for example a mounted container secret. Surrounding whitespace is trimmed. The file is read when the token source is built, not when the config is validated; an unreadable or empty file is an error. Set at most one of ClientSecret and ClientSecretFile. |
|
audience |
string | audience is the audience requested for issued tokens. It is required by platform identity providers such as "githubactions", "flyio" and "aws" and ignored by providers that do not support it. |
|
token-file |
string | token-file is the path to a file used to persist the interactive login token between runs. When set, the token is loaded from the file and refreshed with its refresh token once it expires. |
|
tls-client |
object | tls-client configures TLS for connections to the provider, such as a custom CA bundle. |
connect
ConnectConfig configures the connect services that accept tunnel connections.
| Key | Type | Default | Description |
|---|---|---|---|
defaults |
object | ||
services |
list of object |
events
EventConfig configures how the server publishes events.
| Key | Type | Default | Description |
|---|---|---|---|
default-event-sink |
string | default-event-sink is the deprecated name for agent-registry.url. Events are no longer posted to it. agent-registry.url takes precedence. |
|
tls-client |
object | ||
event-broker |
object |
agent-registry
AgentRegistryConfig locates the agent registry. Leave it unset and tunnel hosts only find forward targets on this server.
| Key | Type | Default | Description |
|---|---|---|---|
url |
string | url is the registry's base URL, for example https://registry.example.com. |
management-tls-server.acme
ACMEConfig specifies parameters for obtaining a certificate via ACME, using either the tls-alpn-01 challenge (delegated to golang.org/x/crypto/acme/autocert) or the dns-01 challenge (a hand-rolled github.com/go-acme/lego/v5 client). The two challenge types share the same account identity and cache directory, but obtain certificates through entirely independent runtime implementations - only the config surface is unified here.
| Key | Type | Default | Description |
|---|---|---|---|
type |
string | type selects the ACME challenge mechanism: ACMEChallengeTLSALPN01 or ACMEChallengeDNS01. An absent/empty Type (the zero value) defaults to ACMEChallengeTLSALPN01, so callers who only need TLS-ALPN-01 can omit this field entirely. |
|
email |
string | ||
directory-url |
string | ||
cache-directory |
string | ||
domains |
list of string | domains is, for Type=dns-01, the SANs to include on the single certificate obtained upfront (may include wildcards, e.g. "*.example.com"); for Type=tls-alpn-01 (default), the whitelist of hosts autocert will provision certificates for on demand via autocert.HostWhitelist. Wildcard entries are rejected for tls-alpn-01 - TLS-ALPN-01 cannot validate wildcard identifiers (RFC 8555 permits wildcards only via dns-01), and autocert's HostWhitelist silently ignores such entries rather than erroring, so NewACMETLSConfig validates this upfront instead. |
|
dns01-propagation-timeout |
duration | dns01-propagation-timeout bounds how long lego waits for DNS propagation of the challenge TXT record. Zero uses lego's default (60s). |
|
dns01-polling-interval |
duration | dns01-polling-interval controls how often lego polls while waiting for propagation. Zero uses lego's default (2s). |
management-tls-server.self-signed
SelfSignedConfig specifies parameters for generating a self-signed certificate.
| Key | Type | Default | Description |
|---|---|---|---|
subject |
object | ||
san |
object | ||
duration |
string | ||
ca |
boolean | ||
bits |
integer | ||
cache-directory |
string | ||
alias |
string |
management-tls-server.local
LocalConfig specifies local certificate and key file locations.
| Key | Type | Default | Description |
|---|---|---|---|
single-pem-file |
string | ||
cert |
string | ||
key |
string | ||
file-wait-interval |
integer | ||
file-wait-max |
integer |
identity.tls-client
ClientConfig specifies TLS client configuration.
| Key | Type | Default | Description |
|---|---|---|---|
root-ca-file |
string | ||
cert |
string | ||
key |
string | ||
insecure-skip-verify |
boolean |
connect.defaults
BaseServiceConfig holds the settings that connect services inherit when they do not set their own.
| Key | Type | Default | Description |
|---|---|---|---|
allow-unauthenticated |
boolean | allow-unauthenticated is a *bool, not a bool, so callers merging this config against a layered default (e.g. connect's per-service overrides) can tell "not set at this level" (nil) apart from an explicit false - a plain bool can't distinguish the two, which would let a true default silently override a service's explicit false. |
|
accept-unauthenticated-risk |
boolean | accept-unauthenticated-risk is the second opt-in AllowUnauthenticated needs before Check accepts it. One flag copied into a production config by mistake is then not enough to open the API. |
|
claim-role-mappings |
list of object | ||
enable-proxy-protocol |
boolean | enable-proxy-protocol is a *bool, not a bool, so MergeServiceConfig can tell "not set at this level" (nil) apart from an explicit false - a plain bool can't distinguish the two, which previously let a true default silently override a service's explicit false. |
|
default-domain |
string | default-domain is a *string, not a value, so MergeServiceConfig can tell "not set at this level" (nil) apart from an explicit empty override - e.g. an internal-only service opting out of the domain suffix connect.defaults applies to every other service. |
|
jwt-validators |
list of object | ||
authorisation |
object | authorisation decides each principal's privileges. Nothing replaces it: claims identify a principal, they do not grant privileges. |
|
tag-policy |
object | tag-policy reserves tag prefixes for chosen roles and principals on the tunnels opened on this service. MergeServiceConfig combines a service's reservations with the defaults' rather than replacing them, so no service can lift one. A forward service finds its targets on reverse services, so reserve the tags it selects by in the defaults, not on the forward service. |
connect.services[]
ServiceConfig is the configuration for a service that can be registered with the server.
| Key | Type | Default | Description |
|---|---|---|---|
allow-unauthenticated |
boolean | allow-unauthenticated is a *bool, not a bool, so callers merging this config against a layered default (e.g. connect's per-service overrides) can tell "not set at this level" (nil) apart from an explicit false - a plain bool can't distinguish the two, which would let a true default silently override a service's explicit false. |
|
accept-unauthenticated-risk |
boolean | accept-unauthenticated-risk is the second opt-in AllowUnauthenticated needs before Check accepts it. One flag copied into a production config by mistake is then not enough to open the API. |
|
claim-role-mappings |
list of object | ||
enable-proxy-protocol |
boolean | enable-proxy-protocol is a *bool, not a bool, so MergeServiceConfig can tell "not set at this level" (nil) apart from an explicit false - a plain bool can't distinguish the two, which previously let a true default silently override a service's explicit false. |
|
default-domain |
string | default-domain is a *string, not a value, so MergeServiceConfig can tell "not set at this level" (nil) apart from an explicit empty override - e.g. an internal-only service opting out of the domain suffix connect.defaults applies to every other service. |
|
jwt-validators |
list of object | ||
authorisation |
object | authorisation decides each principal's privileges. Nothing replaces it: claims identify a principal, they do not grant privileges. |
|
tag-policy |
object | tag-policy reserves tag prefixes for chosen roles and principals on the tunnels opened on this service. MergeServiceConfig combines a service's reservations with the defaults' rather than replacing them, so no service can lift one. A forward service finds its targets on reverse services, so reserve the tags it selects by in the defaults, not on the forward service. |
|
name |
string | ||
service-type |
string | ||
direction |
string | ||
visibility |
string | ||
listen-address |
string | ||
external-port |
string | ||
config |
map | ||
rate-limiter |
object | rate-limiter controls per-principal tunnel-creation rate limiting. When nil, defaults of 1 req/s with a burst of 3 are used. |
|
max-tunnels |
integer | max-tunnels caps the tunnels this service holds at once; a connection beyond it is refused with 503 and Retry-After. Zero means no cap. |
|
max-tunnels-per-principal |
integer | max-tunnels-per-principal caps the tunnels one principal holds on this service at once, with the same refusal. A reconnecting agent whose previous tunnel the server has not yet noticed is gone counts against it, so leave headroom above the number of agents a principal runs. Zero means no cap. |
events.event-broker
EventBrokerConfig configures publishing to an eventbroker instance. It is the only way the server publishes events; omit the block and none are published.
Topics follow a dot-separated reverse-DNS naming convention (e.g. "connect.tunnel.lifecycle"). At least one dot is required — single-word names collide with reserved eventbroker URL segments ("stream", "batch", etc.).
TLS and authentication are handled by the shared event HTTP client (which carries the server's OIDC token transport), not by this config block.
| Key | Type | Default | Description |
|---|---|---|---|
url |
string | ||
source |
string | default: "connect" | |
lifecycle-topic |
string | lifecycle-topic receives TunnelConnected, TunnelDisconnected, TunnelUpdate, EndpointRegistered, and EndpointDeregistered events. Default: "connect.tunnel.lifecycle". |
|
updates-topic |
string | updates-topic receives periodic TunnelUpdates snapshot events (high frequency). Default: "connect.tunnel.updates". |
management-tls-server.self-signed.subject
CertificateSubject defines X.509 certificate subject information.
| Key | Type | Default | Description |
|---|---|---|---|
c |
list of string | ||
o |
list of string | ||
ou |
list of string | ||
l |
list of string | ||
st |
list of string | ||
street |
list of string | ||
postalcode |
list of string | ||
serialnumber |
string | ||
cn |
string |
management-tls-server.self-signed.san
SANConfig specifies Subject Alternative Names for a certificate (DNS names and IP addresses).
| Key | Type | Default | Description |
|---|---|---|---|
dns-names |
list of string | ||
ip-addresses |
list of string |
connect.defaults.claim-role-mappings[]
ClaimRoleMappingConfig maps a set of JWT claim predicates to an internal role, optionally restricted to a specific PrincipalSource. An empty Source matches any source.
| Key | Type | Default | Description |
|---|---|---|---|
source |
string | source restricts this mapping to a named PrincipalSource (e.g. "flyio", "aws"). Empty means match any source. |
|
claims |
map of string | claims maps claim keys to required values. A value of "*" matches any non-empty string. |
|
role |
string | role is the internal role granted when all claim predicates match. |
|
debug |
boolean | debug enables per-request structured debug logging for this rule. Do not enable in production — evaluated claim values appear in the log output. |
connect.defaults.jwt-validators[]
ValidatorConfig controls validation behavior for issued tokens.
| Key | Type | Default | Description |
|---|---|---|---|
type |
string | type selects a provider-specific behaviour. Accepted values are "github", "githubactions", "keycloak", "flyio" and "aws". Leave empty for a generic OIDC provider discovered from URL. |
|
url |
string | url is the OIDC issuer URL, for example "https://accounts.example.com". Provider metadata and signing keys are discovered from it. |
|
keycloak-realm |
string | keycloak-realm is the Keycloak realm name. It is only used when Type is "keycloak". |
|
audiences |
list of string | audiences lists the accepted values of the token "aud" claim. A token is accepted if it carries at least one of them. |
|
issuer |
string | issuer is the expected token "iss" claim. Signing keys are discovered from its JWKS endpoint. |
|
cache_ttl_seconds |
integer | cache_ttl_seconds is how long, in seconds, discovered signing keys are cached. Defaults to 300 when unset or not positive. |
|
signature_algorithm |
string | signature_algorithm is a single accepted signing algorithm, for example "RS256". Ignored when SignatureAlgorithms is set. |
|
signature_algorithms |
list of string | signature_algorithms lists the accepted signing algorithms, for example "RS256", "ES256". Takes precedence over SignatureAlgorithm. |
|
allowed_clock_skew_seconds |
integer | allowed_clock_skew_seconds is the tolerance, in seconds, applied to the token "exp", "nbf" and "iat" claims. Defaults to 60 when unset or not positive. |
|
debug |
boolean | debug enables debug logging of each token validation attempt and its outcome. Intended for troubleshooting. |
|
claim_predicates |
map | claim_predicates restricts which tokens are accepted by their claims. Each key is a claim name and its value is the required claim value; an array claim matches when it contains the value. All entries must match. Use the reserved keys "and" and "or", each holding a list of such maps, for nested combinations. |
|
hmac_secret |
string | hmac_secret is an optional shared secret for HS256/HS384/HS512 token validation. When non-empty, JWKS discovery is skipped and the secret is used directly as the signing key. Intended for local development and smoke testing only; never use a static shared secret in production. Requires AllowInsecureHMAC: true to prevent accidental production use. |
|
allow_insecure_hmac |
boolean | allow_insecure_hmac must be set to true when HMACSecret is used. This explicit opt-in acknowledges that HMAC shared secrets are not suitable for production deployments. Never set this to true in production config. |
connect.defaults.authorisation
TunnelAuthoriserConfig selects and configures the authorisers used to decide a principal's privileges.
| Key | Type | Default | Description |
|---|---|---|---|
inline |
object | ||
group-inline |
object | ||
dynamic |
object | ||
default-allow-all |
boolean |
connect.defaults.tag-policy
TagPolicyConfig reserves tag prefixes so that only the roles and principals granted a prefix can put a tag under it on a tunnel. Agents choose their own tags and forward services pick their targets by tag, so an unreserved tag can be claimed by any principal allowed to open a tunnel.
| Key | Type | Default | Description |
|---|---|---|---|
reserved-prefixes |
list of object |
connect.services[].rate-limiter
RateLimiterConfig holds configuration for the per-principal rate limiter.
| Key | Type | Default | Description |
|---|---|---|---|
requests-per-second |
number | requests-per-second is the steady-state allowed rate per principal. |
|
burst |
integer | burst is the maximum number of requests allowed in a burst. |
|
ip-requests-per-second |
number | ip-requests-per-second is the steady-state rate allowed per client address, applied before the request is authenticated or authorised so that a flood does not cost a token validation and an account-service call each. Zero takes the default of 50. |
|
ip-burst |
integer | ip-burst is the burst allowed per client address. Zero takes the default of 200. |
|
disable-ip-limit |
boolean | disable-ip-limit turns the per-address limit off. Behind a proxy that does not pass the client address on (no PROXY protocol), every request has the proxy's address and shares one bucket. |
connect.defaults.authorisation.inline
InlineAuthoriserConfig configures an authoriser with privileges defined inline in the configuration.
| Key | Type | Default | Description |
|---|---|---|---|
privileges |
map of object |
connect.defaults.authorisation.group-inline
GroupInlineAuthoriserConfig holds a static mapping of group names to privileges.
| Key | Type | Default | Description |
|---|---|---|---|
group-privileges |
map of object |
connect.defaults.authorisation.dynamic
DynamicAuthoriserConfig configures an authoriser that asks a remote service for a principal's privileges.
| Key | Type | Default | Description |
|---|---|---|---|
url |
string | http://accounts/ | |
authorization-timeout |
duration | ||
cache-ttl |
duration | cache-ttl is how long an answer from the account service is reused, so a wave of reconnecting agents does not become a wave of calls. Zero takes the default of 30s; a negative value turns the cache off. |
|
stale-ttl |
duration | stale-ttl is how long an expired answer may still be served while the account service cannot be reached, so agents authorised shortly before an outage stay authorised through it. Zero takes the default of 10m; a negative value turns it off. |
connect.defaults.tag-policy.reserved-prefixes[]
ReservedTagPrefix reserves one tag prefix for the roles and principals listed. A prefix with neither may not be used by anyone.
| Key | Type | Default | Description |
|---|---|---|---|
prefix |
string | prefix is matched case-insensitively against the start of each tag. |
|
roles |
list of string | roles that may use the prefix: OIDC groups and roles assigned by claim-role-mappings. |
|
principals |
list of string | principals that may use the prefix, by exact principal ID. |
connect.defaults.authorisation.inline.privileges.<name>
PrivilegeConfig configures the privileges granted to a principal.
| Key | Type | Default | Description |
|---|---|---|---|
has-custom-domain |
boolean | ||
has-custom-subdomain |
boolean | ||
enable-dynamic-subdomain |
boolean | ||
has-network-acl |
boolean | ||
enable-forward-tunnels |
boolean |