- Go 98.4%
- Go Template 0.7%
- Dockerfile 0.5%
- Makefile 0.4%
Update jonasled.dev/infra/images/scratch-rootless:latest Docker digest to 9e291c8 See merge request jonasled/adblock-dns!2 |
||
|---|---|---|
| cmd | ||
| deploy/helm/adblock-dns | ||
| internal | ||
| .dockerignore | ||
| .env.example | ||
| .gitignore | ||
| .gitlab-ci.yml | ||
| config.example.yaml | ||
| Dockerfile | ||
| go.mod | ||
| go.sum | ||
| Makefile | ||
| README.md | ||
| renovate.json | ||
adblock-dns
Cloud-native DNS server in Go: Pi-hole-style ad blocking, local DNS overrides, DNSSEC validation, Prometheus metrics + Grafana dashboard, multi-replica operation with optional shared cache, and a "same config everywhere" multi-zone model (home + datacenter) where sites never depend on each other.
Features
| Area | What you get |
|---|---|
| Blocking | hosts / plain-domain / Adblock (||domain^, @@ exceptions) lists, auto-refresh with ETag + on-disk cache (works offline), regex rules, CNAME-cloaking protection, null / NXDOMAIN / REFUSED / custom-IP answers |
| Overrides | local records (A, AAAA, CNAME, TXT, MX, SRV, PTR … + wildcards), allow/block overrides of the lists (precedence: allow > block > list exceptions > lists), conditional forwarding zones, runtime changes via API |
| Upstream | recursive (own iterative resolver from the root, bailiwick-checked, RTT-ranked servers) or forward to custom servers (UDP multiplexed sockets, TCP, DoT tls://ip:853#name) |
| DNSSEC | full validation from the root trust anchor (RRSIG, DS chain, NSEC/NSEC3 denial, opt-out), strict / permissive / off, AD bit + Extended DNS Error on failures, CD honoured |
| Cache | sharded byte-bounded LRU storing packed wire format (hit = copy + TTL patch, no unpacking), prefetch, serve-stale (RFC 8767), negative caching, single-flight de-duplication |
| HA | N stateless replicas; runtime overrides sync between them (LWW CRDT); optional shared Redis/Valkey cache — every dependency is best-effort and can fail without affecting resolution |
| Encrypted DNS | DNS-over-TLS (RFC 7858) and DNS-over-HTTPS (RFC 8484, GET+POST, HTTP/2) sharing the same cache/policy; certificates hot-reload on rotation; DoH can run plain behind a TLS-terminating ingress |
| Ops | /metrics, /healthz, /readyz, JSON logs, Helm chart with minimal privileges, Grafana dashboard |
Quick start
cp .env.example .env # auto-loaded (godotenv); real env vars win
go run ./cmd/adblock-dns # listens on :5353 (unprivileged)
dig @127.0.0.1 -p 5353 cloudflare.com # "ad" flag = DNSSEC validated
Libraries used as requested: logrus (via jonasled.dev/jonasled/go-libs/log, which also provides
LOG_LEVEL/LOG_FOLDER), go-libs config helpers for env access, and godotenv/autoload.
Configuration
Precedence: defaults → YAML (global) → YAML zones.<ZONE> → environment. See
config.example.yaml and .env.example.
| Env | Default | |
|---|---|---|
ZONE |
– | selects zones.<name> and per-zone records |
CONFIG_FILE |
/etc/adblock-dns/config.yaml or ./config.yaml |
|
DNS_ADDR / DNS_LISTENERS |
:5353 / min(CPU,8) |
N UDP + N TCP SO_REUSEPORT sockets |
UPSTREAM_MODE / UPSTREAM_SERVERS |
recursive |
forward needs servers |
DNSSEC_MODE |
strict |
permissive logs bogus but serves; off |
CACHE_MAX_MB, CACHE_MIN_TTL, CACHE_MAX_TTL, CACHE_NEG_TTL, CACHE_STALE |
64, 5s, 24h, 1h, 1h | |
REDIS_ADDR (+REDIS_PASSWORD, REDIS_TLS, REDIS_DB) |
off | shared cache, key prefix is per zone |
BLOCK_MODE |
null |
null nxdomain refused ip (+BLOCK_IPV4/6) |
API_TOKEN |
– | enables admin API (:8080) and replica sync |
SYNC_PEERS / SYNC_PEERS_DNS |
– | static host:port list / headless service name |
DOT_ADDR / DOH_ADDR / DOH_PATH |
off / off / /dns-query |
e.g. :8853, :8443; DoT needs the cert below |
DNS_TLS_CERT / DNS_TLS_KEY |
– | PEM files for DoT/DoH; DoH without them serves plain HTTP (behind an ingress) |
ACL_CIDRS |
allow all | restrict clients |
LOG_LEVEL, LOG_FORMAT |
INFO, text | json for clusters |
Multi-zone: one config, several sites
ZONE=home and ZONE=dc1 run the same file. The zone decides which records apply (give the same name
different answers per site), which zones.<name> overrides are merged (e.g. recursive at home, forwarding to the
datacenter resolvers in the DC, a Redis only the DC has), and which peers it syncs with. A site never needs
another site: lists are cached on disk, Redis/peers are best-effort (circuit breaker, tight timeouts), recursion
needs only the internet. Listing a remote site in sync.peers makes runtime changes propagate across sites
whenever the link is up and converge when it returns; use zones: on API calls to scope a change to one site.
Admin API (bearer token, port 8080)
H="Authorization: Bearer $API_TOKEN"
curl -XPUT -H "$H" :8080/api/v1/allow/example.com # override a list entry (all replicas)
curl -XPUT -H "$H" :8080/api/v1/block/tracker.example -d '{"zones":["home"]}'
curl -XPOST -H "$H" :8080/api/v1/records -d '{"name":"nas.lan","type":"A","value":"192.168.1.10"}'
curl -XPOST -H "$H" :8080/api/v1/blocking -d '{"enabled":false,"duration":"10m"}' # pause blocking
curl -XPOST -H "$H" :8080/api/v1/cache/flush
curl -H "$H" :8080/api/v1/status
Kubernetes
docker build -t registry.example.com/adblock-dns:0.1.0 . && docker push …
helm install dns deploy/helm/adblock-dns -n dns --create-namespace \
--set zone=home --set image.repository=registry.example.com/adblock-dns \
--set service.dns.type=LoadBalancer --set redis.enabled=true \
--set serviceMonitor.enabled=true --set grafanaDashboard.enabled=true -f my-config.yaml
Encrypted DNS: --set tls.existingSecret=dns-tls --set dot.enabled=true --set doh.enabled=true (Service exposes
853/443, containers listen on 8853/8443); doh.ingress.* publishes DoH through an ingress.
Minimal privileges: non-root (65532), read-only root FS, all capabilities dropped, seccomp RuntimeDefault,
no service-account token, listens on 5353 (Service maps 53 → 5353, so NET_BIND_SERVICE is unnecessary),
distroless static image, optional NetworkPolicy, PDB, spread across nodes. The only writable path is an
emptyDir for list downloads / runtime state.
Grafana: import deploy/helm/adblock-dns/dashboards/adblock-dns.json or enable grafanaDashboard. The
dashboard filters on a zone label, which the chart's ServiceMonitor adds; with other scrape setups add
zone yourself (the adblockdns_info{zone=…} metric shows the expected values).
Performance & memory
- Blocklists are 64-bit hashes in an open-addressing table, ~16 B/domain (1 M domains ≈ 16 MB), zero-alloc lookups.
- Cache hits never unpack a message; the cache is byte-bounded (
CACHE_MAX_MB), LRU-evicted, swept periodically. - Go GC honours the container limit automatically (
GOMEMLIMIT= 90 % of the cgroup limit unless set). - Measured on an 8-core laptop, load generator on the same host, warm cache, 64 clients:
~300 k qps, p50 160 µs, p99 0.9 ms, 32 MB RSS with the default 64 MiB cache and a small list.
Use
make bench/cmd/dnsbenchto reproduce, or pointdnsperf/flamethrowerat it to compare with CoreDNS, Unbound, Pi-hole (FTL) or AdGuard Home under identical conditions.
Limitations / roadmap
- DNSSEC: wildcard-denial parts of NXDOMAIN proofs are not verified (covering/closest-encloser records are); algorithms beyond RSA/ECDSA/Ed25519 are treated as insecure.
- No DoQ listener (DoT/DoH listeners and DoT upstream are supported), no per-client groups, no query log / top-domain lists (counters only, to keep Prometheus cardinality bounded), no QNAME minimisation, no hot-reload of the YAML (pods roll on change; API changes are live).
- Sync endpoint is bearer-token authenticated; set
SYNC_TLS/API_TLS_CERTandSYNC_CA_FILEwhen peers are reached over untrusted networks.