Configuration

CLI flags

The full set is in coremain/run.go (init() registers them on Caddy's flag set):

Flag	Default	Effect
-conf <path>	Corefile in CWD	Path to the Corefile
-pidfile <path>	(none)	Write the process PID to this file
-quiet	false	Suppress informational logging
-version	false	Print version and exit
-plugins	false	List compiled-in plugins and exit
-dns.port <port>	53	Default port for dns:// listeners

Caddy contributes additional flags (-validate, -conf, etc.). Most are not used in production but -validate is handy:

./coredns -conf Corefile -validate

Environment variables

CoreDNS itself does not consume environment variables outside of the standard Go runtime ones. Plugins do — for example, the AWS SDK reads AWS_REGION, AWS_ACCESS_KEY_ID, etc. from its credential chain.

Corefile grammar

A Corefile is a Caddyfile with the dns server type. The grammar (informal):

corefile     := serverblock+
serverblock  := address-list "{" directive* "}"
              | address-list directive          ; one-line
address-list := address ("," address)*
address      := [scheme://] zone [:port]        ; e.g. `tls://example.com:853`
scheme       := dns | tls | https | https3 | quic | grpc
zone         := dns-name | "."                  ; "." is the root zone
directive    := plugin-name argument* ("{" subdirective* "}")?
subdirective := keyword argument*

Whitespace and newlines are significant for separating tokens but not for indentation. Comments begin with #.

A minimal Corefile:

.:53 {
    forward . 8.8.8.8
}

A Corefile with multiple server blocks, multiple schemes, views, and shared plugins:

tls://example.com:853 dns://example.com:53 {
    tls cert.pem key.pem
    cache
    forward . tls://1.1.1.1
}

. {
    log
    errors
    forward . 8.8.8.8
}

The first server block runs on both dns:// and tls:// for example.com. The second is a wildcard fallback for everything else on :53.

Plugin invocation grammar

Each plugin's exact subdirective grammar lives in its README.md and setup.go. The common patterns:

plugin-name [args...]
plugin-name [args...] {
    sub-directive [args...]
    ...
}

For example, forward:

forward . tls://1.1.1.1 tls://1.0.0.1 {
    tls_servername cloudflare-dns.com
    health_check 5s
    max_concurrent 1000
    policy random
}

plugin.cfg and directive ordering

plugin.cfg lists every plugin in the order they should appear in the chain. The format is one of:

name:package
name:replacement:package
name:github.com/external/plugin

The third form is for plugins outside this repository (e.g. on:github.com/coredns/caddy/onevent).

When you add a new plugin, edit plugin.cfg and run make gen. The generators rebuild:

• core/plugin/zplugin.go — anonymous imports.
• core/dnsserver/zdirectives.go — the ordered directive list.

The order of plugins is the order in which they receive each query. The current plugin.cfg order, abbreviated:

metadata > geoip > cancel > tls > reload > nsid > bufsize > root > bind > debug
> trace > ready > health > pprof > prometheus > errors > log > dnstap > local
> dns64 > acl > any > chaos > loadbalance > cache > rewrite > header > dnssec
> autopath > template > transfer > hosts > route53 > azure > clouddns > nomad
> federation > k8s_external > kubernetes > file > auto > secondary > etcd
> loop > forward > grpc > erratic > whoami > on

The official ordering rationale is in the plugins README.

Server-block options

Inside a server block, certain plugins behave more like options than handlers:

Plugin	Effect	See
bind	Restrict listen addresses	Transport
tls	Configure TLS for the block	Transport
https, https3, quic, grpc_server	Set per-protocol caps	Transport
proxyproto	Enable PROXY protocol	Transport
multisocket	Number of SO_REUSEPORT listeners	Transport
timeouts	TCP read/write/idle timeouts	Transport
bufsize	EDNS0 buffer size clamp	Transport
nsid	Add NSID OPT to responses	Transport
view	Match expression for splitting traffic	Security

Internal config struct

core/dnsserver/config.go defines the Config per server block. Setup functions on each plugin populate fields directly. The most relevant ones:

Field	Default	Set by
Zone	from address	dnsserver.NewConfig
Transport	dns	from scheme
ListenHosts	[""]	bind
Port	53	from address
Root	(empty)	root
Debug	false	debug
Stacktrace	false	debug
TsigSecret	nil	tsig
TLSConfig	nil	tls
ReadTimeout, WriteTimeout, IdleTimeout	per-protocol	timeouts
MaxHTTPSConnections	200	https
MaxHTTPS3Streams	256	https3
MaxQUICStreams, MaxQUICWorkerPoolSize	256, 1000	quic
MaxGRPCStreams, MaxGRPCConnections	256, 200	grpc_server
NumSockets	1	multisocket
ProxyProtoConnPolicy	nil	proxyproto
Plugin	(chain)	populated by RegisterPlugin callbacks
View	nil	view

Reload

The reload plugin watches the Corefile every INTERVAL (default 30s, optional JITTER) and triggers caddy.Restart on a SHA-256 change. Reload is graceful: new processes inherit listeners via SO_REUSEPORT.

Pidfile

-pidfile <path> writes the PID once the listeners are up. Useful for systemd unit files that want to track the post-fork PID.

Default Corefile

If no Corefile is found and -conf is not supplied, CoreDNS uses a baked-in default that loads whoami and log on .:53 (see Fun facts).