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
 185     :param int status: The HTTP status code to return
 186     :param string body: The body of the HTTP response, or a URL if the status code is a redirect (3xx)
 187     :param string contentType: The HTTP Content-Type header to return for a 200 response, ignored otherwise. Default is ''application/dns-message''.
 188
 189   .. method:: DNSQuestion:setTag(key, value)
 190
 191     .. versionadded:: 1.2.0
 192
 193     Set a tag into the DNSQuestion object.
 194
 195     :param string key: The tag's key
 196     :param string value: The tag's value
 197
 198   .. method:: DNSQuestion:setTagArray(tags)
 199
 200     .. versionadded:: 1.2.0
 201
 202     Set an array of tags into the DNSQuestion object.
 203
 204     :param table tags: A table of tags, using strings as keys and values
 205
 206   .. method:: DNSQuestion:setTrailingData(tail) -> bool
 207
 208     .. versionadded:: 1.4.0
 209
 210     Set the data following the DNS message, overwriting anything already present.
 211
 212     :param string tail: The new data
 213     :returns: true if the operation succeeded, false otherwise
 214
 215 .. _DNSResponse:
 216
 217 DNSResponse object
 218 ==================
 219
 220 .. class:: DNSResponse
 221
 222   This object has all the functions and members of a :ref:`DNSQuestion <DNSQuestion>` and some more
 223
 224   .. method:: DNSResponse:editTTLs(func)
 225
 226     The function ``func`` is invoked for every entry in the answer, authority and additional section.
 227
 228     ``func`` points to a function with the following prototype: ``myFunc(section, qclass, qtype, ttl)``
 229
 230     All parameters to ``func`` are integers:
 231
 232     - ``section`` is the section in the packet and can be compared to :ref:`DNSSection`
 233     - ``qclass`` is the QClass of the record. Can be compared to :ref:`DNSClass`
 234     - ``qtype`` is the QType of the record. Can be e.g. compared to ``DNSQType.A``, ``DNSQType.AAAA`` :ref:`constants <DNSQType>` and the like.
 235     - ``ttl`` is the current TTL
 236
 237     This function must return an integer with the new TTL.
 238     Setting this TTL to 0 to leaves it unchanged
 239
 240     :param string func: The function to call to edit TTLs.
 241
 242 .. _DNSHeader:
 243
 244 DNSHeader (``dh``) object
 245 =========================
 246
 247 .. class:: DNSHeader
 248
 249   This object holds a representation of a DNS packet's header.
 250
 251   .. method:: DNSHeader:getRD() -> bool
 252
 253     Get recursion desired flag.
 254
 255   .. method:: DNSHeader:setRD(rd)
 256
 257     Set recursion desired flag.
 258
 259     :param bool rd: State of the RD flag
 260
 261   .. method:: DNSHeader:setTC(tc)
 262
 263     Set truncation flag (TC).
 264
 265     :param bool tc: State of the TC flag
 266
 267   .. method:: DNSHeader:setQR(qr)
 268
 269     Set Query/Response flag.
 270     Setting QR to true means "This is an answer packet".
 271
 272     :param bool qr: State of the QR flag
 273
 274   .. method:: DNSHeader:getCD() -> bool
 275
 276     Get checking disabled flag.
 277
 278   .. method:: DNSHeader:setCD(cd)
 279
 280     Set checking disabled flag.
 281
 282     :param bool cd: State of the CD flag
 283
 284 .. _EDNSOptionView:
 285
 286 EDNSOptionView object
 287 =====================
 288
 289 .. class:: EDNSOptionView
 290
 291   .. versionadded:: 1.3.3
 292
 293   An object that represents the values of a single EDNS option received in a query.
 294
 295   .. method:: EDNSOptionView:count()
 296
 297     The number of values for this EDNS option.
 298
 299   .. method:: EDNSOptionView:getValues()
 300
 301     Return a table of NULL-safe strings values for this EDNS option.