Glossary

Project-specific terms used throughout this wiki and the codebase.

CoreDNS terms

Corefile. The CoreDNS configuration file. A list of server blocks, each with one or more zone keys and a brace-enclosed body of directives. Default location: Corefile in the working directory. See Reference: configuration.

Server block. A keys { body } group in a Corefile. Each block becomes one or more *Config instances after parsing — one per key. Plugins added inside the body are shared across all keys in the same block via firstConfigInBlock. See core/dnsserver/register.go.

Directive. A single line inside a server block whose first token is the name of a plugin. The order of directives in the Corefile is irrelevant — execution order is fixed by plugin.cfg and propagated to core/dnsserver/zdirectives.go.

Plugin. A compiled-in handler. Each plugin lives in plugin/<name>/, registers itself with plugin.Register("name", setup), and provides a ServeDNS method. Plugins are chained right-to-left when a config is compiled. See Plugin system and Plugins overview.

Plugin chain. The compiled, linked-list head returned from setup calls. A request enters at the head and walks down via plugin.NextOrFailure(name, p.Next, ctx, w, r) until a plugin writes a response.

Server type. A Caddy concept. CoreDNS registers one server type, dns, in core/dnsserver/register.go. The Caddy framework drives the parse-and-bind lifecycle around it.

Zone. A DNS suffix the server is authoritative or responsible for in a given block. The same listen address can host multiple zones; the server picks the longest matching suffix in Server.ServeDNS.

Transport. The wire protocol used by a server: dns (UDP+TCP), tls (DoT), https (DoH), https3 (DoH3), quic (DoQ), or grpc. Selected by the URL-style scheme in a Corefile key (tls://example.org).

Plugin-side concepts

Handler. Interface in plugin/plugin.go. ServeDNS(ctx, w, r) (int, error) plus Name() string. Every plugin implements this.

plugin.Plugin. A function func(Handler) Handler that wraps the next plugin. Returned from a plugin's setup via dnsserver.GetConfig(c).AddPlugin(...) and used by NewServer to fold the chain.

Fallthrough. A plugin policy: when a query does not match the plugin's responsibility, it should call the next plugin instead of returning a definitive answer. The shared plugin/pkg/fallthrough package implements the convention.

Metadata. A context.Context value populated by plugins that implement MetadataCollector. The server calls Collect once per request before the chain runs. Plugins set lazy values with metadata.SetValueFunc and read them with metadata.ValueFunc.

View. A plugin that scopes a server block to clients matching a CEL-like expression. Implemented as a Viewer in core/dnsserver/view.go that contributes a FilterFunc to its Config.

ScrubWriter. A dns.ResponseWriter wrapper that truncates replies to the client's advertised buffer size. Installed by Server.ServeDNS so plugins can write full messages without worrying about UDP size.

plugin/pkg/. Shared helpers — caches, parse helpers, log, transport defaults, dnsutil, response classification, reuseport listeners, and so on. Plugins import these instead of duplicating code. See Shared packages.

DNS-related terms

Rcode. The DNS response code: NOERROR, SERVFAIL, REFUSED, NXDOMAIN, etc. CoreDNS uses rcode return values from ServeDNS to know whether a plugin already wrote to the client (plugin.ClientWrite).

EDNS0 / OPT. The pseudo-record carrying extended DNS options. request.Request.Size, Do, and SizeAndDo interpret the OPT record to negotiate UDP buffer size and DNSSEC OK.

DNSSEC OK (DO bit). Indicates the client wants DNSSEC records in the response.

Authoritative Data (AD bit). Indicates the response was DNSSEC-validated.

Checking Disabled (CD bit). Tells a validator to return all data.

TSIG. Transaction signature for authenticating DNS messages. Configured per-server via TsigSecret; tied to plugins like tsig, transfer, secondary.

AXFR / IXFR. Full and incremental zone transfers. Handled by the transfer and secondary plugins.

NSID (RFC 5001). Optional name server identifier returned in an OPT record. Provided by the nsid plugin.

dnstap. A binary structured logging format for DNS messages, framed via golang-framestream. Emitted by the dnstap plugin and consumed by the forward, dnstap, and others.

DoT, DoH, DoH3, DoQ. DNS-over-TLS (RFC 7858), DNS-over-HTTPS over HTTP/2 (RFC 8484), DoH over HTTP/3, and DNS-over-QUIC (RFC 9250). Each maps to a CoreDNS server type.

Build and codegen

zplugin.go. Generated file at core/plugin/zplugin.go. Contains blank imports for every plugin in plugin.cfg. Pulls each plugin's init() into the binary.

zdirectives.go. Generated file at core/dnsserver/zdirectives.go. Holds the Directives slice in execution order — the same order as plugin.cfg. Both files are produced by directives_generate.go and refreshed by make gen.

make gen. Convenience target wrapping go generate coredns.go && go get. CI verifies its output is committed (workflow verify-make-gen.yml).

COREDNS_PLUGINS. Environment variable consulted by directives_generate.go to add extra plugins to the build without editing plugin.cfg.

CNCF / governance

SC. Steering committee. The list of members lives at the top of CODEOWNERS. Governance is described in GOVERNANCE.md.

DCO. Developer Certificate of Origin. CoreDNS is a CNCF project; every commit must carry a Signed-off-by line. Enforced by Probot. See Contributing.

Lame duck. A short period between SIGTERM and shutdown during which the server still serves queries but the ready plugin reports not-ready. Configurable on the health plugin.