From: bert hubert <bert.hubert@powerdns.com>
Date: Tue, 23 May 2017 10:01:47 +0000 (+0200)
Subject: add documentation for TimedIPSetRule()
X-Git-Tag: rec-4.1.0-alpha1~61^2
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1c1b7226bedd0192592dbe8b5a759cf9522fadae;p=thirdparty%2Fpdns.git

add documentation for TimedIPSetRule()
---

diff --git a/pdns/README-dnsdist.md b/pdns/README-dnsdist.md
index 827a7e9007..237f4f0001 100644
--- a/pdns/README-dnsdist.md
+++ b/pdns/README-dnsdist.md
@@ -439,6 +439,7 @@ A DNS rule can be:
  * a RecordsTypeCountRule
  * a SuffixMatchNodeRule
  * a TCPRule
+ * a TimedIPSetRule
  * a TrailingDataRule
 
 Some specific actions do not stop the processing when they match, contrary to all other actions:
@@ -625,6 +626,50 @@ The regex is applied case insensitively.
 
 Alternatively, if compiled in, RE2Rule provides similar functionality, but against libre2.
 
+Runtime-modifiable IP address sets
+----------------------------------
+From within maintenance() or other places, we may find that certain IP
+addresses must be treated differently for a certain time.
+
+This may be used to temporarily shunt traffic to another pool for example.
+
+`TimedIPSetRule()` creates an object to which native IP addresses can be
+added in ComboAddress form. 
+
+The following methods are available on this rule:
+
+ * `add(CA, seconds)`: Add an IP address to the set for the next `second` seconds
+ * `cleanup()`: Purge the set from expired IP addresses
+ * `clear()`: Clear the entire set
+ * `slice()`: Convert the TimedIPSetRule into a DNSRule that can be passed to `addAction()`
+
+A working example:
+
+```
+tisrElGoog=TimedIPSetRule()
+tisrRest=TimedIPSetRule()
+addAction(tisrElGoog:slice(), PoolAction("elgoog"))
+addAction(tisrRest:slice(), PoolAction(""))
+
+elgoogPeople=newNMG()
+elgoogPeople:addMask("192.168.5.0/28")
+
+function pickPool(dq)
+	if(elgoogPeople:match(dq.remoteaddr)) -- in real life, this would be external
+	then
+		print("Lua caught query for a googlePerson")
+		tisrElGoog:add(dq.remoteaddr, 10)
+		return DNSAction.Pool, "elgoog"
+	else
+		print("Lua caught query for restPerson")
+		tisrRest:add(dq.remoteaddr, 60)
+		return DNSAction.None, ""
+	end
+end
+
+addLuaAction(AllRule(), pickPool)
+```
+
 Inspecting live traffic
 -----------------------
 This is still much in flux, but for now, try:
@@ -1426,6 +1471,7 @@ instantiate a server with additional parameters
     * `RE2Rule(regex)`: matches the query name against the supplied regex using the RE2 engine
     * `SuffixMatchNodeRule(smn, [quiet-bool])`: matches based on a group of domain suffixes for rapid testing of membership. Pass `true` as second parameter to prevent listing of all domains matched.
     * `TCPRule(tcp)`: matches question received over TCP if `tcp` is true, over UDP otherwise
+    * `TimedIPSetRule()`: rule which matches a runtime-modifiable set of IP addresses, which also expire
     * `TrailingDataRule()`: matches if the query has trailing data
  * Rule management related:
     * `clearRules()`: remove all current rules