dnsdist PowerDNS.COM BV Sep 30, 2021 CONTENTS 1 dnsdist Overview 1 1.1 Running dnsdist...........................................1 1.2 Questions, requests or comments?..................................1 2 Installing dnsdist 3 2.1 Installing from Packages.......................................3 2.1.1 Debian............................................3 2.1.2 Red Hat...........................................3 2.1.3 FreeBSD..........................................3 2.2 Installing from Source........................................3 2.2.1 From tarball.........................................4 2.2.2 From git...........................................4 2.2.3 OS Specific Instructions..................................5 3 Quickstart Guide 7 3.1 Running in the Foreground......................................7 3.2 dnsdist Console and Configuration................................7 3.2.1 Changing Server Settings..................................8 3.3 Restricting Access..........................................9 3.4 More Information..........................................9 4 Running and Configuring dnsdist 11 4.1 Running as unprivileged user.................................... 11 4.2 Understanding how queries are forwarded to backends....................... 11 5 Packet Policies 13 5.1 Packet Actions............................................ 13 5.1.1 Examples.......................................... 13 5.2 Rule Generators........................................... 14 5.3 Managing Rules........................................... 15 5.4 Matching Packets (Selectors).................................... 19 5.4.1 Combining Rules...................................... 24 5.4.2 Convenience Functions................................... 25 5.5 Actions................................................ 25 6 Statistics 39 6.1 acl-drops............................................... 39 6.2 cache-hits............................................... 39 6.3 cache-misses............................................. 39 6.4 cpu-iowait.............................................. 39 6.5 cpu-steal............................................... 40 6.6 cpu-sys-msec............................................. 40 6.7 cpu-user-msec............................................ 40 6.8 doh-query-pipe-full.......................................... 40 6.9 doh-response-pipe-full........................................ 40 i 6.10 downstream-send-errors....................................... 40 6.11 downstream-timeouts......................................... 40 6.12 dyn-block-nmg-size......................................... 40 6.13 dyn-blocked............................................. 40 6.14 empty-queries............................................ 40 6.15 fd-usage............................................... 41 6.16 frontend-noerror........................................... 41 6.17 frontend-nxdomain.......................................... 41 6.18 frontend-servfail........................................... 41 6.19 latency-avg100............................................ 41 6.20 latency-avg1000........................................... 41 6.21 latency-avg10000........................................... 41 6.22 latency-avg1000000......................................... 41 6.23 latency-slow............................................. 41 6.24 latency-sum.............................................. 41 6.25 latency-count............................................. 42 6.26 latency-bucket............................................ 42 6.27 latency0-1.............................................. 42 6.28 latency1-10.............................................. 42 6.29 latency10-50............................................. 42 6.30 latency50-100............................................ 42 6.31 latency100-1000........................................... 42 6.32 no-policy............................................... 42 6.33 noncompliant-queries........................................ 42 6.34 noncompliant-responses....................................... 42 6.35 proxy-protocol-invalid........................................ 43 6.36 queries................................................ 43 6.37 rdqueries............................................... 43 6.38 real-memory-usage.......................................... 43 6.39 responses............................................... 43 6.40 rule-drop............................................... 43 6.41 rule-nxdomain............................................ 43 6.42 rule-refused.............................................. 43 6.43 rule-servfail.............................................. 43 6.44 rule-truncated............................................. 43 6.45 security-status............................................ 44 6.46 self-answered............................................. 44 6.47 servfail-responses.......................................... 44 6.48 tcp-listen-overflows......................................... 44 6.49 trunc-failures............................................. 44 6.50 udp-in-errors............................................. 44 6.51 udp-noport-errors........................................... 44 6.52 udp-recvbuf-errors.......................................... 44 6.53 udp-sndbuf-errors.......................................... 45 6.54 uptime................................................ 45 7 Caching Responses 47 8 Exporting statistics via Carbon 49 8.1 Setting up a carbon export...................................... 49 8.2 Query counters............................................ 49 9 Working with the dnsdist Console 51 10 DNS-over-HTTPS (DoH) 53 10.1 Incoming............................................... 53 10.1.1 Custom responses...................................... 54 10.1.2 DNS over HTTP...................................... 54 10.1.3 Internal design....................................... 54 ii 10.1.4 Investigating issues..................................... 55 10.2 Outgoing............................................... 55 10.2.1 Internal design....................................... 55 11 DNS-over-TLS 57 11.1 Incoming............................................... 57 11.2 Outgoing............................................... 57 11.3 Investigating issues.......................................... 58 12 DNSCrypt 59 13 Configuring Downstream Servers 61 13.1 Healthcheck............................................. 61 13.2 Source address selection....................................... 62 13.3 Securing the channel......................................... 62 14 Dynamic Rule Generation 63 14.1 DynBlockRulesGroup........................................ 63 15 Guides 65 15.1 Built-in webserver.......................................... 65 15.1.1 Security of the Webserver.................................. 65 15.1.2 dnsdist API......................................... 65 15.2 Server pools............................................. 74 15.3 Loadbalancing and Server Policies.................................. 75 15.3.1 Built-in Policies....................................... 75 15.3.2 Lua server policies..................................... 77 15.3.3 ServerPolicy Objects.................................... 78 15.3.4 Functions.......................................... 78 16 Advanced Topics 81 16.1 Access Control............................................ 81 16.1.1 Listening on different addresses.............................. 81 16.1.2 Modifying the ACL..................................... 82 16.2 Passing the source address to the backend.............................. 82 16.2.1 Using EDNS Client Subnet................................. 82 16.2.2 X-Proxied-For........................................ 83 16.2.3 Proxy Protocol....................................... 83 16.2.4 Influence on caching.................................... 84 16.3 TeeAction: copy the DNS traffic stream............................... 84 16.4 Lua actions in rules.......................................... 85 16.5 Runtime-modifiable IP address sets................................. 85 16.6 Rules for traffic exceeding QPS limits................................ 86 16.7 eBPF Socket Filtering........................................ 86 16.8 Performance Tuning......................................... 88 16.8.1 UDP and incoming DNS over HTTPS........................... 88 16.8.2 Outgoing DoH....................................... 90 16.8.3 TCP and DNS over TLS.................................. 91 16.8.4 Rules and Lua........................................ 92 16.8.5 Lock contention and sharding............................... 92 16.8.6 Memory usage....................................... 93 16.9 SNMP support............................................ 93 16.10 AXFR, IXFR and NOTIFY..................................... 106 16.11 Running multiple instances..................................... 107 16.11.1 Using systemd....................................... 107 16.12 Out-of-order............................................. 107 16.13 OCSP Stapling............................................ 107 16.13.1 Local PKI.......................................... 108 16.13.2 Certificate signed by an external authority......................... 108 iii 16.13.3 Testing........................................... 109 16.14 TLS Sessions Management..................................... 109 16.14.1 TLS sessions........................................ 109 16.14.2 Keys management for incoming connections in dnsdist.................. 110 16.14.3 Content