pdns/recursordist/docs/lua-scripting/dq.rst

   1 The DNSQuestion (``dq``) object
   2 ===============================
   3 Apart from the :func:`ipfilter`-function, all functions work on a ``dq`` (DNSQuestion) object.
   4 This object contains details about the current state of the question.
   5 This state can be modified from the various hooks.
   6
   7 The DNSQuestion object contains at least the following fields:
   8
   9 .. class:: DNSQuestion
  10
  11   An object that contains everything about the current query.
  12   This object has the following attributes:
  13
  14   .. attribute:: DNSQuestion.qname
  15
  16       :class:`DNSName` of the name this query is for.
  17
  18   .. attribute:: DNSQuestion.qtype
  19
  20       Type this query is for as an integer, can be compared against ``pdns.A``, ``pdns.AAAA``.
  21
  22   .. attribute:: DNSQuestion.rcode
  23
  24       current DNS Result Code, which can be overridden, including to several magical values
  25       The rcode can be set to pdns.DROP to drop the query.
  26       Other statuses are normal DNS return codes, like ``pdns.NOERROR``, ``pdns.NXDOMAIN`` etc.
  27
  28   .. attribute:: DNSQuestion.isTcp
  29
  30       Whether the query was received over TCP.
  31
  32   .. attribute:: DNSQuestion.remoteaddr
  33
  34       :class:`ComboAddress` of the requestor.
  35
  36   .. attribute:: DNSQuestion.localaddr
  37
  38       :class:`ComboAddress` where this query was received on.
  39
  40   .. attribute:: DNSQuestion.variable
  41
  42       Boolean which, if set, indicates the recursor should not packet cache this answer.
  43       Honored even when returning false from a hook!
  44       Important when providing answers that vary over time or based on sender details.
  45
  46   .. attribute:: DNSQuestion.followupFunction
  47
  48       String that signals the nameserver to take one an additional action:
  49
  50       - followCNAMERecords: When adding a CNAME to the answer, this tells the recursor to follow that CNAME. See :ref:`CNAME Chain Resolution <cnamechainresolution>`
  51       - getFakeAAAARecords: Get a fake AAAA record, see :doc:`DNS64 <../dns64>`
  52       - getFakePTRRecords: Get a fake PTR record, see :doc:`DNS64 <../dns64>`
  53       - udpQueryResponse: Do a UDP query and call a handler, see :ref:`UDP Query Response <udpqueryresponse>`
  54
  55   .. attribute:: DNSQuestion.appliedPolicy
  56
  57     The decision that was made by the policy engine, see :ref:`modifyingpolicydecisions`.
  58
  59     .. attribute:: DNSQuestion.appliedPolicy.policyName
  60
  61       A string with the name of the policy.
  62       Set by :ref:`policyName <rpz-policyName>` in the :func:`rpzFile` and :func:`rpzMaster` configuration items.
  63       It is advised to overwrite this when modifying the :attr:`DNSQuestion.appliedPolicy.policyKind`
  64
  65     .. attribute:: DNSQuestion.appliedPolicy.policyAction
  66
  67         The action taken by the engine
  68
  69     .. attribute:: DNSQuestion.appliedPolicy.policyCustom
  70
  71         The CNAME content for the ``pdns.policyactions.Custom`` response, a string
  72
  73     .. attribute:: DNSQuestion.appliedPolicy.policyKind
  74
  75       The kind of policy response, there are several policy kinds:
  76
  77       -  ``pdns.policykinds.Custom`` will return a NoError, CNAME answer with the value specified in :attr:`DNSQuestion.appliedPolicy.policyCustom`
  78       -  ``pdns.policykinds.Drop`` will simply cause the query to be dropped
  79       -  ``pdns.policykinds.NoAction`` will continue normal processing of the query
  80       -  ``pdns.policykinds.NODATA`` will return a NoError response with no value in the answer section
  81       -  ``pdns.policykinds.NXDOMAIN`` will return a response with a NXDomain rcode
  82       -  ``pdns.policykinds.Truncate`` will return a NoError, no answer, truncated response over UDP. Normal processing will continue over TCP
  83
  84     .. attribute:: DNSQuestion.appliedPolicy.policyTTL
  85
  86         The TTL in seconds for the ``pdns.policyactions.Custom`` response
  87
  88   .. attribute:: DNSQuestion.wantsRPZ
  89
  90       A boolean that indicates the use of the Policy Engine.
  91       Can be set to ``false`` in ``prerpz`` to disable RPZ for this query.
  92
  93   .. attribute:: DNSQuestion.data
  94
  95       A Lua object reference that is persistent throughout the lifetime of the :class:`DNSQuestion` object for a single query.
  96       It can be used to store custom data.
  97       Most scripts initialise this to an empty table early on so they can store multiple items.
  98
  99   .. attribute:: DNSQuestion.requestorId
 100
 101       .. versionadded:: 4.1.0
 102
 103       A string that will be used to set the ``requestorId`` field in :doc:`protobuf <../lua-config/protobuf>` messages.
 104
 105   .. attribute:: DNSQuestion.deviceId
 106
 107       .. versionadded:: 4.1.0
 108
 109       A string that will be used to set the ``deviceId`` field in :doc:`protobuf <../lua-config/protobuf>` messages.
 110
 111   .. attribute:: DNSQuestion.deviceName
 112
 113       .. versionadded:: 4.3.0
 114
 115       A string that will be used to set the ``deviceName`` field in :doc:`protobuf <../lua-config/protobuf>` messages.
 116
 117   .. attribute:: DNSQuestion.udpAnswer
 118
 119       Answer to the :attr:`udpQuery <DNSQuestion.udpQuery>` when when using the ``udpQueryResponse`` :attr:`followupFunction <DNSQuestion.followupFunction>`.
 120       Only filled when the call-back function is invoked.
 121
 122   .. attribute:: DNSQuestion.udpQueryDest
 123
 124       Destination IP address to send the UDP packet to when using the ``udpQueryResponse`` :attr:`followupFunction <DNSQuestion.followupFunction>`
 125
 126   .. attribute:: DNSQuestion.udpQuery
 127
 128       The content of the UDP payload when using the ``udpQueryResponse`` :attr:`followupFunction <DNSQuestion.followupFunction>`
 129
 130   .. attribute:: DNSQuestion.udpCallback
 131
 132       The name of the callback function that is called when using the ``udpQueryResponse`` :attr:`followupFunction <DNSQuestion.followupFunction>` when an answer is received.
 133
 134   .. attribute:: DNSQuestion.validationState
 135
 136       .. versionadded:: 4.1.0
 137
 138       The result of the DNSSEC validation, accessible from the ``postresolve``, ``nxdomain`` and ``nodata`` hooks.
 139       Possible states are ``pdns.validationstates.Indeterminate``, ``pdns.validationstates.Bogus``, ``pdns.validationstates.Insecure`` and ``pdns.validationstates.Secure``.
 140       The result will always be ``pdns.validationstates.Indeterminate`` is validation is disabled or was not requested.
 141
 142   .. attribute:: DNSQuestion.logResponse
 143
 144       .. versionadded:: 4.2.0
 145
 146       Whether the response to this query will be exported to a remote protobuf logger, if one has been configured.
 147
 148   It also supports the following methods:
 149
 150   .. method:: DNSQuestion:addAnswer(type, content, [ttl, name])
 151
 152      Add an answer to the record of ``type`` with ``content``.
 153
 154      :param int type: The type of record to add, can be ``pdns.AAAA`` etc.
 155      :param str content: The content of the record, will be parsed into wireformat based on the ``type``
 156      :param int ttl: The TTL in seconds for this record, defaults to 3600
 157      :param DNSName name: The name of this record, defaults to :attr:`DNSQuestion.qname`
 158
 159   .. method:: DNSQuestion:addRecord(type, content, place, [ttl, name])
 160
 161      Add a record of ``type`` with ``content`` in section ``place``.
 162
 163      :param int type: The type of record to add, can be ``pdns.AAAA`` etc.
 164      :param str content: The content of the record, will be parsed into wireformat based on the ``type``
 165      :param int place: The section to place the record, see :attr:`DNSRecord.place`
 166      :param int ttl: The TTL in seconds for this record, defaults to 3600
 167      :param DNSName name: The name of this record, defaults to :attr:`DNSQuestion.qname`
 168
 169   .. method:: DNSQuestion:addPolicyTag(tag)
 170
 171      Add policyTag ``tag`` to the list of policyTags.
 172
 173      :param str tag: The tag to add
 174
 175   .. method:: DNSQuestion:getPolicyTags() -> {str}
 176
 177       Get the current policy tags as a table of strings.
 178
 179   .. method:: DNSQuestion:setPolicyTags(tags)
 180
 181       Set the policy tags to ``tags``, overwriting any existing policy tags.
 182
 183       :param {str} tags: The policy tags
 184
 185   .. method:: DNSQuestion:discardPolicy(policyname)
 186
 187      Skip the filtering policy (for example RPZ) named ``policyname`` for this query.
 188      This is mostly useful in the ``prerpz`` hook.
 189
 190      :param str policyname: The name of the policy to ignore.
 191
 192   .. method:: DNSQuestion:getDH() -> DNSHeader
 193
 194       Returns the :class:`DNSHeader` of the query or nil.
 195
 196   .. method:: DNSQuestion:getRecords() -> {DNSRecord}
 197
 198       Get a table of DNS Records in this DNS Question (or answer by now).
 199
 200   .. method:: DNSQuestion:setRecords(records)
 201
 202       After your edits, update the answers of this question
 203
 204       :param {DNSRecord} records: The records to put in the packet
 205
 206   .. method:: DNSQuestion:getEDNSFlag(name) -> bool
 207
 208       Returns true if the EDNS flag with ``name`` is set in the query.
 209
 210       :param string name: Name of the flag.
 211
 212   .. method:: DNSQuestion:getEDNSFlags() -> {str}
 213
 214       Returns a list of strings with all the EDNS flag mnemonics in the query.
 215
 216   .. method:: DNSQuestion:getEDNSOption(num) -> str
 217
 218       Get the EDNS Option with number ``num`` as a bytestring.
 219
 220   .. method:: DNSQuestion:getEDNSOptions() -> {str: str}
 221
 222       Get a map of all EDNS Options
 223
 224   .. method:: DNSQuestion:getEDNSSubnet() -> Netmask
 225
 226       Returns the :class:`Netmask` specified in the EDNSSubnet option, or empty if there was none.
 227
 228 DNSHeader Object
 229 ================
 230
 231 The DNS header as returned by :meth:`DNSQuestion:getDH()` represents a header of a DNS message.
 232
 233 .. class:: DNSHeader
 234
 235     represents a header of a DNS message.
 236
 237   .. method:: DNSHeader:getRD() -> bool
 238
 239       The value of the Recursion Desired bit.
 240
 241   .. method:: DNSHeader:getAA() -> bool
 242
 243       The value of the Authoritative Answer bit.
 244
 245   .. method:: DNSHeader:getAD() -> bool
 246
 247       The value of the Authenticated Data bit.
 248
 249   .. method:: DNSHeader:getCD() -> bool
 250
 251       The value of the Checking Disabled bit.
 252
 253   .. method:: DNSHeader:getTC() -> bool
 254
 255       The value of the Truncation bit.
 256
 257   .. method:: DNSHeader:getRCODE() -> int
 258
 259       The Response Code of the query
 260
 261   .. method:: DNSHeader:getOPCODE() -> int
 262
 263       The Operation Code of the query
 264
 265   .. method:: DNSHeader:getID() -> int
 266
 267       The ID of the query
 268
 269 The EDNSOptionView Class
 270 ========================
 271
 272 .. class:: EDNSOptionView
 273
 274   An object that represents the values of a single EDNS option
 275
 276   .. method:: EDNSOptionView:count()
 277      .. versionadded:: 4.2.0
 278
 279     The number of values for this EDNS option.
 280
 281   .. method:: EDNSOptionView:getValues()
 282      .. versionadded:: 4.2.0
 283
 284     Return a table of NULL-safe strings values for this EDNS option.
 285
 286   .. attribute:: EDNSOptionView.size
 287
 288     The size in bytes of the first value of this EDNS option.
 289
 290   .. method:: EDNSOptionView:getContent()
 291
 292     Returns a NULL-safe string object of the first value of this EDNS option.