Transforms

Active contributors: greenpau, johnbelamaric, miekg, rtreffer, ekleiner, Tantalor93, chrisohaver

Purpose

Transforms reshape questions or answers without owning a zone. They sit between the listener and the backends.

Plugins in this group

Plugin	Source	One-liner
rewrite	plugin/rewrite/	Rewrite question name/type/class or answer fields, simple or complex
template	plugin/template/	Synthesize replies from regex-match templates
header	plugin/header/	Set/clear flags on the response header
minimal	plugin/minimal/	Implement RFC 8482 minimal-responses (drop unsolicited additional/authority)
loadbalance	plugin/loadbalance/	Round-robin A/AAAA records in answers
any	plugin/any/	RFC 8482 ANY-type minimal answer (HINFO refusal)
chaos	plugin/chaos/	Reply to version.bind and friends in CH class
autopath	plugin/autopath/	Search-domain optimisation for Kubernetes pods
metadata	plugin/metadata/	Populate per-request metadata for downstream plugins

How they fit

graph LR
    Q[query] --> M[metadata]
    M --> AC[acl]
    AC --> CH[chaos]
    CH --> AN[any]
    AN --> RW[rewrite]
    RW --> AP[autopath]
    AP --> TPL[template]
    TPL --> BE[backends]
    BE --> HDR[header / minimal / loadbalance]
    HDR --> Out[reply]

The transforms before backends mostly mutate the question; the ones after mutate the answer via wrapped ResponseWriters.

Plugins in detail

rewrite

Two execution modes:

• Simple rewrites (parser tokens decided at setup): rewrite name, type, class, EDNS0 options, TTL, and CNAME targets. Cheap.
• Complex rewrites with expr expressions (plugin/pkg/expression/) and conditional logic.

Variants are listed in the README and include name [exact|prefix|suffix|substring|regex], type, class, edns0 local set/append/replace, edns0 nsid, edns0 subnet, ttl, and cname. The continue|stop token controls whether the rewrite chain keeps walking after a match.

template

Generate answers from regex matches against the qname. Useful for synthetic zones (e.g. *.test.local → 127.0.0.1). Supports answer, authority, additional sections and per-rcode templates.

header

Set or clear aa, ra, ad, tc, cd flags on outgoing replies. Used in front of backends that don't quite produce the right header bits (most often forward upstreams that lie about authoritative).

minimal

Wraps the response writer to strip the additional/authority sections from non-NS responses, implementing RFC 8482 minimal-response semantics. Reduces UDP fragmentation risk.

loadbalance

Round-robins A and AAAA records inside answers. Stateless; the rotation is pseudo-random per query.

any

Returns a minimal answer for ANY queries (RFC 8482) — typically an HINFO RR explaining the policy. Defends against ANY-amplification abuses.

chaos

Answers version.bind, version.server, id.server, hostname.bind in the CH class. Configurable strings. The presence of chaos (or forward/proxy) is what flips Server.classChaos = true.

autopath

Kubernetes-specific optimisation. Pods come with a search list (namespace.svc.cluster.local, svc.cluster.local, ...) and resolvers normally walk it sequentially, paying a round trip per attempt. autopath performs the search server-side: it tries the qname, then sequential variants, and returns the first hit synthesized as a CNAME chain. Enabled in cooperation with kubernetes.

metadata

Implements MetadataCollector (core/dnsserver/server.go). Once per request, the server calls metadata.Collect(ctx, req), which iterates registered providers. Providers include other plugins that implement the metadata.Provider interface and contribute lazy values via metadata.SetValueFunc(ctx, key, fn). Consumers (log, errors, replacer) read values with metadata.ValueFunc(ctx, key)(). This pattern keeps cross-cutting state explicit but lazy.

Cross-plugin notes

• metadata must run first among the transforms (and it is — it sits second in plugin.cfg after root).
• chaos, forward, and (legacy) proxy flip CoreDNS into accepting CH-class queries, otherwise they're refused at the server level.
• loadbalance cooperates with file-based backends — it rotates the answer set the backend produces.
• autopath requires kubernetes to know which pods the search list belongs to.
• rewrite sits before the backend chain and can route queries between zones.

Key source files

File	Purpose
plugin/metadata/metadata.go, setup.go	Per-request metadata fan-in
plugin/rewrite/rewrite.go, plus 30+ siblings	Rewrite engine
plugin/template/template.go	Response synthesizer
plugin/header/header.go	Header mutator
plugin/minimal/minimal.go	RFC 8482 minimal responses
plugin/loadbalance/loadbalance.go	Answer rotation
plugin/any/any.go	ANY refusal
plugin/chaos/chaos.go	CH class answers
plugin/autopath/autopath.go	Kubernetes search optimisation
plugin/pkg/replacer/	Placeholder substitution
plugin/pkg/expression/	Expression evaluator used by rewrite

Related pages

• Backends — these plugins typically run before backends.
• Observability — metadata is consumed by log, errors, and prometheus.
• Plugin system — MetadataCollector interface.