Utility

Active contributors: miekg, johnbelamaric, snebel29, chrisohaver, yongtang

Purpose

Small helper plugins that don't fit the other groups: filesystem roots, geographic IP lookup, request cancellation, configuration reload, lifecycle hooks, the demo whoami/erratic plugins, and a graveyard for deprecated names.

Plugins in this group

Plugin	Source	One-liner
root	plugin/root/	Set the base path for relative file references
geoip	plugin/geoip/	Annotate the request with a MaxMind GeoIP2 lookup
cancel	plugin/cancel/	Cancel slow downstream requests after a deadline
debug	plugin/debug/	Disable panic recovery; enable debug log
reload	plugin/reload/	Watch the Corefile and trigger a graceful restart
local	plugin/local/	Implement localhost/localhost.localdomain and the standard reverse zones
import	plugin/import/	Caddyfile-level include directive (handled at parse time)
whoami	plugin/whoami/	Return the client's IP address as the answer
erratic	plugin/erratic/	Deliberately broken responder for testing
on	(out-of-tree, in coredns/caddy)	Run shell commands on lifecycle events (startup, shutdown, restart)
deprecated	plugin/deprecated/	Marker plugin for deprecated directive names

Plugins in detail

root

Sets Config.Root. The file plugin (and any other plugin that reads files) prepends this path to relative arguments. Used in containerised setups so paths in the Corefile can stay relative.

geoip

Loads a MaxMind GeoIP2 database (oschwald/geoip2-golang/v2) and looks up the client IP on each request. Result is exposed via metadata: geoip/country/iso_code, geoip/city/name, geoip/location/longitude, etc. Consumed by rewrite and view to do geo-based routing. See plugin/geoip/geoip.go.

cancel

Wraps the downstream call in context.WithCancel. If the upstream HTTP/QUIC connection is closed before the chain returns, the cancel propagates so plugins like forward give up early.

debug

Two effects: log.D.Set() to flip on clog.Debug* output, and Config.Debug = true so Server.ServeDNS skips the recover(). Useful when you want a panic to actually crash the process.

reload

Computes a SHA-256 of the Corefile every INTERVAL (default 30s, with optional JITTER). On change, it calls caddy.Restart which re-parses and starts a fresh set of servers, swapping listeners via reuseport. The plugin counts attempts and failures via metrics.

local

Answers localhost. and localhost.localdomain. plus the standard reverse zones (1.0.0.127.in-addr.arpa. etc.) so they don't escape to upstream resolvers.

import

Parsed at Caddyfile-load time (Caddy itself implements it). Lets a Corefile include other files via globs. From the README:

.:53 {
    import example1.txt
}
import example2.txt

whoami

The simplest plugin in the tree. Returns A and AAAA records pointing at the client's IP. Used as a default plugin when no Corefile is supplied so a fresh coredns binary at least replies to something.

erratic

Configurable broken server for stress testing: drops a percentage of requests, returns garbled responses, lies about TTLs. Documented as a debugging aid.

on

Runs shell commands on Caddy lifecycle events (startup, shutdown, restart). Lives in github.com/coredns/caddy/onevent (loaded via the on: line in plugin.cfg).

deprecated

Acts on directive names that used to be supported. When a deprecated name appears in a Corefile, the plugin emits a warning pointing to its replacement. Implementation is in plugin/deprecated/deprecated.go.

Cross-plugin notes

• root should appear first in the chain so other plugins see the configured base path; that's why it's at the top of plugin.cfg.
• geoip populates metadata; view, rewrite, and log consume it.
• reload is process-wide. Loading it in two server blocks results in two reload watchers but one set of generated servers.
• local and forward are commonly paired so that loopback queries don't traverse the network.

Key source files

File	Purpose
plugin/root/root.go	Sets Config.Root
plugin/geoip/geoip.go, setup.go	MaxMind lookup and metadata population
plugin/cancel/cancel.go	context.WithCancel wrapper
plugin/debug/debug.go	Debug toggles
plugin/reload/reload.go	File-watcher and Caddy restart
plugin/local/local.go	Localhost / reverse-zone responder
plugin/whoami/whoami.go	Client IP echo
plugin/erratic/erratic.go	Broken responder for testing
plugin/deprecated/deprecated.go	Deprecation warnings

Related pages

• Transforms — metadata is what geoip populates.
• Backends — root interacts with the file plugin.
• Build and code generation — how plugin.cfg decides which utilities are compiled in.