From: Ondřej Surý Date: Mon, 23 Jan 2017 15:07:16 +0000 (+0100) Subject: Update policy.TRACE documentation X-Git-Tag: v1.2.0-rc3~2^2~1 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7323db7460bcd42add0bc3d245bf25b2f13aba53;p=thirdparty%2Fknot-resolver.git Update policy.TRACE documentation --- diff --git a/modules/policy/README.rst b/modules/policy/README.rst index 3d579d81c..184c5cbe5 100644 --- a/modules/policy/README.rst +++ b/modules/policy/README.rst @@ -28,11 +28,12 @@ There are several defined actions: it can be a single IP (string) or a list of up to four IPs. * ``MIRROR(ip)`` - mirror query to given IP and continue solving it (useful for partial snooping) * ``REROUTE({{subnet,target}, ...})`` - reroute addresses in response matching given subnet to given target, e.g. ``{'192.0.2.0/24', '127.0.0.0'}`` will rewrite '192.0.2.55' to '127.0.0.55', see :ref:`renumber module ` for more information. +* ``TRACE`` - pretty-print DNS response packets into the log (useful for debugging weird DNS servers) .. warning:: The policy module only looks at the inbound DNS queries. Thus the ``FORWARD(ip)`` policy does only forward inbound query to the specified IP address(es) and it doesn't and it can't do DNSSEC validation. If you need DNSSEC validation, you either need to disable ``FORWARD(ip)`` policy or use an upstream DNSSEC-validating resolver. .. 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. - + Example configuration ^^^^^^^^^^^^^^^^^^^^^ @@ -43,7 +44,7 @@ Example configuration -- Whitelist 'www[0-9].badboy.cz' policy.add(policy.pattern(policy.PASS, '\4www[0-9]\6badboy\2cz')) -- Block all names below badboy.cz - policy.add(policy.suffix(policy.DENY, {'\6badboy\2cz'})) + policy.add(policy.suffix(policy.DENY, {todname('badboy.cz.')})) -- Custom rule policy.add(function (req, query) if query:qname():find('%d.%d.%d.224\7in-addr\4arpa') then @@ -59,11 +60,13 @@ Example configuration -- Enforce local RPZ policy.add(policy.rpz(policy.DENY, 'blacklist.rpz')) -- Forward all queries below 'company.se' to given resolver - policy.add(policy.suffix(policy.FORWARD('192.168.1.1'), {'\7company\2se'})) + policy.add(policy.suffix(policy.FORWARD('192.168.1.1'), {todname('company.se')})) -- Forward all queries matching pattern policy.add(policy.pattern(policy.FORWARD('2001:DB8::1'), '\4bad[0-9]\2cz')) -- Forward all queries (complete stub mode) policy.add(policy.all(policy.FORWARD('2001:DB8::1'))) + -- Print all responses with matching suffix + policy.add(policy.suffix(policy.TRACE, {todname('rhybar.cz.')})) -- Mirror all queries and retrieve information local rule = policy.add(policy.all(policy.MIRROR('127.0.0.2'))) -- Print information about the rule @@ -105,6 +108,10 @@ Properties Reroute addresses in response matching given subnet to given target, e.g. ``{'192.0.2.0/24', '127.0.0.0'}`` will rewrite '192.0.2.55' to '127.0.0.55'. +.. envvar:: policy.TRACE + + Print pretty-formate (dig-like) DNS answers that Knot Resolver receive from upstream (authoritative) DNS servers. Very useful when dealing with non-compliant DNS servers that violate DNS protocol. + .. function:: policy.add(rule, postrule) :param rule: added rule, i.e. ``policy.pattern(policy.DENY, '[0-9]+\2cz')``