From: Pieter Lexis Date: Thu, 25 Jan 2018 16:19:40 +0000 (+0100) Subject: docs: Layout the Lua scripting docs better X-Git-Tag: dnsdist-1.3.0~116^2~3 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=54c79a88e11b1869bd96364251d84a443a1a16f5;p=thirdparty%2Fpdns.git docs: Layout the Lua scripting docs better Add missing functions, fix broken attributes and methods. --- diff --git a/pdns/recursordist/docs/lua-scripting/comboaddress.rst b/pdns/recursordist/docs/lua-scripting/comboaddress.rst index 68668e4c0d..a36dd996c3 100644 --- a/pdns/recursordist/docs/lua-scripting/comboaddress.rst +++ b/pdns/recursordist/docs/lua-scripting/comboaddress.rst @@ -24,44 +24,50 @@ To compare the address (so not the port) of two ComboAddresses, use :meth:`:equa To convert an address to human-friendly representation, use :meth:`:toString ` or :meth:`:toStringWithPort `. To get only the port number, use :meth:`:getPort() `. +.. function:: NewCA(address) -> ComboAddress + + Creates a :class:`ComboAddress`. + + :param string address: The address to convert + .. class:: ComboAddress - An object representing an IP address and port tuple. + An object representing an IP address and port tuple. -.. classmethod:: ComboAddress:getPort() -> int + .. method:: ComboAddress:getPort() -> int - The portnumber. + The portnumber. -.. classmethod:: ComboAddress:getRaw() -> str + .. method:: ComboAddress:getRaw() -> str - A bytestring representing the address. + A bytestring representing the address. -.. classmethod:: ComboAddress:isIPv4() -> bool + .. method:: ComboAddress:isIPv4() -> bool - True if the address is an IPv4 address. + True if the address is an IPv4 address. -.. classmethod:: ComboAddress:isIPv6() -> bool + .. method:: ComboAddress:isIPv6() -> bool - True if the address is an IPv6 address. + True if the address is an IPv6 address. -.. classmethod:: ComboAddress:isMappedIPv4() -> bool + .. method:: ComboAddress:isMappedIPv4() -> bool - True if the address is an IPv4 address mapped into an IPv6 one. + True if the address is an IPv4 address mapped into an IPv6 one. -.. classmethod:: ComboAddress:mapToIPv4() -> ??? + .. method:: ComboAddress:mapToIPv4() -> ComboAddress - If the address is an IPv4 mapped into an IPv6 one, return the corresponding IPv4 address. + If the address is an IPv4 mapped into an IPv6 one, return the corresponding IPv4 :class:`ComboAddress`. -.. classmethod:: ComboAddress:toString() -> str + .. method:: ComboAddress:toString() -> str - Returns the IP address without the port number as a string. + Returns the IP address without the port number as a string. -.. classmethod:: ComboAddress:toStringWithPort() -> str + .. method:: ComboAddress:toStringWithPort() -> str - Returns the IP address with the port number as a string. + Returns the IP address with the port number as a string. -.. classmethod:: ComboAddress:truncate(bits) + .. method:: ComboAddress:truncate(bits) - Truncate to the supplied number of bits + Truncate to the supplied number of bits - :param int bits: The number of bits to truncate to + :param int bits: The number of bits to truncate to diff --git a/pdns/recursordist/docs/lua-scripting/dnsname.rst b/pdns/recursordist/docs/lua-scripting/dnsname.rst index 9c0ae67601..9e63861efc 100644 --- a/pdns/recursordist/docs/lua-scripting/dnsname.rst +++ b/pdns/recursordist/docs/lua-scripting/dnsname.rst @@ -6,15 +6,16 @@ This native format is exposed to Lua as well. The DNSName object ------------------ - -.. class:: DNSName - - A ``DNSName`` object represents a name in the DNS. - It is returned by several functions and has several functions to programmatically interact with it. +The PowerDNS Recursor's Lua engine has the notion of a :class:`DNSName`, an object that represents a name in the DNS. +It is returned by several functions and has several functions to programmatically interact with it. +:class:`DNSNames ` can be compared agains each other using the :meth:`:equal ` function or the ``==`` operator. +As names in the DNS are case-insensitive, ``www.powerdns.com`` is equal to ``Www.PowerDNS.cOM``. Creating a :class:`DNSName` is done with :func:`newDN()`. The PowerDNS Recursor will complain loudly if the name is invalid (e.g. too long, dot in the wrong place). +A small example of the functionality of a :class:`DNSName` is shown below: + .. code-block:: lua myname = newDN("www.example.com") @@ -22,58 +23,67 @@ The PowerDNS Recursor will complain loudly if the name is invalid (e.g. too long print(myname:wirelength()) -- prints "17" name2 = newDN(myname) name2:chopoff() -- returns true, as 'www' was stripped + print(name2:countLabels()) -- prints "2" if myname:isPartOf(name2) then -- prints "it is" print('it is') end -:class:`DNSNames ` can be compared agains each other using the :meth:`:equal ` function or the ``==`` operator. - .. function:: newDN(name) -> DNSName Returns the :class:`DNSName` object of ``name``. :param string name: The name to create a DNSName for -.. classmethod:: DNSName::chopOff() -> bool +.. class:: DNSName + + A ``DNSName`` object represents a name in the DNS. + + .. method:: DNSName:chopOff() -> bool - Removes the left-most label and returns ``true``. - ``false`` is returned if no label was removed + Removes the left-most label and returns ``true``. + ``false`` is returned if no label was removed -.. classmethod:: DNSName:countLabels() -> int + .. method:: DNSName:countLabels() -> int - Returns the number of DNSLabels in the name + Returns the number of DNSLabels in the name -.. classmethod:: DNSName:isPartOf(name) -> bool + .. method:: DNSName:equal(name) -> bool - Returns true if the DNSName is part of the DNS tree of ``name``. + Returns true when both names are equal for the DNS, i.e case insensitive. - .. code-block:: Lua + :param DNSName name: The name to compare against. - newDN("www.powerdns.com"):isPartOf(newDN("CoM.")) -- true + .. method:: DNSName:isPartOf(name) -> bool - :param DNSName name: The name to check against + Returns true if the DNSName is part of the DNS tree of ``name``. -.. classmethod:: DNSName:toString() -> str - DNSName:toStringNoDot() -> str + .. code-block:: Lua - Returns a human-readable form of the DNSName. - With or without trailing dot. + newDN("www.powerdns.com"):isPartOf(newDN("CoM.")) -- true -.. classmethod:: DNSName:wirelength -> int + :param DNSName name: The name to check against - Returns the length in bytes of the DNSName as it would be on the wire. + .. method:: DNSName:toString() -> str + DNSName:toStringNoDot() -> str + + Returns a human-readable form of the DNSName. + With or without trailing dot. + + .. method:: DNSName:wirelength() -> int + + Returns the length in bytes of the DNSName as it would be on the wire. DNS Suffix Match Groups ----------------------- -The func:`newDS` function creates a "Suffix Match group" that allows fast checking if a :class:`DNSName` is part of a group. +The :func:`newDS` function creates a "Suffix Match group" that allows fast checking if a :class:`DNSName` is part of a group. This could e.g. be used to answer questions for known malware domains. -To check e.g. the ``dq.qname`` against a list: +To check e.g. the :attr:`dq.qname` against a list: -.. code-block:: Lua +.. code-block:: lua m = newDS() - m:add({'example.com', 'example.net}) + m:add({'example.com', 'example.net'}) m:check(dq.qname) -- Would be true is dq.qname is a name in example.com or example.net .. function:: newDS() -> DNSSuffixMatchGroup @@ -84,21 +94,21 @@ To check e.g. the ``dq.qname`` against a list: This class represents a group of DNS names that can be used to quickly compare a single :class:`DNSName` against. -.. classmethod:: DNSSuffixMatchGroup::add(domain) - DNSSuffixMatchGroup::add(domains) + .. method:: DNSSuffixMatchGroup:add(domain) + DNSSuffixMatchGroup:add(domains) - Add one or more domains to the Suffix Match Group. + Add one or more domains to the Suffix Match Group. - :param str domain: A domain name to add - :param {str} domain: A list of Domains to add + :param str domain: A domain name to add + :param {str} domain: A list of Domains to add -.. classmethod:: DNSSuffixMatchGroup:check(domain) -> bool + .. method:: DNSSuffixMatchGroup:check(domain) -> bool - Check ``domain`` against the Suffix Match Group. - Returns true if it is matched, false otherwise. + Check ``domain`` against the Suffix Match Group. + Returns true if it is matched, false otherwise. - :param DNSName domain: The domain name to check + :param DNSName domain: The domain name to check -.. classmethod:: DNSSuffixMatchGroup:toString() -> str + .. method:: DNSSuffixMatchGroup:toString() -> str - Returns a string of the set of suffixes matched by the Suffix Match Group + Returns a string of the set of suffixes matched by the Suffix Match Group diff --git a/pdns/recursordist/docs/lua-scripting/dnsrecord.rst b/pdns/recursordist/docs/lua-scripting/dnsrecord.rst index 5caa797b13..4b386b284b 100644 --- a/pdns/recursordist/docs/lua-scripting/dnsrecord.rst +++ b/pdns/recursordist/docs/lua-scripting/dnsrecord.rst @@ -6,37 +6,42 @@ DNS record objects are returned by :meth:`DNSQuestion:getRecords`. .. class:: DNSRecord Represents a single DNS record. + It has these attributes: -.. attribute:: DNSRecord.name -> DNSName + .. attribute:: DNSRecord.name - The name of the record. + The name of the record. A :class:`DNSName`. -.. attribute:: DNSRecord.place -> int + .. attribute:: DNSRecord.place - The place where the record is located, - - 1 for the answer section - - 2 for the authority section - - 3 for the additional section + The place where the record is located, -.. attribute:: DNSRecord.ttl -> int + - 0 for the question section + - 1 for the answer section + - 2 for the authority section + - 3 for the additional section - The TTL of the record + .. attribute:: DNSRecord.ttl -.. attribute:: DNSRecord.type -> int + The TTL of the record - The type of the record, for example pdns.A + .. attribute:: DNSRecord.type -.. classmethod:: DNSRecord:changeContent(newcontent) + The type of the record (as an integer). Can for example be compared to ``pdns.A``. - Replace the record content with ``newcontent``. - The type and class cannot be changed. + And the following methods: - :param str newcontent: The replacing content + .. method:: DNSRecord:changeContent(newcontent) -.. classmethod:: DNSRecord:getCA() -> ComboAddress + Replace the record content with ``newcontent``. + The type and class cannot be changed. - If the record type is A or AAAA, a :class:`ComboAddress` representing the content is returned, nil otherwise. + :param str newcontent: The replacing content -.. classmethod:: DNSRecord:getContent() -> str + .. method:: DNSRecord:getCA() -> ComboAddress - Return a string representation of the record content. + If the record type is A or AAAA, a :class:`ComboAddress` representing the content is returned, nil otherwise. + + .. method:: DNSRecord:getContent() -> str + + Return a string representation of the record content. diff --git a/pdns/recursordist/docs/lua-scripting/dq.rst b/pdns/recursordist/docs/lua-scripting/dq.rst index 963d6ab93a..a8c7621c22 100644 --- a/pdns/recursordist/docs/lua-scripting/dq.rst +++ b/pdns/recursordist/docs/lua-scripting/dq.rst @@ -8,211 +8,210 @@ The DNSQuestion object contains at least the following fields: .. class:: DNSQuestion - An object that contains everything about the current query. + An object that contains everything about the current query. + This object has the following attributes: -.. attribute:: DNSQuestion.qname + .. attribute:: DNSQuestion.qname - :class:`DNSName` of the name this query is for. + :class:`DNSName` of the name this query is for. -.. attribute:: DNSQuestion.qtype + .. attribute:: DNSQuestion.qtype - Type this query is for as an integer, can be compared against ``pdns.A``, ``pdns.AAAA``. + Type this query is for as an integer, can be compared against ``pdns.A``, ``pdns.AAAA``. -.. attribute:: DNSQuestion.rcode + .. attribute:: DNSQuestion.rcode - current DNS Result Code, which can be overridden, including to several magical values - The rcode can be set to pdns.DROP to drop the query. - Other statuses are normal DNS return codes, like ``pdns.NOERROR``, ``pdns.NXDOMAIN`` etc. + current DNS Result Code, which can be overridden, including to several magical values + The rcode can be set to pdns.DROP to drop the query. + Other statuses are normal DNS return codes, like ``pdns.NOERROR``, ``pdns.NXDOMAIN`` etc. -.. attribute:: DNSQuestion.isTcp + .. attribute:: DNSQuestion.isTcp - Boolean whether the query have been received over TCP. + Boolean whether the query have been received over TCP. -.. attribute:: DNSQuestion.remoteaddr -> ComboAddress + .. attribute:: DNSQuestion.remoteaddr - :class:`ComboAddress` of the requestor. + :class:`ComboAddress` of the requestor. -.. attribute:: DNSQuestion.localaddr -> ComboAddress + .. attribute:: DNSQuestion.localaddr - :class:`ComboAddress` where this query was received on. + :class:`ComboAddress` where this query was received on. -.. attribute:: DNSQuestion.variable + .. attribute:: DNSQuestion.variable - Boolean which, if set, indicates the recursor should not packet cache this answer. - Honored even when returning false from a hook! - Important when providing answers that vary over time or based on sender details. + Boolean which, if set, indicates the recursor should not packet cache this answer. + Honored even when returning false from a hook! + Important when providing answers that vary over time or based on sender details. -.. attribute:: DNSQuestion.followupFunction + .. attribute:: DNSQuestion.followupFunction - String that signals the nameserver to take one an additional action: + String that signals the nameserver to take one an additional action: - - followCNAMERecords: When adding a CNAME to the answer, this tells the recursor to follow that CNAME. See :ref:`CNAME Chain Resolution ` - - getFakeAAAARecords: Get a fake AAAA record, see :doc:`DNS64 <../dns64>` - - getFakePTRRecords: Get a fake PTR record, see :doc:`DNS64 <../dns64>` - - udpQueryResponse: Do a UDP query and call a handler, see :ref:`UDP Query Response ` + - followCNAMERecords: When adding a CNAME to the answer, this tells the recursor to follow that CNAME. See :ref:`CNAME Chain Resolution ` + - getFakeAAAARecords: Get a fake AAAA record, see :doc:`DNS64 <../dns64>` + - getFakePTRRecords: Get a fake PTR record, see :doc:`DNS64 <../dns64>` + - udpQueryResponse: Do a UDP query and call a handler, see :ref:`UDP Query Response ` -.. attribute:: DNSQuestion.appliedPolicy + .. attribute:: DNSQuestion.appliedPolicy The decision that was made by the policy engine, see :ref:`modifyingpolicydecisions`. -.. attribute:: DNSQuestion.appliedPolicy.policyName + .. attribute:: DNSQuestion.appliedPolicy.policyName - A string with the name of the policy. - Set by :ref:`policyName ` in the :func:`rpzFile` and :func:`rpzMaster` configuration items. - It is advised to overwrite this when modifying the :attr:`DNSQuestion.appliedPolicy.policyKind` + A string with the name of the policy. + Set by :ref:`policyName ` in the :func:`rpzFile` and :func:`rpzMaster` configuration items. + It is advised to overwrite this when modifying the :attr:`DNSQuestion.appliedPolicy.policyKind` -.. attribute:: DNSQuestion.appliedPolicy.policyAction + .. attribute:: DNSQuestion.appliedPolicy.policyAction - The action taken by the engine + The action taken by the engine -.. attribute:: DNSQuestion.appliedPolicy.policyCustom + .. attribute:: DNSQuestion.appliedPolicy.policyCustom - The CNAME content for the ``pdns.policyactions.Custom`` response, a string + The CNAME content for the ``pdns.policyactions.Custom`` response, a string -.. attribute:: DNSQuestion.appliedPolicy.policyKind + .. attribute:: DNSQuestion.appliedPolicy.policyKind - The kind of policy response, there are several policy kinds: + The kind of policy response, there are several policy kinds: - - ``pdns.policykinds.Custom`` will return a NoError, CNAME answer with the value specified in :attr:`DNSQuestion.appliedPolicy.policyCustom` - - ``pdns.policykinds.Drop`` will simply cause the query to be dropped - - ``pdns.policykinds.NoAction`` will continue normal processing of the query - - ``pdns.policykinds.NODATA`` will return a NoError response with no value in the answer section - - ``pdns.policykinds.NXDOMAIN`` will return a response with a NXDomain rcode - - ``pdns.policykinds.Truncate`` will return a NoError, no answer, truncated response over UDP. Normal processing will continue over TCP + - ``pdns.policykinds.Custom`` will return a NoError, CNAME answer with the value specified in :attr:`DNSQuestion.appliedPolicy.policyCustom` + - ``pdns.policykinds.Drop`` will simply cause the query to be dropped + - ``pdns.policykinds.NoAction`` will continue normal processing of the query + - ``pdns.policykinds.NODATA`` will return a NoError response with no value in the answer section + - ``pdns.policykinds.NXDOMAIN`` will return a response with a NXDomain rcode + - ``pdns.policykinds.Truncate`` will return a NoError, no answer, truncated response over UDP. Normal processing will continue over TCP -.. attribute:: DNSQuestion.appliedPolicy.policyTTL + .. attribute:: DNSQuestion.appliedPolicy.policyTTL - The TTL in seconds for the ``pdns.policyactions.Custom`` response + The TTL in seconds for the ``pdns.policyactions.Custom`` response -.. attribute:: DNSQuestion.wantsRPZ + .. attribute:: DNSQuestion.wantsRPZ - A boolean that indicates the use of the Policy Engine. - Can be set to ``false`` in ``prerpz`` to disable RPZ for this query. + A boolean that indicates the use of the Policy Engine. + Can be set to ``false`` in ``prerpz`` to disable RPZ for this query. -.. attribute:: DNSQuestion.data + .. attribute:: DNSQuestion.data - A Lua object reference that is persistent throughout the lifetime of the :class:`DNSQuestion` object for a single query. - It can be used to store custom data. - Most scripts initialise this to an empty table early on so they can store multiple items. + A Lua object reference that is persistent throughout the lifetime of the :class:`DNSQuestion` object for a single query. + It can be used to store custom data. + Most scripts initialise this to an empty table early on so they can store multiple items. -.. attribute:: DNSQuestion.requestorId str + .. attribute:: DNSQuestion.requestorId - .. versionadded:: 4.1.0 + .. versionadded:: 4.1.0 - A string that will be used to set the ``requestorId`` field in :doc:`protobuf <../lua-config/protobuf>` messages. + A string that will be used to set the ``requestorId`` field in :doc:`protobuf <../lua-config/protobuf>` messages. -.. attribute:: DNSQuestion.deviceId str + .. attribute:: DNSQuestion.deviceId - .. versionadded:: 4.1.0 + .. versionadded:: 4.1.0 - A string that will be used to set the ``deviceId`` field in :doc:`protobuf <../lua-config/protobuf>` messages. + A string that will be used to set the ``deviceId`` field in :doc:`protobuf <../lua-config/protobuf>` messages. -.. attribute:: DNSQuestion.udpAnswer -> str + .. attribute:: DNSQuestion.udpAnswer - Answer to the :attr:`udpQuery ` when when using the ``udpQueryResponse`` :attr:`followupFunction `. - Only filled when the call-back function is invoked. + Answer to the :attr:`udpQuery ` when when using the ``udpQueryResponse`` :attr:`followupFunction `. + Only filled when the call-back function is invoked. -.. attribute:: DNSQuestion.udpQueryDest -> str + .. attribute:: DNSQuestion.udpQueryDest - Destination IP address to send the UDP packet to when using the ``udpQueryResponse`` :attr:`followupFunction ` + Destination IP address to send the UDP packet to when using the ``udpQueryResponse`` :attr:`followupFunction ` -.. attribute:: DNSQuestion.udpQuery -> str + .. attribute:: DNSQuestion.udpQuery - The content of the UDP payload when using the ``udpQueryResponse`` :attr:`followupFunction ` + The content of the UDP payload when using the ``udpQueryResponse`` :attr:`followupFunction ` -.. attribute:: DNSQuestion.udpCallback -> str + .. attribute:: DNSQuestion.udpCallback - The name of the callback function that is called when using the ``udpQueryResponse`` :attr:`followupFunction ` when an answer is received. + The name of the callback function that is called when using the ``udpQueryResponse`` :attr:`followupFunction ` when an answer is received. -.. attribute:: DNSQuestion.validationState + .. attribute:: DNSQuestion.validationState - .. versionadded:: 4.1.0 + .. versionadded:: 4.1.0 - The result of the DNSSEC validation, accessible from the ``postresolve``, ``nxdomain`` and ``nodata`` hooks. - Possible states are ``pdns.validationstates.Indeterminate``, ``pdns.validationstates.Bogus``, ``pdns.validationstates.Insecure`` and ``pdns.validationstates.Secure``. - The result will always be ``pdns.validationstates.Indeterminate`` is validation is disabled or was not requested. + The result of the DNSSEC validation, accessible from the ``postresolve``, ``nxdomain`` and ``nodata`` hooks. + Possible states are ``pdns.validationstates.Indeterminate``, ``pdns.validationstates.Bogus``, ``pdns.validationstates.Insecure`` and ``pdns.validationstates.Secure``. + The result will always be ``pdns.validationstates.Indeterminate`` is validation is disabled or was not requested. -It also supports the following methods: + It also supports the following methods: -.. classmethod:: DNSQuestion:addAnswer(type, content, [ttl, name]) + .. method:: DNSQuestion:addAnswer(type, content, [ttl, name]) - Add an answer to the record of ``type`` with ``content``. + Add an answer to the record of ``type`` with ``content``. - :param int type: The type of record to add, can be ``pdns.AAAA`` etc. - :param str content: The content of the record, will be parsed into wireformat based on the ``type`` - :param int ttl: The TTL in seconds for this record - :param ??? name: The name of this record, defaults to :attr:`DNSQuestion.qname` + :param int type: The type of record to add, can be ``pdns.AAAA`` etc. + :param str content: The content of the record, will be parsed into wireformat based on the ``type`` + :param int ttl: The TTL in seconds for this record + :param DNSName name: The name of this record, defaults to :attr:`DNSQuestion.qname` -.. classmethod:: DNSQuestion:addPolicyTag(tag) + .. method:: DNSQuestion:addPolicyTag(tag) - Add a policy tag. + Add a policy tag. - :param str tag: The tag to add + :param str tag: The tag to add -.. classmethod:: DNSQuestion:discardPolicy(policyname) + .. method:: DNSQuestion:discardPolicy(policyname) - Skip the filtering policy (for example RPZ) named ``policyname`` for this query. - This is mostly useful in the ``prerpz`` hook. + Skip the filtering policy (for example RPZ) named ``policyname`` for this query. + This is mostly useful in the ``prerpz`` hook. - :param str policyname: The name of the policy to ignore. + :param str policyname: The name of the policy to ignore. -.. classmethod:: DNSQuestion:getDH() -> DNSHeader + .. method:: DNSQuestion:getDH() -> DNSHeader - Returns the :class:`DNSHeader` of the query or nil. + Returns the :class:`DNSHeader` of the query or nil. -.. classmethod:: DNSQuestion:getPolicyTags() -> {str} + .. method:: DNSQuestion:getPolicyTags() -> {str} - Get the current policy tags as a table of strings. + Get the current policy tags as a table of strings. -.. classmethod:: DNSQuestion:getRecords() -> {DNSRecord} + .. method:: DNSQuestion:getRecords() -> {DNSRecord} - Get a table of DNS Records in this DNS Question (or answer by now). + Get a table of DNS Records in this DNS Question (or answer by now). -.. classmethod:: DNSQuestion:setPolicyTags(tags) + .. method:: DNSQuestion:setPolicyTags(tags) - Set the policy tags to ``tags``, overwriting any existing policy tags. + Set the policy tags to ``tags``, overwriting any existing policy tags. - :param {str} tags: The policy tags + :param {str} tags: The policy tags -.. classmethod:: DNSQuestion:setRecords(records) + .. method:: DNSQuestion:setRecords(records) - After your edits, update the answers of this question + After your edits, update the answers of this question - :param {DNSRecord} records: The records to put in the packet + :param {DNSRecord} records: The records to put in the packet -.. classmethod:: DNSQuestion:getEDNSFlag(name) -> bool + .. method:: DNSQuestion:getEDNSFlag(name) -> bool - Returns true if the EDNS flag with ``name`` is set in the query. + Returns true if the EDNS flag with ``name`` is set in the query. - :param string name: Name of the flag. + :param string name: Name of the flag. -.. classmethod:: DNSQuestion:getEDNSFlags() -> {str} + .. method:: DNSQuestion:getEDNSFlags() -> {str} - Returns a list of strings with all the EDNS flag mnemonics in the query. + Returns a list of strings with all the EDNS flag mnemonics in the query. -.. classmethod:: DNSQuestion:getEDNSOption(num) -> str + .. method:: DNSQuestion:getEDNSOption(num) -> str - Get the EDNS Option with number ``num`` as a bytestring. + Get the EDNS Option with number ``num`` as a bytestring. -.. classmethod:: DNSQuestion:getEDNSOptions() {str: str} + .. method:: DNSQuestion:getEDNSOptions() -> {str: str} - Get a map of all EDNS Options + Get a map of all EDNS Options -.. classmethod:: DNSQuestion:getEDNSSubnet() -> Netmask + .. method:: DNSQuestion:getEDNSSubnet() -> Netmask - Returns the netmask specified in the EDNSSubnet option, or empty if there was none. + Returns the :class:`Netmask` specified in the EDNSSubnet option, or empty if there was none. -.. classmethod:: DNSQuestion:addPolicyTag(tag) + .. method:: DNSQuestion:addPolicyTag(tag) - Add policyTag ``tag`` to the list of policyTags + Add policyTag ``tag`` to the list of policyTags - :param str tag: The tag to add - -.. classmethod:: DNSQuestion:getPolicyTags() -> {str} - - Get a list the policyTags for this message. + :param str tag: The tag to add + .. method:: DNSQuestion:getPolicyTags() -> {str} + Get a list the policyTags for this message. DNSHeader Object ================ @@ -223,37 +222,37 @@ The DNS header as returned by :meth:`DNSQuestion:getDH()` represents a header of represents a header of a DNS message. -.. classmethod:: DNSHeader:getRD() -> bool + .. method:: DNSHeader:getRD() -> bool - The value of the Recursion Desired bit. + The value of the Recursion Desired bit. -.. classmethod:: DNSHeader:getAA() -> bool + .. method:: DNSHeader:getAA() -> bool - The value of the Authoritative Answer bit. + The value of the Authoritative Answer bit. -.. classmethod:: DNSHeader:getAD() -> bool + .. method:: DNSHeader:getAD() -> bool - The value of the Authenticated Data bit. + The value of the Authenticated Data bit. -.. classmethod:: DNSHeader:getCD() -> bool + .. method:: DNSHeader:getCD() -> bool - The value of the Checking Disabled bit. + The value of the Checking Disabled bit. -.. classmethod:: DNSHeader:getTC() -> bool + .. method:: DNSHeader:getTC() -> bool - The value of the Truncation bit. + The value of the Truncation bit. -.. classmethod:: DNSHeader:getRCODE() -> int + .. method:: DNSHeader:getRCODE() -> int - The Response Code of the query + The Response Code of the query -.. classmethod:: DNSHeader:getOPCODE() -> int + .. method:: DNSHeader:getOPCODE() -> int - The Operation Code of the query + The Operation Code of the query -.. classmethod:: DNSHeader:getID() -> int + .. method:: DNSHeader:getID() -> int - The ID of the query + The ID of the query The EDNSOptionView Class ======================== @@ -262,10 +261,10 @@ The EDNSOptionView Class An object that represents a single EDNS option -.. attribute:: EDNSOptionView.size -> int + .. attribute:: EDNSOptionView.size - The size in bytes of the EDNS option. + The size in bytes of the EDNS option. -.. classmethod:: EDNSOptionView:getContent() -> str + .. method:: EDNSOptionView:getContent() - Returns a NULL-safe string object of the EDNS option's content + Returns a NULL-safe string object of the EDNS option's content diff --git a/pdns/recursordist/docs/lua-scripting/functions.rst b/pdns/recursordist/docs/lua-scripting/functions.rst index 8026a252d8..356b2f34d9 100644 --- a/pdns/recursordist/docs/lua-scripting/functions.rst +++ b/pdns/recursordist/docs/lua-scripting/functions.rst @@ -3,13 +3,15 @@ Other functions These are some functions that don't really have a place in one of the other categories. -.. function:: getregisteredname(name) +.. function:: getregisteredname(name) -> str Returns the shortest domain name based on Mozilla's Public Suffix List. In general it will tell you the 'registered domain' for a given name. For example ``getregisteredname('www.powerdns.com')`` returns "powerdns.com" + :param str name: The name to check for. + .. function:: getRecursorThreadId() -> int returns an unsigned integer identifying the thread handling the current request. diff --git a/pdns/recursordist/docs/lua-scripting/netmask.rst b/pdns/recursordist/docs/lua-scripting/netmask.rst index fb8f565506..3b9c3961af 100644 --- a/pdns/recursordist/docs/lua-scripting/netmask.rst +++ b/pdns/recursordist/docs/lua-scripting/netmask.rst @@ -7,87 +7,99 @@ There are two classes in the PowerDNS Recursor that can be used to match IP addr Netmask class ------------- +The :class:`Netmask` class represents an IP netmask. -.. class:: Netmask +.. code-block:: Lua + + mask = newNetmask("192.0.2.1/24") + mask:isIPv4() -- true + mask:match("192.0.2.8") -- true + +.. function:: newNetmask(mask) -> Netmask - Represents an IP netmask. - Can be created with + Creates a new :class:`Netmask`. - .. code-block:: Lua + :param str mask: The mask to convert. + +.. class:: Netmask - newNetmask("192.0.2.1/24") + Represents a netmask. -.. classmethod:: Netmask:empty() -> bool + .. method:: Netmask:empty() -> bool - True if the netmask doesn't contain a valid address. + True if the netmask doesn't contain a valid address. -.. classmethod:: Netmask:getBits() -> int + .. method:: Netmask:getBits() -> int - The number of bits in the address. + The number of bits in the address. -.. classmethod:: Netmask:getNetwork() -> ComboAddress + .. method:: Netmask:getNetwork() -> ComboAddress - Returns a :class:`ComboAddress` representing the network (no mask applied). + Returns a :class:`ComboAddress` representing the network (no mask applied). -.. classmethod:: Netmask:getMaskedNetwork() -> ComboAddress + .. method:: Netmask:getMaskedNetwork() -> ComboAddress - Returns a :class:`ComboAddress` representing the network (truncating according to the mask). + Returns a :class:`ComboAddress` representing the network (truncating according to the mask). -.. classmethod:: Netmask:isIpv4() -> bool + .. method:: Netmask:isIpv4() -> bool - True if the netmask is an IPv4 netmask. + True if the netmask is an IPv4 netmask. -.. classmethod:: Netmask:isIpv6 -> bool + .. method:: Netmask:isIpv6() -> bool - True if the netmask is an IPv6 netmask. + True if the netmask is an IPv6 netmask. -.. classmethod:: Netmask:match(address) -> bool + .. method:: Netmask:match(address) -> bool - True if the address passed in address matches + True if the address passed in address matches - :param str address: IP Address to match against. + :param str address: IP Address to match against. -.. classmethod:: Netmask:toString() -> str + .. method:: Netmask:toString() -> str - Returns a human-friendly representation. + Returns a human-friendly representation. NetMaskGroup class ------------------ NetMaskGroups are more powerful than plain Netmasks. +They can be matched against netmasks objects: -.. class:: NetMaskGroup +.. code-block:: lua + + nmg = newNMG() + nmg:addMask("127.0.0.0/8") + nmg:addMasks({"213.244.168.0/24", "130.161.0.0/16"}) + nmg:addMasks(dofile("bad.ips")) -- contains return {"ip1","ip2"..} - IP addresses are passed to Lua in native format. - They can be matched against netmasks objects: + if nmg:match(dq.remoteaddr) then + print("Intercepting query from ", dq.remoteaddr) + end - .. code-block:: Lua +Prefixing a mask with ``!`` excludes that mask from matching. - nmg = newNMG() - nmg:addMask("127.0.0.0/8") - nmg:addMasks({"213.244.168.0/24", "130.161.0.0/16"}) - nmg:addMasks(dofile("bad.ips")) -- contains return {"ip1","ip2"..} +.. function:: newNMG() -> NetMaskGroup - if nmg:match(dq.remoteaddr) then - print("Intercepting query from ", dq.remoteaddr) - end + Returns a new, empty :class:`NetMaskGroup`. + +.. class:: NetMaskGroup - Prefixing a mask with ``!`` excludes that mask from matching. + IP addresses are passed to Lua in native format. -.. classmethod:: NetMaskGroup:addMask(mask) + .. method:: NetMaskGroup:addMask(mask) - Adds ``mask`` to the NetMaskGroup. + Adds ``mask`` to the NetMaskGroup. - :param str mask: The mask to add. + :param str mask: The mask to add. -.. classmethod:: NetMaskGroup:addMasks(masks) + .. method:: NetMaskGroup:addMasks(masks) - Adds ``masks`` to the NetMaskGroup. + Adds ``masks`` to the NetMaskGroup. - :param {str} mask: The masks to add. + :param {str} mask: The masks to add. -.. classmethod:: NetMaskGroup:match(address) -> bool + .. method:: NetMaskGroup:match(address) -> bool - Returns true if ``address`` matches any of the masks in the group. + Returns true if ``address`` matches any of the masks in the group. - :param ComboAddress address: The IP addres to match the netmasks against. + :param ComboAddress address: The IP addres to match the netmasks against. diff --git a/pdns/recursordist/docs/lua-scripting/statistics.rst b/pdns/recursordist/docs/lua-scripting/statistics.rst index 9a1a7fa997..1a6d56ea3b 100644 --- a/pdns/recursordist/docs/lua-scripting/statistics.rst +++ b/pdns/recursordist/docs/lua-scripting/statistics.rst @@ -8,11 +8,15 @@ Generating Metrics Custom metrics can be added which will be shown in the output of 'rec_control get-all' and sent to the metrics server over the Carbon protocol. They will also appear in the JSON HTTP API. -Create a custom metric with: ``myMetric=getMetric("myspecialmetric")``. +Create a custom metric with: + +.. code-block:: lua + + myMetric=getMetric("myspecialmetric") .. function:: getMetric(name) -> Metric - Returns the :class:`Metric` object with the name ``name``. + Returns the :class:`Metric` object with the name ``name``, creating the metric if it does not exist. :param str name: The metric to retrieve @@ -20,25 +24,25 @@ Create a custom metric with: ``myMetric=getMetric("myspecialmetric")``. Represents a custom metric -.. classmethod:: Metric::inc() + .. method:: Metric::inc() - Increase metric by 1 + Increase metric by 1 -.. classmethod:: Metric::incBy(amount) + .. method:: Metric::incBy(amount) - Increase metric by amount + Increase metric by amount - :param int amount: + :param int amount: -.. classmethod:: Metric::set(to) + .. method:: Metric::set(to) - Set metric to value ``to`` + Set metric to value ``to`` - :param int to: + :param int to: -.. classmethod:: Metric::get() -> int + .. method:: Metric::get() -> int - Get value of metric + Get value of metric Metrics are shared across all of PowerDNS and are fully atomic and high performance. A :class:`Metric` object is effectively a pointer to an atomic value.