Add DNS-over-TLS and DNS-over-HTTPS listeners with hot-reloaded certs, Helm support

Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
This commit is contained in:
Jonas Leder 2026-11-09 17:24:48 +01:00
commit e8ab48fb7c
14 changed files with 429 additions and 2 deletions

View file

@ -9,3 +9,7 @@ CACHE_MAX_MB=64
# REDIS_ADDR=127.0.0.1:6379 # optional shared cache
API_TOKEN=change-me # enables admin API + replica sync
CONFIG_FILE=./config.example.yaml
# DOT_ADDR=:8853 # DNS-over-TLS (needs cert)
# DOH_ADDR=:8443 # DNS-over-HTTPS
# DNS_TLS_CERT=./tls/c.pem
# DNS_TLS_KEY=./tls/k.pem

View file

@ -11,5 +11,5 @@ RUN CGO_ENABLED=0 go build -trimpath -ldflags "-s -w -X main.version=${VERSION}"
FROM gcr.io/distroless/static-debian12:nonroot
COPY --from=build /out/adblock-dns /adblock-dns
USER 65532:65532
EXPOSE 5353/udp 5353/tcp 9153 8080
EXPOSE 5353/udp 5353/tcp 8853 8443 9153 8080
ENTRYPOINT ["/adblock-dns"]

View file

@ -14,6 +14,7 @@ Prometheus metrics + Grafana dashboard, multi-replica operation with optional sh
| 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
@ -44,6 +45,8 @@ Precedence: defaults → YAML (global) → YAML `zones.<ZONE>` → environment.
| `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 |
@ -78,6 +81,9 @@ helm install dns deploy/helm/adblock-dns -n dns --create-namespace \
--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
@ -101,7 +107,7 @@ dashboard filters on a `zone` label, which the chart's ServiceMonitor adds; with
* 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 DoH/DoT/DoQ *listeners* yet (DoT *upstream* is supported), no per-client groups, no query log / top-domain lists
* 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

View file

@ -3,6 +3,7 @@ package main
import (
"context"
"crypto/tls"
"net/http"
"os"
"os/signal"
@ -163,6 +164,31 @@ func main() {
log.Info("API_TOKEN not set: admin API and replica sync are disabled")
}
if cfg.DoTAddr != "" || cfg.DoHAddr != "" {
var tlsDoT, tlsDoH *tls.Config
if cfg.DNSTLSCert != "" {
if tlsDoT, err = server.NewTLSConfig(cfg.DNSTLSCert, cfg.DNSTLSKey, "dot"); err != nil {
log.Fatalf("tls: %v", err)
}
if tlsDoH, err = server.NewTLSConfig(cfg.DNSTLSCert, cfg.DNSTLSKey, "h2", "http/1.1"); err != nil {
log.Fatalf("tls: %v", err)
}
}
if cfg.DoTAddr != "" {
go func() {
if err := server.RunDoT(ctx, cfg.DoTAddr, cfg.Listeners, tlsDoT, eng, log); err != nil {
log.Fatalf("dot: %v", err)
}
}()
}
if cfg.DoHAddr != "" {
go func() {
if err := server.RunDoH(ctx, cfg.DoHAddr, cfg.DoHPath, tlsDoH, eng, log); err != nil {
log.Fatalf("doh: %v", err)
}
}()
}
}
if err := server.Run(ctx, cfg.DNSAddr, cfg.Listeners, eng, log, started); err != nil {
log.Fatalf("dns server: %v", err)
}

View file

@ -53,6 +53,12 @@ spec:
ports:
- {name: dns-udp, containerPort: 5353, protocol: UDP}
- {name: dns-tcp, containerPort: 5353, protocol: TCP}
{{- if .Values.dot.enabled }}
- {name: dot, containerPort: 8853, protocol: TCP}
{{- end }}
{{- if .Values.doh.enabled }}
- {name: doh, containerPort: 8443, protocol: TCP}
{{- end }}
- {name: metrics, containerPort: 9153, protocol: TCP}
- {name: api, containerPort: 8080, protocol: TCP}
env:
@ -66,6 +72,21 @@ spec:
valueFrom: {fieldRef: {fieldPath: status.podIP}}
- name: API_TOKEN
valueFrom: {secretKeyRef: {name: {{ include "adblock-dns.secretName" . }}, key: token}}
{{- if or .Values.dot.enabled .Values.doh.enabled }}
{{- if .Values.tls.existingSecret }}
- {name: DNS_TLS_CERT, value: /etc/adblock-dns/tls/tls.crt}
- {name: DNS_TLS_KEY, value: /etc/adblock-dns/tls/tls.key}
{{- else if .Values.dot.enabled }}
{{- fail "dot.enabled requires tls.existingSecret" }}
{{- end }}
{{- end }}
{{- if .Values.dot.enabled }}
- {name: DOT_ADDR, value: ":8853"}
{{- end }}
{{- if .Values.doh.enabled }}
- {name: DOH_ADDR, value: ":8443"}
- {name: DOH_PATH, value: {{ .Values.doh.path | quote }}}
{{- end }}
{{- if .Values.sync.enabled }}
- {name: SYNC_PEERS_DNS, value: "{{ include "adblock-dns.fullname" . }}-headless.{{ .Release.Namespace }}.svc:8080"}
{{- end }}
@ -95,8 +116,15 @@ spec:
volumeMounts:
- {name: config, mountPath: /etc/adblock-dns, readOnly: true}
- {name: data, mountPath: /data}
{{- if .Values.tls.existingSecret }}
- {name: tls, mountPath: /etc/adblock-dns/tls, readOnly: true}
{{- end }}
volumes:
- name: config
configMap: {name: {{ include "adblock-dns.fullname" . }}}
{{- if .Values.tls.existingSecret }}
- name: tls
secret: {secretName: {{ .Values.tls.existingSecret }}, defaultMode: 0440}
{{- end }}
- name: data
emptyDir: {sizeLimit: {{ .Values.dataVolume.sizeLimit }}}

View file

@ -0,0 +1,32 @@
{{- if and .Values.doh.enabled .Values.doh.ingress.enabled }}
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: {{ include "adblock-dns.fullname" . }}-doh
labels: {{- include "adblock-dns.labels" . | nindent 4 }}
{{- $ann := .Values.doh.ingress.annotations }}
{{- if or $ann .Values.tls.existingSecret }}
annotations:
{{- if .Values.tls.existingSecret }}
nginx.ingress.kubernetes.io/backend-protocol: HTTPS
{{- end }}
{{- with $ann }}{{ toYaml . | nindent 4 }}{{ end }}
{{- end }}
spec:
{{- if .Values.doh.ingress.className }}
ingressClassName: {{ .Values.doh.ingress.className }}
{{- end }}
{{- if .Values.doh.ingress.tlsSecret }}
tls:
- hosts: [{{ .Values.doh.ingress.host | quote }}]
secretName: {{ .Values.doh.ingress.tlsSecret }}
{{- end }}
rules:
- host: {{ .Values.doh.ingress.host | quote }}
http:
paths:
- path: {{ .Values.doh.path }}
pathType: Exact
backend:
service: {name: {{ include "adblock-dns.fullname" . }}-dns, port: {number: 443}}
{{- end }}

View file

@ -12,6 +12,12 @@ spec:
- ports: # DNS from clients
- {port: 5353, protocol: UDP}
- {port: 5353, protocol: TCP}
{{- if .Values.dot.enabled }}
- {port: 8853, protocol: TCP}
{{- end }}
{{- if .Values.doh.enabled }}
- {port: 8443, protocol: TCP}
{{- end }}
{{- with .Values.networkPolicy.dnsClients }}
from: {{- toYaml . | nindent 8 }}
{{- end }}

View file

@ -19,6 +19,12 @@ spec:
ports:
- {name: dns-udp, port: {{ .Values.service.dns.port }}, targetPort: dns-udp, protocol: UDP}
- {name: dns-tcp, port: {{ .Values.service.dns.port }}, targetPort: dns-tcp, protocol: TCP}
{{- if .Values.dot.enabled }}
- {name: dot, port: 853, targetPort: dot, protocol: TCP}
{{- end }}
{{- if .Values.doh.enabled }}
- {name: doh, port: 443, targetPort: doh, protocol: TCP}
{{- end }}
---
# Headless: peer discovery for replica sync and per-pod metrics scraping.
apiVersion: v1

View file

@ -46,6 +46,24 @@ redis:
tls: false
existingSecret: "" # secret with key "password" (optional)
# Encrypted DNS. Needs a kubernetes.io/tls Secret (e.g. from cert-manager); the
# certificate is hot-reloaded on rotation. Container ports are unprivileged
# (8853/8443); the Service exposes 853/443.
tls:
existingSecret: ""
dot:
enabled: false
doh:
enabled: false
path: /dns-query
# Serve plain HTTP and let an ingress terminate TLS (when tls.existingSecret is empty).
ingress:
enabled: false
className: ""
host: dns.example.com
annotations: {}
tlsSecret: ""
service:
dns:
type: ClusterIP # LoadBalancer for a LAN VIP (e.g. MetalLB)

View file

@ -118,6 +118,11 @@ type Config struct {
NodeID string
DNSAddr string
DoTAddr string // DNS-over-TLS listen address (empty = disabled)
DoHAddr string // DNS-over-HTTPS listen address (empty = disabled)
DoHPath string
DNSTLSCert string
DNSTLSKey string
Listeners int
ACL []*net.IPNet
DataDir string
@ -184,6 +189,7 @@ func Load() (*Config, error) {
c := &Config{
Zone: glconfig.GetOrDefault("ZONE", ""),
DNSAddr: ":5353",
DoHPath: "/dns-query",
DataDir: "data",
LogFormat: "text",
MetricsAdr: ":9153",
@ -378,6 +384,11 @@ func (c *Config) applyEnv() (err error) {
}
str("DNS_ADDR", &c.DNSAddr)
str("DOT_ADDR", &c.DoTAddr)
str("DOH_ADDR", &c.DoHAddr)
str("DOH_PATH", &c.DoHPath)
str("DNS_TLS_CERT", &c.DNSTLSCert)
str("DNS_TLS_KEY", &c.DNSTLSKey)
str("DATA_DIR", &c.DataDir)
str("LOG_FORMAT", &c.LogFormat)
str("METRICS_ADDR", &c.MetricsAdr)
@ -468,6 +479,12 @@ func (c *Config) validate() error {
if c.BlockIPv4 == nil || c.BlockIPv6 == nil {
return fmt.Errorf("invalid blocking IP")
}
if c.DoTAddr != "" && (c.DNSTLSCert == "" || c.DNSTLSKey == "") {
return fmt.Errorf("DOT_ADDR requires DNS_TLS_CERT and DNS_TLS_KEY")
}
if (c.DNSTLSCert == "") != (c.DNSTLSKey == "") {
return fmt.Errorf("DNS_TLS_CERT and DNS_TLS_KEY must be set together")
}
if c.Listeners < 1 {
c.Listeners = 1
}

135
internal/server/doh.go Normal file
View file

@ -0,0 +1,135 @@
package server
import (
"context"
"crypto/tls"
"encoding/base64"
"fmt"
"io"
"net"
"net/http"
"strconv"
"time"
"github.com/miekg/dns"
"github.com/sirupsen/logrus"
)
const dohContentType = "application/dns-message"
// dohWriter adapts an HTTP request to dns.ResponseWriter so the DoH endpoint
// reuses the exact same handler (and cache) as UDP/TCP/DoT.
type dohWriter struct {
remote net.Addr
local net.Addr
out []byte
}
func (w *dohWriter) LocalAddr() net.Addr { return w.local }
func (w *dohWriter) RemoteAddr() net.Addr { return w.remote }
func (w *dohWriter) WriteMsg(m *dns.Msg) error {
b, err := m.Pack()
w.out = b
return err
}
func (w *dohWriter) Write(b []byte) (int, error) { w.out = append(w.out[:0], b...); return len(b), nil }
func (w *dohWriter) Close() error { return nil }
func (w *dohWriter) TsigStatus() error { return nil }
func (w *dohWriter) TsigTimersOnly(bool) {}
func (w *dohWriter) Hijack() {}
// DoHHandler implements RFC 8484 (GET ?dns=… and POST application/dns-message).
func DoHHandler(h dns.Handler, path string) http.Handler {
mux := http.NewServeMux()
mux.HandleFunc(path, func(rw http.ResponseWriter, r *http.Request) {
var wire []byte
var err error
switch r.Method {
case http.MethodGet:
q := r.URL.Query().Get("dns")
if q == "" {
http.Error(rw, "missing dns parameter", http.StatusBadRequest)
return
}
wire, err = base64.RawURLEncoding.DecodeString(q)
case http.MethodPost:
if ct := r.Header.Get("Content-Type"); ct != dohContentType {
http.Error(rw, "unsupported media type", http.StatusUnsupportedMediaType)
return
}
wire, err = io.ReadAll(io.LimitReader(r.Body, 65536))
default:
rw.Header().Set("Allow", "GET, POST")
http.Error(rw, "method not allowed", http.StatusMethodNotAllowed)
return
}
if err != nil || len(wire) < 12 {
http.Error(rw, "bad request", http.StatusBadRequest)
return
}
req := new(dns.Msg)
if req.Unpack(wire) != nil {
http.Error(rw, "bad dns message", http.StatusBadRequest)
return
}
remote, _ := net.ResolveTCPAddr("tcp", r.RemoteAddr)
if remote == nil {
remote = &net.TCPAddr{}
}
w := &dohWriter{remote: remote, local: &net.TCPAddr{}}
h.ServeDNS(w, req)
if w.out == nil {
http.Error(rw, "no response", http.StatusInternalServerError)
return
}
rw.Header().Set("Content-Type", dohContentType)
rw.Header().Set("Cache-Control", "max-age="+strconv.FormatUint(uint64(minTTL(w.out)), 10))
_, _ = rw.Write(w.out)
})
return mux
}
// minTTL returns the smallest RR TTL (0 for empty/failed responses).
func minTTL(wire []byte) uint32 {
var m dns.Msg
if m.Unpack(wire) != nil || m.Rcode == dns.RcodeServerFailure {
return 0
}
t := uint32(0)
first := true
for _, sec := range [][]dns.RR{m.Answer, m.Ns} {
for _, rr := range sec {
if first || rr.Header().Ttl < t {
t, first = rr.Header().Ttl, false
}
}
}
return t
}
// RunDoH serves DNS-over-HTTPS. With tlsCfg == nil it serves plain HTTP, meant
// for use behind a TLS-terminating ingress/proxy.
func RunDoH(ctx context.Context, addr, path string, tlsCfg *tls.Config, h dns.Handler, log *logrus.Logger) error {
srv := &http.Server{
Addr: addr, Handler: DoHHandler(h, path), TLSConfig: tlsCfg,
ReadHeaderTimeout: 5 * time.Second, ReadTimeout: 10 * time.Second, WriteTimeout: 10 * time.Second, IdleTimeout: 60 * time.Second,
}
errc := make(chan error, 1)
go func() {
if tlsCfg != nil {
errc <- srv.ListenAndServeTLS("", "")
} else {
log.Warn("DoH without TLS: serving plain HTTP, only use behind a TLS-terminating proxy")
errc <- srv.ListenAndServe()
}
}()
log.Infof("DNS-over-HTTPS listening on %s%s (tls=%v)", addr, path, tlsCfg != nil)
select {
case <-ctx.Done():
sctx, cancel := context.WithTimeout(context.Background(), 5*time.Second)
defer cancel()
return srv.Shutdown(sctx)
case err := <-errc:
return fmt.Errorf("doh: %w", err)
}
}

View file

@ -0,0 +1,52 @@
package server
import (
"bytes"
"encoding/base64"
"net/http"
"net/http/httptest"
"testing"
"github.com/miekg/dns"
)
type echo struct{}
func (echo) ServeDNS(w dns.ResponseWriter, r *dns.Msg) {
m := new(dns.Msg)
m.SetReply(r)
m.Answer = []dns.RR{&dns.A{Hdr: dns.RR_Header{Name: r.Question[0].Name, Rrtype: dns.TypeA, Class: dns.ClassINET, Ttl: 42}, A: []byte{1, 2, 3, 4}}}
_ = w.WriteMsg(m)
}
func TestDoH(t *testing.T) {
q := new(dns.Msg)
q.SetQuestion("example.com.", dns.TypeA)
wire, _ := q.Pack()
h := DoHHandler(echo{}, "/dns-query")
check := func(rec *httptest.ResponseRecorder) {
t.Helper()
if rec.Code != 200 || rec.Header().Get("Content-Type") != dohContentType || rec.Header().Get("Cache-Control") != "max-age=42" {
t.Fatalf("code=%d headers=%v", rec.Code, rec.Header())
}
var m dns.Msg
if err := m.Unpack(rec.Body.Bytes()); err != nil || len(m.Answer) != 1 {
t.Fatalf("bad body: %v", err)
}
}
get := httptest.NewRecorder()
h.ServeHTTP(get, httptest.NewRequest("GET", "/dns-query?dns="+base64.RawURLEncoding.EncodeToString(wire), nil))
check(get)
post := httptest.NewRecorder()
req := httptest.NewRequest("POST", "/dns-query", bytes.NewReader(wire))
req.Header.Set("Content-Type", dohContentType)
h.ServeHTTP(post, req)
check(post)
bad := httptest.NewRecorder()
h.ServeHTTP(bad, httptest.NewRequest("GET", "/dns-query?dns=!!", nil))
if bad.Code != http.StatusBadRequest {
t.Fatalf("want 400, got %d", bad.Code)
}
}

45
internal/server/dot.go Normal file
View file

@ -0,0 +1,45 @@
package server
import (
"context"
"crypto/tls"
"sync"
"time"
"github.com/miekg/dns"
"github.com/sirupsen/logrus"
)
// RunDoT serves DNS-over-TLS (RFC 7858) until ctx ends.
func RunDoT(ctx context.Context, addr string, n int, cfg *tls.Config, h dns.Handler, log *logrus.Logger) error {
var servers []*dns.Server
for i := 0; i < n; i++ {
servers = append(servers, &dns.Server{
Addr: addr, Net: "tcp-tls", Handler: h, TLSConfig: cfg, ReusePort: true,
ReadTimeout: 5 * time.Second, WriteTimeout: 5 * time.Second,
IdleTimeout: func() time.Duration { return 30 * time.Second }, MaxTCPQueries: 1024,
})
}
errc := make(chan error, len(servers))
var wg sync.WaitGroup
for _, s := range servers {
wg.Add(1)
go func() {
defer wg.Done()
if err := s.ListenAndServe(); err != nil {
errc <- err
}
}()
}
log.Infof("DNS-over-TLS listening on %s", addr)
var err error
select {
case <-ctx.Done():
case err = <-errc:
}
for _, s := range servers {
_ = s.Shutdown()
}
wg.Wait()
return err
}

52
internal/server/tls.go Normal file
View file

@ -0,0 +1,52 @@
package server
import (
"crypto/tls"
"os"
"sync"
"time"
)
// certReloader serves a certificate from disk and re-reads it when the files
// change (cert-manager / Kubernetes secret rotation) without a restart.
type certReloader struct {
cert, key string
mu sync.Mutex
c *tls.Certificate
mtime time.Time
checked time.Time
}
// NewTLSConfig builds a server TLS config with hot certificate reload.
func NewTLSConfig(cert, key string, protos ...string) (*tls.Config, error) {
r := &certReloader{cert: cert, key: key}
if _, err := r.get(nil); err != nil {
return nil, err
}
return &tls.Config{MinVersion: tls.VersionTLS12, GetCertificate: r.get, NextProtos: protos}, nil
}
func (r *certReloader) get(*tls.ClientHelloInfo) (*tls.Certificate, error) {
r.mu.Lock()
defer r.mu.Unlock()
if r.c != nil && time.Since(r.checked) < 30*time.Second {
return r.c, nil
}
r.checked = time.Now()
st, err := os.Stat(r.cert)
if err == nil && r.c != nil && st.ModTime().Equal(r.mtime) {
return r.c, nil
}
c, lerr := tls.LoadX509KeyPair(r.cert, r.key)
if lerr != nil {
if r.c != nil {
return r.c, nil // keep serving the old certificate
}
return nil, lerr
}
r.c = &c
if err == nil {
r.mtime = st.ModTime()
}
return r.c, nil
}