Build an Unpolluted DNS with CoreDNS and dnsredir: A Step‑by‑Step Guide

CoreDNS is a Go‑written, plugin‑based DNS server that became the default DNS solution for Kubernetes 1.13 and aims to be the cloud‑native DNS and service‑discovery platform.

Key features include a Caddy‑inspired plugin chain, a concise DSL called Corefile for configuration, and an all‑in‑one binary with built‑in cache, backend storage and health checks.

Corefile Overview

The Corefile defines servers, zones and the plugins each server loads. The basic syntax is ZONE:[PORT] { PLUGIN ... }, where ZONE specifies the domain the server is authoritative for and PORT defaults to 53.

ZONE:[PORT] {
  [PLUGIN] ...
}

Examples show a simple .{} server, multiple servers sharing a port, and reverse zones using 0.0.10.in-addr.arpa {}. CoreDNS also supports DNS‑over‑TLS and DNS‑over‑gRPC via tls:// and grpc:// blocks.

Plugin Execution Model

When a request arrives, CoreDNS selects the most specific zone, then runs the plugins in the order defined in plugin.cfg. Plugins can either fully handle the request, pass it on with fallthrough, or add a hint for later plugins.

Using dnsredir for Split‑DNS

The third‑party dnsredir plugin combines the capabilities of proxy and forward, supporting UDP, TCP, DoT and DoH, multiple backends, health checks and failover. Its syntax is:

dnsredir FROM... {
  to TO...
}

FROM...

is a file list (e.g., FelixOnMars’ China domain lists) that maps domains to upstream servers; TO... specifies the upstream DNS servers (e.g., 114.114.114.114 for domestic queries, 8.8.8.8 for international queries).

Example configuration:

dnsredir accelerated-domains.china.conf google.china.conf apple.china.conf mydns.conf {
  expire 15s
  max_fails 3
  health_check 3s
  policy round_robin
  path_reload 2s
  to 114.114.114.114 223.5.5.5 119.29.29.29
}

dnsredir . {
  expire 60s
  max_fails 5
  health_check 5s
  policy random
  spray
  to tls://[email protected] tls://[email protected]
}

Building a Custom CoreDNS Binary

Since the official binary no longer includes proxy, a custom build that bundles dnsredir is required. A CI/CD project (https://github.com/missdeer/coredns_custom_build) provides pre‑compiled binaries for various OSes.

Download, unzip and place the binary in /usr/local/bin:

$ wget "https://appveyorcidatav2.blob.core.windows.net/missdeer-15199/coredns-custom-build/1-7-1-514/idbodwxwywg1xgdg/distrib/coredns-linux-amd64.zip"
$ tar zxf coredns-linux-amd64.zip
$ mv coredns-linux-amd64/coredns /usr/local/bin/

Complete Corefile Example

cat > /usr/local/etc/Corefile <<EOF
(global_cache) {
  cache {
    success 65536 3600 300
    denial 8192 600 60
    prefetch 1 60m 10%
  }
}

.:7913 {
  ads {
    default-lists
    blacklist https://raw.githubusercontent.com/privacy-protection-tools/anti-AD/master/anti-ad-domains.txt
    whitelist https://files.krnl.eu/whitelist.txt
    log
    auto-update-interval 24h
    list-store ads-cache
  }
  errors
  hosts { fallthrough }
  health
  prometheus :9153
  import global_cache
  template ANY AAAA { rcode NXDOMAIN }
  dnsredir accelerated-domains.china.conf google.china.conf apple.china.conf mydns.conf {
    expire 15s
    max_fails 3
    health_check 3s
    policy round_robin
    path_reload 2s
    to 114.114.114.114 223.5.5.5 119.29.29.29
  }
  dnsredir . {
    expire 60s
    max_fails 5
    health_check 5s
    policy random
    spray
    to tls://[email protected] tls://[email protected]
  }
  log
  loop
  reload 6s
}
EOF

Key plugins explained:

hosts : loads /etc/hosts; if a name matches, it is returned immediately.

fallthrough : passes the request to the next plugin when hosts has no entry.

cache : stores responses for the configured TTL.

reload : watches the Corefile and reloads on changes.

errors : logs errors.

dnsredir : performs split‑DNS as described above.

Automating Domain‑List Updates

A script downloads the latest China domain lists and places them under /usr/local/etc:

#!/bin/bash
rm accelerated-domains.china.conf
wget https://cdn.jsdelivr.net/gh/felixonmars/dnsmasq-china-list/accelerated-domains.china.conf -O /usr/local/etc/accelerated-domains.china.conf
rm apple.china.conf
wget https://cdn.jsdelivr.net/gh/felixonmars/dnsmasq-china-list/apple.china.conf -O /usr/local/etc/apple.china.conf
rm google.china.conf
wget https://cdn.jsdelivr.net/gh/felixonmars/dnsmasq-china-list/google.china.conf -O /usr/local/etc/google.china.conf

Add a crontab entry to run the script every two days at 14:00:

0 14 */2 * * /usr/local/bin/update_coredns.sh

macOS Service Setup

Create /Library/LaunchAgents/coredns.plist (attributes stripped) to start CoreDNS at boot:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple Computer//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
  <key>Label</key><string>coredns</string>
  <key>ProgramArguments</key><array>
    <string>/usr/local/bin/coredns</string>
    <string>-conf</string>
    <string>/usr/local/etc/Corefile</string>
  </array>
  <key>StandardOutPath</key><string>/var/log/coredns.stdout.log</string>
  <key>StandardErrorPath</key><string>/var/log/coredns.stderr.log</string>
  <key>RunAtLoad</key><true/>
  <key>KeepAlive</key><true/>
</dict>
</plist>

Load and verify the service:

$ sudo launchctl load -w /Library/LaunchAgents/coredns.plist
$ sudo launchctl list | grep coredns

Check listening ports with lsof and confirm DNS resolution using a tool such as doggo:

$ doggo www.youtube.com @udp://127.0.0.1

Finally, set the system DNS to 127.0.0.1 to route all queries through the configured CoreDNS instance.