From: Peter van Dijk Date: Wed, 10 Apr 2019 20:04:04 +0000 (+0200) Subject: update docs X-Git-Tag: dnsdist-1.4.0-alpha1~3^2 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=09b45aa88971d0fbcd93195f85aedac62d9f7d82;p=pdns update docs --- diff --git a/pdns/dnsdistdist/docs/advanced/axfr.rst b/pdns/dnsdistdist/docs/advanced/axfr.rst index dcc787ea4..dc883b85c 100644 --- a/pdns/dnsdistdist/docs/advanced/axfr.rst +++ b/pdns/dnsdistdist/docs/advanced/axfr.rst @@ -13,12 +13,16 @@ AXFR or IXFR queries destined to this master. There are two issues that can aris The first issue can be solved by routing SOA, AXFR and IXFR requests explicitly to the master:: newServer({address="192.168.1.2", name="master", pool={"master", "otherpool"}}) - addAction(OrRule({QTypeRule(dnsdist.SOA), QTypeRule(dnsdist.AXFR), QTypeRule(dnsdist.IXFR)}), PoolAction("master")) + addAction(OrRule({QTypeRule(DNSQType.SOA), QTypeRule(DNSQType.AXFR), QTypeRule(DNSQType.IXFR)}), PoolAction("master")) The second one might require allowing AXFR/IXFR from the :program:`dnsdist` source address and moving the source address check to :program:`dnsdist`'s side:: - addAction(AndRule({OrRule({QTypeRule(dnsdist.AXFR), QTypeRule(dnsdist.IXFR)}), NotRule(makeRule("192.168.1.0/24"))}), RCodeAction(dnsdist.REFUSED)) + addAction(AndRule({OrRule({QTypeRule(DNSQType.AXFR), QTypeRule(DNSQTypeIXFR)}), NotRule(makeRule("192.168.1.0/24"))}), RCodeAction(DNSRCode.REFUSED)) + +.. versionchanged:: 1.4.0 + Before 1.4.0, the QTypes were in the ``dnsdist`` namespace. Use ``dnsdist.AXFR`` and ``dnsdist.IXFR`` in these versions. + Before 1.4.0, the RCodes were in the ``dnsdist`` namespace. Use ``dnsdist.REFUSED`` in these versions. When :program:`dnsdist` is deployed in front of slaves, however, an issue might arise with NOTIFY queries, because the slave will receive a notification coming from the :program:`dnsdist` address, @@ -26,5 +30,7 @@ and not the master's one. One way to fix this issue is to allow NOTIFY from the address on the slave side (for example with PowerDNS's `trusted-notification-proxy`) and move the address check to :program:`dnsdist`'s side:: - addAction(AndRule({OpcodeRule(DNSOpcode.Notify), NotRule(makeRule("192.168.1.0/24"))}), RCodeAction(dnsdist.REFUSED)) + addAction(AndRule({OpcodeRule(DNSOpcode.Notify), NotRule(makeRule("192.168.1.0/24"))}), RCodeAction(DNSRCode.REFUSED)) +.. versionchanged:: 1.4.0 + Before 1.4.0, the RCodes were in the ``dnsdist`` namespace. Use ``dnsdist.REFUSED`` in these versions. \ No newline at end of file diff --git a/pdns/dnsdistdist/docs/guides/cache.rst b/pdns/dnsdistdist/docs/guides/cache.rst index 1a6bdd3e3..979ab25d9 100644 --- a/pdns/dnsdistdist/docs/guides/cache.rst +++ b/pdns/dnsdistdist/docs/guides/cache.rst @@ -49,7 +49,10 @@ For example, to remove all expired entries:: Specific entries can also be removed using the :meth:`PacketCache:expungeByName` method:: - getPool("poolname"):getCache():expungeByName(newDNSName("powerdns.com"), dnsdist.A) + getPool("poolname"):getCache():expungeByName(newDNSName("powerdns.com"), DNSQType.A) + +.. versionchanged:: 1.4.0 + Before 1.4.0, the QTypes were in the ``dnsdist`` namespace. Use ``dnsdist.A`` in these versions. Finally, the :meth:`PacketCache:expunge` method will remove all entries until at most n entries remain in the cache:: diff --git a/pdns/dnsdistdist/docs/reference/config.rst b/pdns/dnsdistdist/docs/reference/config.rst index d6f0be0be..4252d890a 100644 --- a/pdns/dnsdistdist/docs/reference/config.rst +++ b/pdns/dnsdistdist/docs/reference/config.rst @@ -614,7 +614,7 @@ See :doc:`../guides/cache` for a how to. :param int n: Number of entries to keep - .. method:: PacketCache:expungeByName(name [, qtype=dnsdist.ANY[, suffixMatch=false]]) + .. method:: PacketCache:expungeByName(name [, qtype=DNSQType.ANY[, suffixMatch=false]]) .. versionchanged:: 1.2.0 ``suffixMatch`` parameter added. @@ -622,7 +622,7 @@ See :doc:`../guides/cache` for a how to. Remove entries matching ``name`` and type from the cache. :param DNSName name: The name to expunge - :param int qtype: The type to expunge + :param int qtype: The type to expunge, can be a pre-defined :ref:`DNSQType` :param bool suffixMatch: When set to true, remove al entries under ``name`` .. method:: PacketCache:getStats() diff --git a/pdns/dnsdistdist/docs/reference/constants.rst b/pdns/dnsdistdist/docs/reference/constants.rst index 248f67148..03793cfa2 100644 --- a/pdns/dnsdistdist/docs/reference/constants.rst +++ b/pdns/dnsdistdist/docs/reference/constants.rst @@ -8,6 +8,8 @@ There are many constants in :program:`dnsdist`. OPCode ------ +These constants represent the `OpCode `__ of a query. + - ``DNSOpcode.Query`` - ``DNSOpcode.IQuery`` - ``DNSOpcode.Status`` @@ -21,6 +23,8 @@ Reference: https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml# DNSClass ------ +These constants represent the `CLASS `__ of a DNS record. + - ``DNSClass.IN`` - ``DNSClass.CHAOS`` - ``DNSClass.NONE`` @@ -33,31 +37,34 @@ Reference: https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml# RCode ----- -- ``dnsdist.NOERROR`` -- ``dnsdist.FORMERR`` -- ``dnsdist.SERVFAIL`` -- ``dnsdist.NXDOMAIN`` -- ``dnsdist.NOTIMP`` -- ``dnsdist.REFUSED`` -- ``dnsdist.YXDOMAIN`` -- ``dnsdist.YXRRSET`` -- ``dnsdist.NXRRSET`` -- ``dnsdist.NOTAUTH`` -- ``dnsdist.NOTZONE`` -- ``dnsdist.BADVERS`` -- ``dnsdist.BADSIG`` -- ``dnsdist.BADKEY`` -- ``dnsdist.BADTIME`` -- ``dnsdist.BADMODE`` -- ``dnsdist.BADNAME`` -- ``dnsdist.BADALG`` -- ``dnsdist.BADTRUNC`` -- ``dnsdist.BADCOOKIE`` - -RCodes below and including ``BADVERS`` are extended RCodes that can only be matched using :func:`ERCodeRule`. - -Reference: https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml#dns-parameters-6 - +These constants represent the different `RCODEs `__ for DNS messages. + +.. versionchanged:: 1.4.0 + The prefix is changed from ``dnsdist`` to ``DNSRCode``. + +- ``DNSRCode.NOERROR`` +- ``DNSRCode.FORMERR`` +- ``DNSRCode.SERVFAIL`` +- ``DNSRCode.NXDOMAIN`` +- ``DNSRCode.NOTIMP`` +- ``DNSRCode.REFUSED`` +- ``DNSRCode.YXDOMAIN`` +- ``DNSRCode.YXRRSET`` +- ``DNSRCode.NXRRSET`` +- ``DNSRCode.NOTAUTH`` +- ``DNSRCode.NOTZONE`` + +RCodes below are extended RCodes that can only be matched using :func:`ERCodeRule`. + +- ``DNSRCode.BADVERS`` +- ``DNSRCode.BADSIG`` +- ``DNSRCode.BADKEY`` +- ``DNSRCode.BADTIME`` +- ``DNSRCode.BADMODE`` +- ``DNSRCode.BADNAME`` +- ``DNSRCode.BADALG`` +- ``DNSRCode.BADTRUNC`` +- ``DNSRCode.BADCOOKIE`` .. _EDNSOptionCode: @@ -80,8 +87,10 @@ Reference: https://www.iana.org/assignments/dns-parameters/dns-parameters.xhtml# .. _DNSSection: -DNS Section ------------ +DNS Packet Sections +------------------- + +These constants represent the section in the DNS Packet. - ``DNSSection.Question`` - ``DNSSection.Answer`` @@ -109,6 +118,22 @@ These constants represent an Action that can be returned from :func:`LuaAction` * ``DNSAction.Truncate``: truncate the response * ``DNSAction.NoRecurse``: set rd=0 on the query +.. _DNSQType: + +DNSQType +-------- + +.. versionchanged:: 1.3.0 + The prefix is changed from ``dnsdist.`` to ``DNSQType``. + +All named `QTypes `__ are available as constants, prefixed with ``DNSQType.``, e.g.: + + * ``DNSQType.AAAA`` + * ``DNSQType.AXFR`` + * ``DNSQType.A`` + * ``DNSQType.NS`` + * ``DNSQType.SOA`` + * etc. .. _DNSResponseAction: diff --git a/pdns/dnsdistdist/docs/reference/dq.rst b/pdns/dnsdistdist/docs/reference/dq.rst index 117ac18bb..e451eb62e 100644 --- a/pdns/dnsdistdist/docs/reference/dq.rst +++ b/pdns/dnsdistdist/docs/reference/dq.rst @@ -47,7 +47,7 @@ This state can be modified from the various hooks. .. attribute:: DNSQuestion.qtype QType (as an unsigned integer) of this question. - Can be compared against ``dnsdist.A``, ``dnsdist.AAAA`` etc. + Can be compared against the pre-defined :ref:`constants ` like ``DNSQType.A``, DNSQType.AAAA``. .. attribute:: DNSQuestion.remoteaddr @@ -170,7 +170,7 @@ DNSResponse object - ``section`` is the section in the packet and can be compared to :ref:`DNSSection` - ``qclass`` is the QClass of the record. Can be compared to :ref:`DNSQClass` - - ``qtype`` is the QType of the record. Can be e.g. compared to ``dnsdist.A``, ``dnsdist.AAAA`` and the like. + - ``qtype`` is the QType of the record. Can be e.g. compared to ``DNSQType.A``, ``DNSQType.AAAA`` :ref:`constants ` and the like. - ``ttl`` is the current TTL This function must return an integer with the new TTL. diff --git a/pdns/dnsdistdist/docs/rules-actions.rst b/pdns/dnsdistdist/docs/rules-actions.rst index ec23c155e..f2ad20a6d 100644 --- a/pdns/dnsdistdist/docs/rules-actions.rst +++ b/pdns/dnsdistdist/docs/rules-actions.rst @@ -81,7 +81,10 @@ Rule Generators Set the TC-bit (truncate) on ANY queries received over UDP, forcing a retry over TCP. This function is deprecated as of 1.2.0 and will be removed in 1.3.0. This is equivalent to doing:: - addAction(AndRule({QTypeRule(dnsdist.ANY), TCPRule(false)}), TCAction()) + addAction(AndRule({QTypeRule(DNSQType.ANY), TCPRule(false)}), TCAction()) + + .. versionchanged:: 1.4.0 + Before 1.4.0, the QTypes were in the ``dnsdist`` namespace. Use ``dnsdist.ANY`` in these versions. .. function:: addDelay(DNSrule, delay) @@ -718,7 +721,7 @@ These ``DNSRule``\ s be one of the following items: Matches if there is at least ``minCount`` and at most ``maxCount`` records of type ``type`` in the section ``section``. ``section`` can be specified as an integer or as a ref:`DNSSection`. - ``qtype`` may be specified as an integer or as one of the built-in QTypes, for instance ``dnsdist.A`` or ``dnsdist.TXT``. + ``qtype`` may be specified as an integer or as one of the :ref:`built-in QTypes `, for instance ``DNSQType.A`` or ``DNSQType.TXT``. :param int section: The section to match on :param int qtype: The QTYPE to match on