]> git.ipfire.org Git - thirdparty/pdns.git/blob - pdns/dnsdistdist/docs/rules-actions.rst
d1e18c5703ab64f609d1c029b890410d577f078a
[thirdparty/pdns.git] / pdns / dnsdistdist / docs / rules-actions.rst
1 Packet Policies
2 ===============
3
4 dnsdist works in essence like any other loadbalancer:
5
6 It receives packets on one or several addresses it listens on, and determines whether it will process this packet based on the :doc:`advanced/acl`. Should the packet be processed, dnsdist attempts to match any of the configured rules in order and when one matches, the associated action is performed.
7
8 These rule and action combinations are considered policies.
9
10 Packet Actions
11 --------------
12
13 Each packet can be:
14
15 - Dropped
16 - Turned into an answer directly
17 - Forwarded to a downstream server
18 - Modified and forwarded to a downstream and be modified back
19 - Be delayed
20
21 This decision can be taken at different times during the forwarding process.
22
23 Examples
24 ~~~~~~~~
25
26 Rules for traffic exceeding QPS limits
27 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
28
29 Traffic that exceeds a QPS limit, in total or per IP (subnet) can be matched by a rule.
30
31 For example::
32
33 addAction(MaxQPSIPRule(5, 32, 48), DelayAction(100))
34
35 This measures traffic per IPv4 address and per /48 of IPv6, and if traffic for such an address (range) exceeds 5 qps, it gets delayed by 100ms. (Please note: :func:`DelayAction` can only delay UDP traffic).
36
37 As another example::
38
39 addAction(MaxQPSIPRule(5), NoRecurseAction())
40
41 This strips the Recursion Desired (RD) bit from any traffic per IPv4 or IPv6 /64 that exceeds 5 qps.
42 This means any those traffic bins is allowed to make a recursor do 'work' for only 5 qps.
43
44 If this is not enough, try::
45
46 addAction(MaxQPSIPRule(5), DropAction())
47
48 or::
49
50 addAction(MaxQPSIPRule(5), TCAction())
51
52 This will respectively drop traffic exceeding that 5 QPS limit per IP or range, or return it with TC=1, forcing clients to fall back to TCP.
53
54 To turn this per IP or range limit into a global limit, use ``NotRule(MaxQPSRule(5000))`` instead of :func:`MaxQPSIPRule`.
55
56 Regular Expressions
57 ^^^^^^^^^^^^^^^^^^^
58
59 :func:`RegexRule` matches a regular expression on the query name, and it works like this::
60
61 addAction(RegexRule("[0-9]{5,}"), DelayAction(750)) -- milliseconds
62 addAction(RegexRule("[0-9]{4,}\\.example$"), DropAction())
63
64 This delays any query for a domain name with 5 or more consecutive digits in it.
65 The second rule drops anything with more than 4 consecutive digits within a .example domain.
66
67 Note that the query name is presented without a trailing dot to the regex.
68 The regex is applied case insensitively.
69
70 Alternatively, if compiled in, :func:`RE2Rule` provides similar functionality, but against libre2.
71
72 Rule Generators
73 ---------------
74
75 :program:`dnsdist` contains several functions that make it easier to add actions and rules.
76
77 .. function:: addAnyTCRule()
78
79 .. deprecated:: 1.2.0
80
81 Set the TC-bit (truncate) on ANY queries received over UDP, forcing a retry over TCP.
82 This function is deprecated as of 1.2.0 and will be removed in 1.3.0. This is equivalent to doing::
83
84 addAction(AndRule({QTypeRule(DNSQType.ANY), TCPRule(false)}), TCAction())
85
86 .. versionchanged:: 1.4.0
87 Before 1.4.0, the QTypes were in the ``dnsdist`` namespace. Use ``dnsdist.ANY`` in these versions.
88
89 .. function:: addDelay(DNSrule, delay)
90
91 .. deprecated:: 1.2.0
92
93 Delay the query for ``delay`` milliseconds before sending to a backend.
94 This function is deprecated as of 1.2.0 and will be removed in 1.3.0, please use instead:
95
96 addAction(DNSRule, DelayAction(delay))
97
98 :param DNSRule: The DNSRule to match traffic
99 :param int delay: The delay time in milliseconds.
100
101 .. function:: addDisableValidationRule(DNSrule)
102
103 .. deprecated:: 1.2.0
104
105 Set the CD (Checking Disabled) flag to 1 for all queries matching the DNSRule.
106 This function is deprecated as of 1.2.0 and will be removed in 1.3.0. Please use the :func:`DisableValidationAction` action instead.
107
108 .. function:: addDomainBlock(domain)
109
110 .. deprecated:: 1.2.0
111
112 Drop all queries for ``domain`` and all names below it.
113 Deprecated as of 1.2.0 and will be removed in 1.3.0, please use instead:
114
115 addAction(domain, DropAction())
116
117 :param string domain: The domain name to block
118
119 .. function:: addDomainSpoof(domain, IPv4[, IPv6])
120 addDomainSpoof(domain, {IP[,...]})
121
122 .. deprecated:: 1.2.0
123
124 Generate answers for A/AAAA/ANY queries.
125 This function is deprecated as of 1.2.0 and will be removed in 1.3.0, please use:
126
127 addAction(domain, SpoofAction({IP[,...]}))
128
129 or:
130
131 addAction(domain, SpoofAction(IPv4[, IPv6]))
132
133 :param string domain: Domain name to spoof for
134 :param string IPv4: IPv4 address to spoof in the reply
135 :param string IPv6: IPv6 address to spoof in the reply
136 :param string IP: IP address to spoof in the reply
137
138 .. function:: addDomainCNAMESpoof(domain, cname)
139
140 .. deprecated:: 1.2.0
141
142 Generate CNAME answers for queries. This function is deprecated as of 1.2.0 and will be removed in 1.3.0, in favor of using:
143
144 addAction(domain, SpoofCNAMEAction(cname))
145
146 :param string domain: Domain name to spoof for
147 :param string cname: Domain name to add CNAME to
148
149 .. function:: addLuaAction(DNSrule, function [, options])
150
151 .. versionchanged:: 1.3.0
152 Added the optional parameter ``options``.
153
154 .. versionchanged:: 1.3.0
155 The second argument returned by the ``function`` can be omitted. For earlier releases, simply return an empty string.
156
157 .. deprecated:: 1.4.0
158 Removed in 1.4.0, use :func:`LuaAction` with :func:`addAction` instead.
159
160 Invoke a Lua function that accepts a :class:`DNSQuestion`.
161 This function works similar to using :func:`LuaAction`.
162 The ``function`` should return both a :ref:`DNSAction` and its argument `rule`. The `rule` is used as an argument
163 of the following :ref:`DNSAction`: `DNSAction.Spoof`, `DNSAction.Pool` and `DNSAction.Delay`.
164 If the Lua code fails, ServFail is returned.
165
166 :param DNSRule: match queries based on this rule
167 :param string function: the name of a Lua function
168 :param table options: A table with key: value pairs with options.
169
170 Options:
171
172 * ``uuid``: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
173
174 ::
175
176 function luarule(dq)
177 if(dq.qtype==dnsdist.NAPTR)
178 then
179 return DNSAction.Pool, "abuse" -- send to abuse pool
180 else
181 return DNSAction.None, "" -- no action
182 -- return DNSAction.None -- as of dnsdist version 1.3.0
183 end
184 end
185
186 addLuaAction(AllRule(), luarule)
187
188 .. function:: addLuaResponseAction(DNSrule, function [, options])
189
190 .. versionchanged:: 1.3.0
191 Added the optional parameter ``options``.
192
193 .. versionchanged:: 1.3.0
194 The second argument returned by the ``function`` can be omitted. For earlier releases, simply return an empty string.
195
196 .. deprecated:: 1.4.0
197 Removed in 1.4.0, use :func:`LuaResponseAction` with :func:`addResponseAction` instead.
198
199 Invoke a Lua function that accepts a :class:`DNSResponse`.
200 This function works similar to using :func:`LuaResponseAction`.
201 The ``function`` should return both a :ref:`DNSResponseAction` and its argument `rule`. The `rule` is used as an argument
202 of the `DNSResponseAction.Delay`.
203 If the Lua code fails, ServFail is returned.
204
205 :param DNSRule: match queries based on this rule
206 :param string function: the name of a Lua function
207 :param table options: A table with key: value pairs with options.
208
209 Options:
210
211 * ``uuid``: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
212
213 .. function:: addNoRecurseRule(DNSrule)
214
215 .. deprecated:: 1.2.0
216
217 Clear the RD flag for all queries matching the rule.
218 This function is deprecated as of 1.2.0 and will be removed in 1.3.0, please use:
219
220 addAction(DNSRule, NoRecurseAction())
221
222 :param DNSRule: match queries based on this rule
223
224 .. function:: addPoolRule(DNSRule, pool)
225
226 .. deprecated:: 1.2.0
227
228 Send queries matching the first argument to the pool ``pool``.
229 e.g.::
230
231 addPoolRule("example.com", "myPool")
232
233 This function is deprecated as of 1.2.0 and will be removed in 1.3.0, this is equivalent to::
234
235 addAction("example.com", PoolAction("myPool"))
236
237 :param DNSRule: match queries based on this rule
238 :param string pool: The name of the pool to send the queries to
239
240 .. function:: addQPSLimit(DNSrule, limit)
241
242 .. deprecated:: 1.2.0
243
244 Limit queries matching the DNSRule to ``limit`` queries per second.
245 All queries over the limit are dropped.
246 This function is deprecated as of 1.2.0 and will be removed in 1.3.0, please use:
247
248 addAction(DNSRule, QPSAction(limit))
249
250 :param DNSRule: match queries based on this rule
251 :param int limit: QPS limit for this rule
252
253 .. function:: addQPSPoolRule(DNSRule, limit, pool)
254
255 .. deprecated:: 1.2.0
256
257 Send at most ``limit`` queries/s for this pool, letting the subsequent rules apply otherwise.
258 This function is deprecated as of 1.2.0 and will be removed in 1.3.0, as it is only a convience function for the following syntax::
259
260 addAction("192.0.2.0/24", QPSPoolAction(15, "myPool")
261
262 :param DNSRule: match queries based on this rule
263 :param int limit: QPS limit for this rule
264 :param string pool: The name of the pool to send the queries to
265
266
267 Managing Rules
268 --------------
269
270 Active Rules can be shown with :func:`showRules` and removed with :func:`rmRule`::
271
272 > addAction("h4xorbooter.xyz.", QPSAction(10))
273 > addAction({"130.161.0.0/16", "145.14.0.0/16"} , QPSAction(20))
274 > addAction({"nl.", "be."}, QPSAction(1))
275 > showRules()
276 # Matches Rule Action
277 0 0 h4xorbooter.xyz. qps limit to 10
278 1 0 130.161.0.0/16, 145.14.0.0/16 qps limit to 20
279 2 0 nl., be. qps limit to 1
280
281 For Rules related to the incoming query:
282
283 .. function:: addAction(DNSrule, action [, options])
284
285 .. versionchanged:: 1.3.0
286 Added the optional parameter ``options``.
287
288 Add a Rule and Action to the existing rules.
289
290 :param DNSrule rule: A DNSRule, e.g. an :func:`AllRule` or a compounded bunch of rules using e.g. :func:`AndRule`
291 :param action: The action to take
292 :param table options: A table with key: value pairs with options.
293
294 Options:
295
296 * ``uuid``: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
297
298 .. function:: clearRules()
299
300 Remove all current rules.
301
302 .. function:: getAction(n) -> Action
303
304 Returns the Action associated with rule ``n``.
305
306 :param int n: The rule number
307
308 .. function:: mvRule(from, to)
309
310 Move rule ``from`` to a position where it is in front of ``to``.
311 ``to`` can be one larger than the largest rule, in which case the rule will be moved to the last position.
312
313 :param int from: Rule number to move
314 :param int to: Location to more the Rule to
315
316 .. function:: newRuleAction(rule, action[, options])
317
318 .. versionchanged:: 1.3.0
319 Added the optional parameter ``options``.
320
321 Return a pair of DNS Rule and DNS Action, to be used with :func:`setRules`.
322
323 :param Rule rule: A `Rule <#traffic-matching>`_
324 :param Action action: The `Action <#actions>`_ to apply to the matched traffic
325 :param table options: A table with key: value pairs with options.
326
327 Options:
328
329 * ``uuid``: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
330
331 .. function:: setRules(rules)
332
333 Replace the current rules with the supplied list of pairs of DNS Rules and DNS Actions (see :func:`newRuleAction`)
334
335 :param [RuleAction] rules: A list of RuleActions
336
337 .. function:: showRules([options])
338
339 .. versionchanged:: 1.3.0
340 ``options`` optional parameter added
341
342 Show all defined rules for queries, optionally displaying their UUIDs.
343
344 :param table options: A table with key: value pairs with display options.
345
346 Options:
347
348 * ``showUUIDs=false``: bool - Whether to display the UUIDs, defaults to false.
349 * ``truncateRuleWidth=-1``: int - Truncate rules output to ``truncateRuleWidth`` size. Defaults to ``-1`` to display the full rule.
350
351 .. function:: topRule()
352
353 Move the last rule to the first position.
354
355 .. function:: rmRule(id)
356
357 .. versionchanged:: 1.3.0
358 ``id`` can now be an UUID.
359
360 Remove rule ``id``.
361
362 :param int id: The UUID of the rule to remove if ``id`` is an UUID, its position otherwise
363
364 For Rules related to responses:
365
366 .. function:: addResponseAction(DNSRule, action [, options])
367
368 .. versionchanged:: 1.3.0
369 Added the optional parameter ``options``.
370
371 Add a Rule and Action for responses to the existing rules.
372
373 :param DNSRule: A DNSRule, e.g. an :func:`AllRule` or a compounded bunch of rules using e.g. :func:`AndRule`
374 :param action: The action to take
375 :param table options: A table with key: value pairs with options.
376
377 Options:
378
379 * ``uuid``: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
380
381 .. function:: mvResponseRule(from, to)
382
383 Move response rule ``from`` to a position where it is in front of ``to``.
384 ``to`` can be one larger than the largest rule, in which case the rule will be moved to the last position.
385
386 :param int from: Rule number to move
387 :param int to: Location to more the Rule to
388
389 .. function:: rmResponseRule(id)
390
391 .. versionchanged:: 1.3.0
392 ``id`` can now be an UUID.
393
394 Remove response rule ``id``.
395
396 :param int id: The UUID of the rule to remove if ``id`` is an UUID, its position otherwise
397
398 .. function:: showResponseRules([options])
399
400 .. versionchanged:: 1.3.0
401 ``options`` optional parameter added
402
403 Show all defined response rules, optionally displaying their UUIDs.
404
405 :param table options: A table with key: value pairs with display options.
406
407 Options:
408
409 * ``showUUIDs=false``: bool - Whether to display the UUIDs, defaults to false.
410 * ``truncateRuleWidth=-1``: int - Truncate rules output to ``truncateRuleWidth`` size. Defaults to ``-1`` to display the full rule.
411
412 .. function:: topResponseRule()
413
414 Move the last response rule to the first position.
415
416 Functions for manipulating Cache Hit Respone Rules:
417
418 .. function:: addCacheHitResponseAction(DNSRule, action [, options])
419
420 .. versionadded:: 1.2.0
421
422 .. versionchanged:: 1.3.0
423 Added the optional parameter ``options``.
424
425 Add a Rule and ResponseAction for Cache Hits to the existing rules.
426
427 :param DNSRule: A DNSRule, e.g. an :func:`AllRule` or a compounded bunch of rules using e.g. :func:`AndRule`
428 :param action: The action to take
429 :param table options: A table with key: value pairs with options.
430
431 Options:
432
433 * ``uuid``: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
434
435 .. function:: mvCacheHitResponseRule(from, to)
436
437 .. versionadded:: 1.2.0
438
439 Move cache hit response rule ``from`` to a position where it is in front of ``to``.
440 ``to`` can be one larger than the largest rule, in which case the rule will be moved to the last position.
441
442 :param int from: Rule number to move
443 :param int to: Location to more the Rule to
444
445 .. function:: rmCacheHitResponseRule(id)
446
447 .. versionadded:: 1.2.0
448
449 .. versionchanged:: 1.3.0
450 ``id`` can now be an UUID.
451
452 :param int id: The UUID of the rule to remove if ``id`` is an UUID, its position otherwise
453
454 .. function:: showCacheHitResponseRules([options])
455
456 .. versionadded:: 1.2.0
457
458 .. versionchanged:: 1.3.0
459 ``options`` optional parameter added
460
461 Show all defined cache hit response rules, optionally displaying their UUIDs.
462
463 :param table options: A table with key: value pairs with display options.
464
465 Options:
466
467 * ``showUUIDs=false``: bool - Whether to display the UUIDs, defaults to false.
468 * ``truncateRuleWidth=-1``: int - Truncate rules output to ``truncateRuleWidth`` size. Defaults to ``-1`` to display the full rule.
469
470 .. function:: topCacheHitResponseRule()
471
472 .. versionadded:: 1.2.0
473
474 Move the last cache hit response rule to the first position.
475
476 Functions for manipulating Self-Answered Response Rules:
477
478 .. function:: addSelfAnsweredResponseAction(DNSRule, action [, options])
479
480 .. versionadded:: 1.3.0
481
482 Add a Rule and Action for Self-Answered queries to the existing rules.
483
484 :param DNSRule: A DNSRule, e.g. an :func:`AllRule` or a compounded bunch of rules using e.g. :func:`AndRule`
485 :param action: The action to take
486
487 .. function:: mvSelfAnsweredResponseRule(from, to)
488
489 .. versionadded:: 1.3.0
490
491 Move self answered response rule ``from`` to a position where it is in front of ``to``.
492 ``to`` can be one larger than the largest rule, in which case the rule will be moved to the last position.
493
494 :param int from: Rule number to move
495 :param int to: Location to more the Rule to
496
497 .. function:: rmSelfAnsweredResponseRule(id)
498
499 .. versionadded:: 1.3.0
500
501 Remove self answered response rule ``id``.
502
503 :param int id: The UUID of the rule to remove if ``id`` is an UUID, its position otherwise
504
505 .. function:: showSelfAnsweredResponseRules([options])
506
507 .. versionadded:: 1.3.0
508
509 Show all defined self answered response rules, optionally displaying their UUIDs.
510
511 :param table options: A table with key: value pairs with display options.
512
513 Options:
514
515 * ``showUUIDs=false``: bool - Whether to display the UUIDs, defaults to false.
516 * ``truncateRuleWidth=-1``: int - Truncate rules output to ``truncateRuleWidth`` size. Defaults to ``-1`` to display the full rule.
517
518 .. function:: topSelfAnsweredResponseRule()
519
520 .. versionadded:: 1.3.0
521
522 Move the last self answered response rule to the first position.
523
524 .. _RulesIntro:
525
526 Matching Packets (Selectors)
527 ----------------------------
528
529 Packets can be matched by selectors, called a ``DNSRule``.
530 These ``DNSRule``\ s be one of the following items:
531
532 * A string that is either a domain name or netmask
533 * A list of strings that are either domain names or netmasks
534 * A :class:`DNSName`
535 * A list of :class:`DNSName`\ s
536 * A (compounded) ``Rule``
537
538 .. versionadded:: 1.2.0
539 A DNSRule can also be a :class:`DNSName` or a list of these
540
541 .. function:: AllRule()
542
543 Matches all traffic
544
545 .. function:: DNSSECRule()
546
547 Matches queries with the DO flag set
548
549 .. function:: DSTPortRule(port)
550
551 Matches questions received to the destination port.
552
553 :param int port: Match destination port.
554
555 .. function:: EDNSOptionRule(optcode)
556
557 .. versionadded:: 1.4.0
558
559 Matches queries or responses with the specified EDNS option present.
560 ``optcode`` is specified as an integer, or a constant such as `EDNSOptionCode.ECS`.
561
562 .. function:: EDNSVersionRule(version)
563
564 .. versionadded:: 1.4.0
565
566 Matches queries or responses with an OPT record whose EDNS version is greater than the specified EDNS version.
567
568 :param int version: The EDNS version to match on
569
570 .. function:: ERCodeRule(rcode)
571
572 Matches queries or responses with the specified ``rcode``.
573 ``rcode`` can be specified as an integer or as one of the built-in :ref:`DNSRCode`.
574 The full 16bit RCode will be matched. If no EDNS OPT RR is present, the upper 12 bits are treated as 0.
575
576 :param int rcode: The RCODE to match on
577
578 .. function:: HTTPHeaderRule(name, regex)
579
580 .. versionadded:: 1.4.0
581
582 Matches DNS over HTTPS queries with a HTTP header ``name`` whose content matches the regular expression ``regex``.
583
584 :param str name: The case-insensitive name of the HTTP header to match on
585 :param str regex: A regular expression to match the content of the specified header
586
587 .. function:: HTTPPathRegexRule(regex)
588
589 .. versionadded:: 1.4.0
590
591 Matches DNS over HTTPS queries with a HTTP path matching the regular expression supplied in ``regex``. For example, if the query has been sent to the https://192.0.2.1:443/PowerDNS?dns=... URL, the path would be '/PowerDNS'.
592 Only valid DNS over HTTPS queries are matched. If you want to match all HTTP queries, see :meth:`DOHFrontend.setResponsesMap` instead.
593
594 :param str regex: The regex to match on
595
596 .. function:: HTTPPathRule(path)
597
598 .. versionadded:: 1.4.0
599
600 Matches DNS over HTTPS queries with a HTTP path of ``path``. For example, if the query has been sent to the https://192.0.2.1:443/PowerDNS?dns=... URL, the path would be '/PowerDNS'.
601 Only valid DNS over HTTPS queries are matched. If you want to match all HTTP queries, see :meth:`DOHFrontend.setResponsesMap` instead.
602
603 :param str path: The exact HTTP path to match on
604
605 .. function:: KeyValueStoreLookupRule(kvs, lookupKey)
606
607 .. versionadded:: 1.4.0
608
609 As of 1.4.0, this code is considered experimental.
610
611 Return true if the key returned by 'lookupKey' exists in the key value store referenced by 'kvs'.
612 The store can be a CDB (:func:`newCDBKVStore`) or a LMDB database (:func:`newLMDBKVStore`).
613 The key can be based on the qname (:func:`KeyValueLookupKeyQName` and :func:`KeyValueLookupKeySuffix`),
614 source IP (:func:`KeyValueLookupKeySourceIP`) or the value of an existing tag (:func:`KeyValueLookupKeyTag`).
615
616 :param KeyValueStore kvs: The key value store to query
617 :param KeyValueLookupKey lookupKey: The key to use for the lookup
618
619 .. function:: MaxQPSIPRule(qps[, v4Mask[, v6Mask[, burst[, expiration[, cleanupDelay[, scanFraction]]]]]])
620
621 .. versionchanged:: 1.3.1
622 Added the optional parameters ``expiration``, ``cleanupDelay`` and ``scanFraction``.
623
624 Matches traffic for a subnet specified by ``v4Mask`` or ``v6Mask`` exceeding ``qps`` queries per second up to ``burst`` allowed.
625 This rule keeps track of QPS by netmask or source IP. This state is cleaned up regularly if ``cleanupDelay`` is greater than zero,
626 removing existing netmasks or IP addresses that have not been seen in the last ``expiration`` seconds.
627
628 :param int qps: The number of queries per second allowed, above this number traffic is matched
629 :param int v4Mask: The IPv4 netmask to match on. Default is 32 (the whole address)
630 :param int v6Mask: The IPv6 netmask to match on. Default is 64
631 :param int burst: The number of burstable queries per second allowed. Default is same as qps
632 :param int expiration: How long to keep netmask or IP addresses after they have last been seen, in seconds. Default is 300
633 :param int cleanupDelay: The number of seconds between two cleanups. Default is 60
634 :param int scanFraction: The maximum fraction of the store to scan for expired entries, for example 5 would scan at most 20% of it. Default is 10 so 10%
635
636 .. function:: MaxQPSRule(qps)
637
638 Matches traffic **not** exceeding this qps limit. If e.g. this is set to 50, starting at the 51st query of the current second traffic stops being matched.
639 This can be used to enforce a global QPS limit.
640
641 :param int qps: The number of queries per second allowed, above this number the traffic is **not** matched anymore
642
643 .. function:: NetmaskGroupRule(nmg[, src[, quiet]])
644
645 .. versionchanged:: 1.4.0
646 ``quiet`` parameter added
647
648 Matches traffic from/to the network range specified in ``nmg``.
649
650 Set the ``src`` parameter to false to match ``nmg`` against destination address instead of source address.
651 This can be used to differentiate between clients
652
653 :param NetMaskGroup nmg: The NetMaskGroup to match on
654 :param bool src: Whether to match source or destination address of the packet. Defaults to true (matches source)
655 :param bool quiet: Do not display the list of matched netmasks in Rules. Default is false.
656
657 .. function:: OpcodeRule(code)
658
659 Matches queries with opcode ``code``.
660 ``code`` can be directly specified as an integer, or one of the :ref:`built-in DNSOpcodes <DNSOpcode>`.
661
662 :param int code: The opcode to match
663
664 .. function:: ProbaRule(probability)
665
666 .. versionadded:: 1.3.0
667
668 Matches queries with a given probability. 1.0 means "always"
669
670 :param double probability: Probability of a match
671
672 .. function:: QClassRule(qclass)
673
674 Matches queries with the specified ``qclass``.
675 ``class`` can be specified as an integer or as one of the built-in :ref:`DNSClass`.
676
677 :param int qclass: The Query Class to match on
678
679 .. function:: QNameRule(qname)
680
681 .. versionadded:: 1.2.0
682
683 Matches queries with the specified qname exactly.
684
685 :param string qname: Qname to match
686
687 .. function:: QNameSetRule(set)
688
689 .. versionadded:: 1.4.0
690
691 Matches if the set contains exact qname.
692
693 To match subdomain names, see :func:`SuffixMatchNodeRule`.
694
695 :param DNSNameSet set: Set with qnames.
696
697 .. function:: QNameLabelsCountRule(min, max)
698
699 Matches if the qname has less than ``min`` or more than ``max`` labels.
700
701 :param int min: Minimum number of labels
702 :param int max: Maximum nimber of labels
703
704 .. function:: QNameWireLengthRule(min, max)
705
706 Matches if the qname's length on the wire is less than ``min`` or more than ``max`` bytes.
707
708 :param int min: Minimum number of bytes
709 :param int max: Maximum nimber of bytes
710
711 .. function:: QTypeRule(qtype)
712
713 Matches queries with the specified ``qtype``
714 ``qtype`` may be specified as an integer or as one of the built-in QTypes.
715 For instance ``dnsdist.A``, ``dnsdist.TXT`` and ``dnsdist.ANY``.
716
717 :param int qtype: The QType to match on
718
719 .. function:: RCodeRule(rcode)
720
721 Matches queries or responses with the specified ``rcode``.
722 ``rcode`` can be specified as an integer or as one of the built-in :ref:`DNSRCode`.
723 Only the non-extended RCode is matched (lower 4bits).
724
725 :param int rcode: The RCODE to match on
726
727 .. function:: RDRule()
728
729 .. versionadded:: 1.2.0
730
731 Matches queries with the RD flag set.
732
733 .. function:: RegexRule(regex)
734
735 Matches the query name against the ``regex``.
736
737 .. code-block:: Lua
738
739 addAction(RegexRule("[0-9]{5,}"), DelayAction(750)) -- milliseconds
740 addAction(RegexRule("[0-9]{4,}\\.example$"), DropAction())
741
742 This delays any query for a domain name with 5 or more consecutive digits in it.
743 The second rule drops anything with more than 4 consecutive digits within a .EXAMPLE domain.
744
745 Note that the query name is presented without a trailing dot to the regex.
746 The regex is applied case insensitively.
747
748 :param string regex: A regular expression to match the traffic on
749
750 .. function:: RecordsCountRule(section, minCount, maxCount)
751
752 Matches if there is at least ``minCount`` and at most ``maxCount`` records in the section ``section``.
753 ``section`` can be specified as an integer or as a :ref:`DNSSection`.
754
755 :param int section: The section to match on
756 :param int minCount: The minimum number of entries
757 :param int maxCount: The maximum number of entries
758
759 .. function:: RecordsTypeCountRule(section, qtype, minCount, maxCount)
760
761 Matches if there is at least ``minCount`` and at most ``maxCount`` records of type ``type`` in the section ``section``.
762 ``section`` can be specified as an integer or as a :ref:`DNSSection`.
763 ``qtype`` may be specified as an integer or as one of the :ref:`built-in QTypes <DNSQType>`, for instance ``DNSQType.A`` or ``DNSQType.TXT``.
764
765 :param int section: The section to match on
766 :param int qtype: The QTYPE to match on
767 :param int minCount: The minimum number of entries
768 :param int maxCount: The maximum number of entries
769
770 .. function:: RE2Rule(regex)
771
772 Matches the query name against the supplied regex using the RE2 engine.
773
774 For an example of usage, see :func:`RegexRule`.
775
776 :note: Only available when dnsdist was built with libre2 support.
777
778 :param str regex: The regular expression to match the QNAME.
779
780 .. function:: SNIRule(name)
781
782 .. versionadded:: 1.4.0
783
784 Matches against the TLS Server Name Indication value sent by the client, if any. Only makes
785 sense for DoT or DoH, and for that last one matching on the HTTP Host header using :func:`HTTPHeaderRule`
786 might provide more consistent results.
787 As of the version 2.3.0-beta of h2o, it is unfortunately not possible to extract the SNI value from DoH
788 connections, and it is therefore necessary to use the HTTP Host header until version 2.3.0 is released.
789
790 :param str name: The exact SNI name to match.
791
792 .. function:: SuffixMatchNodeRule(smn[, quiet])
793
794 Matches based on a group of domain suffixes for rapid testing of membership.
795 Pass true as second parameter to prevent listing of all domains matched.
796
797 To match domain names exactly, see :func:`QNameSetRule`.
798
799 :param SuffixMatchNode smb: The SuffixMatchNode to match on
800 :param bool quiet: Do not display the list of matched domains in Rules. Default is false.
801
802 .. function:: TagRule(name [, value])
803
804 .. versionadded:: 1.3.0
805
806 Matches question or answer with a tag named ``name`` set. If ``value`` is specified, the existing tag value should match too.
807
808 :param bool name: The name of the tag that has to be set
809 :param bool value: If set, the value the tag has to be set to. Default is unset
810
811 .. function:: TCPRule([tcp])
812
813 Matches question received over TCP if ``tcp`` is true, over UDP otherwise.
814
815 :param bool tcp: Match TCP traffic. Default is true.
816
817 .. function:: TrailingDataRule()
818
819 Matches if the query has trailing data.
820
821 .. function:: PoolAvailableRule(poolname)
822
823 .. versionadded:: 1.3.3
824
825 Check whether a pool has any servers available to handle queries
826
827 .. code-block:: Lua
828
829 --- Send queries to default pool when servers are available
830 addAction(PoolAvailableRule(""), PoolAction(""))
831 --- Send queries to fallback pool if not
832 addAction(AllRule(), PoolAction("fallback"))
833
834 :param string poolname: Pool to check
835
836 Combining Rules
837 ~~~~~~~~~~~~~~~
838
839 .. function:: AndRule(selectors)
840
841 Matches traffic if all ``selectors`` match.
842
843 :param {Rule} selectors: A table of Rules
844
845 .. function:: NotRule(selector)
846
847 Matches the traffic if the ``selector`` rule does not match;
848
849 :param Rule selector: A Rule
850
851 .. function:: OrRule(selectors)
852
853 Matches the traffic if one or more of the the ``selectors`` Rules does match.
854
855 :param {Rule} selector: A table of Rules
856
857 Convenience Functions
858 ~~~~~~~~~~~~~~~~~~~~~
859
860 .. function:: makeRule(rule)
861
862 Make a :func:`NetmaskGroupRule` or a :func:`SuffixMatchNodeRule`, depending on it is called.
863 ``makeRule("0.0.0.0/0")`` will for example match all IPv4 traffic, ``makeRule({"be","nl","lu"})`` will match all Benelux DNS traffic.
864
865 :param string rule: A string to convert to a rule.
866
867
868 Actions
869 -------
870
871 :ref:`RulesIntro` need to be combined with an action for them to actually do something with the matched packets.
872 Some actions allow further processing of rules, this is noted in their description.
873 The following actions exist.
874
875 .. function:: AllowAction()
876
877 Let these packets go through.
878
879 .. function:: AllowResponseAction()
880
881 Let these packets go through.
882
883 .. function:: ContinueAction(action)
884
885 .. versionadded:: 1.4.0
886
887 Execute the specified action and override its return with None, making it possible to continue the processing.
888 Subsequent rules are processed after this action.
889
890 :param int action: Any other action
891
892 .. function:: DelayAction(milliseconds)
893
894 Delay the response by the specified amount of milliseconds (UDP-only).
895 Subsequent rules are processed after this action.
896
897 :param int milliseconds: The amount of milliseconds to delay the response
898
899 .. function:: DelayResponseAction(milliseconds)
900
901 Delay the response by the specified amount of milliseconds (UDP-only).
902 Subsequent rules are processed after this action.
903
904 :param int milliseconds: The amount of milliseconds to delay the response
905
906 .. function:: DisableECSAction()
907
908 Disable the sending of ECS to the backend.
909 Subsequent rules are processed after this action.
910
911 .. function:: DisableValidationAction()
912
913 Set the CD bit in the query and let it go through.
914
915 .. function:: DnstapLogAction(identity, logger[, alterFunction])
916
917 .. versionadded:: 1.3.0
918
919 Send the the current query to a remote logger as a :doc:`dnstap <reference/dnstap>` message.
920 ``alterFunction`` is a callback, receiving a :class:`DNSQuestion` and a :class:`DnstapMessage`, that can be used to modify the message.
921 Subsequent rules are processed after this action.
922
923 :param string identity: Server identity to store in the dnstap message
924 :param logger: The :func:`FrameStreamLogger <newFrameStreamUnixLogger>` or :func:`RemoteLogger <newRemoteLogger>` object to write to
925 :param alterFunction: A Lua function to alter the message before sending
926
927 .. function:: DnstapLogResponseAction(identity, logger[, alterFunction])
928
929 .. versionadded:: 1.3.0
930
931 Send the the current response to a remote logger as a :doc:`dnstap <reference/dnstap>` message.
932 ``alterFunction`` is a callback, receiving a :class:`DNSQuestion` and a :class:`DnstapMessage`, that can be used to modify the message.
933 Subsequent rules are processed after this action.
934
935 :param string identity: Server identity to store in the dnstap message
936 :param logger: The :func:`FrameStreamLogger <newFrameStreamUnixLogger>` or :func:`RemoteLogger <newRemoteLogger>` object to write to
937 :param alterFunction: A Lua function to alter the message before sending
938
939 .. function:: DropAction()
940
941 Drop the packet.
942
943 .. function:: DropResponseAction()
944
945 Drop the packet.
946
947 .. function:: ECSOverrideAction(override)
948
949 Whether an existing EDNS Client Subnet value should be overridden (true) or not (false).
950 Subsequent rules are processed after this action.
951
952 :param bool override: Whether or not to override ECS value
953
954 .. function:: ECSPrefixLengthAction(v4, v6)
955
956 Set the ECS prefix length.
957 Subsequent rules are processed after this action.
958
959 :param int v4: The IPv4 netmask length
960 :param int v6: The IPv6 netmask length
961
962
963 .. function:: ERCodeAction(rcode [, options])
964
965 .. versionadded:: 1.4.0
966
967 .. versionchanged:: 1.5.0
968 Added the optional parameter ``options``.
969
970 Reply immediately by turning the query into a response with the specified EDNS extended ``rcode``.
971 ``rcode`` can be specified as an integer or as one of the built-in :ref:`DNSRCode`.
972
973 :param int rcode: The extended RCODE to respond with.
974 :param table options: A table with key: value pairs with options.
975
976 Options:
977
978 * ``aa``: bool - Set the AA bit to this value (true means the bit is set, false means it's cleared). Default is to clear it.
979 * ``ad``: bool - Set the AD bit to this value (true means the bit is set, false means it's cleared). Default is to clear it.
980 * ``ra``: bool - Set the RA bit to this value (true means the bit is set, false means it's cleared). Default is to copy the value of the RD bit from the incoming query.
981
982 .. function:: HTTPStatusAction(status, body, contentType="" [, options])
983
984 .. versionadded:: 1.4.0
985
986 .. versionchanged:: 1.5.0
987 Added the optional parameter ``options``.
988
989 Return an HTTP response with a status code of ''status''. For HTTP redirects, ''body'' should be the redirect URL.
990
991 :param int status: The HTTP status code to return.
992 :param string body: The body of the HTTP response, or a URL if the status code is a redirect (3xx).
993 :param string contentType: The HTTP Content-Type header to return for a 200 response, ignored otherwise. Default is ''application/dns-message''.
994 :param table options: A table with key: value pairs with options.
995
996 Options:
997
998 * ``aa``: bool - Set the AA bit to this value (true means the bit is set, false means it's cleared). Default is to clear it.
999 * ``ad``: bool - Set the AD bit to this value (true means the bit is set, false means it's cleared). Default is to clear it.
1000 * ``ra``: bool - Set the RA bit to this value (true means the bit is set, false means it's cleared). Default is to copy the value of the RD bit from the incoming query.
1001
1002 .. function:: KeyValueStoreLookupAction(kvs, lookupKey, destinationTag)
1003
1004 .. versionadded:: 1.4.0
1005
1006 As of 1.4.0, this code is considered experimental.
1007
1008 Does a lookup into the key value store referenced by 'kvs' using the key returned by 'lookupKey',
1009 and storing the result if any into the tag named 'destinationTag'.
1010 The store can be a CDB (:func:`newCDBKVStore`) or a LMDB database (:func:`newLMDBKVStore`).
1011 The key can be based on the qname (:func:`KeyValueLookupKeyQName` and :func:`KeyValueLookupKeySuffix`),
1012 source IP (:func:`KeyValueLookupKeySourceIP`) or the value of an existing tag (:func:`KeyValueLookupKeyTag`).
1013
1014 :param KeyValueStore kvs: The key value store to query
1015 :param KeyValueLookupKey lookupKey: The key to use for the lookup
1016 :param string destinationTag: The name of the tag to store the result into
1017
1018 .. function:: LogAction([filename[, binary[, append[, buffered[, verboseOnly[, includeTimestamp]]]]]])
1019
1020 .. versionchanged:: 1.4.0
1021 Added the optional parameters ``verboseOnly`` and ``includeTimestamp``, made ``filename`` optional.
1022
1023 Log a line for each query, to the specified ``file`` if any, to the console (require verbose) if the empty string is given as filename.
1024
1025 If an empty string is supplied in the file name, the logging is done to stdout, and only in verbose mode by default. This can be changed by setting ``verboseOnly`` to false.
1026
1027 When logging to a file, the ``binary`` optional parameter specifies whether we log in binary form (default) or in textual form. Before 1.4.0 the binary log format only included the qname and qtype. Since 1.4.0 it includes an optional timestamp, the query ID, qname, qtype, remote address and port.
1028
1029 The ``append`` optional parameter specifies whether we open the file for appending or truncate each time (default).
1030 The ``buffered`` optional parameter specifies whether writes to the file are buffered (default) or not.
1031
1032 Subsequent rules are processed after this action.
1033
1034 :param string filename: File to log to. Set to an empty string to log to the normal stdout log, this only works when ``-v`` is set on the command line.
1035 :param bool binary: Do binary logging. Default true
1036 :param bool append: Append to the log. Default false
1037 :param bool buffered: Use buffered I/O. Default true
1038 :param bool verboseOnly: Whether to log only in verbose mode when logging to stdout. Default is true
1039 :param bool includeTimestamp: Whether to include a timestamp for every entry. Default is false
1040
1041 .. function:: LogResponseAction([filename[, append[, buffered[, verboseOnly[, includeTimestamp]]]]]])
1042
1043 .. versionadded:: 1.5.0
1044
1045 Log a line for each response, to the specified ``file`` if any, to the console (require verbose) if the empty string is given as filename.
1046
1047 If an empty string is supplied in the file name, the logging is done to stdout, and only in verbose mode by default. This can be changed by setting ``verboseOnly`` to false.
1048
1049 The ``append`` optional parameter specifies whether we open the file for appending or truncate each time (default).
1050 The ``buffered`` optional parameter specifies whether writes to the file are buffered (default) or not.
1051
1052 Subsequent rules are processed after this action.
1053
1054 :param string filename: File to log to. Set to an empty string to log to the normal stdout log, this only works when ``-v`` is set on the command line.
1055 :param bool append: Append to the log. Default false
1056 :param bool buffered: Use buffered I/O. Default true
1057 :param bool verboseOnly: Whether to log only in verbose mode when logging to stdout. Default is true
1058 :param bool includeTimestamp: Whether to include a timestamp for every entry. Default is false
1059
1060 .. function:: LuaAction(function)
1061
1062 Invoke a Lua function that accepts a :class:`DNSQuestion`.
1063
1064 The ``function`` should return a :ref:`DNSAction`. If the Lua code fails, ServFail is returned.
1065
1066 :param string function: the name of a Lua function
1067
1068 .. function:: LuaResponseAction(function)
1069
1070 Invoke a Lua function that accepts a :class:`DNSResponse`.
1071
1072 The ``function`` should return a :ref:`DNSResponseAction`. If the Lua code fails, ServFail is returned.
1073
1074 :param string function: the name of a Lua function
1075
1076 .. function:: MacAddrAction(option)
1077
1078 Add the source MAC address to the query as EDNS0 option ``option``.
1079 This action is currently only supported on Linux.
1080 Subsequent rules are processed after this action.
1081
1082 :param int option: The EDNS0 option number
1083
1084 .. function:: NoneAction()
1085
1086 Does nothing.
1087 Subsequent rules are processed after this action.
1088
1089 .. function:: NoRecurseAction()
1090
1091 Strip RD bit from the question, let it go through.
1092 Subsequent rules are processed after this action.
1093
1094 .. function:: PoolAction(poolname)
1095
1096 Send the packet into the specified pool.
1097
1098 :param string poolname: The name of the pool
1099
1100 .. function:: QPSAction(maxqps)
1101
1102 Drop a packet if it does exceed the ``maxqps`` queries per second limits.
1103 Letting the subsequent rules apply otherwise.
1104
1105 :param int maxqps: The QPS limit
1106
1107 .. function:: QPSPoolAction(maxqps, poolname)
1108
1109 Send the packet into the specified pool only if it does not exceed the ``maxqps`` queries per second limits.
1110 Letting the subsequent rules apply otherwise.
1111
1112 :param int maxqps: The QPS limit for that pool
1113 :param string poolname: The name of the pool
1114
1115 .. function:: RCodeAction(rcode [, options])
1116
1117 .. versionchanged:: 1.5.0
1118 Added the optional parameter ``options``.
1119
1120 Reply immediately by turning the query into a response with the specified ``rcode``.
1121 ``rcode`` can be specified as an integer or as one of the built-in :ref:`DNSRCode`.
1122
1123 :param int rcode: The RCODE to respond with.
1124 :param table options: A table with key: value pairs with options.
1125
1126 Options:
1127
1128 * ``aa``: bool - Set the AA bit to this value (true means the bit is set, false means it's cleared). Default is to clear it.
1129 * ``ad``: bool - Set the AD bit to this value (true means the bit is set, false means it's cleared). Default is to clear it.
1130 * ``ra``: bool - Set the RA bit to this value (true means the bit is set, false means it's cleared). Default is to copy the value of the RD bit from the incoming query.
1131
1132 .. function:: RemoteLogAction(remoteLogger[, alterFunction [, options]])
1133
1134 .. versionchanged:: 1.3.0
1135 ``options`` optional parameter added.
1136
1137 .. versionchanged:: 1.4.0
1138 ``ipEncryptKey`` optional key added to the options table.
1139
1140 Send the content of this query to a remote logger via Protocol Buffer.
1141 ``alterFunction`` is a callback, receiving a :class:`DNSQuestion` and a :class:`DNSDistProtoBufMessage`, that can be used to modify the Protocol Buffer content, for example for anonymization purposes.
1142 Subsequent rules are processed after this action.
1143
1144 :param string remoteLogger: The :func:`remoteLogger <newRemoteLogger>` object to write to
1145 :param string alterFunction: Name of a function to modify the contents of the logs before sending
1146 :param table options: A table with key: value pairs.
1147
1148 Options:
1149
1150 * ``serverID=""``: str - Set the Server Identity field.
1151 * ``ipEncryptKey=""``: str - A key, that can be generated via the :func:`makeIPCipherKey` function, to encrypt the IP address of the requestor for anonymization purposes. The encryption is done using ipcrypt for IPv4 and a 128-bit AES ECB operation for IPv6.
1152
1153 .. function:: RemoteLogResponseAction(remoteLogger[, alterFunction[, includeCNAME [, options]]])
1154
1155 .. versionchanged:: 1.3.0
1156 ``options`` optional parameter added.
1157
1158 .. versionchanged:: 1.4.0
1159 ``ipEncryptKey`` optional key added to the options table.
1160
1161 Send the content of this response to a remote logger via Protocol Buffer.
1162 ``alterFunction`` is the same callback that receiving a :class:`DNSQuestion` and a :class:`DNSDistProtoBufMessage`, that can be used to modify the Protocol Buffer content, for example for anonymization purposes.
1163 ``includeCNAME`` indicates whether CNAME records inside the response should be parsed and exported.
1164 The default is to only exports A and AAAA records.
1165 Subsequent rules are processed after this action.
1166
1167 :param string remoteLogger: The :func:`remoteLogger <newRemoteLogger>` object to write to
1168 :param string alterFunction: Name of a function to modify the contents of the logs before sending
1169 :param bool includeCNAME: Whether or not to parse and export CNAMEs. Default false
1170 :param table options: A table with key: value pairs.
1171
1172 Options:
1173
1174 * ``serverID=""``: str - Set the Server Identity field.
1175 * ``ipEncryptKey=""``: str - A key, that can be generated via the :func:`makeIPCipherKey` function, to encrypt the IP address of the requestor for anonymization purposes. The encryption is done using ipcrypt for IPv4 and a 128-bit AES ECB operation for IPv6.
1176
1177 .. function:: SetECSAction(v4 [, v6])
1178
1179 .. versionadded:: 1.3.1
1180
1181 Set the ECS prefix and prefix length sent to backends to an arbitrary value.
1182 If both IPv4 and IPv6 masks are supplied the IPv4 one will be used for IPv4 clients
1183 and the IPv6 one for IPv6 clients. Otherwise the first mask is used for both, and
1184 can actually be an IPv6 mask.
1185 Subsequent rules are processed after this action.
1186
1187 :param string v4: The IPv4 netmask, for example "192.0.2.1/32"
1188 :param string v6: The IPv6 netmask, if any
1189
1190 .. function:: SkipCacheAction()
1191
1192 Don't lookup the cache for this query, don't store the answer.
1193
1194 .. function:: SNMPTrapAction([message])
1195
1196 Send an SNMP trap, adding the optional ``message`` string as the query description.
1197 Subsequent rules are processed after this action.
1198
1199 :param string message: The message to include
1200
1201 .. function:: SNMPTrapResponseAction([message])
1202
1203 Send an SNMP trap, adding the optional ``message`` string as the query description.
1204 Subsequent rules are processed after this action.
1205
1206 :param string message: The message to include
1207
1208 .. function:: SpoofAction(ip [, options])
1209 SpoofAction(ips [, options])
1210
1211 .. versionchanged:: 1.5.0
1212 Added the optional parameter ``options``.
1213
1214 Forge a response with the specified IPv4 (for an A query) or IPv6 (for an AAAA) addresses.
1215 If you specify multiple addresses, all that match the query type (A, AAAA or ANY) will get spoofed in.
1216
1217 :param string ip: An IPv4 and/or IPv6 address to spoof
1218 :param {string} ips: A table of IPv4 and/or IPv6 addresses to spoof
1219 :param table options: A table with key: value pairs with options.
1220
1221 Options:
1222
1223 * ``aa``: bool - Set the AA bit to this value (true means the bit is set, false means it's cleared). Default is to clear it.
1224 * ``ad``: bool - Set the AD bit to this value (true means the bit is set, false means it's cleared). Default is to clear it.
1225 * ``ra``: bool - Set the RA bit to this value (true means the bit is set, false means it's cleared). Default is to copy the value of the RD bit from the incoming query.
1226 * ``ttl``: int - The TTL of the record.
1227
1228 .. function:: SpoofCNAMEAction(cname [, options])
1229
1230 .. versionchanged:: 1.5.0
1231 Added the optional parameter ``options``.
1232
1233 Forge a response with the specified CNAME value.
1234
1235 :param string cname: The name to respond with
1236 :param table options: A table with key: value pairs with options.
1237
1238 Options:
1239
1240 * ``aa``: bool - Set the AA bit to this value (true means the bit is set, false means it's cleared). Default is to clear it.
1241 * ``ad``: bool - Set the AD bit to this value (true means the bit is set, false means it's cleared). Default is to clear it.
1242 * ``ra``: bool - Set the RA bit to this value (true means the bit is set, false means it's cleared). Default is to copy the value of the RD bit from the incoming query.
1243 * ``ttl``: int - The TTL of the record.
1244
1245 .. function:: SpoofRawAction(rawAnswer [, options])
1246
1247 .. versionadded:: 1.5.0
1248
1249 Forge a response with the specified raw bytes as record data.
1250 For example, for a TXT record of "aaa" "bbbb": SpoofRawAction("\003aaa\004bbbb")
1251
1252 :param string rawAnswer: The raw record data
1253 :param table options: A table with key: value pairs with options.
1254
1255 Options:
1256
1257 * ``aa``: bool - Set the AA bit to this value (true means the bit is set, false means it's cleared). Default is to clear it.
1258 * ``ad``: bool - Set the AD bit to this value (true means the bit is set, false means it's cleared). Default is to clear it.
1259 * ``ra``: bool - Set the RA bit to this value (true means the bit is set, false means it's cleared). Default is to copy the value of the RD bit from the incoming query.
1260 * ``ttl``: int - The TTL of the record.
1261
1262 .. function:: TagAction(name, value)
1263
1264 .. versionadded:: 1.3.0
1265
1266 Associate a tag named ``name`` with a value of ``value`` to this query, that will be passed on to the response.
1267 Subsequent rules are processed after this action.
1268
1269 :param string name: The name of the tag to set
1270 :param string value: The value of the tag
1271
1272 .. function:: TagResponseAction(name, value)
1273
1274 .. versionadded:: 1.3.0
1275
1276 Associate a tag named ``name`` with a value of ``value`` to this response.
1277 Subsequent rules are processed after this action.
1278
1279 :param string name: The name of the tag to set
1280 :param string value: The value of the tag
1281
1282 .. function:: TCAction()
1283
1284 Create answer to query with TC and RD bits set, to force the client to TCP.
1285
1286 .. function:: TeeAction(remote[, addECS])
1287
1288 Send copy of query to ``remote``, keep stats on responses.
1289 If ``addECS`` is set to true, EDNS Client Subnet information will be added to the query.
1290
1291 :param string remote: An IP:PORT conbination to send the copied queries to
1292 :param bool addECS: Whether or not to add ECS information. Default false
1293
1294 .. function:: TempFailureCacheTTLAction(ttl)
1295
1296 Set the cache TTL to use for ServFail and Refused replies. TTL is not applied for successful replies.
1297
1298 :param int ttl: Cache TTL for temporary failure replies