From: Remi Gacogne Date: Mon, 15 Aug 2016 08:15:17 +0000 (+0200) Subject: Add documentation for the `prerpz` hook X-Git-Tag: rec-4.0.2~1^2~14 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=b92bc9ad73991bbb33f7c7a3e282b723d2835ac9;p=thirdparty%2Fpdns.git Add documentation for the `prerpz` hook --- diff --git a/docs/markdown/recursor/scripting.md b/docs/markdown/recursor/scripting.md index b40d623af4..c1d95e33b5 100644 --- a/docs/markdown/recursor/scripting.md +++ b/docs/markdown/recursor/scripting.md @@ -22,6 +22,7 @@ For extra performance, a Just In Time compiled version of Lua called Queries can be intercepted in many places: * before any packet parsing begins (`ipfilter`) +* before any filtering policy have been applied (`prerpz`) * before the resolving logic starts to work (`preresolve`) * after the resolving process failed to find a correct answer for a domain (`nodata`, `nxdomain`) * after the whole process is done and an answer is ready for the client (`postresolve`) @@ -103,6 +104,7 @@ It also supports the following methods: * `addAnswer(type, content, [ttl, name])`: add an answer to the record of `type` with `content`. Optionally supply TTL and the name of the answer too, which defaults to the name of the question +* `discardPolicy(policyname)`: skip the filtering policy (for example RPZ) named `policyname` for this query. This is mostly useful in the `prerpz` hook. * `getRecords()`: get a table of DNS Records in this DNS Question (or answer by now) * `setRecords(records)`: after your edits, update the answers of this question * `getEDNSOption(num)`: get the EDNS Option with number `num` @@ -152,6 +154,26 @@ e.g. been filtered for certain IPs (this logic should be implemented in the setting dq.variable to `true`. In the latter case, repeated queries will pass through the entire Lua script. +### `function prerpz(dq)` + +This hook is called before any filtering policy have been applied, making it +possible to completely disable filtering by setting `wantsRPZ` to false. +Using the `discardPolicy()` function, it is also possible to selectively disable +one or more filtering policy, for example RPZ zones, based on the content of the +`dq` object. + +As an example, to disable the `malware` policy for `example.com` queries: + +``` +function prerpz(dq) + -- disable the RPZ policy named 'malware' for example.com + if dq.qname:equal('example.com') then + dq:discardPolicy('malware') + end + return true +end +``` + ### `function preresolve(dq)` is called before any DNS resolution is attempted, and if this function indicates it, it can supply a direct answer to the DNS query, overriding the