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