3 The DNSQuestion (``dq``) object
4 ===============================
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.
10 .. class:: DNSQuestion
12 The DNSQuestion object has several attributes, many of them read-only:
14 .. attribute:: DNSQuestion.dh
16 The :ref:`DNSHeader` of this query.
18 .. attribute:: DNSQuestion.ecsOverride
20 Whether an existing ECS value should be overridden, settable.
22 .. attribute:: DNSQuestion.ecsPrefixLength
24 The ECS prefix length to use, settable.
26 .. attribute:: DNSQuestion.len
28 The length of the data starting at :attr:`DNSQuestion.dh`, including any trailing bytes following the DNS message.
30 .. attribute:: DNSQuestion.localaddr
32 :ref:`ComboAddress` of the local bind this question was received on.
34 .. attribute:: DNSQuestion.opcode
36 Integer describing the OPCODE of the packet. Can be matched against :ref:`DNSOpcode`.
38 .. attribute:: DNSQuestion.qclass
40 QClass (as an unsigned integer) of this question.
41 Can be compared against :ref:`DNSQClass`.
43 .. attribute:: DNSQuestion.qname
45 :class:`DNSName` of this question.
47 .. attribute:: DNSQuestion.qtype
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``.
52 .. attribute:: DNSQuestion.remoteaddr
54 :ref:`ComboAddress` of the remote client.
56 .. attribute:: DNSQuestion.rcode
58 RCode (as an unsigned integer) of this question.
59 Can be compared against :ref:`DNSRCode`
61 .. attribute:: DNSQuestion.size
63 The total size of the buffer starting at :attr:`DNSQuestion.dh`.
65 .. attribute:: DNSQuestion.skipCache
67 Whether to skip cache lookup / storing the answer for this question, settable.
69 .. attribute:: DNSQuestion.tcp
71 Whether the query was received over TCP.
73 .. attribute:: DNSQuestion.useECS
75 Whether to send ECS to the backend, settable.
77 It also supports the following methods:
79 .. method:: DNSQuestion:getDO() -> bool
81 .. versionadded:: 1.2.0
83 Get the value of the DNSSEC OK bit.
85 :returns: true if the DO bit was set, false otherwise
87 .. method:: DNSQuestion:getEDNSOptions() -> table
89 .. versionadded:: 1.3.3
91 Return the list of EDNS Options, if any.
93 :returns: A table of EDNSOptionView objects, indexed on the ECS Option code
95 .. method:: DNSQuestion:getTag(key) -> string
97 .. versionadded:: 1.2.0
99 Get the value of a tag stored into the DNSQuestion object.
101 :param string key: The tag's key
102 :returns: The tag's value if it was set, an empty string otherwise
104 .. method:: DNSQuestion:getTagArray() -> table
106 .. versionadded:: 1.2.0
108 Get all the tags stored into the DNSQuestion object.
110 :returns: A table of tags, using strings as keys and values
112 .. method:: DNSQuestion:getTrailingData() -> string
114 .. versionadded:: 1.4.0
116 Get all data following the DNS message.
118 :returns: The trailing data as a null-safe string
120 .. method:: DNSQuestion:sendTrap(reason)
122 .. versionadded:: 1.2.0
126 :param string reason: An optional string describing the reason why this trap was sent
128 .. method:: DNSQuestion:setTag(key, value)
130 .. versionadded:: 1.2.0
132 Set a tag into the DNSQuestion object.
134 :param string key: The tag's key
135 :param string value: The tag's value
137 .. method:: DNSQuestion:setTagArray(tags)
139 .. versionadded:: 1.2.0
141 Set an array of tags into the DNSQuestion object.
143 :param table tags: A table of tags, using strings as keys and values
145 .. method:: DNSQuestion:setTrailingData(tail) -> bool
147 .. versionadded:: 1.4.0
149 Set the data following the DNS message, overwriting anything already present.
151 :param string tail: The new data
152 :returns: true if the operation succeeded, false otherwise
159 .. class:: DNSResponse
161 This object has all the functions and members of a :ref:`DNSQuestion <DNSQuestion>` and some more
163 .. method:: DNSResponse:editTTLs(func)
165 The function ``func`` is invoked for every entry in the answer, authority and additional section.
167 ``func`` points to a function with the following prototype: ``myFunc(section, qclass, qtype, ttl)``
169 All parameters to ``func`` are integers:
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
176 This function must return an integer with the new TTL.
177 Setting this TTL to 0 to leaves it unchanged
179 :param string func: The function to call to edit TTLs.
183 DNSHeader (``dh``) object
184 =========================
188 This object holds a representation of a DNS packet's header.
190 .. method:: DNSHeader:getRD() -> bool
192 Get recursion desired flag.
194 .. method:: DNSHeader:setRD(rd)
196 Set recursion desired flag.
198 :param bool rd: State of the RD flag
200 .. method:: DNSHeader:setTC(tc)
202 Set truncation flag (TC).
204 :param bool tc: State of the TC flag
206 .. method:: DNSHeader:setQR(qr)
208 Set Query/Response flag.
209 Setting QR to true means "This is an answer packet".
211 :param bool qr: State of the QR flag
213 .. method:: DNSHeader:getCD() -> bool
215 Get checking disabled flag.
217 .. method:: DNSHeader:setCD(cd)
219 Set checking disabled flag.
221 :param bool cd: State of the CD flag
225 EDNSOptionView object
226 =====================
228 .. class:: EDNSOptionView
230 .. versionadded:: 1.3.3
232 An object that represents the values of a single EDNS option received in a query.
234 .. method:: EDNSOptionView:count()
236 The number of values for this EDNS option.
238 .. method:: EDNSOptionView:getValues()
240 Return a table of NULL-safe strings values for this EDNS option.