]>
Commit | Line | Data |
---|---|---|
223bb49e PL |
1 | The DNSQuestion (``dq``) object |
2 | =============================== | |
3 | Apart from the :func:`ipfilter`-function, all functions work on a ``dq`` (DNSQuestion) object. | |
4 | This object contains details about the current state of the question. | |
5 | This state can be modified from the various hooks. | |
6 | ||
7 | The DNSQuestion object contains at least the following fields: | |
8 | ||
9 | .. class:: DNSQuestion | |
10 | ||
54c79a88 PL |
11 | An object that contains everything about the current query. |
12 | This object has the following attributes: | |
223bb49e | 13 | |
f055bd07 RG |
14 | .. attribute:: DNSQuestion.addPaddingToResponse |
15 | ||
16 | .. versionadded:: 4.5.0 | |
17 | ||
18 | Whether the response will get EDNS Padding. See :ref:`setting-edns-padding-from` and :ref:`setting-edns-padding-mode`. | |
19 | ||
af231ceb RG |
20 | .. attribute:: DNSQuestion.extendedErrorCode |
21 | ||
22 | .. versionadded:: 4.5.0 | |
23 | ||
0cb1d590 | 24 | The extended error code, if any. See :ref:`setting-extended-resolution-errors`. |
af231ceb RG |
25 | |
26 | .. attribute:: DNSQuestion.extendedErrorExtra | |
27 | ||
28 | .. versionadded:: 4.5.0 | |
29 | ||
0cb1d590 | 30 | The extended error extra text, as a string, if any. See :ref:`setting-extended-resolution-errors`. |
af231ceb RG |
31 | |
32 | .. attribute:: DNSQuestion.qname | |
33 | ||
34 | :class:`DNSName` of the name this query is for. | |
35 | ||
54c79a88 | 36 | .. attribute:: DNSQuestion.qtype |
223bb49e | 37 | |
54c79a88 | 38 | Type this query is for as an integer, can be compared against ``pdns.A``, ``pdns.AAAA``. |
223bb49e | 39 | |
54c79a88 | 40 | .. attribute:: DNSQuestion.rcode |
223bb49e | 41 | |
9e441100 | 42 | current DNS Result Code, which can be overridden, including to several magical values. |
bcea3520 | 43 | Before 4.4.0, the rcode can be set to ``pdns.DROP`` to drop the query, for later versions refer to :ref:`hook-semantics`. |
54c79a88 | 44 | Other statuses are normal DNS return codes, like ``pdns.NOERROR``, ``pdns.NXDOMAIN`` etc. |
223bb49e | 45 | |
54c79a88 | 46 | .. attribute:: DNSQuestion.isTcp |
223bb49e | 47 | |
c7349b0e | 48 | Whether the query was received over TCP. |
223bb49e | 49 | |
54c79a88 | 50 | .. attribute:: DNSQuestion.remoteaddr |
223bb49e | 51 | |
54c79a88 | 52 | :class:`ComboAddress` of the requestor. |
ad6f25d5 | 53 | If the proxy protocol is used, this will contain the source address from the proxy protocol header. |
223bb49e | 54 | |
54c79a88 | 55 | .. attribute:: DNSQuestion.localaddr |
223bb49e | 56 | |
54c79a88 | 57 | :class:`ComboAddress` where this query was received on. |
ad6f25d5 OM |
58 | If the proxy protocol is used, this will contain the destination address from the proxy protocol header. |
59 | ||
5e100a4c | 60 | .. attribute:: DNSQuestion.interface_remoteaddr |
ad6f25d5 | 61 | |
8691ee2c | 62 | Source :class:`ComboAddress` of the packet received by the recursor. If the proxy protocol is not used, the value will match ``remoteaddr``. |
ad6f25d5 | 63 | |
5e100a4c | 64 | .. attribute:: DNSQuestion.interface_localaddr |
ad6f25d5 | 65 | |
8691ee2c | 66 | Destination :class:`ComboAddress` of the packet received by the recursor. If the proxy protocol is not used, the value will match ``localaddr``. |
223bb49e | 67 | |
54c79a88 | 68 | .. attribute:: DNSQuestion.variable |
223bb49e | 69 | |
54c79a88 PL |
70 | Boolean which, if set, indicates the recursor should not packet cache this answer. |
71 | Honored even when returning false from a hook! | |
72 | Important when providing answers that vary over time or based on sender details. | |
223bb49e | 73 | |
54c79a88 | 74 | .. attribute:: DNSQuestion.followupFunction |
223bb49e | 75 | |
54c79a88 | 76 | String that signals the nameserver to take one an additional action: |
223bb49e | 77 | |
54c79a88 PL |
78 | - followCNAMERecords: When adding a CNAME to the answer, this tells the recursor to follow that CNAME. See :ref:`CNAME Chain Resolution <cnamechainresolution>` |
79 | - getFakeAAAARecords: Get a fake AAAA record, see :doc:`DNS64 <../dns64>` | |
80 | - getFakePTRRecords: Get a fake PTR record, see :doc:`DNS64 <../dns64>` | |
81 | - udpQueryResponse: Do a UDP query and call a handler, see :ref:`UDP Query Response <udpqueryresponse>` | |
223bb49e | 82 | |
b044d4cc RG |
83 | .. attribute:: DNSQuestion.followupName |
84 | ||
85 | see :doc:`DNS64 <../dns64>` | |
86 | ||
87 | .. attribute:: DNSQuestion.followupPrefix | |
88 | ||
89 | see :doc:`DNS64 <../dns64>` | |
90 | ||
54c79a88 | 91 | .. attribute:: DNSQuestion.appliedPolicy |
223bb49e PL |
92 | |
93 | The decision that was made by the policy engine, see :ref:`modifyingpolicydecisions`. | |
94 | ||
54c79a88 | 95 | .. attribute:: DNSQuestion.appliedPolicy.policyName |
223bb49e | 96 | |
54c79a88 | 97 | A string with the name of the policy. |
ac45fee1 | 98 | Set by :ref:`policyName <rpz-policyName>` in the :func:`rpzFile` and :func:`rpzPrimary` configuration items. |
54c79a88 | 99 | It is advised to overwrite this when modifying the :attr:`DNSQuestion.appliedPolicy.policyKind` |
223bb49e | 100 | |
767d7660 OM |
101 | .. attribute:: DNSQuestion.appliedPolicy.policyType |
102 | ||
ac45fee1 O |
103 | The type of match for the policy. |
104 | ||
767d7660 OM |
105 | - ``pdns.policytypes.None`` the empty policy type |
106 | - ``pdns.policytypes.QName`` a match on qname | |
107 | - ``pdns.policytypes.ClientIP`` a match on client IP | |
108 | - ``pdns.policytypes.ResponseIP`` a match on response IP | |
109 | - ``pdns.policytypes.NSDName`` a match on the name of a nameserver | |
110 | - ``pdns.policytypes.NSIP`` a match on the IP of a nameserver | |
223bb49e | 111 | |
54c79a88 | 112 | .. attribute:: DNSQuestion.appliedPolicy.policyCustom |
223bb49e | 113 | |
54c79a88 | 114 | The CNAME content for the ``pdns.policyactions.Custom`` response, a string |
223bb49e | 115 | |
54c79a88 | 116 | .. attribute:: DNSQuestion.appliedPolicy.policyKind |
223bb49e | 117 | |
54c79a88 | 118 | The kind of policy response, there are several policy kinds: |
223bb49e | 119 | |
54c79a88 PL |
120 | - ``pdns.policykinds.Custom`` will return a NoError, CNAME answer with the value specified in :attr:`DNSQuestion.appliedPolicy.policyCustom` |
121 | - ``pdns.policykinds.Drop`` will simply cause the query to be dropped | |
122 | - ``pdns.policykinds.NoAction`` will continue normal processing of the query | |
123 | - ``pdns.policykinds.NODATA`` will return a NoError response with no value in the answer section | |
124 | - ``pdns.policykinds.NXDOMAIN`` will return a response with a NXDomain rcode | |
125 | - ``pdns.policykinds.Truncate`` will return a NoError, no answer, truncated response over UDP. Normal processing will continue over TCP | |
223bb49e | 126 | |
54c79a88 | 127 | .. attribute:: DNSQuestion.appliedPolicy.policyTTL |
223bb49e | 128 | |
54c79a88 | 129 | The TTL in seconds for the ``pdns.policyactions.Custom`` response |
223bb49e | 130 | |
b3e25e9e OM |
131 | .. attribute:: DNSQuestion.appliedPolicy.policyTrigger |
132 | ||
133 | The trigger (left-hand) part of the RPZ rule that was matched | |
134 | ||
47528f06 | 135 | .. attribute:: DNSQuestion.appliedPolicy.policyHit |
b3e25e9e OM |
136 | |
137 | The value that was matched. This is a string representing a name or an address. | |
138 | ||
54c79a88 | 139 | .. attribute:: DNSQuestion.wantsRPZ |
223bb49e | 140 | |
54c79a88 PL |
141 | A boolean that indicates the use of the Policy Engine. |
142 | Can be set to ``false`` in ``prerpz`` to disable RPZ for this query. | |
223bb49e | 143 | |
54c79a88 | 144 | .. attribute:: DNSQuestion.data |
223bb49e | 145 | |
54c79a88 PL |
146 | A Lua object reference that is persistent throughout the lifetime of the :class:`DNSQuestion` object for a single query. |
147 | It can be used to store custom data. | |
148 | Most scripts initialise this to an empty table early on so they can store multiple items. | |
223bb49e | 149 | |
54c79a88 | 150 | .. attribute:: DNSQuestion.requestorId |
223bb49e | 151 | |
54c79a88 | 152 | .. versionadded:: 4.1.0 |
223bb49e | 153 | |
54c79a88 | 154 | A string that will be used to set the ``requestorId`` field in :doc:`protobuf <../lua-config/protobuf>` messages. |
223bb49e | 155 | |
54c79a88 | 156 | .. attribute:: DNSQuestion.deviceId |
bf770968 | 157 | |
54c79a88 | 158 | .. versionadded:: 4.1.0 |
bf770968 | 159 | |
54c79a88 | 160 | A string that will be used to set the ``deviceId`` field in :doc:`protobuf <../lua-config/protobuf>` messages. |
bf770968 | 161 | |
0a6a45c8 CHB |
162 | .. attribute:: DNSQuestion.deviceName |
163 | ||
cee8bfbd | 164 | .. versionadded:: 4.3.0 |
0a6a45c8 CHB |
165 | |
166 | A string that will be used to set the ``deviceName`` field in :doc:`protobuf <../lua-config/protobuf>` messages. | |
167 | ||
54c79a88 | 168 | .. attribute:: DNSQuestion.udpAnswer |
223bb49e | 169 | |
b25f56ed | 170 | Answer to the :attr:`udpQuery <DNSQuestion.udpQuery>` when using the ``udpQueryResponse`` :attr:`followupFunction <DNSQuestion.followupFunction>`. |
54c79a88 | 171 | Only filled when the call-back function is invoked. |
223bb49e | 172 | |
54c79a88 | 173 | .. attribute:: DNSQuestion.udpQueryDest |
223bb49e | 174 | |
54c79a88 | 175 | Destination IP address to send the UDP packet to when using the ``udpQueryResponse`` :attr:`followupFunction <DNSQuestion.followupFunction>` |
223bb49e | 176 | |
54c79a88 | 177 | .. attribute:: DNSQuestion.udpQuery |
223bb49e | 178 | |
54c79a88 | 179 | The content of the UDP payload when using the ``udpQueryResponse`` :attr:`followupFunction <DNSQuestion.followupFunction>` |
223bb49e | 180 | |
54c79a88 | 181 | .. attribute:: DNSQuestion.udpCallback |
223bb49e | 182 | |
54c79a88 | 183 | The name of the callback function that is called when using the ``udpQueryResponse`` :attr:`followupFunction <DNSQuestion.followupFunction>` when an answer is received. |
223bb49e | 184 | |
54c79a88 | 185 | .. attribute:: DNSQuestion.validationState |
1921a4c2 | 186 | |
54c79a88 | 187 | .. versionadded:: 4.1.0 |
1921a4c2 | 188 | |
54c79a88 PL |
189 | The result of the DNSSEC validation, accessible from the ``postresolve``, ``nxdomain`` and ``nodata`` hooks. |
190 | Possible states are ``pdns.validationstates.Indeterminate``, ``pdns.validationstates.Bogus``, ``pdns.validationstates.Insecure`` and ``pdns.validationstates.Secure``. | |
7e26ff77 | 191 | The result will always be ``pdns.validationstates.Indeterminate`` if validation is disabled or was not requested. |
1921a4c2 | 192 | |
19ffa2d9 RG |
193 | .. attribute:: DNSQuestion.detailedValidationState |
194 | ||
195 | .. versionadded:: 4.4.2 | |
196 | ||
197 | The result of the DNSSEC validation, accessible from the ``postresolve``, ``nxdomain`` and ``nodata`` hooks. | |
198 | By contrast with :attr:`validationState <DNSQuestion.validationState>`, there are several Bogus states to be | |
199 | able to better understand the reason for a DNSSEC validation failure. | |
0c7f618f | 200 | |
201 | Possible states are: | |
202 | ||
19ffa2d9 RG |
203 | - ``pdns.validationstates.Indeterminate`` |
204 | - ``pdns.validationstates.BogusNoValidDNSKEY`` | |
205 | - ``pdns.validationstates.BogusInvalidDenial`` | |
206 | - ``pdns.validationstates.BogusUnableToGetDSs`` | |
207 | - ``pdns.validationstates.BogusUnableToGetDNSKEYs`` | |
208 | - ``pdns.validationstates.BogusSelfSignedDS`` | |
209 | - ``pdns.validationstates.BogusNoRRSIG`` | |
210 | - ``pdns.validationstates.BogusNoValidRRSIG`` | |
211 | - ``pdns.validationstates.BogusMissingNegativeIndication`` | |
212 | - ``pdns.validationstates.BogusSignatureNotYetValid`` | |
213 | - ``pdns.validationstates.BogusSignatureExpired`` | |
214 | - ``pdns.validationstates.BogusUnsupportedDNSKEYAlgo`` | |
215 | - ``pdns.validationstates.BogusUnsupportedDSDigestType`` | |
216 | - ``pdns.validationstates.BogusNoZoneKeyBitSet`` | |
217 | - ``pdns.validationstates.BogusRevokedDNSKEY`` | |
218 | - ``pdns.validationstates.BogusInvalidDNSKEYProtocol`` | |
219 | - ``pdns.validationstates.Insecure`` | |
220 | - ``pdns.validationstates.Secure`` | |
221 | ||
222 | The result will always be ``pdns.validationstates.Indeterminate`` is validation is disabled or was not requested. | |
223 | There is a convenience function named ``isValidationStateBogus`` that accepts such a state and return a boolean | |
224 | indicating whether this state is a Bogus one. | |
225 | ||
f1c7929a RG |
226 | .. attribute:: DNSQuestion.logResponse |
227 | ||
228 | .. versionadded:: 4.2.0 | |
229 | ||
230 | Whether the response to this query will be exported to a remote protobuf logger, if one has been configured. | |
231 | ||
b044d4cc RG |
232 | .. attribute:: DNSQuestion.tag |
233 | ||
f5a0551d | 234 | The packetcache tag set via :func:`gettag` or :func:`gettag_ffi`. |
b0b7cb61 | 235 | Default tag is zero. Internally to the recursor, the tag is interpreted as an unsigned 32-bit integer. |
b044d4cc | 236 | |
4add4a58 OM |
237 | .. attribute:: DNSQuestion.queryTime |
238 | ||
239 | .. versionadded:: 4.8.0 | |
240 | ||
241 | The time the query was received | |
242 | ||
243 | .. attribute:: DNSQuestion.queryTime.tv_sec | |
244 | ||
245 | The number of seconds since the Unix epoch. | |
246 | ||
247 | .. attribute:: DNSQuestion.queryTime.tv_usec | |
248 | ||
758165f2 | 249 | The number of microseconds, to be added to the number of seconds in :attr:`DNSQuestion.queryTime.tv_sec` to get a high accuracy timestamp. |
4add4a58 | 250 | |
54c79a88 | 251 | It also supports the following methods: |
223bb49e | 252 | |
54c79a88 | 253 | .. method:: DNSQuestion:addAnswer(type, content, [ttl, name]) |
223bb49e | 254 | |
54c79a88 | 255 | Add an answer to the record of ``type`` with ``content``. |
223bb49e | 256 | |
54c79a88 PL |
257 | :param int type: The type of record to add, can be ``pdns.AAAA`` etc. |
258 | :param str content: The content of the record, will be parsed into wireformat based on the ``type`` | |
385f9865 | 259 | :param int ttl: The TTL in seconds for this record, defaults to 3600 |
54c79a88 | 260 | :param DNSName name: The name of this record, defaults to :attr:`DNSQuestion.qname` |
223bb49e | 261 | |
eac36302 | 262 | .. method:: DNSQuestion:addRecord(type, content, place, [ttl, name]) |
263 | ||
264 | Add a record of ``type`` with ``content`` in section ``place``. | |
265 | ||
266 | :param int type: The type of record to add, can be ``pdns.AAAA`` etc. | |
267 | :param str content: The content of the record, will be parsed into wireformat based on the ``type`` | |
268 | :param int place: The section to place the record, see :attr:`DNSRecord.place` | |
385f9865 | 269 | :param int ttl: The TTL in seconds for this record, defaults to 3600 |
eac36302 | 270 | :param DNSName name: The name of this record, defaults to :attr:`DNSQuestion.qname` |
271 | ||
54c79a88 | 272 | .. method:: DNSQuestion:addPolicyTag(tag) |
223bb49e | 273 | |
18a9de33 | 274 | Add policyTag ``tag`` to the list of policyTags. |
223bb49e | 275 | |
54c79a88 | 276 | :param str tag: The tag to add |
223bb49e | 277 | |
18a9de33 OM |
278 | .. method:: DNSQuestion:getPolicyTags() -> {str} |
279 | ||
280 | Get the current policy tags as a table of strings. | |
281 | ||
282 | .. method:: DNSQuestion:setPolicyTags(tags) | |
283 | ||
284 | Set the policy tags to ``tags``, overwriting any existing policy tags. | |
285 | ||
286 | :param {str} tags: The policy tags | |
287 | ||
54c79a88 | 288 | .. method:: DNSQuestion:discardPolicy(policyname) |
223bb49e | 289 | |
54c79a88 PL |
290 | Skip the filtering policy (for example RPZ) named ``policyname`` for this query. |
291 | This is mostly useful in the ``prerpz`` hook. | |
223bb49e | 292 | |
54c79a88 | 293 | :param str policyname: The name of the policy to ignore. |
223bb49e | 294 | |
54c79a88 | 295 | .. method:: DNSQuestion:getDH() -> DNSHeader |
223bb49e | 296 | |
54c79a88 | 297 | Returns the :class:`DNSHeader` of the query or nil. |
223bb49e | 298 | |
d14a6965 RG |
299 | .. method:: DNSQuestion:getProxyProtocolValues() -> {ProxyProtocolValue} |
300 | ||
301 | .. versionadded:: 4.4.0 | |
302 | ||
303 | Get the Proxy Protocol Type-Length Values if any, as a table of :class:`ProxyProtocolValue` objects. | |
304 | ||
54c79a88 | 305 | .. method:: DNSQuestion:getRecords() -> {DNSRecord} |
223bb49e | 306 | |
54c79a88 | 307 | Get a table of DNS Records in this DNS Question (or answer by now). |
223bb49e | 308 | |
54c79a88 | 309 | .. method:: DNSQuestion:setRecords(records) |
223bb49e | 310 | |
54c79a88 | 311 | After your edits, update the answers of this question |
223bb49e | 312 | |
54c79a88 | 313 | :param {DNSRecord} records: The records to put in the packet |
223bb49e | 314 | |
54c79a88 | 315 | .. method:: DNSQuestion:getEDNSFlag(name) -> bool |
223bb49e | 316 | |
54c79a88 | 317 | Returns true if the EDNS flag with ``name`` is set in the query. |
223bb49e | 318 | |
54c79a88 | 319 | :param string name: Name of the flag. |
223bb49e | 320 | |
54c79a88 | 321 | .. method:: DNSQuestion:getEDNSFlags() -> {str} |
223bb49e | 322 | |
54c79a88 | 323 | Returns a list of strings with all the EDNS flag mnemonics in the query. |
223bb49e | 324 | |
54c79a88 | 325 | .. method:: DNSQuestion:getEDNSOption(num) -> str |
223bb49e | 326 | |
54c79a88 | 327 | Get the EDNS Option with number ``num`` as a bytestring. |
223bb49e | 328 | |
54c79a88 | 329 | .. method:: DNSQuestion:getEDNSOptions() -> {str: str} |
223bb49e | 330 | |
54c79a88 | 331 | Get a map of all EDNS Options |
223bb49e | 332 | |
54c79a88 | 333 | .. method:: DNSQuestion:getEDNSSubnet() -> Netmask |
223bb49e | 334 | |
54c79a88 | 335 | Returns the :class:`Netmask` specified in the EDNSSubnet option, or empty if there was none. |
223bb49e | 336 | |
223bb49e PL |
337 | DNSHeader Object |
338 | ================ | |
339 | ||
340 | The DNS header as returned by :meth:`DNSQuestion:getDH()` represents a header of a DNS message. | |
341 | ||
342 | .. class:: DNSHeader | |
343 | ||
344 | represents a header of a DNS message. | |
345 | ||
54c79a88 | 346 | .. method:: DNSHeader:getRD() -> bool |
223bb49e | 347 | |
54c79a88 | 348 | The value of the Recursion Desired bit. |
223bb49e | 349 | |
54c79a88 | 350 | .. method:: DNSHeader:getAA() -> bool |
223bb49e | 351 | |
54c79a88 | 352 | The value of the Authoritative Answer bit. |
223bb49e | 353 | |
54c79a88 | 354 | .. method:: DNSHeader:getAD() -> bool |
223bb49e | 355 | |
54c79a88 | 356 | The value of the Authenticated Data bit. |
223bb49e | 357 | |
54c79a88 | 358 | .. method:: DNSHeader:getCD() -> bool |
223bb49e | 359 | |
54c79a88 | 360 | The value of the Checking Disabled bit. |
223bb49e | 361 | |
54c79a88 | 362 | .. method:: DNSHeader:getTC() -> bool |
223bb49e | 363 | |
54c79a88 | 364 | The value of the Truncation bit. |
223bb49e | 365 | |
54c79a88 | 366 | .. method:: DNSHeader:getRCODE() -> int |
223bb49e | 367 | |
54c79a88 | 368 | The Response Code of the query |
223bb49e | 369 | |
54c79a88 | 370 | .. method:: DNSHeader:getOPCODE() -> int |
223bb49e | 371 | |
54c79a88 | 372 | The Operation Code of the query |
223bb49e | 373 | |
54c79a88 | 374 | .. method:: DNSHeader:getID() -> int |
223bb49e | 375 | |
54c79a88 | 376 | The ID of the query |
223bb49e | 377 | |
b044d4cc RG |
378 | DNSRecord Object |
379 | ================ | |
380 | ||
d6906f80 | 381 | See :doc:`DNSRecord <dnsrecord>`. |
b044d4cc | 382 | |
223bb49e PL |
383 | The EDNSOptionView Class |
384 | ======================== | |
385 | ||
386 | .. class:: EDNSOptionView | |
387 | ||
29e6303a RG |
388 | An object that represents the values of a single EDNS option |
389 | ||
390 | .. method:: EDNSOptionView:count() | |
391 | .. versionadded:: 4.2.0 | |
392 | ||
393 | The number of values for this EDNS option. | |
394 | ||
395 | .. method:: EDNSOptionView:getValues() | |
396 | .. versionadded:: 4.2.0 | |
397 | ||
398 | Return a table of NULL-safe strings values for this EDNS option. | |
223bb49e | 399 | |
54c79a88 | 400 | .. attribute:: EDNSOptionView.size |
223bb49e | 401 | |
29e6303a | 402 | The size in bytes of the first value of this EDNS option. |
223bb49e | 403 | |
54c79a88 | 404 | .. method:: EDNSOptionView:getContent() |
223bb49e | 405 | |
29e6303a | 406 | Returns a NULL-safe string object of the first value of this EDNS option. |
d14a6965 RG |
407 | |
408 | The ProxyProtocolValue Class | |
409 | ============================ | |
410 | ||
411 | .. class:: ProxyProtocolValue | |
412 | ||
413 | .. versionadded:: 4.4.0 | |
414 | ||
415 | An object that represents the value of a Proxy Protocol Type-Length Value | |
416 | ||
417 | .. method:: ProxyProtocolValue:getContent() -> str | |
418 | ||
419 | Returns a NULL-safe string object. | |
420 | ||
421 | .. method:: ProxyProtocolValue:getType() -> int | |
422 | ||
423 | Returns the type of this value. |