Agent config file reference
Every key a connect agent config file can set, generated from the structs the agent loads its config into. For what the settings do and how they fit together, see the agent configuration guide. An editor can check a config file as you type with the JSON Schema at https://dioad.github.io/connect/schema/agent.schema.json; "connect agent config validate" also checks the rules the schema cannot express.
Top level
Config is the top-level configuration for the agent.
| Key | Type | Default | Description |
|---|---|---|---|
log |
object | ||
identity |
object | identity provides the OIDC client configuration for agent identity. |
|
management |
object | management defines the configuration for the agent's management interface. |
|
acme-dns |
object | acme-dns defines the configuration for the agent-local acme-dns-compatible HTTP API. It lets an external ACME client running as a sibling exec process (e.g. maddy, via its built-in "acmedns" libdns provider) publish DNS-01 challenge values into the same ChallengeStore this agent's own dns-01 tunnels already use, instead of depending on a sibling tunnel's certificate lifecycle. See doc/architecture/agent/future/MADDY_LIBDNS_ACME_DESIGN.md. Optional - leave ListenAddress empty (the default) to disable it entirely. |
|
traffic |
object | traffic defines how the agent handles network traffic. |
|
tunnel-defaults |
object | tunnel-defaults provides default values for tunnel configurations. |
|
services |
object | services defines the services (like exec) that the agent should run. |
|
discovery |
object | discovery configures dynamic tunnel discovery sources. |
|
plugins |
object | plugins configures external tunnel server plugins: where signed plugin releases are found and which signing keys are trusted. See doc/user/PLUGINS.md. |
|
status |
object | status configures the status file the agent keeps for connect agent status and other tools. |
|
shutdown-timeout |
duration | shutdown-timeout bounds the agent's graceful-shutdown sequence: drain all tunnels, stop all exec child processes (maddy, coredns, ...), then stop the management and acme-dns HTTP servers. When unset or non-positive it defaults to defaultShutdownTimeout (5s). Raise it for an agent running several exec processes or many tunnels, where 5s can be too short and Stop deadlines start biting. |
|
profile-cpu-output |
string | profile-cpu-output specifies the file path where CPU profile data should be saved. |
|
profile-memory-output |
string | profile-memory-output specifies the file path where the heap profile is written when the agent stops. |
|
profile-block-output |
string | profile-block-output specifies the file path where the blocking profile is written when the agent stops. |
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. |
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. |
management
ManagementConfig configures the agent's local management interface.
| Key | Type | Default | Description |
|---|---|---|---|
listen-address |
string | listen-address is the address the management interface will listen on (e.g., ":4444"). |
|
operations-listen-address |
string | OperationsListenAddress, when set, starts a second listener serving /health/live, /health/ready and /metrics with no authentication, for a platform health check and metrics scraper that cannot log in. The management interface keeps its authentication. Bind it where only the platform can reach it: a private network or loopback. Needs listen-address. | |
session-secret |
string | ||
session-secret-file |
string | session-secret-file is a file holding the session secret, for deployments that mount secrets as files instead of putting them in the config. Set at most one of session-secret and session-secret-file. Surrounding whitespace is ignored. |
|
local-auth-disabled |
boolean | local-auth-disabled explicitly opts out of local basic-auth for the management interface. By default, when the management interface is enabled (ListenAddress is non-empty), a missing or empty htpasswd file causes the agent to refuse to start rather than run the management interface unauthenticated. |
|
local-auth |
object | local-auth configures local HTTP Basic authentication for the management interface, backed by a bcrypt-hashed htpasswd-style credentials file (HTPasswdFile, one "user:bcrypt-hash" entry per line). HTPasswdFile defaults to ~/.config/dioad/connect/htpasswd when left empty. Users is not read by the basic-auth handler - credentials always come from HTPasswdFile, not this list. |
|
allow-unauthenticated-non-loopback |
boolean | allow-unauthenticated-non-loopback explicitly opts in to serving the management interface - including the full tunnel-control API (POST /api/tunnels, POST /api/tunnel/{id}/state, GET /api/events) - unauthenticated on a non-loopback listener. By default the agent refuses to start in that combination (LocalAuthDisabled: true, bound to a non-loopback address) because anyone who can reach the listener then has full tunnel control with no credential. Only set this when a trusted TLS-terminating proxy or equivalent network control already sits in front of this listener. |
acme-dns
ACMEDNSConfig configures the agent-local acme-dns-compatible HTTP API.
| Key | Type | Default | Description |
|---|---|---|---|
listen-address |
string | listen-address is the address this API listens on (e.g. "127.0.0.1:8556"). Defaults to "127.0.0.1:8556" if left empty. It must be a loopback address: unlike the coredns tunnel's own DNS listener, this HTTP API is never bridged across the reverse tunnel, and the internally generated per-account credentials below are only a safe authentication mechanism because the listener itself is unreachable from anywhere but this host. See validateACMEDNSListenAddress. |
|
accounts |
list of object | accounts are the identities external ACME clients authenticate as, mirroring the acme-dns protocol's per-account model. Each account maps to exactly one target domain: an accepted update publishes "_acme-challenge.<domain>." into the shared ChallengeStore. The API runs when there is at least one account here or a "maddy" exec sets config.acme-dns.enable - there is no separate enable flag. A maddy exec needs no account here: the agent creates one for its MX hostname. |
traffic
TrafficConfig used to contain tunnel configuration.
| Key | Type | Default | Description |
|---|---|---|---|
tunnels |
list of object | ||
forward-tunnels |
list of object |
tunnel-defaults
TunnelConfigDefaults holds default tunnel settings that individual tunnels inherit when they do not set their own.
| Key | Type | Default | Description |
|---|---|---|---|
endpoint |
string | ||
subdomain |
string | ||
tls-client |
object | tls-client and TLSServer are pointers, not values, so WithOverrides can tell "not set at this level" (nil) apart from an explicit empty override. |
|
tls-server |
object | ||
network-acl |
object | network-acl is a *authz.NetworkACLConfig, not a value, so WithOverrides can tell "not set at this level" (nil) apart from an explicit zero-value ACL - the zero value is deny-all, a meaningful explicit choice that a more permissive default must not silently override. |
services
ServiceConfig configures the services run by the agent.
| Key | Type | Default | Description |
|---|---|---|---|
exec |
list of object |
discovery
DiscoveryConfig holds configuration for all dynamic tunnel discovery sources.
| Key | Type | Default | Description |
|---|---|---|---|
docker |
list of object | docker lists Docker-based discovery sources. Each entry configures the agent to watch a Docker daemon for labelled containers and create tunnels for them automatically. |
|
file |
list of object | file lists file-based discovery sources. Each entry configures the agent to load tunnels from a YAML file (under that file's own traffic: key) and watch it for changes. The agent's own traffic: block is always available as an implicit, unnamed entry of this kind (see ServiceFactory.buildFileSources) - File is for additional or separate files. |
plugins
Config is the agent's plugins section.
| Key | Type | Default | Description |
|---|---|---|---|
directory |
string | directory holds one sub-directory per plugin, each containing manifest.json, manifest.json.sig and the plugin binaries. Plugins are disabled when it is empty. |
|
cache-directory |
string | cache-directory receives digest-verified copies of plugin binaries; only these copies are ever executed. Defaults to a "plugins" directory under the user cache directory. |
|
require-signature |
boolean | require-signature rejects plugins without a valid signature from a trusted key. Defaults to true. |
|
trusted-keys |
list of object | trusted-keys are the public keys plugin manifests may be signed with. |
|
allow-unsigned |
list of string | allow-unsigned names plugins exempt from RequireSignature, for local development. Every load of such a plugin is logged as a warning. |
|
env-allowlist |
list of string | env-allowlist names the agent environment variables passed to plugin processes. Nothing else from the agent's environment is passed. |
status
StatusConfig configures the status file the agent keeps for connect agent status and other tools. See doc/user/AGENT_STATUS_FILES.md.
| Key | Type | Default | Description |
|---|---|---|---|
directory |
string | directory is where the agent keeps its status file, shared with any other agents that use it. Defaults to $CONNECT_AGENT_STATUS_DIR, or ~/.config/dioad/connect/status.d when that is unset. |
|
disabled |
boolean | disabled turns the status file off. connect agent status then only reports this agent through its management interface. |
identity.tls-client
ClientConfig specifies TLS client configuration.
| Key | Type | Default | Description |
|---|---|---|---|
root-ca-file |
string | ||
cert |
string | ||
key |
string | ||
insecure-skip-verify |
boolean |
management.local-auth
ServerConfig configures HTTP Basic authentication for a server.
| Key | Type | Default | Description |
|---|---|---|---|
allow-insecure-http |
boolean | ||
htpasswd-file |
string | ||
users |
list of string | ||
realm |
string | ||
throttle |
object | throttle limits failed logins per client address. It is enabled by default; see ThrottleConfig for the limits. |
acme-dns.accounts[]
ACMEDNSAccountConfig is the YAML shape of one ACMEDNSConfig.Accounts entry. It is intentionally self-contained rather than cross-referenced by name from a maddy exec's own config - the same duplication-by-convention already accepted elsewhere in this codebase for e.g. tls-server.acme.cache-directory (see doc/architecture/agent/future/CONNECT_AGENT_SERVICE_DESIGN.md's Background section), and simpler than adding a cross-reference lookup mechanism for a single, config-time-static relationship. There is deliberately no Password field: it is generated internally, fresh on every agent start, and never appears in any config file on either side - see internal/servers/coredns.ACMEDNSResource.Password.
| Key | Type | Default | Description |
|---|---|---|---|
username |
string | ||
subdomain |
string | ||
domain |
string |
traffic.tunnels[]
ReverseConfig represents the configuration for a reverse tunnel.
| Key | Type | Default | Description |
|---|---|---|---|
name |
string | name is the name of the tunnel. |
|
type |
string | type is the type of the tunnel (e.g., "forward", "reverse"). |
|
endpoint |
string | endpoint is the endpoint URL of the tunnel. |
|
tags |
list of string | tags is a list of tags associated with the tunnel. |
|
config |
map | ||
tls-server |
object | tls-server and TunnelTLSClient are pointers, not values, so callers merging this config against a layered default (global tunnel defaults, per-discovery-source defaults) can tell "not set at this level" (nil) apart from an explicit empty override. |
|
tls-client |
object | ||
network-acl |
object | network-acl is a *authz.NetworkACLConfig, not a value, so callers merging this config against a layered default (global tunnel defaults, per-discovery-source defaults) can tell "not set at this level" (nil) apart from an explicit zero-value ACL - the zero value is deny-all (AllowByDefault is false with no allow/deny lists), which is a meaningful, security-relevant explicit choice that a permissive default must not silently override. |
|
hostname |
string | hostname is the endpoint name the tunnel registers in place of its name. It lets tunnels of one type share a hostname, such as several tcp tunnels serving the mx host on different ports, while each keeps the unique name that depends-on, discovery and the management API identify it by. When unset, the tunnel registers under its name. |
|
extra-names |
list of string | ||
subdomain |
string | ||
custom-domains |
list of string | ||
publish-public-ip |
string | ||
dns |
object |
The keys of config depend on type:
coredns:configdummy:configdynamichello:configecho:configfile:confighello:confighttpreverseproxy:configmailrouter:configmailsupport:configmta-sts:configsocks5:configtcp:configwebhookdebug:config
traffic.forward-tunnels[]
ForwardConfig represents the configuration for a forward tunnel.
| Key | Type | Default | Description |
|---|---|---|---|
name |
string | name is the name of the tunnel. |
|
type |
string | type is the type of the tunnel (e.g., "forward", "reverse"). |
|
endpoint |
string | endpoint is the endpoint URL of the tunnel. |
|
tags |
list of string | tags is a list of tags associated with the tunnel. |
|
config |
map | ||
tls-server |
object | tls-server and TunnelTLSClient are pointers, not values, so callers merging this config against a layered default (global tunnel defaults, per-discovery-source defaults) can tell "not set at this level" (nil) apart from an explicit empty override. |
|
tls-client |
object | ||
network-acl |
object | network-acl is a *authz.NetworkACLConfig, not a value, so callers merging this config against a layered default (global tunnel defaults, per-discovery-source defaults) can tell "not set at this level" (nil) apart from an explicit zero-value ACL - the zero value is deny-all (AllowByDefault is false with no allow/deny lists), which is a meaningful, security-relevant explicit choice that a permissive default must not silently override. |
|
listen-address |
string |
tunnel-defaults.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 |
tunnel-defaults.network-acl
NetworkACLConfig describes the configuration for network-based access control.
| Key | Type | Default | Description |
|---|---|---|---|
allow |
list of string | ||
deny |
list of string | ||
allow-by-default |
boolean |
services.exec[]
Config describes an exec: what it is, how it is configured, and what it depends on.
| Key | Type | Default | Description |
|---|---|---|---|
name |
string | ||
type |
string | ||
tags |
list of string | ||
config |
map | ||
depends-on |
list of object | ||
dependency-timeout |
duration | dependency-timeout bounds how long the supervisor waits for DependsOn to be met before logging an error and marking the exec as timed out. Zero uses the manager's default. |
|
command |
string | ||
args |
list of string | ||
environment |
map of string | ||
working-directory |
string |
The keys of config depend on type:
maddy:config
discovery.docker[]
DiscoveryConfig configures a single Docker-based tunnel discovery source.
| Key | Type | Default | Description |
|---|---|---|---|
socket |
string | socket is the Docker socket path or URL (e.g. "unix:///var/run/docker.sock"). When empty, the default Docker socket is used. |
|
label-prefix |
string | label-prefix is the prefix used to identify connect-related labels on containers. Defaults to "dioad.connect" when empty. |
|
use-container-name |
boolean | use-container-name controls how the target host is inferred when constructing tunnel target URLs for discovered containers.When false (default — agent running on the Docker host): When true (agent running as a Docker container on the same network): Note: "use-container-name" only affects auto-inferred target values. Per-container overrides via "tunnel.config.target-url" (httpreverseproxy) or "tunnel.config.target-address" (tcp) labels always take precedence. |
|
allowed-types |
list of string | allowed-types lists the tunnel types a container label may select via "tunnel.type". Containers requesting any other type are skipped. Defaults to "httpreverseproxy" and "tcp" when empty.Container labels, including those baked into third-party images, are untrusted input: widen this list only for types you are willing to let any labelled container instantiate. |
|
allowed-endpoint-hosts |
list of string | allowed-endpoint-hosts lists the hostnames a container may name in its "tunnel.endpoint" label. The agent presents its identity token to the endpoint, so labels naming any other host are rejected. The host of the configured default endpoint is always allowed, so a label can still pick another path on it. Empty means labels cannot move the endpoint to a new host. |
|
allow-custom-targets |
boolean | allow-custom-targets permits "tunnel.config.target-url" and "tunnel.config.target-address" labels that point somewhere other than a port the container itself exposes. Link-local and unspecified addresses are rejected regardless. |
|
defaults |
object | defaults provides fallback tunnel configuration values for discovered containers that do not specify all tunnel fields via labels. |
discovery.file[]
DiscoveryConfig configures a single file-based tunnel discovery source: a YAML file containing traffic.tunnels/traffic.forward-tunnels- shaped content under its own traffic: key, loaded at boot and watched for changes afterward.
| Key | Type | Default | Description |
|---|---|---|---|
path |
string | path is the file to load tunnels from and watch for changes. |
|
defaults |
object | defaults provides fallback tunnel configuration values for tunnels loaded from this file, merged over the global tunnel-defaults. |
plugins.trusted-keys[]
TrustedKey is one plugin signing key.
| Key | Type | Default | Description |
|---|---|---|---|
name |
string | name identifies the key in logs. |
|
public-key |
string | public-key is "ed25519:<base64 PKIX>", as printed by "connect plugin keygen". |
management.local-auth.throttle
ThrottleConfig limits failed logins per client address to slow down password guessing. Throttling is enabled unless Disabled is set.
| Key | Type | Default | Description |
|---|---|---|---|
disabled |
boolean | disabled turns failed-login throttling off. By default throttling is on. |
|
max-failures |
integer | max-failures is the number of rejected logins allowed within Window before the client address is locked out. Defaults to 10. |
|
window |
duration | window is how long a failed login counts towards MaxFailures. Defaults to 5 minutes. |
|
lockout |
duration | lockout is how long a client address is rejected with 429 once MaxFailures is reached, even if it then supplies the right password. Defaults to 5 minutes. |
traffic.tunnels[].dns
TunnelDNSConfig holds the DNS records a tunnel declares it requires. It is decoded from the "dns:" YAML block on the tunnel stanza and is independent of any specific server type.
| Key | Type | Default | Description |
|---|---|---|---|
mx |
list of object | ||
txt |
list of object | ||
cname |
list of object | ||
srv |
list of object |
traffic.tunnels[].config (type: coredns)
Config configures the embedded CoreDNS server.
| Key | Type | Default | Description |
|---|---|---|---|
tls-server |
object | ||
smtp-domains |
list of object | ||
listen-address |
string | ||
listen-protocol |
string | ||
enable-logging |
boolean | ||
enable-debug |
boolean |
traffic.tunnels[].config (type: dummy)
Config configures the dummy server.
| Key | Type | Default | Description |
|---|---|---|---|
local-listen-address |
string | ||
enable-prometheus-metrics |
boolean | ||
debug |
boolean |
traffic.tunnels[].config (type: dynamichello)
Config configures the dynamic hello server.
| Key | Type | Default | Description |
|---|---|---|---|
custom-message |
string | ||
metadata |
map of string |
traffic.tunnels[].config (type: echo)
Config configures the echo server.
| Key | Type | Default | Description |
|---|---|---|---|
local-listen-address |
string | ||
enable-prometheus-metrics |
boolean | ||
debug |
boolean |
traffic.tunnels[].config (type: file)
Config configures the file server.
| Key | Type | Default | Description |
|---|---|---|---|
local-listen-address |
string | ||
enable-prometheus-metrics |
boolean | ||
debug |
boolean | ||
root-directory |
string | ||
prefix |
string | ||
disable-dynamic-prefix |
boolean | ||
metadata |
object | ||
authentication |
object |
traffic.tunnels[].config (type: hello)
Config configures the hello server.
| Key | Type | Default | Description |
|---|---|---|---|
custom-message |
string | ||
metadata |
map of string |
traffic.tunnels[].config (type: httpreverseproxy)
Config configures the HTTP reverse proxy server.
| Key | Type | Default | Description |
|---|---|---|---|
target-url |
string | ||
authentication |
object | ||
tls-client |
object | ||
address-validation |
object |
traffic.tunnels[].config (type: mailrouter)
Config holds configuration for the "mailrouter" tunnel type.
Unlike mailsupport, this has no auth config: the admin API and dashboard UI (see resource_extension.go, adminui) are reachable only through the agent's own local management API, never published through connect-server, so there is currently no way to obtain a token to validate against them (the agent may have no network path to an IdP at all). See doc/AGENT_CONFIGURATION.md's mailrouter section for the reasoning and what changes first if that ever needs to be revisited.
| Key | Type | Default | Description |
|---|---|---|---|
domain |
string | ||
limits |
object | ||
routes |
list of object |
traffic.tunnels[].config (type: mailsupport)
Config holds the configuration for the mail support tunnel server.
| Key | Type | Default | Description |
|---|---|---|---|
metadata |
object | ||
maddy-command |
string | ||
maddy-config-file-path |
string | ||
enable-debug |
boolean | ||
jwt-validators |
list of object | ||
principal-acl |
object | principal-acl defines an explicit allow/deny list for the API and profile routes. When AllowList is empty the tunnel's own TunnelPrincipal (injected via metadata) is used as the sole allowed caller. If neither an explicit AllowList nor a TunnelPrincipal are available, all access is denied (default-deny policy). |
traffic.tunnels[].config (type: mta-sts)
Config holds the configuration for the MTA-STS policy-hosting tunnel.
| Key | Type | Default | Description |
|---|---|---|---|
mta-sts |
object | ||
metadata |
object |
traffic.tunnels[].config (type: socks5)
Config configures the SOCKS5 server. The server only accepts CONNECT requests.
| Key | Type | Default | Description |
|---|---|---|---|
allowed-ports |
list of integer | allowed-ports lists the destination ports the server connects to. Empty allows any port. |
|
block-private-destinations |
boolean | block-private-destinations refuses destinations that are not public internet addresses: loopback, private and unique local, link-local (including cloud metadata endpoints), multicast and other special-purpose ranges. Set it on any exit other principals use. |
|
quota |
object | quota limits connections per principal: the tenant whose forward tunnel the connection arrived on, which connect-server sends in the PROXY header. With a quota set, a connection without a principal is refused, so set one only behind a connect-server that sends it. |
traffic.tunnels[].config (type: tcp)
Config configures the TCP forwarding server.
| Key | Type | Default | Description |
|---|---|---|---|
target-address |
string | target-address is the host:port each tunnel connection is forwarded to. |
|
proxy-protocol-version |
integer | proxy-protocol-version is the PROXY protocol version, 1 or 2, of a header sent ahead of each connection to name the client that connected to the tunnel; 0 sends none. The target must expect it. A maddy exec fed by this tunnel reads it automatically. |
traffic.tunnels[].config (type: webhookdebug)
Config configures the webhook debug server.
| Key | Type | Default | Description |
|---|---|---|---|
history |
integer |
tunnel-defaults.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). |
tunnel-defaults.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 |
tunnel-defaults.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 |
services.exec[].depends-on[]
Dependency names another exec or service that an exec needs to be running first.
| Key | Type | Default | Description |
|---|---|---|---|
name |
string | ||
type |
string | ||
service-type |
string |
services.exec[].config (type: maddy)
Config configures the maddy mail server run by the agent.
| Key | Type | Default | Description |
|---|---|---|---|
state-dir |
string | ||
runtime-dir |
string | ||
config-dir |
string | ||
aliases-path |
string | ||
debug |
boolean | ||
io-debug |
boolean | ||
aliases |
map of string | ||
enable-socks5 |
boolean | enable-socks5 sends maddy's outbound mail through the agent's forward tunnel of type socks5, found by its listen-address: its port, and its host unless it listens on every address, which maddy reaches on loopback. Port 1080 stands in until that tunnel registers. It needs at most one forward tunnel of type socks5; other forward tunnels are ignored. |
|
acme-dns |
object | acme-dns configures maddy to obtain its own TLS certificate directly, via maddy's built-in "acmedns" libdns provider, instead of extracting one from a sibling HTTPS tunnel's autocert cache (this exec's default, and the only behavior when Enable is false). See doc/architecture/agent/future/MADDY_LIBDNS_ACME_DESIGN.md. Requires maddy itself to be built with the "libdns_acmedns" build tag, and a matching account configured under this agent's top-level "acme-dns.accounts" -- Username/Subdomain here must equal one of those accounts exactly (see ACMEDNSAccountConfig). There is no Password field: it is looked up automatically from the matching account at render time (see ACMEDNSPasswordLookup) -- nothing ever puts it in a config file. |
|
cert-source |
object | cert-source explicitly names the HTTPS tunnel maddy's certificate should be extracted from, removing the ambiguity of the default domain-based search in getMaddyServiceCertificate (finding 52, doc/claude-review-architecture.md: two tunnels can legitimately serve the same domain, and the implicit search has no way to break the tie). Both Type and Name must be set together, or both left empty to keep the legacy domain search for backward compatibility. Ignored entirely when ACMEDNS.Enable is set, since maddy then issues its own certificate and no cert-source lookup happens at all. |
traffic.tunnels[].dns.mx[]
Record is a DNS MX record following the same Render pattern as dmarc.Record and spf.Record: fields may contain Go template strings expanded at render time.
| Key | Type | Default | Description |
|---|---|---|---|
host |
string | host is a Go template string for the mail exchange FQDN (must end in "."). Empty defaults to "{{.Domain}}." at render time — the tunnel's own FQDN. |
|
prefix |
string | prefix is the DNS owner label relative to the base domain. "" = apex. |
|
ttl |
integer | ttl is the DNS TTL in seconds advertised to resolvers. Zero uses dns.DefaultTTL. |
|
priority |
integer | priority is the MX preference value. |
traffic.tunnels[].dns.txt[]
TXTRecord is a generic DNS TXT record with optional Go template expansion in Value.
| Key | Type | Default | Description |
|---|---|---|---|
name |
string | name is the DNS owner label relative to the base domain. "" = apex. |
|
value |
string | value is a Go template string for the TXT record content (e.g. "v=spf1 {{.OutboundIPList}} -all"). |
|
ttl |
integer | ttl is the DNS TTL in seconds advertised to resolvers. Zero uses DefaultTTL. |
traffic.tunnels[].dns.cname[]
CNAMERecord is a generic DNS CNAME record with optional Go template expansion in Target. It follows the same Render pattern as mx.Record and netdns.TXTRecord.
| Key | Type | Default | Description |
|---|---|---|---|
name |
string | name is the DNS owner label relative to the base domain. "" = apex. |
|
target |
string | target is a Go template string for the canonical name this record points to (must end in "."), e.g. "{{.BaseDomain}}.". |
|
ttl |
integer | ttl is the DNS TTL in seconds advertised to resolvers. Zero uses netdns.DefaultTTL. |
traffic.tunnels[].dns.srv[]
SRVRecord is a generic DNS SRV record with optional Go template expansion in Target. It follows the same Render pattern as mx.Record and netdns.TXTRecord.
| Key | Type | Default | Description |
|---|---|---|---|
name |
string | name is the DNS owner label relative to the base domain. "" = apex. |
|
priority |
integer | ||
weight |
integer | ||
port |
integer | ||
target |
string | target is a Go template string for the target host (must end in "."), e.g. "{{.Domain}}.". |
|
ttl |
integer | ttl is the DNS TTL in seconds advertised to resolvers. Zero uses netdns.DefaultTTL. |
traffic.tunnels[].config.smtp-domains[] (type: coredns)
SMTPDomain is a mail domain together with the DNS records published for it.
| Key | Type | Default | Description |
|---|---|---|---|
name |
string | ||
records |
object |
traffic.tunnels[].config.metadata (type: file)
TunnelMetadata is the canonical, typed representation of a tunnel's metadata: the agent's local metadata store, and the shape exposed by the JSON search/metadata APIs — see doc/claude-review-architecture.md finding 11. It is a superset of TunnelConnectMetadata (the 12 fields that also cross the wire as response headers) plus fields known only locally to the agent, plus Extra for metadata outside the fixed schema entirely.
| Key | Type | Default | Description |
|---|---|---|---|
originaddr |
string | --- shared with TunnelConnectMetadata (see ToTunnelMetadata) --- | |
connectionid |
string | ||
principal |
string | ||
servicetype |
string | ||
directiontype |
string | ||
visibilitytype |
string | ||
principalemail |
string | ||
forwardtargetinternetaddr |
string | ||
basedomain |
string | ||
trafficport |
string | ||
endpointdomains |
list of string | ||
grantedcustomdomains |
list of string | ||
id |
string | --- known, local-only (never sent as a header) --- | |
trafficprotocol |
string | set locally by the tunnel.Server implementation | |
aliases |
list of string | ||
externalurls |
list of string | ||
dnsconfig |
string | JSON-encoded TunnelDNSConfig blob | |
extra |
map of string | extra holds metadata outside the fixed schema above: discovery-source labels (e.g. Docker container ID/image/name), per-server custom key/value pairs, or user-configured tags. Never sent as an HTTP header — TunnelConnectMetadata has no field for it. |
traffic.tunnels[].config.authentication (type: file)
ServerConfig represents the authentication configuration for an HTTP server.
| Key | Type | Default | Description |
|---|---|---|---|
type |
string | type selects the auth handler explicitly: "github", "basic", "hmac", "jwt", "oidc". When set it takes precedence over zero-value detection. An unrecognised Type returns an error from NewHandler. |
|
basic |
object | ||
github |
object | ||
hmac |
object | ||
jwt |
object | ||
oidc |
object | ||
providers |
list of string |
traffic.tunnels[].config.address-validation (type: httpreverseproxy)
AddressValidationConfig configures IP address validation for the reverse proxy.
| Key | Type | Default | Description |
|---|---|---|---|
enabled |
boolean | enabled controls whether address validation is performed Default: true (validation enabled for security) To disable, explicitly set to false |
|
allowed-ip-ranges |
list of string | allowed-ip-ranges defines custom IP ranges that are allowed If empty, defaults to RFC 1918 private ranges, loopback, and IPv6 private ranges Example: ["10.0.0.0/8", "192.168.0.0/16"] |
|
allow-cloud-metadata |
boolean | allow-cloud-metadata controls whether cloud metadata endpoints (e.g., 169.254.169.254) are permitted as proxy targets. Cloud metadata endpoints are ALWAYS blocked by default, even if 169.254.0.0/16 is included in AllowedIPRanges. This prevents accidental exposure through misconfiguration. Set to true to explicitly allow. Default: false (metadata endpoints always blocked) |
traffic.tunnels[].config.limits (type: mailrouter)
Limits caps resource usage per SMTP session.
| Key | Type | Default | Description |
|---|---|---|---|
max-message-bytes |
integer | ||
max-recipients |
integer |
traffic.tunnels[].config.routes[] (type: mailrouter)
RouteConfig configures one route: which recipient local-parts it matches, which registered handler type processes matching mail, and that handler type's own opaque configuration.
| Key | Type | Default | Description |
|---|---|---|---|
name |
string | name optionally labels this route for its admin-API mount point (see aggregateResource); defaults to Type if empty. |
|
recipients |
list of string | ||
type |
string | ||
config |
map |
The keys of config depend on type:
traffic.tunnels[].config.jwt-validators[] (type: mailsupport)
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. |
traffic.tunnels[].config.principal-acl (type: mailsupport)
PrincipalACLConfig describes the configuration for principal-based access control.
| Key | Type | Default | Description |
|---|---|---|---|
allow-list |
list of string | ||
deny-list |
list of string | ||
allow-by-default |
boolean | allow-by-default controls the outcome when AllowList is empty (no allow rule configured). Mirrors NetworkACLConfig.AllowByDefault; defaults to false (deny) so an unconfigured ACL fails closed. |
traffic.tunnels[].config.mta-sts (type: mta-sts)
Config represents MTA-STS configuration used to create a policy.
| Key | Type | Default | Description |
|---|---|---|---|
mode |
string | ||
mx |
list of string | ||
max-age |
integer |
traffic.tunnels[].config.quota (type: socks5)
QuotaConfig limits how many connections each principal may open through the exit. The exit sees only connections, not what is sent over them, so on a mail exit the limit counts delivery attempts: a retry, or a fallback to another MX host, is another connection.
Counts are kept in memory, so they reset when the agent restarts, and each exit instance keeps its own.
| Key | Type | Default | Description |
|---|---|---|---|
connections-per-day |
integer | connections-per-day is how many connections a principal may open in a 24 hour window, which starts at its first connection. Zero means no limit. |
|
suspend-for |
duration | suspend-for is how long a principal is refused once it has used up its quota, counted from the connection that went over. The refusal lasts at least until the principal's window ends, so SuspendFor can only lengthen it: a value shorter than the time left in the window has no effect. Zero refuses it until its window ends. A new window starts when the suspension ends. |
tunnel-defaults.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 |
tunnel-defaults.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 |
services.exec[].config.acme-dns (type: maddy)
ACMEDNSConfig is maddy's own acme-dns client configuration, rendered directly into the generated maddy.conf's "tls.loader.acme" block. It is deliberately self-contained (not cross-referenced by name from the agent's top-level acme-dns account list) -- see ACMEDNSAccountConfig's doc comment in internal/cmd/agent/agent_config.go for why -- except for the password, which is never operator-configured on either side (see ACMEDNSPasswordLookup).
| Key | Type | Default | Description |
|---|---|---|---|
enable |
boolean | enable switches maddy from the default sibling-tunnel cert-extraction behavior to self-issuing its own certificate via dns-01. |
|
email |
string | email is the ACME account email maddy registers with. Defaults to the tunnel principal's email (the same source and precedent as tls-server.acme's own email default -- see sdk/agent/tunnel.BaseTunnelConfig.Update) if left empty. |
|
server-url |
string | server-url is the base URL of this agent's acme-dns API. Defaults to "http://127.0.0.1:8556" -- this agent's own "acme-dns.listen-address" default -- if left empty. Maddy's acmedns provider appends "/update" itself. |
|
username |
string | username and Subdomain name maddy's account on this agent's acme-dns API. Both default to maddy's MX hostname, the one name its certificate is for, and the agent creates that account itself, so neither needs setting. Set them to use an account from the top-level "acme-dns.accounts" list instead, which must then be for the MX hostname. The password is generated, never configured. |
|
subdomain |
string |
services.exec[].config.cert-source (type: maddy)
CertSourceConfig identifies exactly one tunnel via search.SearchOpts{Type, Name} -- the same way it's named under traffic.tunnels -- so a domain collision between two HTTPS tunnels can never make this ambiguous, unlike the domain-based fallback it replaces.
| Key | Type | Default | Description |
|---|---|---|---|
type |
string | ||
name |
string |
traffic.tunnels[].config.smtp-domains[].records (type: coredns)
RecordsConfig configures the DNS records published for an SMTP domain.
| Key | Type | Default | Description |
|---|---|---|---|
tls-rpt |
object | ||
dkim |
object | ||
mta-sts |
object | ||
spf |
object | Render | |
dmarc |
object | Render | |
maddy-dane |
object | Render | |
maddy-dkim |
object | Render |
traffic.tunnels[].config.authentication.github (type: file)
ServerConfig contains configuration for a GitHub authentication server.
| Key | Type | Default | Description |
|---|---|---|---|
allow-insecure-http |
boolean | ||
client-id |
string | ||
client-secret |
string | ||
config-file |
string | config-file containing ClientID and ClientSecret |
|
principals |
object |
traffic.tunnels[].config.authentication.hmac (type: file)
ServerConfig contains configuration for an HMAC authentication server.
| Key | Type | Default | Description |
|---|---|---|---|
allow-insecure-http |
boolean | ||
shared-key |
string | Inline shared key used to HMAC with value from HTTPHeader | |
signed-headers |
list of string | HTTP Headers to include in the HMAC calculation. | |
timestamp-header |
string | HTTP Header to use for the timestamp (default: X-Timestamp) | |
max-timestamp-diff |
duration | Maximum allowed time difference for the timestamp (default: 5m) | |
max-future-timestamp-diff |
duration | Maximum allowed time difference for future timestamps (default: 30s) This should be smaller than MaxTimestampDiff to prevent pre-signed replay attacks. A smaller value is appropriate since it only needs to account for clock skew. | |
max-request-size |
integer | Maximum request size in bytes (default: 10 MB) |
traffic.tunnels[].config.authentication.jwt (type: file)
ValidatorConfig contains configuration for a JWT token validator.
| Key | Type | Default | Description |
|---|---|---|---|
issuer |
string | issuer is the expected token "iss" claim. Signing keys are discovered from its JWKS endpoint. Required. |
|
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. |
|
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. |
|
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. |
|
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. |
traffic.tunnels[].config.authentication.oidc (type: file)
OIDCServerConfig combines OIDC provider credentials with the login/session middleware settings (redirect-uri, cookies, login/logout paths) needed to complete a login when "type: oidc" is used as a server's sole auth gate.
| 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. |
|
scopes |
list of string | ||
redirect-uri |
string | ||
token-cookie |
object | ||
state-cookie |
object | ||
refresh-cookie |
object | ||
token-expiry |
object | ||
redirect-cookie |
object | ||
id-token-cookie |
object | ||
refresh-window |
duration | ||
login-path |
string | ||
logout-path |
string | ||
allow-insecure-cookies |
boolean | allow-insecure-cookies disables the default Secure attribute on session cookies, allowing them to be sent over plain HTTP. Session cookies carry live OAuth access and refresh tokens, so this must only be set for local HTTP development — never in production. Mirrors oidc.ValidatorConfig.AllowInsecureHMAC's explicit-opt-in shape. |
traffic.tunnels[].config.routes[].config (type: attachment)
Config holds per-route configuration for the "attachment" handler type.
| Key | Type | Default | Description |
|---|---|---|---|
max-attachment-bytes |
integer | 26214400 |
|
root-directory |
string | RootDirectory, if set, switches the handler from the default in-memory store to a disk-backed store rooted at this directory ("~" and environment variables are expanded). Attachments saved to the in-memory store do not survive a restart; a disk-backed store does. | |
path-template |
string | {{.SenderDomain}}/{{.Year}}/{{.Month}} |
path-template controls the save-path directory hierarchy beneath RootDirectory. Only used when RootDirectory is set. See store.PathTemplateData for the available template fields. |
subject-patterns |
list of object | subject-patterns are matched against each attachment's message Subject; a match's named capture groups become additional path-template fields. Only used when RootDirectory is set. Tried before the built-in well-known vendor patterns (see DisableWellKnownSubjectPatterns), so a pattern here can override one of those by matching the same subject more specifically. |
|
disable-well-known-subject-patterns |
boolean | disable-well-known-subject-patterns turns off the built-in registry of well-known vendor subject-patterns (Stripe, AWS, Microsoft, GitHub, Xero), which is otherwise always available in addition to SubjectPatterns. Only used when RootDirectory is set. |
traffic.tunnels[].config.routes[].config (type: dmarc)
Config holds per-route configuration for the "dmarc" mailrouter handler type. Domain and message-transfer limits are configured at the mailrouter tunnel level, not here — see internal/servers/mailrouter.Config.
| Key | Type | Default | Description |
|---|---|---|---|
max-message-bytes |
integer | 26214400 |
|
database-path |
string | DatabasePath, if set, switches the handler from the default in-memory report store to a disk-backed SQLite store at this path ("~" and environment variables are expanded). Reports saved to the in-memory store do not survive a restart; a SQLite-backed store does, and also unlocks the additional analytics endpoints on the report resource (see resource.NewReportResource). |
traffic.tunnels[].config.routes[].config (type: tls-rpt)
Config holds per-route configuration for the "tls-rpt" mailrouter handler type. Domain and message-transfer limits are configured at the mailrouter tunnel level, not here — see internal/servers/mailrouter.Config.
| Key | Type | Default | Description |
|---|---|---|---|
max-message-bytes |
integer | 26214400 |
|
database-path |
string | DatabasePath, if set, switches the handler from the default in-memory report store to a disk-backed SQLite store at this path ("~" and environment variables are expanded). Reports saved to the in-memory store do not survive a restart; a SQLite-backed store does, and also unlocks the additional analytics endpoints on the report resource (see resource.NewReportResource). |
traffic.tunnels[].config.smtp-domains[].records.tls-rpt (type: coredns)
Record represents a TLSRPT (TLS Reporting) DNS TXT record.
| Key | Type | Default | Description |
|---|---|---|---|
version |
string | ||
report-uri-aggregate |
list of string |
traffic.tunnels[].config.smtp-domains[].records.dkim (type: coredns)
Record represents a DKIM DNS record.
| Key | Type | Default | Description |
|---|---|---|---|
version |
string | ||
key-type |
string | ||
public-key |
string |
traffic.tunnels[].config.smtp-domains[].records.mta-sts (type: coredns)
Record represents an MTA-STS DNS TXT record.
| Key | Type | Default | Description |
|---|---|---|---|
version |
string | ||
id |
string |
traffic.tunnels[].config.smtp-domains[].records.spf (type: coredns)
Record represents an SPF DNS record.
| Key | Type | Default | Description |
|---|---|---|---|
version |
string | ||
mechanisms |
list of object | ||
all |
boolean | ||
all-qualifier |
string |
traffic.tunnels[].config.smtp-domains[].records.dmarc (type: coredns)
Record represents a DMARC DNS record.
| Key | Type | Default | Description |
|---|---|---|---|
version |
string | ||
policy |
string | ||
percent |
integer | ||
report-uri-aggregate |
list of string | ||
report-uri-failure |
list of string | ||
subdomain-policy |
string | ||
alignment-policy-dkim |
string | ||
alignment-policy-spf |
string |
traffic.tunnels[].config.smtp-domains[].records.maddy-dane (type: coredns)
MaddyDANERecord is a TLSA/DANE record derived from the certificate maddy serves for its MX hostname, in whichever of maddy's two certificate layouts its state directory holds (see maddyCertificatePath). It preserves the config schema (state-dir, port, auto-refresh, auto-refresh-period-seconds) maddy tunnel configs already use.
| Key | Type | Default | Description |
|---|---|---|---|
state-dir |
string | ||
port |
integer | ||
auto-refresh |
boolean | auto-refresh is rejected in a coredns tunnel's smtp-domains, which reads the certificate again every 30 seconds. |
|
auto-refresh-period-seconds |
integer | auto-refresh-period-seconds is rejected in a coredns tunnel's smtp-domains, which reads the certificate again every 30 seconds. |
traffic.tunnels[].config.smtp-domains[].records.maddy-dkim (type: coredns)
MaddyDKIMRecord is a TXT record derived from the DKIM selector key file maddy writes for a domain. It preserves the config schema (state-dir, auto-refresh, auto-refresh-period-seconds) maddy tunnel configs already use.
| Key | Type | Default | Description |
|---|---|---|---|
state-dir |
string | ||
auto-refresh |
boolean | auto-refresh is rejected in a coredns tunnel's smtp-domains, which reads the key file again every 30 seconds. |
|
auto-refresh-period-seconds |
integer | auto-refresh-period-seconds is rejected in a coredns tunnel's smtp-domains, which reads the key file again every 30 seconds. |
traffic.tunnels[].config.authentication.oidc.token-cookie (type: file)
CookieConfig configures a single session cookie's name, scope, and lifetime.
| Key | Type | Default | Description |
|---|---|---|---|
name |
string | ||
domain |
string | ||
secure |
boolean | ||
path |
string | ||
max-age |
duration |
traffic.tunnels[].config.routes[].config.subject-patterns[] (type: attachment)
SubjectPattern is one named regex matched against the message Subject.
Provider and Vendor are optional pattern-level metadata, not captured from the subject: Provider identifies the invoicing platform that sent the email (e.g. "stripe") and is always fixed per pattern. Vendor is the actual company being paid; set it here when the pattern's own vendor IS the provider (e.g. "Amazon Web Services" for an AWS pattern). Leave Vendor empty and capture a group named exactly "Vendor" in Pattern instead when the platform invoices on behalf of many different businesses (Stripe, Xero) — see extractSubjectFields for the precedence rule between the two.
| Key | Type | Default | Description |
|---|---|---|---|
name |
string | ||
provider |
string | ||
vendor |
string | ||
pattern |
string |
traffic.tunnels[].config.smtp-domains[].records.spf.mechanisms[] (type: coredns)
Mechanism represents an SPF mechanism in a DNS record.
| Key | Type | Default | Description |
|---|---|---|---|
qualifier |
string | ||
name |
string | ||
values |
list of string | ||
value-list |
string |