Skip to content

Commit

Permalink
dnsdist: Deprecate syntactic sugar functions in 1.2.0
Browse files Browse the repository at this point in the history 
Deprecates:
 * addAnyTCRule
 * addDomainBlock
 * addDomainSpoof
 * addDomainCNAMESpoof
 * addPoolRule
 * addNoRecurseRule
 * addDisableValidationRule
 * addQPSPoolRule
 * setDNSSECPool
 * addQPSLimit
 * addDelay
  • Loading branch information
@rgacogne
rgacogne committed Jul 17, 2017
1 parent b6a91fb commit 1533fe6
Show file tree
Hide file tree
Showing 6 changed files with 76 additions and 74 deletions.
75 changes: 31 additions & 44 deletions pdns/README-dnsdist.md
View file
Expand Up @@ -288,14 +288,14 @@ do two things with this kind of traffic. Either we block it outright, like
this:

```
> addDomainBlock("sh43354.cn.")
> addAction("sh43354.cn.", DropAction())
```

Or we configure a server pool dedicated to receiving the nasty stuff:

```
> newServer({address="192.168.1.3", pool="abuse"})
> addPoolRule({"sh43353.cn.", "ezdns.it."}, "abuse")
> addAction({"sh43353.cn.", "ezdns.it."}, PoolAction("abuse"))
```

The wonderful thing about this last solution is that it can also be used for
Expand All @@ -307,21 +307,18 @@ impacting the rest of the world (too much).
We can similarly add clients to the abuse server:

```
> addPoolRule({"192.168.12.0/24", "192.168.13.14"}, "abuse")
> addAction({"192.168.12.0/24", "192.168.13.14"}, PoolAction("abuse"))
```

To define a pool that should receive only a QPS-limited amount of traffic, do:

```
> addQPSPoolRule("com.", 10000, "gtld-cluster")
> addAction("com.", QPSPoolAction(10000, "gtld-cluster"))
```

Traffic exceeding the QPS limit will not match that rule, and subsequent
rules will apply normally.

Both `addDomainBlock` and `addPoolRule` end up the list of Rules
and Actions (for which see below).

Servers can be added to or removed from pools with:
```
> getServer(7):addPool("abuse")
Expand Down Expand Up @@ -391,17 +388,7 @@ Current response actions are:
Rules can be added via:

* addAction(DNS rule, DNS Action)
* addAnyTCRule()
* addDelay(DNS rule, delay in milliseconds)
* addDisableValidationRule(DNS rule)
* addDomainBlock(domain)
* addDomainSpoof(domain, IPv4[, IPv6]) or addDomainSpoof(domain, {IP, IP, IP..})
* addDomainCNAMESpoof(domain, CNAME)
* addLuaAction(DNS rule, Lua function)
* addNoRecurseRule(DNS rule)
* addPoolRule(DNS rule, destination pool)
* addQPSLimit(DNS rule, qps limit)
* addQPSPoolRule(DNS rule, qps limit, destination pool)

Response rules can be added via:

Expand Down Expand Up @@ -497,7 +484,7 @@ If you also called setTC(1), this will tell the remote client to move to
TCP, and in this way you can implement ANY-to-TCP even for downstream
servers that lack this feature.

Note that calling `addAnyTCRule()` achieves the same thing, without
Note that calling `addAction(AndRule{QTypeRule(dnsdist.ANY), TCPRule(false)}, TCAction())` achieves the same thing, without
involving Lua.

Rules for traffic exceeding QPS limits
Expand All @@ -507,7 +494,7 @@ Traffic that exceeds a QPS limit, in total or per IP (subnet) can be matched by
For example:

```
addDelay(MaxQPSIPRule(5, 32, 48), 100)
addAction(MaxQPSIPRule(5, 32, 48), DelayAction(100))
```

This measures traffic per IPv4 address and per /48 of IPv6, and if traffic for such
Expand Down Expand Up @@ -568,7 +555,7 @@ this may make sense.

To select specific packets for Lua attention, use `addLuaAction(x, func)`,
where x is either a netmask, or a domain suffix, or a table of netmasks or a
table of domain suffixes. This is identical to how `addPoolRule()` selects.
table of domain suffixes. This is identical to how `addAction()` selects.

The function should look like this:
```
Expand Down Expand Up @@ -603,7 +590,7 @@ 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"})
setDNSSECPool("dnssec")
addAction(DNSSECRule(), PoolAction("dnssec"))
topRule()
```

Expand Down Expand Up @@ -729,9 +716,9 @@ traffic, you can put ceilings on the amount of traffic you are willing to
forward:

```
> addQPSLimit("h4xorbooter.xyz.", 10)
> addQPSLimit({"130.161.0.0/16", "145.14.0.0/16"} , 20)
> addQPSLimit({"nl.", "be."}, 1)
> addAction("h4xorbooter.xyz.", QPSAction(10))
> addAction({"130.161.0.0/16", "145.14.0.0/16"} , QPSAction(20))
> addAction({"nl.", "be."}, QPSAction(1))
> showRules()
# Matches Rule Action
0 0 h4xorbooter.xyz. qps limit to 10
Expand Down Expand Up @@ -759,8 +746,8 @@ causing a slowdown on the side of the source of the traffic.

To do so, use:
```
> addDelay("yourdomain.in.ua.", 500)
> addDelay({"65.55.37.0/24"}, 500)
> addAction("yourdomain.in.ua.", DelayAction(500))
> addAction({"65.55.37.0/24"}, DelayAction(500))
```
This will delay responses for questions to the mentioned domain, or coming
from the configured subnet, by half a second.
Expand Down Expand Up @@ -1392,7 +1379,7 @@ Here are all functions:
* `addLocal(addr, [, {doTCP=true, reusePort=false, tcpFastOpenSize=0, interface=\"\"}])`: add `addr` to the list of addresses we listen on. The second parameter is an optional table: `doTCP` sets TCP or not (UDP is always enabled), `reusePort` sets SO_REUSEPORT when available, `tcpFastOpenSize` sets the TCP Fast Open queue size, enabling TCP Fast Open when available and the value is larger than 0, `interface` sets the network interface to use
* `setLocal(addr, [, {doTCP=true, reusePort=false, tcpFastOpenSize=0, interface=\"\"}])`: reset list of addresses we listen on to this address. The second parameter is the same optional table than the one described in `addLocal()`
* Blocking related:
* `addDomainBlock(domain)`: block queries within this domain
* `addDomainBlock(domain)`: (deprecated) block queries within this domain
* Carbon/Graphite/Metronome statistics related:
* `carbonServer(serverIP, [ourname], [interval])`: report statistics to serverIP using our hostname, or 'ourname' if provided, every 'interval' seconds
* Query counting related:
Expand Down Expand Up @@ -1522,28 +1509,28 @@ instantiate a server with additional parameters
* `TCAction()`: create answer to query with TC and RD bits set, to move to TCP
* `TeeAction(remote[, addECS])`: send copy of query to remote, keep stats on responses. If `addECS` is set to `true`, EDNS Client Subnet information will be added to the query
* Specialist rule generators
* `addAnyTCRule()`: generate TC=1 answers to ANY queries received over UDP, moving them to TCP
* `addDomainSpoof(domain, ip[, ip6])` or `addDomainSpoof(domain, {IP, IP, IP..})`: generate answers for A/AAAA/ANY queries using the ip parameters
* `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(pool)`: move queries requesting DNSSEC processing to this pool
* `addAnyTCRule()`: (deprecated) generate TC=1 answers to ANY queries received over UDP, moving them to TCP
* `addDomainSpoof(domain, ip[, ip6])` or `addDomainSpoof(domain, {IP, IP, IP..})`: (deprecated) generate answers for A/AAAA/ANY queries using the ip parameters
* `addDomainCNAMESpoof(domain, cname)`: (deprecated) generate CNAME answers for queries using the specified value
* `addDisableValidationRule(domain)`: (deprecated) set the CD flags to 1 for all queries matching the specified domain
* `addNoRecurseRule(domain)`: (deprecated) clear the RD flag for all queries matching the specified domain
* `setDNSSECPool(pool)`: (deprecated) move queries requesting DNSSEC processing to this pool
* Policy member data:
* `name`: the policy name
* `policy`: the policy function
* Pool related:
* `addPoolRule(domain, pool)`: send queries to this domain to that pool
* `addPoolRule({domain, domain}, pool)`: send queries to these domains to that pool
* `addPoolRule(netmask, pool)`: send queries from this netmask to that pool
* `addPoolRule({netmask, netmask}, pool)`: send queries from these netmasks to that pool
* `addQPSPoolRule(x, limit, pool)`: like `addPoolRule`, but only select at most 'limit' queries/s for this pool, letting the subsequent rules apply otherwise
* `addPoolRule(domain, pool)`: (deprecated) send queries to this domain to that pool
* `addPoolRule({domain, domain}, pool)`: (deprecated) send queries to these domains to that pool
* `addPoolRule(netmask, pool)`: (deprecated) send queries from this netmask to that pool
* `addPoolRule({netmask, netmask}, pool)`: (deprecated) send queries from these netmasks to that pool
* `addQPSPoolRule(x, limit, pool)`: (deprecated) like `addPoolRule`, but only select at most 'limit' queries/s for this pool, letting the subsequent rules apply otherwise
* `getPool(poolname)`: return the ServerPool named `poolname`
* `getPoolServers(pool)`: return servers part of this pool
* `showPools()`: list the current server pools
* Lua Action related:
* `addLuaAction(x, func)`: where 'x' is all the combinations from `addPoolRule`, and func is a
* `addLuaAction(x, func)`: where 'x' is all the combinations from `addAction`, and func is a
function with the parameter `dq`, which returns an action to be taken on this packet.
* `addLuaResponseAction(x, func)`: where 'x' is all the combinations from `addPoolRule`, and func is a
* `addLuaResponseAction(x, func)`: where 'x' is all the combinations from `addAction`, and func is a
function with the parameter `dr`, which returns an action to be taken on this response packet.
Good for rare packets but where you want to do a lot of processing.
* Server selection policy related:
Expand All @@ -1568,10 +1555,10 @@ instantiate a server with additional parameters
* `addQPSLimit(netmask, n)`: limit queries within that netmask to n per second
* `addQPSLimit({netmask, netmask}, n)`: limit queries within those netmasks (together) to n per second
* Delaying related:
* `addDelay(domain, n)`: delay answers within that domain by n milliseconds
* `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
* `addDelay(domain, n)`: (deprecated) delay answers within that domain by n milliseconds
* `addDelay({domain, domain}, n)`: (deprecated) delay answers within those domains (together) by n milliseconds
* `addDelay(netmask, n)`: (deprecated) delay answers within that netmask by n milliseconds
* `addDelay({netmask, netmask}, n)`: (deprecated) delay answers within those netmasks (together) by n milliseconds
* Answer changing functions:
* `truncateTC(bool)`: if set (defaults to no starting with dnsdist 1.2.0) truncate TC=1 answers so they are actually empty. Fixes an issue for PowerDNS Authoritative Server 2.9.22. Note: turning this on breaks compatibility with RFC 6891.
* `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
Expand Down
22 changes: 11 additions & 11 deletions pdns/dnsdist-console.cc
View file
Expand Up @@ -272,20 +272,20 @@ const std::vector<ConsoleKeyword> g_consoleKeywords{
/* keyword, function, parameters, description */
{ "addACL", true, "netmask", "add to the ACL set who can use this server" },
{ "addAction", true, "DNS rule, DNS action", "add a rule" },
{ "addAnyTCRule", true, "", "generate TC=1 answers to ANY queries received over UDP, moving them to TCP" },
{ "addDelay", true, "domain, n", "delay answers within that domain by n milliseconds" },
{ "addDisableValidationRule", true, "DNS rule", "set the CD flags to 1 for all queries matching the specified domain" },
{ "addAnyTCRule", true, "", "(deprecated) generate TC=1 answers to ANY queries received over UDP, moving them to TCP" },
{ "addDelay", true, "domain, n", "(deprecated) delay answers within that domain by n milliseconds" },
{ "addDisableValidationRule", true, "DNS rule", "(deprecated) set the CD flags to 1 for all queries matching the specified domain" },
{ "addDNSCryptBind", true, "\"127.0.0.1:8443\", \"provider name\", \"/path/to/resolver.cert\", \"/path/to/resolver.key\", {reusePort=false, tcpFastOpenSize=0, interface=\"\"}", "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. The fifth optional parameter is a table of parameters" },
{ "addDomainBlock", true, "domain", "block queries within this domain" },
{ "addDomainSpoof", true, "domain, ip[, ip6]", "generate answers for A/AAAA/ANY queries using the ip parameters" },
{ "addDomainBlock", true, "domain", "(deprecated) block queries within this domain" },
{ "addDomainSpoof", true, "domain, ip[, ip6]", "(deprecated) generate answers for A/AAAA/ANY queries using the ip parameters" },
{ "addDynBlocks", true, "addresses, message[, seconds[, action]]", "block the set of addresses with message `msg`, for `seconds` seconds (10 by default), applying `action` (default to the one set with `setDynBlocksAction()`)" },
{ "addLocal", true, "addr [, {doTCP=true, reusePort=false, tcpFastOpenSize=0, interface=\"\"}]", "add `addr` to the list of addresses we listen on" },
{ "addLuaAction", true, "x, func", "where 'x' is all the combinations from `addPoolRule`, and func is a function with the parameter `dq`, which returns an action to be taken on this packet. Good for rare packets but where you want to do a lot of processing" },
{ "addLuaResponseAction", true, "x, func", "where 'x' is all the combinations from `addPoolRule`, and func is a function with the parameter `dr`, which returns an action to be taken on this response packet. Good for rare packets but where you want to do a lot of processing" },
{ "addNoRecurseRule", true, "domain", "clear the RD flag for all queries matching the specified domain" },
{ "addPoolRule", true, "domain, pool", "send queries to this domain to that pool" },
{ "addQPSLimit", true, "domain, n", "limit queries within that domain to n per second" },
{ "addQPSPoolRule", true, "x, limit, pool", "like `addPoolRule`, but only select at most 'limit' queries/s for this pool, letting the subsequent rules apply otherwise" },
{ "addLuaAction", true, "x, func", "where 'x' is all the combinations from `addAction`, and func is a function with the parameter `dq`, which returns an action to be taken on this packet. Good for rare packets but where you want to do a lot of processing" },
{ "addLuaResponseAction", true, "x, func", "where 'x' is all the combinations from `addAction`, and func is a function with the parameter `dr`, which returns an action to be taken on this response packet. Good for rare packets but where you want to do a lot of processing" },
{ "addNoRecurseRule", true, "domain", "(deprecated) clear the RD flag for all queries matching the specified domain" },
{ "addPoolRule", true, "domain, pool", "(deprecated) send queries to this domain to that pool" },
{ "addQPSLimit", true, "domain, n", "(deprecated) limit queries within that domain to n per second" },
{ "addQPSPoolRule", true, "x, limit, pool", "(deprecated) like `addPoolRule`, but only select at most 'limit' queries/s for this pool, letting the subsequent rules apply otherwise" },
{ "addCacheHitResponseAction", true, "DNS rule, DNS response action", "add a cache hit response rule" },
{ "addResponseAction", true, "DNS rule, DNS response action", "add a response rule" },
{ "AllowAction", true, "", "let these packets go through" },
Expand Down

0 comments on commit 1533fe6

Please sign in to comment.