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:`DNSClass`.
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:getHTTPHeaders() -> table
97 .. versionadded:: 1.4.0
99 Return the HTTP headers for a DoH query, as a table whose keys are the header names and values the header values.
101 :returns: A table of HTTP headers
103 .. method:: DNSQuestion:getHTTPHost() -> string
105 .. versionadded:: 1.4.0
107 Return the HTTP Host for a DoH query, which may or may not contain the port.
109 :returns: The host of the DoH query
111 .. method:: DNSQuestion:getHTTPPath() -> string
113 .. versionadded:: 1.4.0
115 Return the HTTP path for a DoH query.
117 :returns: The path part of the DoH query URI
119 .. method:: DNSQuestion:getHTTPQueryString() -> string
121 .. versionadded:: 1.4.0
123 Return the HTTP query string for a DoH query.
125 :returns: The query string part of the DoH query URI
127 .. method:: DNSQuestion:getHTTPScheme() -> string
129 .. versionadded:: 1.4.0
131 Return the HTTP scheme for a DoH query.
133 :returns: The scheme of the DoH query, for example ''http'' or ''https''
135 .. method:: DNSQuestion:getServerNameIndication() -> string
137 .. versionadded:: 1.4.0
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.
142 :returns: A string containing the TLS SNI value, if any
144 .. method:: DNSQuestion:getTag(key) -> string
146 .. versionadded:: 1.2.0
148 Get the value of a tag stored into the DNSQuestion object.
150 :param string key: The tag's key
151 :returns: The tag's value if it was set, an empty string otherwise
153 .. method:: DNSQuestion:getTagArray() -> table
155 .. versionadded:: 1.2.0
157 Get all the tags stored into the DNSQuestion object.
159 :returns: A table of tags, using strings as keys and values
161 .. method:: DNSQuestion:getTrailingData() -> string
163 .. versionadded:: 1.4.0
165 Get all data following the DNS message.
167 :returns: The trailing data as a null-safe string
169 .. method:: DNSQuestion:sendTrap(reason)
171 .. versionadded:: 1.2.0
175 :param string reason: An optional string describing the reason why this trap was sent
177 .. method:: DNSQuestion:setHTTPResponse(status, body, contentType="")
179 .. versionadded:: 1.4.0
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 In order for the response to be sent, the QR bit should be set before returning and the function should return Action.HeaderModify.
186 :param int status: The HTTP status code to return
187 :param string body: The body of the HTTP response, or a URL if the status code is a redirect (3xx)
188 :param string contentType: The HTTP Content-Type header to return for a 200 response, ignored otherwise. Default is ''application/dns-message''.
190 .. method:: DNSQuestion:setTag(key, value)
192 .. versionadded:: 1.2.0
194 Set a tag into the DNSQuestion object.
196 :param string key: The tag's key
197 :param string value: The tag's value
199 .. method:: DNSQuestion:setTagArray(tags)
201 .. versionadded:: 1.2.0
203 Set an array of tags into the DNSQuestion object.
205 :param table tags: A table of tags, using strings as keys and values
207 .. method:: DNSQuestion:setTrailingData(tail) -> bool
209 .. versionadded:: 1.4.0
211 Set the data following the DNS message, overwriting anything already present.
213 :param string tail: The new data
214 :returns: true if the operation succeeded, false otherwise
221 .. class:: DNSResponse
223 This object has all the functions and members of a :ref:`DNSQuestion <DNSQuestion>` and some more
225 .. method:: DNSResponse:editTTLs(func)
227 The function ``func`` is invoked for every entry in the answer, authority and additional section.
229 ``func`` points to a function with the following prototype: ``myFunc(section, qclass, qtype, ttl)``
231 All parameters to ``func`` are integers:
233 - ``section`` is the section in the packet and can be compared to :ref:`DNSSection`
234 - ``qclass`` is the QClass of the record. Can be compared to :ref:`DNSClass`
235 - ``qtype`` is the QType of the record. Can be e.g. compared to ``DNSQType.A``, ``DNSQType.AAAA`` :ref:`constants <DNSQType>` and the like.
236 - ``ttl`` is the current TTL
238 This function must return an integer with the new TTL.
239 Setting this TTL to 0 to leaves it unchanged
241 :param string func: The function to call to edit TTLs.
245 DNSHeader (``dh``) object
246 =========================
250 This object holds a representation of a DNS packet's header.
252 .. method:: DNSHeader:getRD() -> bool
254 Get recursion desired flag.
256 .. method:: DNSHeader:setRD(rd)
258 Set recursion desired flag.
260 :param bool rd: State of the RD flag
262 .. method:: DNSHeader:setTC(tc)
264 Set truncation flag (TC).
266 :param bool tc: State of the TC flag
268 .. method:: DNSHeader:setQR(qr)
270 Set Query/Response flag.
271 Setting QR to true means "This is an answer packet".
273 :param bool qr: State of the QR flag
275 .. method:: DNSHeader:getCD() -> bool
277 Get checking disabled flag.
279 .. method:: DNSHeader:setCD(cd)
281 Set checking disabled flag.
283 :param bool cd: State of the CD flag
287 EDNSOptionView object
288 =====================
290 .. class:: EDNSOptionView
292 .. versionadded:: 1.3.3
294 An object that represents the values of a single EDNS option received in a query.
296 .. method:: EDNSOptionView:count()
298 The number of values for this EDNS option.
300 .. method:: EDNSOptionView:getValues()
302 Return a table of NULL-safe strings values for this EDNS option.