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:getServerNameIndication() -> string
  96
  97     .. versionadded:: 1.4.0
  98
  99     Return the TLS Server Name Indication (SNI) value sent by the client over DoT or DoH, if any. See :func:`SNIRule`
 100     for more information, especially about the availability of SNI over DoH.
 101
 102     :returns: A string containing the TLS SNI value, if any
 103
 104   .. method:: DNSQuestion:getTag(key) -> string
 105
 106     .. versionadded:: 1.2.0
 107
 108     Get the value of a tag stored into the DNSQuestion object.
 109
 110     :param string key: The tag's key
 111     :returns: The tag's value if it was set, an empty string otherwise
 112
 113   .. method:: DNSQuestion:getTagArray() -> table
 114
 115     .. versionadded:: 1.2.0
 116
 117     Get all the tags stored into the DNSQuestion object.
 118
 119     :returns: A table of tags, using strings as keys and values
 120
 121   .. method:: DNSQuestion:getTrailingData() -> string
 122
 123     .. versionadded:: 1.4.0
 124
 125     Get all data following the DNS message.
 126
 127     :returns: The trailing data as a null-safe string
 128
 129   .. method:: DNSQuestion:sendTrap(reason)
 130
 131     .. versionadded:: 1.2.0
 132
 133     Send an SNMP trap.
 134
 135     :param string reason: An optional string describing the reason why this trap was sent
 136
 137   .. method:: DNSQuestion:setTag(key, value)
 138
 139     .. versionadded:: 1.2.0
 140
 141     Set a tag into the DNSQuestion object.
 142
 143     :param string key: The tag's key
 144     :param string value: The tag's value
 145
 146   .. method:: DNSQuestion:setTagArray(tags)
 147
 148     .. versionadded:: 1.2.0
 149
 150     Set an array of tags into the DNSQuestion object.
 151
 152     :param table tags: A table of tags, using strings as keys and values
 153
 154   .. method:: DNSQuestion:setTrailingData(tail) -> bool
 155
 156     .. versionadded:: 1.4.0
 157
 158     Set the data following the DNS message, overwriting anything already present.
 159
 160     :param string tail: The new data
 161     :returns: true if the operation succeeded, false otherwise
 162
 163 .. _DNSResponse:
 164
 165 DNSResponse object
 166 ==================
 167
 168 .. class:: DNSResponse
 169
 170   This object has all the functions and members of a :ref:`DNSQuestion <DNSQuestion>` and some more
 171
 172   .. method:: DNSResponse:editTTLs(func)
 173
 174     The function ``func`` is invoked for every entry in the answer, authority and additional section.
 175
 176     ``func`` points to a function with the following prototype: ``myFunc(section, qclass, qtype, ttl)``
 177
 178     All parameters to ``func`` are integers:
 179
 180     - ``section`` is the section in the packet and can be compared to :ref:`DNSSection`
 181     - ``qclass`` is the QClass of the record. Can be compared to :ref:`DNSClass`
 182     - ``qtype`` is the QType of the record. Can be e.g. compared to ``DNSQType.A``, ``DNSQType.AAAA`` :ref:`constants <DNSQType>` and the like.
 183     - ``ttl`` is the current TTL
 184
 185     This function must return an integer with the new TTL.
 186     Setting this TTL to 0 to leaves it unchanged
 187
 188     :param string func: The function to call to edit TTLs.
 189
 190 .. _DNSHeader:
 191
 192 DNSHeader (``dh``) object
 193 =========================
 194
 195 .. class:: DNSHeader
 196
 197   This object holds a representation of a DNS packet's header.
 198
 199   .. method:: DNSHeader:getRD() -> bool
 200
 201     Get recursion desired flag.
 202
 203   .. method:: DNSHeader:setRD(rd)
 204
 205     Set recursion desired flag.
 206
 207     :param bool rd: State of the RD flag
 208
 209   .. method:: DNSHeader:setTC(tc)
 210
 211     Set truncation flag (TC).
 212
 213     :param bool tc: State of the TC flag
 214
 215   .. method:: DNSHeader:setQR(qr)
 216
 217     Set Query/Response flag.
 218     Setting QR to true means "This is an answer packet".
 219
 220     :param bool qr: State of the QR flag
 221
 222   .. method:: DNSHeader:getCD() -> bool
 223
 224     Get checking disabled flag.
 225
 226   .. method:: DNSHeader:setCD(cd)
 227
 228     Set checking disabled flag.
 229
 230     :param bool cd: State of the CD flag
 231
 232 .. _EDNSOptionView:
 233
 234 EDNSOptionView object
 235 =====================
 236
 237 .. class:: EDNSOptionView
 238
 239   .. versionadded:: 1.3.3
 240
 241   An object that represents the values of a single EDNS option received in a query.
 242
 243   .. method:: EDNSOptionView:count()
 244
 245     The number of values for this EDNS option.
 246
 247   .. method:: EDNSOptionView:getValues()
 248
 249     Return a table of NULL-safe strings values for this EDNS option.