Configuration reference¶
dns-gate reads one YAML file (-config, default /etc/dns-gate/config.yaml, or DNS_GATE_CONFIG_URI / DNS_GATE_CONFIG): a file path, s3://bucket/key or ssm:/parameter/name. Decoding is strict: an unknown field stops the gate at startup. Durations are Go durations (90s, 24h) or a whole number of days (14d). dns-gate -check -config file.yaml validates a file and exits.
A complete example is in examples/config.yaml; a small one runs the Quickstart.
| Page | Sections |
|---|---|
| This page | secrets, top level and limits, store, audit, propagation check |
| Providers, discovery and folders | providers, zone discovery, EuroDNS folders, zone profiles |
| Issuers and keys | issuers, gate-issued tokens, token exchange, delegated clients and scopes, oauth.clients, Entra ID, Azure DevOps, virtual_keys |
| Roles, teams and bindings | roles, URL forward rules, groups, teams, ownership, bindings, team_from, protected, adoption and Terraform export |
| Managed policy and delegations | policy: the UI-edited layer, policy.delegations and the delegation API |
| Web UI and MCP | ui, SAML login, mcp, connecting assistants |
Secrets¶
Secrets never live in the YAML file. Each one is read from an environment variable, or from the file named by the same variable with a _FILE suffix (the form to use with Kubernetes Secret volumes).
| Variable | Used for | Required |
|---|---|---|
EURODNS_<ID>_API_KEY, else EURODNS_API_KEY |
EuroDNS X-API-KEY of the provider <ID> |
with a eurodns provider |
EURODNS_<ID>_APP_ID, else EURODNS_APP_ID |
EuroDNS X-APP-ID, overrides eurodns.app_id |
if eurodns.app_id is empty |
DNS_GATE_POSTGRES_DSN |
Postgres connection string | with store.type: postgres |
DNS_GATE_SESSION_KEY |
32-byte key (hex or base64) encrypting UI cookies | with ui.enabled |
DNS_GATE_UI_CLIENT_SECRET |
OIDC client secret of the UI | no (public client with PKCE) |
DNS_GATE_SAML_SP_KEY, DNS_GATE_SAML_SP_CERT |
PEM key (RSA or ECDSA) and certificate of the SAML service provider, signing the AuthnRequests | no (unsigned requests) |
DNS_GATE_TOKEN_SIGNING_KEY |
PEM key (EC P-256 or Ed25519) signing gate-issued tokens | with an issuer self: true |
DNS_GATE_OAUTH_CLIENT_<ID>_SECRET |
Secret of an OAuth client with client_secret_basic or client_secret_post (at least 32 characters) |
for those clients |
<ID> is the provider (or OAuth client) id in upper case, every character other than a letter or a digit replaced by _ (eu-2 gives EURODNS_EU_2_API_KEY); the unprefixed variables serve every EuroDNS provider without its own. Route53 providers use the default AWS credential chain (IRSA, Pod Identity, instance role, environment), optionally assuming a role.
DNS_GATE_SECRETS_ARN names a Secrets Manager secret holding a JSON object of these variables ({"EURODNS_API_KEY":"…"}), loaded into the environment at startup; a variable already set wins. See DEPLOY-LAMBDA.md.
Other environment variables: POD_NAME (lock holder id, defaults to the hostname) and DNS_GATE_REPLICAS (only used to warn when a single-replica store runs with several replicas).
Generate a session key with openssl rand -hex 32, a token signing key with openssl genpkey -algorithm EC -pkeyopt ec_paramgen_curve:P-256 (or -algorithm ed25519).
Top level¶
| Field | Default | Description |
|---|---|---|
listen.address |
:8080 |
HTTP listen address. TLS is terminated in front of the gate. |
listen.trusted_proxies |
[] |
CIDRs of reverse proxies allowed to set X-Forwarded-For. The rightmost untrusted hop is the client address (used by virtual_keys[].allowed_cidrs). |
providers |
(required) | The DNS accounts the gate fronts, see Providers. |
zones |
[] |
Managed zones of the base layer. Zones listed by the active managed policy revision are added to them. Requests for any other zone are refused before authorization (zones found by zone discovery are readable only). Each zone must be selected by a provider. |
check_on_write |
true |
Run the provider dry run (EuroDNS check) before every write; providers without one (Route53) are not affected. |
reconcile_interval |
15m |
Drift detection period per zone (minimum 1m). |
limits.max_body_bytes |
1048576 |
Request body limit. |
limits.max_changes_per_request |
20 |
Default blast-radius limit (RRset changes per request). |
limits.ephemeral_lifetime_factor |
4 |
An ephemeral RRset lives at most its creation plus this many ephemeral_ttl, however often values are added. |
acme.max_registrations |
100 |
acme-dns registrations and httpreq value ledgers per API key or token subject. |
acme.registration_idle |
720h |
Registrations of token subjects and httpreq ledgers unused this long are purged (maintenance, DynamoDB TTL). |
acme.max_values |
20 |
Values of one challenge TXT RRset. |
acme.max_values_per_author |
4 |
Values one API key or token subject may hold in a challenge TXT RRset (at most acme.max_values). |
lock.ttl, lock.wait |
60s, 30s |
Per-zone write lease and how long a request waits for it (then 503 zone_locked). |
Store¶
| Field | Default | Description |
|---|---|---|
store.type |
memory |
memory, sqlite, postgres or dynamodb. |
store.audit_retention |
9600h (400 days) |
Audit events older than this are purged (minimum 24h). |
store.sqlite.path |
Database file, on a persistent volume. | |
store.postgres.max_conns |
5 |
Pool size (1 to 100). The DSN comes from DNS_GATE_POSTGRES_DSN. |
store.dynamodb.table, region, endpoint |
Single-table backend; credentials from the default AWS chain (EKS Pod Identity, IRSA, environment). |
memory loses ownership on restart: tests only (refused with oauth.clients). memory and sqlite support one replica (the chart refuses replicaCount > 1 with them); use postgres or dynamodb to run several replicas.
Audit¶
| Field | Default | Description |
|---|---|---|
audit.format |
native |
Format of the audit lines on stdout: native, ecs (Elastic Common Schema 8.x) or ocsf (OCSF 1.3). The store, the UI and GET /api/v1/audit always keep the native event. Every format keeps "type": "audit". |
audit.hash_chain |
false |
Adds instance_id, seq, prev_hash, hash_alg and hash (SHA-256 chain per process) to every stdout line, checked by dns-gate audit verify. |
audit.hash_chain_key |
From DNS_GATE_AUDIT_CHAIN_KEY or DNS_GATE_AUDIT_CHAIN_KEY_FILE only (32 bytes, hex or base64): the chain becomes an HMAC-SHA256 that cannot be recomputed without the key. Requires audit.hash_chain: true. |
Schema, actions, reasons, mappings, the limits of the chain and export recipes (CloudWatch subscription filter, Kubernetes collectors, API pull) are in AUDIT.md.
Propagation check¶
GET /api/v1/zones/{zone}/rrsets/{host}/{type}/propagation (API.md), the check_propagation MCP tool and the Propagation panel of the UI (RRset drawer when the viewer holds dns.read on the RRset, and right after an apply) ask the authoritative name servers of a managed zone and a list of public resolvers for one RRset, and compare their answers with the RRset as read from the provider.
| Field | Default | Description |
|---|---|---|
propagation.enabled |
true, false on AWS Lambda |
Serves the check (501 not_implemented and no MCP tool when false). On Lambda it must be enabled explicitly, see DEPLOY-LAMBDA.md. |
propagation.resolvers |
the list below | Public resolvers asked, replacing the default list: name, address (an IP address with an optional port, never a host name), filtering (true for a resolver that blocks names by policy), and for display location, country (ISO code) and region (the UI groups by region: anycast, europe, north-america, south-america, asia, oceania, africa, or free text). At most 64. |
propagation.allow_private_resolvers |
false |
Accepts resolver addresses outside the public unicast space (private, loopback, link-local, shared, documentation and the other IANA special-purpose blocks, also when embedded in IPv6). Such a resolver may answer internal names of a split-horizon DNS: anyone allowed to check an RRset would learn its internal answer. |
propagation.query_timeout |
1.5s |
Timeout of one query (100ms to 10s, at most timeout). |
propagation.timeout |
4s |
Deadline of a whole check (query_timeout to 5s): servers that did not answer by then are reported as error (timeout). |
propagation.concurrency |
16 |
Servers one check asks at once (1 to 64). |
propagation.max_in_flight |
3 |
Checks running at once in one process (1 to 64, 503 busy beyond). |
propagation.cache_ttl |
10s |
A result is reused for the same RRset content during this time (1s to 5m), whoever asks. |
propagation.requests_per_minute |
30 |
Checks of one subject that are not served from the cache (1 to 600, 429 beyond). The UI asks every 5 seconds while a panel is open, for at most 2 minutes. |
Per instance. The cache, the per-subject limit (the 4096 most recently seen subjects) and max_in_flight are kept in memory by each process: with several replicas or Lambda instances, a subject can run requests_per_minute checks on each of them, and a load balancer spreading the polls of one panel over replicas finds a cold cache on each.
propagation:
resolvers:
- {name: Cloudflare, address: 1.1.1.1, location: Anycast, country: US, region: anycast}
- {name: Quad9, address: 9.9.9.9, location: Anycast, country: CH, region: anycast, filtering: true}
Network: the gate needs outbound UDP and TCP port 53 to the resolvers and to the name servers of its zones (TCP when an answer is truncated or UDP fails). AWS Lambda functions outside a VPC have it; in a VPC, the security group and the network ACLs must allow it through a NAT gateway. The name servers of a zone are its apex NS as read from the provider (looked up with the system resolver when the gate has none), resolved with the system resolver; those whose address is not public (same check as allow_private_resolvers, never overridable) are skipped. The default resolvers are IPv4, as Lambda functions outside a VPC have no IPv6 egress.
Default resolvers, all documented open resolvers needing no account, unfiltered services where the operator offers one (filtering marks those that block malware or phishing domains):
| Resolver | Address | Location |
|---|---|---|
| Cloudflare | 1.1.1.1 |
Anycast (US) |
| Google Public DNS | 8.8.8.8 |
Anycast (US) |
| Quad9 (filtering) | 9.9.9.9 |
Anycast (CH) |
| OpenDNS (Cisco, filtering) | 208.67.222.222 |
Anycast (US) |
| AdGuard DNS, unfiltered | 94.140.14.140 |
Anycast (CY) |
| Control D, unfiltered | 76.76.2.0 |
Anycast (CA) |
| CleanBrowsing, security filter (filtering) | 185.228.168.9 |
Anycast (US) |
| UltraDNS Public | 64.6.64.6 |
Anycast (US) |
| NextDNS | 45.90.28.0 |
Anycast (US) |
| DNS.SB | 185.222.222.222 |
Anycast (DE) |
| Hurricane Electric | 74.82.42.42 |
Anycast (US) |
| DNS4EU, unfiltered | 86.54.11.100 |
European Union |
| FDN | 80.67.169.12 |
Paris, FR |
| Yandex DNS | 77.88.8.8 |
Moscow, RU |
| CIRA Canadian Shield, private | 149.112.121.10 |
Canada |
| AliDNS (Alibaba) | 223.5.5.5 |
Hangzhou, CN |
| DNSPod (Tencent) | 119.29.29.29 |
Shenzhen, CN |
| 114DNS | 114.114.114.114 |
Nanjing, CN |
| Quad101 (TWNIC) | 101.101.101.101 |
Taipei, TW |
How to read a result, and how answers are compared: Propagation check.
A check is a read: no audit event, a debug log line (propagation). The provider re-read of expect runs only for callers holding dns.read on the whole zone (a record-scoped reader gets the 412), so no refusal is audited either (AUDIT.md).