```
$ cat /etc/dnsdist.conf
-newServer {address="2001:4860:4860::8888", qps=1}
-newServer {address="2001:4860:4860::8844", qps=1}
-newServer {address="2620:0:ccc::2", qps=10}
-newServer {address="2620:0:ccd::2", name="dns1", qps=10}
+newServer({address="2001:4860:4860::8888", qps=1})
+newServer({address="2001:4860:4860::8844", qps=1})
+newServer({address="2620:0:ccc::2", qps=10})
+newServer({address="2620:0:ccd::2", name="dns1", qps=10})
newServer("192.168.1.2")
setServerPolicy(firstAvailable) -- first server within its QPS limit
its RCODE differs from NXDomain, ServFail and Refused.
```
-newServer {address="192.0.2.1", checkType="AAAA", checkName="a.root-servers.net.", mustResolve=true}
+newServer({address="192.0.2.1", checkType="AAAA", checkName="a.root-servers.net.", mustResolve=true})
```
In order to provide the downstream server with the address of the real client,
The default value of 30s can be modified by passing the `tcpRecvTimeout` and `tcpSendTimeout`
parameters to `newServer`:
```
-newServer {address="192.0.2.1", tcpRecvTimeout=10, tcpSendTimeout=10}
+newServer({address="192.0.2.1", tcpRecvTimeout=10, tcpSendTimeout=10})
```
Configuration management
It is suggested to study the output of `delta()` carefully before appending
it to your configuration file.
+```
+> setACL("192.0.2.0/24")
+> showACL()
+192.0.2.0/24
+> delta()
+# Wed Dec 23 2015 15:15:35 CET
+setACL("192.0.2.0/24")
+> addACL("127.0.0.1/8")
+> showACL()
+192.0.2.0/24
+127.0.0.1/8
+> delta()
+# Wed Dec 23 2015 15:15:35 CET
+setACL("192.0.2.0/24")
+# Wed Dec 23 2015 15:15:44 CET
+addACL("127.0.0.1/8")
+>
+```
+
+
Webserver
---------
To visually interact with `dnsdist`, try adding:
Or we configure a server pool dedicated to receiving the nasty stuff:
```
-> newServer{address="192.168.1.3", pool="abuse"}
+> newServer({address="192.168.1.3", pool="abuse"})
> addPoolRule({"sh43353.cn.", "ezdns.it."}, "abuse")
```
------
To provide DNSSEC service from a separate pool, try:
```
-newServer{address="2001:888:2000:1d::2", pool="dnssec"}
-newServer{address="2a01:4f8:110:4389::2", pool="dnssec"}
+newServer({address="2001:888:2000:1d::2", pool="dnssec"})
+newServer({address="2a01:4f8:110:4389::2", pool="dnssec"})
setDNSSECPool("dnssec")
topRule()
```
-----------------------
This is still much in flux, but for now, try:
- * `topQueries(20)`: shows the top-20 queries
- * `topQueries(20,2)`: shows the top-20 two-level domain queries (so `topQueries(20,1)` only shows TLDs)
- * `topResponses(20, 2)`: top-20 servfail responses (use ,3 for NXDOMAIN)
* `grepq(Netmask|DNS Name|100ms [, n])`: shows the last n queries and responses matching the specified client address or range (Netmask), or the specified DNS Name, or slower than 100ms
* `grepq({"::1", "powerdns.com", "100ms"} [, n])`: shows the last n queries and responses matching the specified client address AND range (Netmask) AND the specified DNS Name AND slower than 100ms
* `topBandwidth(top)`: show top-`top` clients that consume the most bandwidth over length of ringbuffer
+ * `topQueries(20)`: shows the top-20 queries
+ * `topQueries(20,2)`: shows the top-20 two-level domain queries (so `topQueries(20,1)` only shows TLDs)
+ * `topResponses(20, 2)`: top-20 servfail responses (use ,3 for NXDOMAIN)
* `topSlow([top][, limit][, labels])`: show `top` queries slower than `limit` milliseconds, grouped by last `labels` labels
For example:
To implement a split horizon, try:
```
-authServer=newServer{address="2001:888:2000:1d::2", pool="auth"}
+authServer=newServer({address="2001:888:2000:1d::2", pool="auth"})
function splitSetup(servers, remote, qname, qtype, dh)
if(dh:getRD() == false)
setKey("plaintext") and the communication between the client and the
server will not be encrypted.
-Configuration management
-------------------------
-
-At every time, `dnsdist` is capable of printing every configuration changes
-made since its start, using the `delta` command:
-```
-> setACL("192.0.2.0/24")
-> showACL()
-192.0.2.0/24
-> delta()
-# Wed Dec 23 2015 15:15:35 CET
-setACL("192.0.2.0/24")
-> addACL("127.0.0.1/8")
-> showACL()
-192.0.2.0/24
-127.0.0.1/8
-> delta()
-# Wed Dec 23 2015 15:15:35 CET
-setACL("192.0.2.0/24")
-# Wed Dec 23 2015 15:15:44 CET
-addACL("127.0.0.1/8")
->
-```
-
ACL, who can use dnsdist
------------------------
For safety reasons, by default only private networks can use `dnsdist`, see below
--------
`dnsdist`, when compiled with --enable-dnscrypt, can be used as a DNSCrypt server,
uncurving queries before forwarding them to downstream servers and curving responses back.
-To make `dnsdist` listen to incoming DNSCrypt queries on 127.0.0.1 port 443,
+To make `dnsdist` listen to incoming DNSCrypt queries on 127.0.0.1 port 8443,
with a provider name of "2.providername", using a resolver certificate and associated key
stored respectively in the `resolver.cert` and `resolver.key` files, the `addDnsCryptBind()`
directive can be used:
* `controlSocket(addr)`: open a control socket on this address / connect to this address in client mode
* Diagnostics and statistics
* `dumpStats()`: print all statistics we gather
+ * `grepq(Netmask|DNS Name|100ms [, n])`: shows the last n queries and responses matching the specified client address or range (Netmask), or the specified DNS Name, or slower than 100ms
+ * `grepq({"::1", "powerdns.com", "100ms"} [, n])`: shows the last n queries and responses matching the specified client address AND range (Netmask) AND the specified DNS Name AND slower than 100ms
* `topQueries(n[, labels])`: show top 'n' queries, as grouped when optionally cut down to 'labels' labels
* `topResponses(n, kind[, labels])`: show top 'n' responses with RCODE=kind (0=NO Error, 2=ServFail, 3=ServFail), as grouped when optionally cut down to 'labels' labels
+ * `topSlow([top][, limit][, labels])`: show `top` queries slower than `limit` milliseconds, grouped by last `labels` labels
+ * `topBandwidth(top)`: show top-`top` clients that consume the most bandwidth over length of ringbuffer
* `showResponseLatency()`: show a plot of the response time latency distribution
* Logging related
* `infolog(string)`: log at level info
* `SpoofCNAMEAction()`: forge a response with the specified CNAME value
* `TCAction()`: create answer to query with TC and RD bits set, to move to TCP/IP
* Specialist rule generators
- * addAnyTCRule(): generate TC=1 answers to ANY queries, moving them to TCP
- * addDomainSpoof(domain, ip[, ip6]): generate answers for A queries using the ip parameter. If ip6 is supplied, generate answers for AAAA queries too
- * addDomainCNAMESpoof(domain, cname): generate CNAME answers for queries using the specified value
- * addDisableValidationRule(domain): set the CD flags to 1 for all queries matching the specified domain
- * addNoRecurseRule(domain): clear the RD flag for all queries matching the specified domain
- * setDNSSECPool(): move queries requesting DNSSEC processing to this pool
+ * `addAnyTCRule()`: generate TC=1 answers to ANY queries, moving them to TCP
+ * `addDomainSpoof(domain, ip[, ip6])`: generate answers for A queries using the ip parameter. If ip6 is supplied, generate answers for AAAA queries too
+ * `addDomainCNAMESpoof(domain, cname)`: generate CNAME answers for queries using the specified value
+ * `addDisableValidationRule(domain)`: set the CD flags to 1 for all queries matching the specified domain
+ * `addNoRecurseRule(domain)`: clear the RD flag for all queries matching the specified domain
+ * `setDNSSECPool()`: move queries requesting DNSSEC processing to this pool
* Policy member data:
* `name`: the policy name
* `policy`: the policy function
* `addDelay({domain, domain}, n)`: delay answers within those domains (together) by n milliseconds
* `addDelay(netmask, n)`: delay answers within that netmask by n milliseconds
* `addDelay({netmask, netmask}, n)`: delay answers within those netmasks (together) by n milliseconds
- * Dynamic block related:
- * `addDynBlocks({netmask, netmask}, reason [, duration])`: add a dynamic block with a message and an optional duration in seconds
- * `clearDynBlocks()`: remove all dynamic block rules
- * `showDynBlocks()`: show current dynamic block rules
- * `setDynBlockNMG()`: set the dynamic block rules
* Answer changing functions:
* `truncateTC(bool)`: if set (default) truncate TC=1 answers so they are actually empty. Fixes an issue for PowerDNS Authoritative Server 2.9.22.
* `fixupCase(bool)`: if set (default to no), rewrite the first qname of the question part of the answer to match the one from the query. It is only useful when you have a downstream server that messes up the case of the question qname in the answer
* member `setQR(bool)`: set Query Response flag (setQR(true) indicates an *answer* packet)
* member `getCD()`: get checking disabled flag
* member `setCD(bool)`: set checking disabled flag
- * DynBlock related
- * `newNMG()`: return a new NetmaskTree<DynBlock>
- * member `add(ComboAddress, msg[, seconds])`: insert a new address into a DynBlock
* NetmaskGroup related
* function `newNMG()`: returns a NetmaskGroup
* member `addMask(mask)`: adds `mask` to the NetmaskGroup
* `newQPSLimiter(rate, burst)`: configure a QPS limiter with that rate and that burst capacity
* member `check()`: check if this QPSLimiter has a token for us. If yes, you must use it.
* SuffixMatchNode related:
- * newSuffixMatchNode(): returns a new SuffixMatchNode
+ * `newSuffixMatchNode()`: returns a new SuffixMatchNode
* member `check(DNSName)`: returns true if DNSName is matched by this group
* member `add(DNSName)`: add this DNSName to the node
* Tuning related:
- * setTCPRecvTimeout(n): set the read timeout on TCP connections from the client, in seconds.
- * setTCPSendTimeout(n): set the write timeout on TCP connections from the client, in seconds.
- * setMaxTCPClientThreads(n): set the maximum of TCP client threads, handling TCP connections.
- * setMaxUDPOutstanding(n): set the maximum number of outstanding UDP queries to a given backend server. This can only be set at configuration time.
+ * `setTCPRecvTimeout(n)`: set the read timeout on TCP connections from the client, in seconds
+ * `setTCPSendTimeout(n)`: set the write timeout on TCP connections from the client, in seconds
+ * `setMaxTCPClientThreads(n)`: set the maximum of TCP client threads, handling TCP connections
+ * `setMaxUDPOutstanding(n)`: set the maximum number of outstanding UDP queries to a given backend server. This can only be set at configuration time
+ * DNSCrypt related:
+ * `addDNSCryptBind("127.0.0.1:8443", "provider name", "/path/to/resolver.cert", "/path/to/resolver.key"):` listen to incoming DNSCrypt queries on 127.0.0.1 port 8443, with a provider name of "provider name", using a resolver certificate and associated key stored respectively in the `resolver.cert` and `resolver.key` files
+ * `generateDNSCryptProviderKeys("/path/to/providerPublic.key", "/path/to/providerPrivate.key"):` generate a new provider keypair
+ * `generateDNSCryptCertificate("/path/to/providerPrivate.key", "/path/to/resolver.cert", "/path/to/resolver.key", serial, validFrom, validUntil):` generate a new resolver private key and related certificate, valid from the `validFrom` timestamp until the `validUntil` one, signed with the provider private key
+ * `printDNSCryptProviderFingerprint("/path/to/providerPublic.key")`: display the fingerprint of the provided resolver public key
+ * `showDNSCryptBinds():`: display the currently configured DNSCrypt binds
All hooks
---------
projects / pdns / commitdiff