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.addPaddingToResponse
  15
  16       .. versionadded:: 4.5.0
  17
  18       Whether the response will get EDNS Padding. See :ref:`setting-yaml-incoming.edns_padding_from` and :ref:`setting-yaml-incoming.edns_padding_mode`.
  19
  20   .. attribute:: DNSQuestion.extendedErrorCode
  21
  22       .. versionadded:: 4.5.0
  23
  24       The extended error code, if any. See :ref:`setting-yaml-recursor.extended_resolution_errors`.
  25
  26   .. attribute:: DNSQuestion.extendedErrorExtra
  27
  28       .. versionadded:: 4.5.0
  29
  30       The extended error extra text, as a string, if any. See :ref:`setting-yaml-recursor.extended_resolution_errors`.
  31
  32   .. attribute:: DNSQuestion.qname
  33
  34       :class:`DNSName` of the name this query is for.
  35
  36   .. attribute:: DNSQuestion.qtype
  37
  38       Type this query is for as an integer, can be compared against ``pdns.A``, ``pdns.AAAA``.
  39
  40   .. attribute:: DNSQuestion.rcode
  41
  42       current DNS Result Code, which can be overridden, including to several magical values.
  43       Before 4.4.0, the rcode can be set to ``pdns.DROP`` to drop the query, for later versions refer to :ref:`hook-semantics`.
  44       Other statuses are normal DNS return codes, like ``pdns.NOERROR``, ``pdns.NXDOMAIN`` etc.
  45
  46   .. attribute:: DNSQuestion.isTcp
  47
  48       Whether the query was received over TCP.
  49
  50   .. attribute:: DNSQuestion.remoteaddr
  51
  52       :class:`ComboAddress` of the requestor.
  53       If the proxy protocol is used, this will contain the source address from the proxy protocol header.
  54
  55   .. attribute:: DNSQuestion.localaddr
  56
  57       :class:`ComboAddress` where this query was received on.
  58       If the proxy protocol is used, this will contain the destination address from the proxy protocol header.
  59
  60   .. attribute:: DNSQuestion.interface_remoteaddr
  61
  62       Source :class:`ComboAddress` of the packet received by the recursor. If the proxy protocol is not used, the value will match ``remoteaddr``.
  63
  64   .. attribute:: DNSQuestion.interface_localaddr
  65
  66       Destination :class:`ComboAddress` of the packet received by the recursor. If the proxy protocol is not used, the value will match ``localaddr``.
  67
  68   .. attribute:: DNSQuestion.variable
  69
  70       Boolean which, if set, indicates the recursor should not packet cache this answer.
  71       Honored even when returning false from a hook!
  72       Important when providing answers that vary over time or based on sender details.
  73
  74   .. attribute:: DNSQuestion.followupFunction
  75
  76       String that signals the nameserver to take one an additional action:
  77
  78       - followCNAMERecords: When adding a CNAME to the answer, this tells the recursor to follow that CNAME. See :ref:`CNAME Chain Resolution <cnamechainresolution>`
  79       - getFakeAAAARecords: Get a fake AAAA record, see :doc:`DNS64 <../dns64>`
  80       - getFakePTRRecords: Get a fake PTR record, see :doc:`DNS64 <../dns64>`
  81       - udpQueryResponse: Do a UDP query and call a handler, see :ref:`UDP Query Response <udpqueryresponse>`
  82
  83   .. attribute:: DNSQuestion.followupName
  84
  85       see :doc:`DNS64 <../dns64>`
  86
  87   .. attribute:: DNSQuestion.followupPrefix
  88
  89       see :doc:`DNS64 <../dns64>`
  90
  91   .. attribute:: DNSQuestion.appliedPolicy
  92
  93     The decision that was made by the policy engine, see :ref:`modifyingpolicydecisions`.
  94
  95     .. attribute:: DNSQuestion.appliedPolicy.policyName
  96
  97       A string with the name of the policy.
  98       Set by :ref:`policyName <rpz-policyName>` in the :func:`rpzFile` and :func:`rpzPrimary` configuration items.
  99       It is advised to overwrite this when modifying the :attr:`DNSQuestion.appliedPolicy.policyKind`
 100
 101     .. attribute:: DNSQuestion.appliedPolicy.policyType
 102
 103       The type of match for the policy.
 104
 105       -  ``pdns.policytypes.None``  the empty policy type
 106       -  ``pdns.policytypes.QName`` a match on qname
 107       -  ``pdns.policytypes.ClientIP`` a match on client IP
 108       -  ``pdns.policytypes.ResponseIP`` a match on response IP
 109       -  ``pdns.policytypes.NSDName`` a match on the name of a nameserver
 110       -  ``pdns.policytypes.NSIP`` a match on the IP of a nameserver
 111
 112     .. attribute:: DNSQuestion.appliedPolicy.policyCustom
 113
 114         The CNAME content for the ``pdns.policyactions.Custom`` response, a string
 115
 116     .. attribute:: DNSQuestion.appliedPolicy.policyKind
 117
 118       The kind of policy response, there are several policy kinds:
 119
 120       -  ``pdns.policykinds.Custom`` will return a NoError, CNAME answer with the value specified in :attr:`DNSQuestion.appliedPolicy.policyCustom`
 121       -  ``pdns.policykinds.Drop`` will simply cause the query to be dropped
 122       -  ``pdns.policykinds.NoAction`` will continue normal processing of the query
 123       -  ``pdns.policykinds.NODATA`` will return a NoError response with no value in the answer section
 124       -  ``pdns.policykinds.NXDOMAIN`` will return a response with a NXDomain rcode
 125       -  ``pdns.policykinds.Truncate`` will return a NoError, no answer, truncated response over UDP. Normal processing will continue over TCP
 126
 127     .. attribute:: DNSQuestion.appliedPolicy.policyTTL
 128
 129         The TTL in seconds for the ``pdns.policyactions.Custom`` response
 130
 131     .. attribute:: DNSQuestion.appliedPolicy.policyTrigger
 132
 133         The trigger (left-hand) part of the RPZ rule that was matched
 134
 135     .. attribute:: DNSQuestion.appliedPolicy.policyHit
 136
 137         The value that was matched. This is a string representing a name or an address.
 138
 139   .. attribute:: DNSQuestion.wantsRPZ
 140
 141       A boolean that indicates the use of the Policy Engine.
 142       Can be set to ``false`` in ``prerpz`` to disable RPZ for this query.
 143
 144   .. attribute:: DNSQuestion.data
 145
 146       A Lua object reference that is persistent throughout the lifetime of the :class:`DNSQuestion` object for a single query.
 147       It can be used to store custom data.
 148       Most scripts initialise this to an empty table early on so they can store multiple items.
 149
 150   .. attribute:: DNSQuestion.requestorId
 151
 152       .. versionadded:: 4.1.0
 153
 154       A string that will be used to set the ``requestorId`` field in :doc:`protobuf <../lua-config/protobuf>` messages.
 155
 156   .. attribute:: DNSQuestion.deviceId
 157
 158       .. versionadded:: 4.1.0
 159
 160       A string that will be used to set the ``deviceId`` field in :doc:`protobuf <../lua-config/protobuf>` messages.
 161
 162   .. attribute:: DNSQuestion.deviceName
 163
 164       .. versionadded:: 4.3.0
 165
 166       A string that will be used to set the ``deviceName`` field in :doc:`protobuf <../lua-config/protobuf>` messages.
 167
 168   .. attribute:: DNSQuestion.udpAnswer
 169
 170       Answer to the :attr:`udpQuery <DNSQuestion.udpQuery>` when using the ``udpQueryResponse`` :attr:`followupFunction <DNSQuestion.followupFunction>`.
 171       Only filled when the call-back function is invoked.
 172
 173   .. attribute:: DNSQuestion.udpQueryDest
 174
 175       Destination IP address to send the UDP packet to when using the ``udpQueryResponse`` :attr:`followupFunction <DNSQuestion.followupFunction>`
 176
 177   .. attribute:: DNSQuestion.udpQuery
 178
 179       The content of the UDP payload when using the ``udpQueryResponse`` :attr:`followupFunction <DNSQuestion.followupFunction>`
 180
 181   .. attribute:: DNSQuestion.udpCallback
 182
 183       The name of the callback function that is called when using the ``udpQueryResponse`` :attr:`followupFunction <DNSQuestion.followupFunction>` when an answer is received.
 184
 185   .. attribute:: DNSQuestion.validationState
 186
 187       .. versionadded:: 4.1.0
 188
 189       The result of the DNSSEC validation, accessible from the ``postresolve``, ``nxdomain`` and ``nodata`` hooks.
 190       Possible states are ``pdns.validationstates.Indeterminate``, ``pdns.validationstates.Bogus``, ``pdns.validationstates.Insecure`` and ``pdns.validationstates.Secure``.
 191       The result will always be ``pdns.validationstates.Indeterminate`` if validation is disabled or was not requested.
 192
 193   .. attribute:: DNSQuestion.detailedValidationState
 194
 195       .. versionadded:: 4.4.2
 196
 197       The result of the DNSSEC validation, accessible from the ``postresolve``, ``nxdomain`` and ``nodata`` hooks.
 198       By contrast with :attr:`validationState <DNSQuestion.validationState>`, there are several Bogus states to be
 199       able to better understand the reason for a DNSSEC validation failure.
 200
 201       Possible states are:
 202
 203       - ``pdns.validationstates.Indeterminate``
 204       - ``pdns.validationstates.BogusNoValidDNSKEY``
 205       - ``pdns.validationstates.BogusInvalidDenial``
 206       - ``pdns.validationstates.BogusUnableToGetDSs``
 207       - ``pdns.validationstates.BogusUnableToGetDNSKEYs``
 208       - ``pdns.validationstates.BogusSelfSignedDS``
 209       - ``pdns.validationstates.BogusNoRRSIG``
 210       - ``pdns.validationstates.BogusNoValidRRSIG``
 211       - ``pdns.validationstates.BogusMissingNegativeIndication``
 212       - ``pdns.validationstates.BogusSignatureNotYetValid``
 213       - ``pdns.validationstates.BogusSignatureExpired``
 214       - ``pdns.validationstates.BogusUnsupportedDNSKEYAlgo``
 215       - ``pdns.validationstates.BogusUnsupportedDSDigestType``
 216       - ``pdns.validationstates.BogusNoZoneKeyBitSet``
 217       - ``pdns.validationstates.BogusRevokedDNSKEY``
 218       - ``pdns.validationstates.BogusInvalidDNSKEYProtocol``
 219       - ``pdns.validationstates.Insecure``
 220       - ``pdns.validationstates.Secure``
 221
 222       The result will always be ``pdns.validationstates.Indeterminate`` is validation is disabled or was not requested.
 223       There is a convenience function named ``isValidationStateBogus`` that accepts such a state and return a boolean
 224       indicating whether this state is a Bogus one.
 225
 226   .. attribute:: DNSQuestion.logResponse
 227
 228       .. versionadded:: 4.2.0
 229
 230       Whether the response to this query will be exported to a remote protobuf logger, if one has been configured.
 231
 232   .. attribute:: DNSQuestion.tag
 233
 234       The packetcache tag set via :func:`gettag` or :func:`gettag_ffi`.
 235       Default tag is zero. Internally to the recursor, the tag is interpreted as an unsigned 32-bit integer.
 236
 237   .. attribute:: DNSQuestion.queryTime
 238
 239      .. versionadded:: 4.8.0
 240
 241      The time the query was received
 242
 243      .. attribute:: DNSQuestion.queryTime.tv_sec
 244
 245         The number of seconds since the Unix epoch.
 246
 247      .. attribute:: DNSQuestion.queryTime.tv_usec
 248
 249         The number of microseconds, to be added to the number of seconds in :attr:`DNSQuestion.queryTime.tv_sec` to get a high accuracy timestamp.
 250
 251   It also supports the following methods:
 252
 253   .. method:: DNSQuestion:addAnswer(type, content, [ttl, name])
 254
 255      Add an answer to the record of ``type`` with ``content``.
 256
 257      :param int type: The type of record to add, can be ``pdns.AAAA`` etc.
 258      :param str content: The content of the record, will be parsed into wireformat based on the ``type``
 259      :param int ttl: The TTL in seconds for this record, defaults to 3600
 260      :param DNSName name: The name of this record, defaults to :attr:`DNSQuestion.qname`
 261
 262   .. method:: DNSQuestion:addRecord(type, content, place, [ttl, name])
 263
 264      Add a record of ``type`` with ``content`` in section ``place``.
 265
 266      :param int type: The type of record to add, can be ``pdns.AAAA`` etc.
 267      :param str content: The content of the record, will be parsed into wireformat based on the ``type``
 268      :param int place: The section to place the record, see :attr:`DNSRecord.place`
 269      :param int ttl: The TTL in seconds for this record, defaults to 3600
 270      :param DNSName name: The name of this record, defaults to :attr:`DNSQuestion.qname`
 271
 272   .. method:: DNSQuestion:addPolicyTag(tag)
 273
 274      Add policyTag ``tag`` to the list of policyTags.
 275
 276      :param str tag: The tag to add
 277
 278   .. method:: DNSQuestion:getPolicyTags() -> {str}
 279
 280       Get the current policy tags as a table of strings.
 281
 282   .. method:: DNSQuestion:setPolicyTags(tags)
 283
 284       Set the policy tags to ``tags``, overwriting any existing policy tags.
 285
 286       :param {str} tags: The policy tags
 287
 288   .. method:: DNSQuestion:discardPolicy(policyname)
 289
 290      Skip the filtering policy (for example RPZ) named ``policyname`` for this query.
 291      This is mostly useful in the ``prerpz`` hook.
 292
 293      :param str policyname: The name of the policy to ignore.
 294
 295   .. method:: DNSQuestion:getDH() -> DNSHeader
 296
 297       Returns the :class:`DNSHeader` of the query or nil.
 298
 299   .. method:: DNSQuestion:getProxyProtocolValues() -> {ProxyProtocolValue}
 300
 301     .. versionadded:: 4.4.0
 302
 303       Get the Proxy Protocol Type-Length Values if any, as a table of  :class:`ProxyProtocolValue` objects.
 304
 305   .. method:: DNSQuestion:getRecords() -> {DNSRecord}
 306
 307       Get a table of DNS Records in this DNS Question (or answer by now).
 308
 309   .. method:: DNSQuestion:setRecords(records)
 310
 311       After your edits, update the answers of this question
 312
 313       :param {DNSRecord} records: The records to put in the packet
 314
 315   .. method:: DNSQuestion:getEDNSFlag(name) -> bool
 316
 317       Returns true if the EDNS flag with ``name`` is set in the query.
 318
 319       :param string name: Name of the flag.
 320
 321   .. method:: DNSQuestion:getEDNSFlags() -> {str}
 322
 323       Returns a list of strings with all the EDNS flag mnemonics in the query.
 324
 325   .. method:: DNSQuestion:getEDNSOption(num) -> str
 326
 327       Get the EDNS Option with number ``num`` as a bytestring.
 328
 329   .. method:: DNSQuestion:getEDNSOptions() -> {str: str}
 330
 331       Get a map of all EDNS Options
 332
 333   .. method:: DNSQuestion:getEDNSSubnet() -> Netmask
 334
 335       Returns the :class:`Netmask` specified in the EDNSSubnet option, or empty if there was none.
 336
 337 DNSHeader Object
 338 ================
 339
 340 The DNS header as returned by :meth:`DNSQuestion:getDH()` represents a header of a DNS message.
 341
 342 .. class:: DNSHeader
 343
 344     represents a header of a DNS message.
 345
 346   .. method:: DNSHeader:getRD() -> bool
 347
 348       The value of the Recursion Desired bit.
 349
 350   .. method:: DNSHeader:getAA() -> bool
 351
 352       The value of the Authoritative Answer bit.
 353
 354   .. method:: DNSHeader:getAD() -> bool
 355
 356       The value of the Authenticated Data bit.
 357
 358   .. method:: DNSHeader:getCD() -> bool
 359
 360       The value of the Checking Disabled bit.
 361
 362   .. method:: DNSHeader:getTC() -> bool
 363
 364       The value of the Truncation bit.
 365
 366   .. method:: DNSHeader:getRCODE() -> int
 367
 368       The Response Code of the query
 369
 370   .. method:: DNSHeader:getOPCODE() -> int
 371
 372       The Operation Code of the query
 373
 374   .. method:: DNSHeader:getID() -> int
 375
 376       The ID of the query
 377
 378 DNSRecord Object
 379 ================
 380
 381 See :doc:`DNSRecord <dnsrecord>`.
 382
 383 The EDNSOptionView Class
 384 ========================
 385
 386 .. class:: EDNSOptionView
 387
 388   An object that represents the values of a single EDNS option
 389
 390   .. method:: EDNSOptionView:count()
 391      .. versionadded:: 4.2.0
 392
 393     The number of values for this EDNS option.
 394
 395   .. method:: EDNSOptionView:getValues()
 396      .. versionadded:: 4.2.0
 397
 398     Return a table of NULL-safe strings values for this EDNS option.
 399
 400   .. attribute:: EDNSOptionView.size
 401
 402     The size in bytes of the first value of this EDNS option.
 403
 404   .. method:: EDNSOptionView:getContent()
 405
 406     Returns a NULL-safe string object of the first value of this EDNS option.
 407
 408 The ProxyProtocolValue Class
 409 ============================
 410
 411 .. class:: ProxyProtocolValue
 412
 413   .. versionadded:: 4.4.0
 414
 415   An object that represents the value of a Proxy Protocol Type-Length Value
 416
 417   .. method:: ProxyProtocolValue:getContent() -> str
 418
 419     Returns a NULL-safe string object.
 420
 421   .. method:: ProxyProtocolValue:getType() -> int
 422
 423     Returns the type of this value.