From: Petr Špaček Date: Thu, 25 Jan 2018 12:50:22 +0000 (+0100) Subject: policy: polish policy module documentation X-Git-Tag: v2.0.0~11^2~2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0c11788fbe6c99a8686b63f54eec45397bec3b42;p=thirdparty%2Fknot-resolver.git policy: polish policy module documentation --- diff --git a/modules/policy/README.rst b/modules/policy/README.rst index 934604ee4..722819dbe 100644 --- a/modules/policy/README.rst +++ b/modules/policy/README.rst @@ -4,11 +4,15 @@ Query policies -------------- This module can block, rewrite, or alter inbound queries based on user-defined policies. -By default, if no rule applies to a query, rules for special-use domain names are applied, as required by :rfc:`6761`. -You can however extend it e.g. to deflect `Slow drip DNS attacks `_ or gray-list resolution of misbehaving zones. +Each policy *rule* has two parts: a *filter* and an *action*. A *filter* selects which queries will be affected by the policy, and *action* which modifies queries matching the associated filter. Typically a rule is defined as follows: ``filter(action(action parameters), filter parameters)``. For example, a filter can be ``suffix`` which matches queries whose suffix part is in specified set, and one of possible actions is ``DENY``, which denies resolution. These are combined together into ``policy.suffix(policy.DENY, {todname('badguy.example.')})``. The rule is effective when it is added into rule table using ``policy.add()``, please see `Policy examples`_. -There are several policy filters available in the ``policy.`` table: +By default, if no rule applies to a query, built-in rules for `special-use `_ and `locally-served `_ domain names are applied. These built-in rules can be overriden using action ``PASS``, see `Policy examples`_ below. + + +Filters +^^^^^^^ +A *filter* selects which queries will be affected by specified *action*. There are several policy filters available in the ``policy.`` table: * ``all(action)`` - always applies the action @@ -22,7 +26,9 @@ There are several policy filters available in the ``policy.`` table: - implements a subset of RPZ_ in zonefile format. See below for details: :any:`policy.rpz`. * custom filter function -There are several actions available in the ``policy.`` table: +Actions +^^^^^^^ +An *action* is function which modifies DNS query. There are several actions available in the ``policy.`` table: * ``PASS`` - let the query pass through; it's useful to make exceptions before wider rules * ``DENY`` - reply NXDOMAIN authoritatively @@ -41,6 +47,8 @@ There are several actions available in the ``policy.`` table: Most actions stop the policy matching on the query, but "chain actions" allow to keep trying to match other rules, until a non-chain action is triggered. +Also, it is possible to write your own action (i.e. Lua function). It is possible to implement complex heuristics, e.g. to deflect `Slow drip DNS attacks `_ or gray-list resolution of misbehaving zones. + .. warning:: The policy module currently only looks at whole DNS requests. The rules won't be re-applied e.g. when following CNAMEs. .. note:: The module (and ``kres``) expects domain names in wire format, not textual representation. So each label in name is prefixed with its length, e.g. "example.com" equals to ``"\7example\3com"``. You can use convenience function ``todname('example.com')`` for automatic conversion. @@ -77,14 +85,13 @@ TLS Examples {'2001:DB8::d0c', hostname='res.example.', ca_file='/etc/knot-resolver/tlsca.crt'} }) +.. _policy_examples: -Other examples -^^^^^^^^^^^^^^ +Policy examples +^^^^^^^^^^^^^^^ .. code-block:: lua - -- Load default policies - modules = { 'policy' } -- Whitelist 'www[0-9].badboy.cz' policy.add(policy.pattern(policy.PASS, '\4www[0-9]\6badboy\2cz')) -- Block all names below badboy.cz