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