pdns/dnsdistdist/docs/reference/dq.rst

   1 .. _DNSQuestion:
   2
   3 The DNSQuestion (``dq``) object
   4 ===============================
   5
   6 A DNSQuestion or ``dq`` object is available in several hooks and Lua actions.
   7 This object contains details about the current state of the question.
   8 This state can be modified from the various hooks.
   9
  10 .. class:: DNSQuestion
  11
  12   The DNSQuestion object has several attributes, many of them read-only:
  13
  14   .. attribute:: DNSQuestion.dh
  15
  16     The :ref:`DNSHeader` of this query.
  17
  18   .. attribute:: DNSQuestion.ecsOverride
  19
  20     Whether an existing ECS value should be overridden, settable.
  21
  22   .. attribute:: DNSQuestion.ecsPrefixLength
  23
  24      The ECS prefix length to use, settable.
  25
  26   .. attribute:: DNSQuestion.len
  27
  28     The length of the data starting at :attr:`DNSQuestion.dh`, including any trailing bytes following the DNS message.
  29
  30   .. attribute:: DNSQuestion.localaddr
  31
  32     :ref:`ComboAddress` of the local bind this question was received on.
  33
  34   .. attribute:: DNSQuestion.opcode
  35
  36     Integer describing the OPCODE of the packet. Can be matched against :ref:`DNSOpcode`.
  37
  38   .. attribute:: DNSQuestion.qclass
  39
  40     QClass (as an unsigned integer) of this question.
  41     Can be compared against :ref:`DNSClass`.
  42
  43   .. attribute:: DNSQuestion.qname
  44
  45     :class:`DNSName` of this question.
  46
  47   .. attribute:: DNSQuestion.qtype
  48
  49     QType (as an unsigned integer) of this question.
  50     Can be compared against the pre-defined :ref:`constants <DNSQType>` like ``DNSQType.A``, DNSQType.AAAA``.
  51
  52   .. attribute:: DNSQuestion.remoteaddr
  53
  54     :ref:`ComboAddress` of the remote client.
  55
  56   .. attribute:: DNSQuestion.rcode
  57
  58     RCode (as an unsigned integer) of this question.
  59     Can be compared against :ref:`DNSRCode`
  60
  61   .. attribute:: DNSQuestion.size
  62
  63     The total size of the buffer starting at :attr:`DNSQuestion.dh`.
  64
  65   .. attribute:: DNSQuestion.skipCache
  66
  67     Whether to skip cache lookup / storing the answer for this question, settable.
  68
  69   .. attribute:: DNSQuestion.tcp
  70
  71     Whether the query was received over TCP.
  72
  73   .. attribute:: DNSQuestion.useECS
  74
  75     Whether to send ECS to the backend, settable.
  76
  77   It also supports the following methods:
  78
  79   .. method:: DNSQuestion:getDO() -> bool
  80
  81     .. versionadded:: 1.2.0
  82
  83     Get the value of the DNSSEC OK bit.
  84
  85     :returns: true if the DO bit was set, false otherwise
  86
  87   .. method:: DNSQuestion:getEDNSOptions() -> table
  88
  89     .. versionadded:: 1.3.3
  90
  91     Return the list of EDNS Options, if any.
  92
  93     :returns: A table of EDNSOptionView objects, indexed on the ECS Option code
  94
  95   .. method:: DNSQuestion:getHTTPHeaders() -> table
  96
  97     .. versionadded:: 1.4.0
  98
  99     Return the HTTP headers for a DoH query, as a table whose keys are the header names and values the header values.
 100
 101     :returns: A table of HTTP headers
 102
 103   .. method:: DNSQuestion:getHTTPHost() -> string
 104
 105     .. versionadded:: 1.4.0
 106
 107     Return the HTTP Host for a DoH query, which may or may not contain the port.
 108
 109     :returns: The host of the DoH query
 110
 111   .. method:: DNSQuestion:getHTTPPath() -> string
 112
 113     .. versionadded:: 1.4.0
 114
 115     Return the HTTP path for a DoH query.
 116
 117     :returns: The path part of the DoH query URI
 118
 119   .. method:: DNSQuestion:getHTTPQueryString() -> string
 120
 121     .. versionadded:: 1.4.0
 122
 123     Return the HTTP query string for a DoH query.
 124
 125     :returns: The query string part of the DoH query URI
 126
 127   .. method:: DNSQuestion:getHTTPScheme() -> string
 128
 129     .. versionadded:: 1.4.0
 130
 131     Return the HTTP scheme for a DoH query.
 132
 133     :returns: The scheme of the DoH query, for example ''http'' or ''https''
 134
 135   .. method:: DNSQuestion:getServerNameIndication() -> string
 136
 137     .. versionadded:: 1.4.0
 138
 139     Return the TLS Server Name Indication (SNI) value sent by the client over DoT or DoH, if any. See :func:`SNIRule`
 140     for more information, especially about the availability of SNI over DoH.
 141
 142     :returns: A string containing the TLS SNI value, if any
 143
 144   .. method:: DNSQuestion:getTag(key) -> string
 145
 146     .. versionadded:: 1.2.0
 147
 148     Get the value of a tag stored into the DNSQuestion object.
 149
 150     :param string key: The tag's key
 151     :returns: The tag's value if it was set, an empty string otherwise
 152
 153   .. method:: DNSQuestion:getTagArray() -> table
 154
 155     .. versionadded:: 1.2.0
 156
 157     Get all the tags stored into the DNSQuestion object.
 158
 159     :returns: A table of tags, using strings as keys and values
 160
 161   .. method:: DNSQuestion:getTrailingData() -> string
 162
 163     .. versionadded:: 1.4.0
 164
 165     Get all data following the DNS message.
 166
 167     :returns: The trailing data as a null-safe string
 168
 169   .. method:: DNSQuestion:sendTrap(reason)
 170
 171     .. versionadded:: 1.2.0
 172
 173     Send an SNMP trap.
 174
 175     :param string reason: An optional string describing the reason why this trap was sent
 176
 177   .. method:: DNSQuestion:setHTTPResponse(status, body, contentType="")
 178
 179     .. versionadded:: 1.4.0
 180
 181     Set the HTTP status code and content to immediately send back to the client.
 182     For HTTP redirects (3xx), the string supplied in ''body'' should be the URL to redirect to.
 183     For 200 responses, the value of the content type header can be specified via the ''contentType'' parameter.
 184     In order for the response to be sent, the QR bit should be set before returning and the function should return Action.HeaderModify.
 185
 186     :param int status: The HTTP status code to return
 187     :param string body: The body of the HTTP response, or a URL if the status code is a redirect (3xx)
 188     :param string contentType: The HTTP Content-Type header to return for a 200 response, ignored otherwise. Default is ''application/dns-message''.
 189
 190   .. method:: DNSQuestion:setNegativeAndAdditionalSOA(nxd, zone, ttl, mname, rname, serial, refresh, retry, expire, minimum)
 191
 192     .. versionadded:: 1.5.0
 193
 194     Turn a question into a response, either a NXDOMAIN or a NODATA one based on ''nxd'', setting the QR bit to 1 and adding a SOA record in the additional section.
 195
 196     :param bool nxd: Whether the answer is a NXDOMAIN (true) or a NODATA (false)
 197     :param string zone: The owner name for the SOA record
 198     :param int ttl: The TTL of the SOA record
 199     :param string mname: The mname of the SOA record
 200     :param string rname: The rname of the SOA record
 201     :param int serial: The value of the serial field in the SOA record
 202     :param int refresh: The value of the refresh field in the SOA record
 203     :param int retry: The value of the retry field in the SOA record
 204     :param int expire: The value of the expire field in the SOA record
 205     :param int minimum: The value of the minimum field in the SOA record
 206
 207   .. method:: DNSQuestion:setTag(key, value)
 208
 209     .. versionadded:: 1.2.0
 210
 211     Set a tag into the DNSQuestion object.
 212
 213     :param string key: The tag's key
 214     :param string value: The tag's value
 215
 216   .. method:: DNSQuestion:setTagArray(tags)
 217
 218     .. versionadded:: 1.2.0
 219
 220     Set an array of tags into the DNSQuestion object.
 221
 222     :param table tags: A table of tags, using strings as keys and values
 223
 224   .. method:: DNSQuestion:setTrailingData(tail) -> bool
 225
 226     .. versionadded:: 1.4.0
 227
 228     Set the data following the DNS message, overwriting anything already present.
 229
 230     :param string tail: The new data
 231     :returns: true if the operation succeeded, false otherwise
 232
 233 .. _DNSResponse:
 234
 235 DNSResponse object
 236 ==================
 237
 238 .. class:: DNSResponse
 239
 240   This object has all the functions and members of a :ref:`DNSQuestion <DNSQuestion>` and some more
 241
 242   .. method:: DNSResponse:editTTLs(func)
 243
 244     The function ``func`` is invoked for every entry in the answer, authority and additional section.
 245
 246     ``func`` points to a function with the following prototype: ``myFunc(section, qclass, qtype, ttl)``
 247
 248     All parameters to ``func`` are integers:
 249
 250     - ``section`` is the section in the packet and can be compared to :ref:`DNSSection`
 251     - ``qclass`` is the QClass of the record. Can be compared to :ref:`DNSClass`
 252     - ``qtype`` is the QType of the record. Can be e.g. compared to ``DNSQType.A``, ``DNSQType.AAAA`` :ref:`constants <DNSQType>` and the like.
 253     - ``ttl`` is the current TTL
 254
 255     This function must return an integer with the new TTL.
 256     Setting this TTL to 0 to leaves it unchanged
 257
 258     :param string func: The function to call to edit TTLs.
 259
 260 .. _DNSHeader:
 261
 262 DNSHeader (``dh``) object
 263 =========================
 264
 265 .. class:: DNSHeader
 266
 267   This object holds a representation of a DNS packet's header.
 268
 269   .. method:: DNSHeader:getRD() -> bool
 270
 271     Get recursion desired flag.
 272
 273   .. method:: DNSHeader:setRD(rd)
 274
 275     Set recursion desired flag.
 276
 277     :param bool rd: State of the RD flag
 278
 279   .. method:: DNSHeader:setTC(tc)
 280
 281     Set truncation flag (TC).
 282
 283     :param bool tc: State of the TC flag
 284
 285   .. method:: DNSHeader:setQR(qr)
 286
 287     Set Query/Response flag.
 288     Setting QR to true means "This is an answer packet".
 289
 290     :param bool qr: State of the QR flag
 291
 292   .. method:: DNSHeader:getCD() -> bool
 293
 294     Get checking disabled flag.
 295
 296   .. method:: DNSHeader:setCD(cd)
 297
 298     Set checking disabled flag.
 299
 300     :param bool cd: State of the CD flag
 301
 302 .. _EDNSOptionView:
 303
 304 EDNSOptionView object
 305 =====================
 306
 307 .. class:: EDNSOptionView
 308
 309   .. versionadded:: 1.3.3
 310
 311   An object that represents the values of a single EDNS option received in a query.
 312
 313   .. method:: EDNSOptionView:count()
 314
 315     The number of values for this EDNS option.
 316
 317   .. method:: EDNSOptionView:getValues()
 318
 319     Return a table of NULL-safe strings values for this EDNS option.