No description
  • Go 98.4%
  • Go Template 0.7%
  • Dockerfile 0.5%
  • Makefile 0.4%
Find a file
Jonas Leder f00dd6fcaa
All checks were successful
ci / backend-test (push) Successful in 46s
ci / build (push) Successful in 1m43s
ci / backend-docker (push) Successful in 0s
ci / build-1 (push) Successful in 34s
ci / chart (push) Successful in 0s
CI: app version defaults to the commit SHA in the helm workflow
Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
2026-11-18 01:37:40 +01:00
.forgejo/workflows CI: app version defaults to the commit SHA in the helm workflow 2026-11-18 01:37:40 +01:00
cmd add forward zones 2026-11-14 14:03:49 +01:00
deploy/helm/adblock-dns Update redis Docker tag to v8 2026-11-14 13:04:19 +00:00
internal implement validation for ML-DSA-44 2026-11-16 11:06:27 +01:00
.dockerignore Build with xx cross-compile and run on scratch-rootless image 2026-11-09 17:37:59 +01:00
.env.example Add DNS-over-TLS and DNS-over-HTTPS listeners with hot-reloaded certs, Helm support 2026-11-09 17:24:48 +01:00
.gitignore build dns server 2026-11-09 17:21:54 +01:00
config.example.yaml add forward zones 2026-11-14 14:03:49 +01:00
Dockerfile Merge branch 'renovate/jonasled.dev-infra-images-scratch-rootless-latest' into 'master' 2026-11-14 13:45:22 +01:00
go.mod build dns server 2026-11-09 17:21:54 +01:00
go.sum build dns server 2026-11-09 17:21:54 +01:00
Makefile build dns server 2026-11-09 17:21:54 +01:00
README.md implement validation for ML-DSA-44 2026-11-16 11:06:27 +01:00
renovate.json enable dashboard 2026-11-14 13:47:55 +01:00

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/dnsbench to reproduce, or point dnsperf / flamethrower at 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/ML-DSA-44 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_CERT and SYNC_CA_FILE when peers are reached over untrusted networks.