Server Configuration Reference
The server is configured via a YAML file (passed with --config). All top-level keys are described below.
Checking a config file
The server refuses to start if its config file contains a key that matches no setting, such as a misspelled key or one that has been renamed, or a setting it would reject. It reports every problem at once, each with the key's full path:
Error: invalid configuration in server.yaml:
events.tls-client-config: unknown key
control.listen-address: must not be empty
To check a file without starting the server, run:
connect server config validate --config server.yaml
Without --config, it checks the file connect server would load.
Besides unknown keys, the checks cover:
control.listen-addressandmanagement-listen-address:host:portform, andcontrol.tls-serverandmanagement-tls-serverblocks that set only one ofacme,self-signedandlocal, with a key for every certificate;connect.services: each service'sservice-typemust be supported, itsdirectionandvisibility(when set) must be valid values, a numericexternal-portmust be a valid port, and service names, which default to the service type, must be unique;events:agent-registry.url,events.default-event-sinkandevents.event-broker.urlmust behttporhttpsURLs,event-brokerneeds aurl, and topics must contain a dot.
Every key, and checking as you type
Server config file keys lists every key a server
config file can set, generated from the code the server loads its config with.
connect server config example prints an example file listing every key with
its description and default, and connect server config schema prints the
JSON Schema of the file.
An editor can check a config file against the schema as you type. Add this line at the top of the file:
# $schema: https://dioad.github.io/connect/schema/server.schema.json
The YAML language server (the VS Code YAML extension and other editors) and
JetBrains IDEs read it. The schema checks each key and the type of each
value; connect server config validate also checks the rules above.
Top-Level Structure
log: # Logging settings
identity: # Server OIDC identity / credentials
control: # Control plane listener (agents connect here)
management-listen-address: # Management listener: health, metrics, status (see below)
shutdown-drain-delay: # How long to fail readiness before closing listeners
connect: # Traffic services and authorisation defaults
events: # Eventbroker integration
agent-registry: # Where to search for forward targets on other servers
log — Logging
| Key | Type | Default | Description |
|---|---|---|---|
level |
string | warn |
Log level: trace, debug, info, warn, error, fatal, panic |
file |
string | (stdout) | Path to log file. Supports ~ expansion. Omit to log to stdout only. |
max-size |
int | 100 | Max log file size in MB before rotation. |
max-backups |
int | 0 | Max number of rotated log files to retain (0 = keep all). |
max-age |
int | 0 | Max number of days to keep rotated log files (0 = no limit). |
use-local-time |
bool | false | Use local time in rotated filenames instead of UTC. |
compress |
bool | false | Gzip-compress rotated log files. |
Example:
log:
level: info
file: /var/log/connect/server.log
max-size: 100
max-backups: 5
max-age: 30
compress: true
identity — Server Identity (OIDC)
Configures how the server authenticates itself (e.g. for token introspection or downstream service calls).
| Key | Type | Description |
|---|---|---|
type |
string | Provider type: keycloak, github, flyio, githubactions, aws |
url |
string | OIDC issuer URL |
keycloak-realm |
string | Keycloak realm name (only for type: keycloak) |
client-id |
string | OAuth2 client ID |
client-secret |
string | OAuth2 client secret |
client-secret-file |
string | File to read the client secret from, such as a mounted secret; surrounding whitespace is trimmed. Use instead of client-secret, not with it. |
token-file |
string | Path to a file where the server stores/reads cached tokens |
audience |
string | Optional token audience override |
tls-client |
object | TLS client config for connecting to the OIDC provider (see TLS Client) |
Example (Keycloak):
identity:
type: keycloak
url: https://auth.lab.dioad.net
keycloak-realm: dioad-labs
client-id: connect-authoriser
client-secret: RSY2TiHmvHyUm9HNuslQpP349nohQC2E
Example (GitHub Actions — no URL needed):
identity:
type: githubactions
audience: githubactions-smoketest
control — Control Plane
The control plane is the endpoint that agents connect to for tunnel establishment.
| Key | Type | Description |
|---|---|---|
listen-address |
string | Required. Address and port to listen on, e.g. 0.0.0.0:8119 |
enable-proxy-protocol |
bool | Accept PROXY protocol on incoming connections |
tls-server |
object | TLS config for the control listener (see TLS Server). To require agent client certificates set both client-auth-type (for example RequireAndVerifyClientCert) and client-ca-file: a CA file without a type checks nothing, and the server rejects that config. The control listener serves no /status; use the management listener for that. |
registration-url |
string | URL where new users can register an account. When set, the server root page displays a "Create a free account" link. |
allow-unauthenticated-non-loopback |
bool | Acknowledge 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. |
Hosted vs. self-hosted
registration-url just points the "Create a free account" link at whatever URL you give it — self-hosted
operators must run (or point at) their own account registration flow. The hosted Dioad Connect service
(https://connect.dioad.dev) sets this to its own signup flow.
Example:
control:
listen-address: 0.0.0.0:8119
tls-server:
local:
cert: /tls/certs/server.pem
key: /tls/certs/server.key
client-auth-type: RequireAndVerifyClientCert
client-ca-file: /tls/ca/clientca-bundle.pem
registration-url: https://auth.example.com/register
Management listener and shutdown
The management listener exposes an HTTP endpoint for health, metrics, and admin tooling. These keys sit at the top level of the file, with the same names every dioad service uses. It reports what the internet-facing control listener records but does not serve itself:
/health/liveand/health/ready: the server's own liveness and readiness;/status: each service's tunnels (count, traffic, timing), keyed by/connect/<service>, plus server metadata;/metrics(unless turned off): the control listener's HTTP request metrics (dioad_net_http_*) alongside the server's own.
| Key | Type | Default | Description |
|---|---|---|---|
management-listen-address |
string | — | Required. Address and port, e.g. 127.0.0.1:5555. A non-loopback address is rejected unless management-tls-server requires client certificates or management-allow-unauthenticated-non-loopback is set. |
management-allow-unauthenticated-non-loopback |
bool | false | Acknowledge that the management listener is reachable from other hosts with no authentication of its own. Set it only when the network in front of the listener is trusted. |
management-enable-proxy-protocol |
bool | false | Require a PROXY protocol header on incoming connections. Leave it off when a platform health check or scraper connects directly: a connection without a header is refused. |
management-tls-server |
object | — | TLS config for the management listener (see TLS Server). With client-auth-type: RequireAndVerifyClientCert and a client-ca-file it also authenticates callers. |
enable-prometheus-metrics |
bool | true | Expose /metrics in Prometheus format. Set it to false to turn metrics off. |
enable-debug |
bool | false | Expose Go pprof debug endpoints at /debug/pprof/. These leak memory contents; keep them off a listener other hosts can reach. |
enable-search |
bool | false | Enable tunnel search API. It lists every registered forward target, so it needs the same protection as enable-debug. |
shutdown-drain-delay |
duration | 0 | How long the server keeps serving after it is told to stop, with /health/ready already failing, so a load balancer stops sending new connections before the listeners close. Zero stops at once. Keep the platform's stop timeout above this plus 30s: see Server Lifecycle and Capacity. |
Example:
management-listen-address: 127.0.0.1:5555
enable-search: true
shutdown-drain-delay: 20s
connect — Traffic Services
Defines the traffic-facing listeners (HTTPS, SMTP, DNS, etc.) and sets defaults applied to all services.
connect:
defaults: # BaseServiceConfig — applied to every service unless overridden
...
services: # []ServiceConfig — one entry per listener
- ...
connect.defaults — Global Service Defaults
All fields from defaults are merged into each service entry that does not set them explicitly.
| Key | Type | Description |
|---|---|---|
default-domain |
string | Base domain for tunnel subdomains, e.g. traffic.example.com |
enable-proxy-protocol |
bool | If true, force PROXY protocol on all services (per-service setting can override for false→true but not true→false) |
jwt-validators |
[]object | OIDC/JWT validators for authenticating incoming tunnel connections (see JWT Validators). A service needs validators, here or in connect.defaults, or allow-unauthenticated: with neither, every agent is rejected and the config is invalid. |
allow-unauthenticated |
bool | Allow connections without a valid JWT. Development only — do not use in production. Needs accept-unauthenticated-risk: true. Rejected on a control listener other hosts can reach, unless control.allow-unauthenticated-non-loopback is set. |
accept-unauthenticated-risk |
bool | The second opt-in allow-unauthenticated needs, so one flag copied into a production config is not enough to open a service. Required with allow-unauthenticated, and rejected without it. A service that inherits allow-unauthenticated from defaults inherits this too. |
claim-role-mappings |
[]object | Map JWT claim predicates to internal roles (see Claim Role Mappings) |
authorisation |
object | Privilege authoriser config (see Authorisation). It is the only way to grant privileges such as custom domains or forward tunnels. |
tag-policy |
object | Reserve tag prefixes for chosen roles and principals (see Tag Policy). A service's own tag-policy adds to this one rather than replacing it. |
Example:
connect:
defaults:
default-domain: traffic.example.com
enable-proxy-protocol: false
jwt-validators:
- url: https://auth.example.com/realms/myrealm
audiences:
- account
claim_predicates:
- or:
- groups: connect-users
- groups: connect-admin
authorisation:
default-allow-all: false
inline:
privileges:
fbb3f321-fbf9-4e0e-bc9f-e80f9d932a63:
has-custom-domain: false
has-custom-subdomain: true
enable-dynamic-subdomain: true
enable-forward-tunnels: false
has-network-acl: false
connect.services — Service Listeners
A list of traffic listeners. Each service binds a port and handles a specific protocol.
| Key | Type | Description |
|---|---|---|
name |
string | Required. Unique service name (also the URL path component, e.g. https → /connect/https) |
service-type |
string | Required. Protocol: tls, https, smtp, dns, imap, imaps, submission, socks5 |
direction |
string | Tunnel direction: reverse (default) or forward |
visibility |
string | public or private. Private services are reachable only by agents, not external clients. |
listen-address |
string | Address and port to listen on, e.g. 0.0.0.0:8443 |
external-port |
string | Port advertised to agents as the public-facing port (may differ from listen-address port when behind a load balancer) |
config |
map | Service-type-specific configuration passed to the protocol handler |
rate-limiter |
object | Per-principal and per-address tunnel-creation rate limiting (see Rate Limiter) |
max-tunnels |
int | Most tunnels this service holds at once. A connection beyond it gets 503 with Retry-After: 60, which the agent waits out. 0 (the default) means no cap. |
max-tunnels-per-principal |
int | Most tunnels one principal holds on this service at once, refused the same way. An agent that reconnects before the server has noticed its old tunnel is gone counts twice, so leave headroom above the number of agents a principal runs. 0 means no cap. |
(all defaults fields) |
Any field from connect.defaults can be overridden per service |
Service types:
service-type |
Protocol | Typical port |
|---|---|---|
tls |
Generic TLS (used for HTTPS tunnels) | 443 / 8443 |
https |
HTTPS | 443 |
smtp |
SMTP | 25 / 587 |
dns |
DNS (UDP/TCP) | 53 / 8853 |
imap |
IMAP | 143 / 993 |
imaps |
IMAP over TLS | 993 |
submission |
SMTP submission | 465 / 587 |
socks5 |
SOCKS5 proxy | 1080 |
Example — standard set of services:
connect:
services:
# Public HTTPS tunnel endpoint
- name: https
service-type: tls
visibility: public
listen-address: 0.0.0.0:8443
external-port: 8443
# Private DNS-over-HTTPS endpoint (agent-facing only)
- name: doh/private
service-type: tls
visibility: private
listen-address: 0.0.0.0:9443
external-port: 9443
# Public SMTP endpoint
- name: smtp
service-type: smtp
visibility: public
listen-address: 0.0.0.0:25
external-port: 587
# Public IMAP endpoint
- name: imap
service-type: imap
visibility: public
listen-address: 0.0.0.0:993
external-port: 8993
# Private SOCKS5 proxy (agent-facing)
- name: private-socks5
service-type: socks5
visibility: private
listen-address: 0.0.0.0:8444
external-port: 8443
# Public forward SOCKS5 exit node
- name: socks5
direction: forward
service-type: tls
visibility: public
config:
target-service-type: socks5
tags:
- dioad/socks5-exit
Forward service config:
| Key | Type | Description |
|---|---|---|
tags |
[]string | Send each forward connection to a reverse tunnel carrying all of these tags |
target-service-type |
string | Only match reverse tunnels on a listener of this service type, for example socks5 for an exit. Set it whenever you select by tags: agents choose their own tags, so without it a tunnel of any service type carrying the same tags can receive this traffic. Reserve the tags as well (see Tag Policy). |
internal-target-endpoint |
string | Only match reverse tunnels serving this endpoint |
static-target-address |
string | Send every connection to this fixed host:port instead of searching |
tls |
object | TLS client config for dialing the target (see TLS Client) |
Example — minimal single-service setup:
connect:
defaults:
default-domain: traffic.example.com
authorisation:
default-allow-all: true
services:
- name: https
service-type: tls
visibility: public
listen-address: 0.0.0.0:8443
external-port: 8443
events — Event Integration
Configures how the server publishes tunnel lifecycle events, which is through the eventbroker.
| Key | Type | Description |
|---|---|---|
default-event-sink |
string | Deprecated name for agent-registry.url, which takes precedence. Events are no longer posted to it. |
tls-client |
object | TLS client config for the eventbroker connection (see TLS Client) |
event-broker |
object | Eventbroker integration (see below). Omit and no events are published. |
events.event-broker — Eventbroker
Events are published to the eventbroker; the agent registry subscribes to its topics.
Topic names follow a dot-separated reverse-DNS convention (e.g. connect.tunnel.lifecycle). At least one dot is required.
| Key | Type | Default | Description |
|---|---|---|---|
url |
string | — | Eventbroker base URL |
source |
string | connect |
Source identifier attached to published events |
lifecycle-topic |
string | connect.tunnel.lifecycle |
Topic for TunnelConnected, TunnelDisconnected, TunnelUpdate, EndpointRegistered, and EndpointDeregistered events |
updates-topic |
string | connect.tunnel.updates |
Topic for periodic TunnelUpdates snapshot events (high frequency) |
Example:
events:
tls-client:
insecure-skip-verify: false
root-ca-file: /tls/ca/events-ca.pem
event-broker:
url: https://eventbroker.example.com
source: connect-prod
lifecycle-topic: connect.tunnel.lifecycle
updates-topic: connect.tunnel.updates
agent-registry — Agent Registry
Locates the agent registry. Tunnel hosts search it for forward targets served by other servers; leave it unset and
they only find targets on this server. Requests carry the server's identity (see identity).
| Key | Type | Description |
|---|---|---|
url |
string | Registry base URL, e.g. https://registry.example.com |
events.default-event-sink is the deprecated name for this key. It is still read when agent-registry.url is unset,
and the server logs a warning at startup while it is set.
Example:
agent-registry:
url: https://registry.example.com
Shared Sub-Configurations
JWT Validators
Validates incoming agent JWT tokens. Multiple validators are tried in order; any one passing is sufficient.
| Key | Type | Description |
|---|---|---|
url |
string | OIDC issuer URL used for JWKS discovery |
audiences |
[]string | Required token audiences |
issuer |
string | Expected iss claim (defaults to url when omitted) |
claim_predicates |
object | Structured claim predicates the token must satisfy (see below) |
cache_ttl_seconds |
int | How long to cache validated tokens (seconds) |
signature_algorithm |
string | Expected signature algorithm (e.g. RS256) |
signature_algorithms |
[]string | Accepted signature algorithms, when more than one must be allowed |
allowed_clock_skew_seconds |
int | Permitted clock skew when validating exp/nbf |
debug |
bool | Emit debug logs for token validation. Do not enable in production. |
hmac_secret |
string | Shared secret for HS256/HS384/HS512 validation, skipping JWKS discovery. Local development and smoke testing only — never use a static shared secret in production. Requires allow_insecure_hmac: true. |
allow_insecure_hmac |
bool | Explicit opt-in required to use hmac_secret, acknowledging it is not suitable for production. |
Claim predicates support and, or, and direct claim key/value matching:
jwt-validators:
- url: https://auth.example.com/realms/myrealm
audiences:
- account
claim_predicates:
- or:
- groups: connect-users
- groups: connect-admin
# Fly.io machine identity — no URL needed
- url: https://oidc.fly.io/personal
audiences:
- account
Claim Role Mappings
Maps JWT claim predicates to internal roles for machine identities (Fly.io, GitHub Actions, AWS). These roles can then be referenced in authorisation rules.
| Key | Type | Description |
|---|---|---|
source |
string | Restrict to a named source: flyio, githubactions, aws, oidc, jwt. Empty = any source. |
claims |
map | Claim key → required value. Use "*" to match any non-empty value. |
role |
string | Internal role granted when all predicates match |
debug |
bool | Log claim values for this rule. Never enable in production. |
Example:
connect:
defaults:
claim-role-mappings:
- source: flyio
claims:
app: my-fly-app
region: "*"
role: fly-agent
- source: githubactions
claims:
repository: myorg/myrepo
role: ci-agent
Authorisation
Controls which principals may create tunnels and what capabilities they have. Three backends can be combined; they are evaluated in order: inline → group-inline → dynamic.
authorisation.default-allow-all
authorisation:
default-allow-all: true # Grant all privileges to any authenticated principal
Development only. Do not use
default-allow-all: truein production.It grants full privileges to a principal that no other authoriser has a record of. It does not apply when the
dynamicauthoriser could not be reached: that principal gets a503withRetry-After, and the agent retries, so an outage of the account service never grants everyone full access.
authorisation.inline — Per-Principal Privileges
Map principals to privilege sets. A principal is identified by the subject
(sub claim) of the token the agent presents: for Keycloak and other OIDC
providers this is a stable ID such as a UUID, not an email address. The server
logs it as the principal field of each tunnel request, which is the easiest
place to find it.
Keys cannot contain dots: the config loader treats a dot as a separator
between nested keys, so a key like user@example.com would be split.
| Privilege key | Type | Description |
|---|---|---|
has-custom-domain |
bool | Allow registering fully-qualified custom domains |
has-custom-subdomain |
bool | Allow requesting a specific subdomain label |
enable-dynamic-subdomain |
bool | Allow auto-generated subdomains |
has-network-acl |
bool | Allow specifying network ACL rules on tunnels |
enable-forward-tunnels |
bool | Allow creating forward (outbound) tunnels |
authorisation:
inline:
privileges:
fbb3f321-fbf9-4e0e-bc9f-e80f9d932a63: # the OIDC subject of a trusted user
has-custom-domain: true
has-custom-subdomain: true
enable-dynamic-subdomain: true
has-network-acl: true
enable-forward-tunnels: true
0d6c8a52-7b1e-4f9a-9c3d-2e5f8b7a6c41: # a restricted user
enable-dynamic-subdomain: true
authorisation.group-inline — Group-Based Privileges
Assign privileges by OIDC group membership. A principal's privileges are the union of all matching groups.
authorisation:
group-inline:
group-privileges:
connect-admin:
has-custom-domain: true
has-custom-subdomain: true
enable-dynamic-subdomain: true
has-network-acl: true
enable-forward-tunnels: true
connect-users:
enable-dynamic-subdomain: true
enable-forward-tunnels: false
authorisation.dynamic — Remote Authorisation Service
Delegate privilege lookups to an external HTTP service.
| Key | Type | Default | Description |
|---|---|---|---|
url |
string | — | Base URL of the account/privilege service |
authorization-timeout |
duration | 10s |
Timeout for each privilege lookup |
cache-ttl |
duration | 30s |
How long an answer is reused, so a wave of reconnecting agents does not become a wave of lookups. A negative value turns the cache off. |
stale-ttl |
duration | 10m |
How long an expired answer may still be used while the account service cannot be reached, so agents authorised shortly before an outage stay authorised. A negative value turns it off. |
Each service keeps its own cache. A change to a principal's privileges, or a revocation, can take up to cache-ttl to apply. After five failed lookups in a row a service stops calling the account service for ten seconds. During an outage a
principal with no usable answer gets 503 with Retry-After, never a 403: see
Authoriser outages.
Hosted vs. self-hosted
dynamic is the mechanism the hosted Dioad Connect service's account system plugs into: privilege
lookups are delegated to an external account/privilege service reachable at url. Self-hosted operators
either run their own compatible account service and point url at it, or skip dynamic entirely and use
inline/group-inline for a fully self-contained privilege map.
authorisation:
dynamic:
url: http://accounts-service/
authorization-timeout: 5s
Authenticated privilege lookups
Privilege lookups are sent authenticated as the server whenever a top-level
identity block is configured — the same OIDC credential already used for
posting events to the agent registry is
reused here, so no additional configuration is required. An account service that requires authentication
(the hosted Dioad Connect account service does) will reject an unauthenticated lookup, so a server pointed
at one must configure identity. When identity is omitted the lookup is sent unauthenticated, which
only works against an account service that does not require it.
Tag Policy
Agents choose the tags on their own tunnels, and forward services pick their targets by tag. Without a tag policy, any principal allowed to open a tunnel can claim the tags of an exit and receive other principals' forward traffic. A tag policy reserves tag prefixes for the roles and principals you grant them. The server refuses a tunnel that asks for a reserved tag the principal hasn't been granted, with 403 Forbidden, in either direction.
Set tag-policy in connect.defaults so it covers every service. A service can set its own tag-policy to add reservations; it can't lift one from the defaults.
A reservation protects the tunnels opened on the services it applies to. An agent claims its tags on a reverse service, but a forward service selects its targets by tag across all the reverse services it can find, so the reservation that protects those targets has to be in connect.defaults, or on every reverse service the forward service selects from. A reservation set only on the forward service protects nothing. At startup the server warns about each forward service that selects by tags that some reverse service doesn't reserve, naming those services. A search matches only a tunnel that carries all of the forward service's tags, so reserving any one of them on a service is enough. The check covers this server's services only: targets registered with other servers through the agent registry follow those servers' own policies.
| Key | Type | Description |
|---|---|---|
reserved-prefixes |
[]object | Tag prefixes to reserve |
reserved-prefixes[].prefix |
string | Required. The reserved prefix, for example dioad/. Matched case-insensitively against the start of each tag. |
reserved-prefixes[].roles |
[]string | Roles that may use the prefix: OIDC groups, or roles assigned by Claim Role Mappings |
reserved-prefixes[].principals |
[]string | Principals that may use the prefix, by exact principal ID. Prefer roles: some principal IDs change, for example a Fly.io Machine's when it is recreated. |
A prefix with no roles and no principals can't be used by anyone. A tag under more than one reserved prefix, such as dioad/smtp-only under both dioad/ and dioad/smtp, must be granted by each of them.
The policy applies to tags agents ask for. It doesn't apply to the tags a forward service searches for, and it doesn't affect tunnels connected before it was set until they reconnect.
Example:
connect:
defaults:
tag-policy:
reserved-prefixes:
- prefix: dioad/
roles:
- socks-exit
- prefix: ops/
principals:
- fbb3f321-fbf9-4e0e-bc9f-e80f9d932a63
services:
- name: private-socks5
service-type: socks5
claim-role-mappings:
- source: flyio
claims:
app_name: my-socks-exit
role: socks-exit
Rate Limiter
Two limits apply to a service's connect endpoint. A per-address limit runs first, before the request is authenticated or authorised, so a flood does not cost a token validation and an account-service call each. A per-principal limit runs after authorisation. When omitted, the per-principal defaults are 1 req/s with a burst of 3, and the per-address defaults are 50 req/s with a burst of 200.
| Key | Type | Default | Description |
|---|---|---|---|
requests-per-second |
float64 | 1.0 |
Sustained tunnel creation rate per principal |
burst |
int | 3 |
Maximum burst above the sustained rate |
ip-requests-per-second |
float64 | 50 |
Sustained request rate per client address, before authentication |
ip-burst |
int | 200 |
Maximum burst per client address |
disable-ip-limit |
bool | false |
Turn the per-address limit off |
The per-address limit keys on the connection's remote address and ignores X-Forwarded-For, which any client can
set. Behind a proxy that does not pass the client address on (no PROXY protocol), every request carries the proxy's
address and shares one bucket: enable enable-proxy-protocol, raise the limit, or disable it. The control
listener's /api/account endpoint has the same per-address limit with the defaults.
/api/account is mounted once for the whole server. It takes its jwt-validators and its dynamic authoriser from
connect.defaults, and where the defaults leave either unset, from the first service that sets it. With neither in
the defaults nor on any service it answers 501.
connect:
services:
- name: https
service-type: tls
listen-address: 0.0.0.0:8443
external-port: 8443
rate-limiter:
requests-per-second: 2.0
burst: 5
TLS Server
Configures TLS for a listener. Exactly one of acme, self-signed, or local should be set.
tls-server:
# Option 1: Automatic certificates via Let's Encrypt (ACME)
acme:
cache-directory: /var/lib/connect/autocert
email: admin@example.com
domains: [] # SANs (tls-alpn-01: whitelist; dns-01: certificate SANs)
directory-url: "" # ACME directory URL (defaults to Let's Encrypt)
# Option 2: Self-signed certificate
self-signed:
cache-directory: /var/lib/connect/certs
alias: connect-server # Filename prefix for the generated files
duration: 8760h
ca: false
bits: 2048
subject:
cn: connect.example.com
o: [Example Org]
san:
dns-names: [connect.example.com]
ip-addresses: [10.0.0.1]
# Option 3: Local certificate files
local:
cert: /tls/certs/server.pem
key: /tls/certs/server.key
single-pem-file: /tls/certs/combined.pem # Alternative: combined cert+key PEM
file-wait-interval: 5 # Seconds between retries waiting for cert files
file-wait-max: 12 # Max number of retries
# mTLS client verification (any mode above)
client-auth-type: RequireAndVerifyClientCert
client-ca-file: /tls/ca/client-ca-bundle.pem
# Additional options
tls-min-version: TLS12 # TLS10, TLS11, TLS12, TLS13
next-protos: [h2, http/1.1] # ALPN protocols
server-name: connect.example.com
TLS Client
Configures TLS for outbound connections (e.g. to the event sink or OIDC provider).
tls-client:
root-ca-file: /tls/ca/ca.crt # Custom CA for verifying the remote server
cert: /tls/certs/client.crt # Client certificate for mTLS
key: /tls/certs/client.key # Client private key for mTLS
insecure-skip-verify: false # Skip server certificate verification (not for production)
Complete Example
log:
level: info
identity:
type: keycloak
url: https://auth.example.com
keycloak-realm: myrealm
client-id: connect-server
client-secret: super-secret
control:
listen-address: 0.0.0.0:8119
tls-server:
local:
cert: /tls/certs/server.pem
key: /tls/certs/server.key
client-auth-type: RequireAndVerifyClientCert
client-ca-file: /tls/ca/client-ca-bundle.pem
management-listen-address: 127.0.0.1:5555
enable-prometheus-metrics: true
enable-debug: false
enable-search: true
shutdown-drain-delay: 20s
connect:
defaults:
default-domain: traffic.example.com
enable-proxy-protocol: false
jwt-validators:
- url: https://auth.example.com/realms/myrealm
audiences:
- account
claim_predicates:
- or:
- groups: connect-users
- groups: connect-admin
authorisation:
group-inline:
group-privileges:
connect-admin:
has-custom-domain: true
has-custom-subdomain: true
enable-dynamic-subdomain: true
has-network-acl: true
enable-forward-tunnels: true
connect-users:
enable-dynamic-subdomain: true
services:
- name: https
service-type: tls
visibility: public
listen-address: 0.0.0.0:8443
external-port: 8443
- name: smtp
service-type: smtp
visibility: public
listen-address: 0.0.0.0:25
external-port: 587
- name: imap
service-type: imap
visibility: public
listen-address: 0.0.0.0:993
external-port: 993
events:
tls-client:
root-ca-file: /tls/ca/events-ca.pem
agent-registry:
url: https://registry.example.com