Getting started

This page covers building CoreDNS from source, running it against a Corefile, and finding your way around the test and lint commands.

Prerequisites

• Go matching .go-version (currently 1.25.0 or later). The Makefile sets GOTOOLCHAIN=go$(GOLANG_VERSION) so the right Go toolchain downloads automatically when invoked through make.
• git for checkout and version metadata. The Makefile derives the build's commit string from git describe --dirty --always and bakes it into the binary via -ldflags.
• For make gen: nothing extra; it shells out to go generate and go get.
• For Docker builds: see Makefile.docker and the top-level Dockerfile.

CoreDNS itself has no cgo dependencies (CGO_ENABLED=0 by default in the Makefile), so cross-compilation works without a C toolchain.

Build

git clone https://github.com/coredns/coredns
cd coredns
make

make is the default target (all: coredns). Internally it:

1. Runs make check, which calls go generate coredns.go if core/plugin/zplugin.go or core/dnsserver/zdirectives.go are out of date relative to plugin.cfg.
2. Calls go build -tags="$(GOTAGS)" -ldflags="..." and writes the coredns binary into the repo root.

The default GOTAGS=grpcnotrace disables the gRPC tracing build. To enable additional plugins not in the default list, set COREDNS_PLUGINS and re-run make gen:

COREDNS_PLUGINS=example:github.com/coredns/example make gen
make

A clean build in Docker without setting up Go locally:

docker run --rm -i -t \
  -v $PWD:/go/src/github.com/coredns/coredns \
  -w /go/src/github.com/coredns/coredns \
  golang:1.25 sh -c 'GOFLAGS="-buildvcs=false" make gen && GOFLAGS="-buildvcs=false" make'

Run

The binary expects a Corefile in the current directory by default. The simplest one:

.:53 {
    forward . 8.8.8.8
    log
}

Then:

./coredns -conf Corefile
dig @127.0.0.1 -p 53 example.com

coredns accepts the following CLI flags (defined in coremain/run.go):

Flag	Meaning
-conf <file>	Path to Corefile. Use stdin to read from stdin. Default: Corefile in cwd.
-dns.port <port>	Default port for keys that omit one. Default: 53.
-p <port>	Short alias for -dns.port.
-pidfile <path>	Write PID to this file.
-plugins	List installed plugins and exit.
-version	Show version and exit.
-quiet	Suppress startup output.

Without any Corefile, the default loads whoami + log on :53 (see dnsserver.RegisterServerType's DefaultInput).

Common Corefile shapes

Forwarder with cache and metrics:

.:53 {
    cache 30
    forward . 1.1.1.1 8.8.8.8 {
        prefer_udp
    }
    prometheus :9153
    log
    errors
}

Authoritative file zone with on-the-fly DNSSEC and zone transfer:

example.org:1053 {
    file /var/lib/coredns/example.org
    dnssec
    transfer {
        to *
    }
    log
    errors
}

DNS-over-TLS and DNS-over-HTTPS on the same Corefile:

tls://example.org https://example.org {
    tls /etc/ssl/cert.pem /etc/ssl/key.pem
    forward . 1.1.1.1
}

For more shapes see the README examples and the per-plugin docs under plugin/<name>/README.md. The full set of recognized directives and their order is in Reference: configuration.

Tests

Unit tests are colocated with each package; integration tests live in test/:

go test ./...                       # everything
go test ./plugin/forward/...        # one plugin
go test -run TestServeDNS ./test    # one integration test
go test -race ./plugin/cache/...    # with race detector

Many integration tests bind ephemeral ports (:0); a few rely on Docker for etcd or Kubernetes. The CI workflow lives in .github/workflows/go.test.yml.

Lint and format

make check                          # regenerate code from plugin.cfg
gofmt -s -d .                       # check formatting
golangci-lint run                   # static analysis (config: .golangci.yml)

.golangci.yml enables gosec, revive, staticcheck, govet/nilness, prealloc, unused, modernize, and a handful of others, with an exclusion list for tests.

The make.doc Makefile and the verify-make-gen workflow enforce that committed generated files match what make gen produces. CI fails if they drift.

Verify the install

./coredns -plugins | head             # list compiled-in plugins
./coredns -version                    # version + git commit
dig @127.0.0.1 -p 53 +short example.com

Listing plugins is a quick way to confirm a build with COREDNS_PLUGINS actually included your plugin.

Where to next

• How to contribute — branching, PRs, and the CNCF DCO.
• Patterns and conventions — the rules every plugin and core package follows.
• Reference: configuration — every flag, env var, and generated file.
• Plugins overview — what each plugin does.