Skip to content

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