Configuration
Environment Variables
Complete reference for all DNS Resolver environment variables.
Environment Variables
DNS Resolver is configured entirely via environment variables. The entrypoint reads these at every container start, generates the Corefile and zone file from templates, validates them, and then starts CoreDNS and docker-gen.
Required variables
| Variable | Required | Default | Description |
|---|---|---|---|
DOMAIN | Yes | — | Internal domain zone (e.g. home.example.com). A wildcard A record (*.DOMAIN) and a zone SOA are generated for this domain. |
HOST_IP | Yes | — | IP address that all *.DOMAIN (and DOMAIN) queries resolve to. Typically the LAN IP of the Docker host. |
The container exits immediately if either of these is missing.
DNS behaviour
| Variable | Required | Default | Description |
|---|---|---|---|
DNS_UPSTREAM | No | 1.1.1.1 | Upstream resolver for all queries that are not within DOMAIN. Accepts a single IP address. |
DNS_AUTHORITATIVE | No | true | Controls what happens when a subdomain under DOMAIN is not in the hosts file or zone. See Authoritative vs split-horizon. |
Authoritative vs split-horizon
DNS_AUTHORITATIVE | Unknown subdomain under DOMAIN | External query |
|---|---|---|
true (default) | NXDOMAIN | Forwarded to DNS_UPSTREAM |
false | Forwarded to DNS_UPSTREAM | Forwarded to DNS_UPSTREAM |
Use false for split-horizon DNS: the zone is served locally, but unknown subdomains fall through to your upstream resolver rather than returning NXDOMAIN.
ACME DNS-01
| Variable | Required | Default | Description |
|---|---|---|---|
ACME_DNS_ENABLED | No | false | Set to true to add a CoreDNS forward stanza that proxies all auth.DOMAIN queries to the acme-dns sidecar container at acme-dns:53. See ACME DNS-01. |
Reload and debounce intervals
These control the latency between a container event and its DNS entry becoming resolvable.
| Variable | Required | Default | Description |
|---|---|---|---|
HOSTS_RELOAD | No | 15s | How often CoreDNS re-reads /etc/coredns/hosts. Accepts CoreDNS duration format: 5s, 1m30s, etc. |
ZONE_RELOAD | No | 30s | How often CoreDNS re-reads the static zone file. The zone file only changes on container restart, so a longer interval is usually fine. |
DOCKERGEN_WAIT | No | 5s:30s | docker-gen debounce window in min:max format. docker-gen waits at least min after the last event before rewriting the hosts file, and at most max. |
Tuning guidance
| Deployment type | Recommended settings |
|---|---|
| Stable infrastructure (few containers, rare events) | DOCKERGEN_WAIT=5s:30s, HOSTS_RELOAD=15s (defaults) |
| Dynamic infrastructure (many containers, frequent events) | DOCKERGEN_WAIT=1s:5s, HOSTS_RELOAD=5s |