]>
Commit | Line | Data |
---|---|---|
20d81666 PL |
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 | ||
832c1792 | 33 | addAction(MaxQPSIPRule(5, 32, 48), DelayAction(100)) |
20d81666 | 34 | |
b0570525 | 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). |
20d81666 PL |
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 | ||
832c1792 RG |
79 | .. deprecated:: 1.2.0 |
80 | ||
7488f983 RG |
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:: | |
20d81666 | 83 | |
09b45aa8 PD |
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. | |
20d81666 PL |
88 | |
89 | .. function:: addDelay(DNSrule, delay) | |
90 | ||
832c1792 RG |
91 | .. deprecated:: 1.2.0 |
92 | ||
20d81666 | 93 | Delay the query for ``delay`` milliseconds before sending to a backend. |
7488f983 | 94 | This function is deprecated as of 1.2.0 and will be removed in 1.3.0, please use instead: |
832c1792 RG |
95 | |
96 | addAction(DNSRule, DelayAction(delay)) | |
20d81666 PL |
97 | |
98 | :param DNSRule: The DNSRule to match traffic | |
99 | :param int delay: The delay time in milliseconds. | |
100 | ||
101 | .. function:: addDisableValidationRule(DNSrule) | |
102 | ||
832c1792 RG |
103 | .. deprecated:: 1.2.0 |
104 | ||
20d81666 | 105 | Set the CD (Checking Disabled) flag to 1 for all queries matching the DNSRule. |
7488f983 | 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. |
20d81666 PL |
107 | |
108 | .. function:: addDomainBlock(domain) | |
109 | ||
832c1792 RG |
110 | .. deprecated:: 1.2.0 |
111 | ||
20d81666 | 112 | Drop all queries for ``domain`` and all names below it. |
7488f983 | 113 | Deprecated as of 1.2.0 and will be removed in 1.3.0, please use instead: |
832c1792 RG |
114 | |
115 | addAction(domain, DropAction()) | |
20d81666 PL |
116 | |
117 | :param string domain: The domain name to block | |
118 | ||
119 | .. function:: addDomainSpoof(domain, IPv4[, IPv6]) | |
120 | addDomainSpoof(domain, {IP[,...]}) | |
121 | ||
832c1792 RG |
122 | .. deprecated:: 1.2.0 |
123 | ||
20d81666 | 124 | Generate answers for A/AAAA/ANY queries. |
7488f983 | 125 | This function is deprecated as of 1.2.0 and will be removed in 1.3.0, please use: |
832c1792 RG |
126 | |
127 | addAction(domain, SpoofAction({IP[,...]})) | |
128 | ||
129 | or: | |
130 | ||
131 | addAction(domain, SpoofAction(IPv4[, IPv6])) | |
20d81666 PL |
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 | ||
832c1792 RG |
140 | .. deprecated:: 1.2.0 |
141 | ||
7488f983 | 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: |
832c1792 RG |
143 | |
144 | addAction(domain, SpoofCNAMEAction(cname)) | |
20d81666 PL |
145 | |
146 | :param string domain: Domain name to spoof for | |
147 | :param string cname: Domain name to add CNAME to | |
148 | ||
e33e53fc CH |
149 | .. function:: addLuaAction(DNSrule, function [, options]) |
150 | ||
151 | .. versionchanged:: 1.3.0 | |
152 | Added the optional parameter ``options``. | |
20d81666 | 153 | |
87cb3110 PL |
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 | ||
955de53b PD |
157 | .. deprecated:: 1.4.0 |
158 | Removed in 1.4.0, use :func:`LuaAction` with :func:`addAction` instead. | |
159 | ||
20d81666 PL |
160 | Invoke a Lua function that accepts a :class:`DNSQuestion`. |
161 | This function works similar to using :func:`LuaAction`. | |
fbd6b779 | 162 | The ``function`` should return both a :ref:`DNSAction` and its argument `rule`. The `rule` is used as an argument |
87cb3110 PL |
163 | of the following :ref:`DNSAction`: `DNSAction.Spoof`, `DNSAction.Pool` and `DNSAction.Delay`. |
164 | If the Lua code fails, ServFail is returned. | |
20d81666 PL |
165 | |
166 | :param DNSRule: match queries based on this rule | |
167 | :param string function: the name of a Lua function | |
e33e53fc CH |
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. | |
20d81666 | 173 | |
fbd6b779 CHB |
174 | :: |
175 | ||
b774d943 | 176 | function luaaction(dq) |
fc16b739 | 177 | if(dq.qtype==DNSQType.NAPTR) |
fbd6b779 CHB |
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 | ||
b774d943 | 186 | addLuaAction(AllRule(), luaaction) |
fbd6b779 | 187 | |
e33e53fc CH |
188 | .. function:: addLuaResponseAction(DNSrule, function [, options]) |
189 | ||
190 | .. versionchanged:: 1.3.0 | |
191 | Added the optional parameter ``options``. | |
20d81666 | 192 | |
87cb3110 PL |
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 | ||
955de53b PD |
196 | .. deprecated:: 1.4.0 |
197 | Removed in 1.4.0, use :func:`LuaResponseAction` with :func:`addResponseAction` instead. | |
198 | ||
5f23eb98 CH |
199 | Invoke a Lua function that accepts a :class:`DNSResponse`. |
200 | This function works similar to using :func:`LuaResponseAction`. | |
fbd6b779 | 201 | The ``function`` should return both a :ref:`DNSResponseAction` and its argument `rule`. The `rule` is used as an argument |
87cb3110 PL |
202 | of the `DNSResponseAction.Delay`. |
203 | If the Lua code fails, ServFail is returned. | |
20d81666 PL |
204 | |
205 | :param DNSRule: match queries based on this rule | |
206 | :param string function: the name of a Lua function | |
e33e53fc CH |
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. | |
20d81666 PL |
212 | |
213 | .. function:: addNoRecurseRule(DNSrule) | |
214 | ||
832c1792 RG |
215 | .. deprecated:: 1.2.0 |
216 | ||
20d81666 | 217 | Clear the RD flag for all queries matching the rule. |
7488f983 | 218 | This function is deprecated as of 1.2.0 and will be removed in 1.3.0, please use: |
832c1792 RG |
219 | |
220 | addAction(DNSRule, NoRecurseAction()) | |
20d81666 PL |
221 | |
222 | :param DNSRule: match queries based on this rule | |
223 | ||
224 | .. function:: addPoolRule(DNSRule, pool) | |
225 | ||
832c1792 RG |
226 | .. deprecated:: 1.2.0 |
227 | ||
20d81666 PL |
228 | Send queries matching the first argument to the pool ``pool``. |
229 | e.g.:: | |
230 | ||
231 | addPoolRule("example.com", "myPool") | |
232 | ||
7488f983 | 233 | This function is deprecated as of 1.2.0 and will be removed in 1.3.0, this is equivalent to:: |
20d81666 PL |
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 | ||
832c1792 RG |
242 | .. deprecated:: 1.2.0 |
243 | ||
20d81666 PL |
244 | Limit queries matching the DNSRule to ``limit`` queries per second. |
245 | All queries over the limit are dropped. | |
7488f983 | 246 | This function is deprecated as of 1.2.0 and will be removed in 1.3.0, please use: |
832c1792 | 247 | |
8499caaf | 248 | addAction(DNSRule, QPSAction(limit)) |
20d81666 PL |
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 | ||
832c1792 RG |
255 | .. deprecated:: 1.2.0 |
256 | ||
20d81666 | 257 | Send at most ``limit`` queries/s for this pool, letting the subsequent rules apply otherwise. |
7488f983 | 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:: |
20d81666 PL |
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 | ||
8499caaf RG |
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)) | |
20d81666 PL |
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 | ||
4d5959e6 RG |
283 | .. function:: addAction(DNSrule, action [, options]) |
284 | ||
285 | .. versionchanged:: 1.3.0 | |
286 | Added the optional parameter ``options``. | |
20d81666 PL |
287 | |
288 | Add a Rule and Action to the existing rules. | |
289 | ||
be59738a | 290 | :param DNSrule rule: A DNSRule, e.g. an :func:`AllRule` or a compounded bunch of rules using e.g. :func:`AndRule` |
20d81666 | 291 | :param action: The action to take |
4d5959e6 RG |
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. | |
20d81666 PL |
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 | ||
4d5959e6 RG |
316 | .. function:: newRuleAction(rule, action[, options]) |
317 | ||
318 | .. versionchanged:: 1.3.0 | |
319 | Added the optional parameter ``options``. | |
20d81666 PL |
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 | |
4d5959e6 RG |
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. | |
20d81666 PL |
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 | ||
3a5a3376 CHB |
337 | .. function:: showRules([options]) |
338 | ||
339 | .. versionchanged:: 1.3.0 | |
340 | ``options`` optional parameter added | |
4d5959e6 RG |
341 | |
342 | Show all defined rules for queries, optionally displaying their UUIDs. | |
20d81666 | 343 | |
3a5a3376 CHB |
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. | |
20d81666 PL |
350 | |
351 | .. function:: topRule() | |
352 | ||
353 | Move the last rule to the first position. | |
354 | ||
dcdc32c2 | 355 | .. function:: rmRule(id) |
20d81666 | 356 | |
4d5959e6 RG |
357 | .. versionchanged:: 1.3.0 |
358 | ``id`` can now be an UUID. | |
20d81666 | 359 | |
4d5959e6 RG |
360 | Remove rule ``id``. |
361 | ||
362 | :param int id: The UUID of the rule to remove if ``id`` is an UUID, its position otherwise | |
20d81666 PL |
363 | |
364 | For Rules related to responses: | |
365 | ||
4d5959e6 RG |
366 | .. function:: addResponseAction(DNSRule, action [, options]) |
367 | ||
368 | .. versionchanged:: 1.3.0 | |
369 | Added the optional parameter ``options``. | |
20d81666 PL |
370 | |
371 | Add a Rule and Action for responses to the existing rules. | |
372 | ||
be59738a | 373 | :param DNSRule: A DNSRule, e.g. an :func:`AllRule` or a compounded bunch of rules using e.g. :func:`AndRule` |
20d81666 | 374 | :param action: The action to take |
4d5959e6 RG |
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. | |
20d81666 PL |
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 | ||
dcdc32c2 | 389 | .. function:: rmResponseRule(id) |
20d81666 | 390 | |
4d5959e6 RG |
391 | .. versionchanged:: 1.3.0 |
392 | ``id`` can now be an UUID. | |
20d81666 | 393 | |
4d5959e6 RG |
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 | ||
3a5a3376 CHB |
398 | .. function:: showResponseRules([options]) |
399 | ||
400 | .. versionchanged:: 1.3.0 | |
401 | ``options`` optional parameter added | |
20d81666 | 402 | |
4d5959e6 | 403 | Show all defined response rules, optionally displaying their UUIDs. |
20d81666 | 404 | |
3a5a3376 CHB |
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. | |
20d81666 PL |
411 | |
412 | .. function:: topResponseRule() | |
413 | ||
414 | Move the last response rule to the first position. | |
415 | ||
2d4783a8 | 416 | Functions for manipulating Cache Hit Respone Rules: |
20d81666 | 417 | |
2d4783a8 | 418 | .. function:: addCacheHitResponseAction(DNSRule, action [, options]) |
20d81666 PL |
419 | |
420 | .. versionadded:: 1.2.0 | |
421 | ||
4d5959e6 RG |
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. | |
20d81666 | 426 | |
be59738a | 427 | :param DNSRule: A DNSRule, e.g. an :func:`AllRule` or a compounded bunch of rules using e.g. :func:`AndRule` |
20d81666 | 428 | :param action: The action to take |
4d5959e6 RG |
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. | |
20d81666 PL |
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 | ||
4d5959e6 | 445 | .. function:: rmCacheHitResponseRule(id) |
20d81666 PL |
446 | |
447 | .. versionadded:: 1.2.0 | |
448 | ||
4d5959e6 RG |
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 | |
20d81666 | 453 | |
3a5a3376 | 454 | .. function:: showCacheHitResponseRules([options]) |
20d81666 PL |
455 | |
456 | .. versionadded:: 1.2.0 | |
457 | ||
3a5a3376 CHB |
458 | .. versionchanged:: 1.3.0 |
459 | ``options`` optional parameter added | |
460 | ||
4d5959e6 RG |
461 | Show all defined cache hit response rules, optionally displaying their UUIDs. |
462 | ||
3a5a3376 CHB |
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. | |
20d81666 PL |
469 | |
470 | .. function:: topCacheHitResponseRule() | |
471 | ||
472 | .. versionadded:: 1.2.0 | |
473 | ||
474 | Move the last cache hit response rule to the first position. | |
475 | ||
2d4783a8 CH |
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 | ||
be59738a | 484 | :param DNSRule: A DNSRule, e.g. an :func:`AllRule` or a compounded bunch of rules using e.g. :func:`AndRule` |
2d4783a8 CH |
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 | ||
3a5a3376 | 505 | .. function:: showSelfAnsweredResponseRules([options]) |
2d4783a8 CH |
506 | |
507 | .. versionadded:: 1.3.0 | |
508 | ||
509 | Show all defined self answered response rules, optionally displaying their UUIDs. | |
510 | ||
3a5a3376 CHB |
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. | |
2d4783a8 CH |
517 | |
518 | .. function:: topSelfAnsweredResponseRule() | |
519 | ||
520 | .. versionadded:: 1.3.0 | |
521 | ||
522 | Move the last self answered response rule to the first position. | |
523 | ||
20d81666 PL |
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 | ||
ca567c4b RG |
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 | ||
9ba32868 | 578 | .. function:: HTTPHeaderRule(name, regex) |
6ec3dde9 | 579 | |
9ba32868 RG |
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 | ||
56f2845e | 587 | .. function:: HTTPPathRegexRule(regex) |
6ec3dde9 | 588 | |
56f2845e RG |
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'. | |
28b56482 | 592 | Only valid DNS over HTTPS queries are matched. If you want to match all HTTP queries, see :meth:`DOHFrontend.setResponsesMap` instead. |
56f2845e RG |
593 | |
594 | :param str regex: The regex to match on | |
595 | ||
9ba32868 | 596 | .. function:: HTTPPathRule(path) |
6ec3dde9 | 597 | |
9ba32868 RG |
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'. | |
28b56482 | 601 | Only valid DNS over HTTPS queries are matched. If you want to match all HTTP queries, see :meth:`DOHFrontend.setResponsesMap` instead. |
9ba32868 RG |
602 | |
603 | :param str path: The exact HTTP path to match on | |
604 | ||
73e1f0c5 | 605 | .. function:: KeyValueStoreLookupRule(kvs, lookupKey) |
6ec3dde9 | 606 | |
d81a1d9c RG |
607 | .. versionadded:: 1.4.0 |
608 | ||
609 | As of 1.4.0, this code is considered experimental. | |
73e1f0c5 RG |
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 | ||
b774d943 RG |
619 | .. function:: LuaFFIRule(function) |
620 | ||
621 | .. versionadded:: 1.5.0 | |
622 | ||
623 | Invoke a Lua FFI function that accepts a pointer to a ``dnsdist_ffi_dnsquestion_t`` object, whose bindings are defined in ``dnsdist-lua-ffi.hh``. | |
624 | ||
625 | The ``function`` should return true if the query matches, or false otherwise. If the Lua code fails, false is returned. | |
626 | ||
627 | :param string function: the name of a Lua function | |
628 | ||
8eb84a56 RG |
629 | .. function:: LuaRule(function) |
630 | ||
631 | .. versionadded:: 1.5.0 | |
632 | ||
633 | Invoke a Lua function that accepts a :class:`DNSQuestion` object. | |
634 | ||
635 | The ``function`` should return true if the query matches, or false otherwise. If the Lua code fails, false is returned. | |
636 | ||
637 | :param string function: the name of a Lua function | |
638 | ||
05f4003d | 639 | .. function:: MaxQPSIPRule(qps[, v4Mask[, v6Mask[, burst[, expiration[, cleanupDelay[, scanFraction]]]]]]) |
3a4c3e1e | 640 | |
67ce0bdd | 641 | .. versionchanged:: 1.3.1 |
05f4003d | 642 | Added the optional parameters ``expiration``, ``cleanupDelay`` and ``scanFraction``. |
20d81666 | 643 | |
67ce0bdd RG |
644 | Matches traffic for a subnet specified by ``v4Mask`` or ``v6Mask`` exceeding ``qps`` queries per second up to ``burst`` allowed. |
645 | This rule keeps track of QPS by netmask or source IP. This state is cleaned up regularly if ``cleanupDelay`` is greater than zero, | |
646 | removing existing netmasks or IP addresses that have not been seen in the last ``expiration`` seconds. | |
20d81666 PL |
647 | |
648 | :param int qps: The number of queries per second allowed, above this number traffic is matched | |
649 | :param int v4Mask: The IPv4 netmask to match on. Default is 32 (the whole address) | |
650 | :param int v6Mask: The IPv6 netmask to match on. Default is 64 | |
01270388 | 651 | :param int burst: The number of burstable queries per second allowed. Default is same as qps |
67ce0bdd RG |
652 | :param int expiration: How long to keep netmask or IP addresses after they have last been seen, in seconds. Default is 300 |
653 | :param int cleanupDelay: The number of seconds between two cleanups. Default is 60 | |
05f4003d | 654 | :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% |
20d81666 PL |
655 | |
656 | .. function:: MaxQPSRule(qps) | |
657 | ||
e24d817d | 658 | 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. |
20d81666 PL |
659 | This can be used to enforce a global QPS limit. |
660 | ||
e24d817d | 661 | :param int qps: The number of queries per second allowed, above this number the traffic is **not** matched anymore |
20d81666 | 662 | |
b7fa60c9 PL |
663 | .. function:: NetmaskGroupRule(nmg[, src[, quiet]]) |
664 | ||
665 | .. versionchanged:: 1.4.0 | |
666 | ``quiet`` parameter added | |
20d81666 PL |
667 | |
668 | Matches traffic from/to the network range specified in ``nmg``. | |
669 | ||
670 | Set the ``src`` parameter to false to match ``nmg`` against destination address instead of source address. | |
3a5a3376 | 671 | This can be used to differentiate between clients |
20d81666 PL |
672 | |
673 | :param NetMaskGroup nmg: The NetMaskGroup to match on | |
674 | :param bool src: Whether to match source or destination address of the packet. Defaults to true (matches source) | |
0d70c2c6 | 675 | :param bool quiet: Do not display the list of matched netmasks in Rules. Default is false. |
20d81666 PL |
676 | |
677 | .. function:: OpcodeRule(code) | |
678 | ||
679 | Matches queries with opcode ``code``. | |
827b5ca3 | 680 | ``code`` can be directly specified as an integer, or one of the :ref:`built-in DNSOpcodes <DNSOpcode>`. |
20d81666 PL |
681 | |
682 | :param int code: The opcode to match | |
683 | ||
d3826006 | 684 | .. function:: ProbaRule(probability) |
685 | ||
686 | .. versionadded:: 1.3.0 | |
687 | ||
688 | Matches queries with a given probability. 1.0 means "always" | |
689 | ||
690 | :param double probability: Probability of a match | |
691 | ||
20d81666 PL |
692 | .. function:: QClassRule(qclass) |
693 | ||
694 | Matches queries with the specified ``qclass``. | |
fe77446e | 695 | ``class`` can be specified as an integer or as one of the built-in :ref:`DNSClass`. |
20d81666 PL |
696 | |
697 | :param int qclass: The Query Class to match on | |
698 | ||
cf68eefa | 699 | .. function:: QNameRule(qname) |
20d81666 PL |
700 | |
701 | .. versionadded:: 1.2.0 | |
702 | ||
703 | Matches queries with the specified qname exactly. | |
704 | ||
705 | :param string qname: Qname to match | |
706 | ||
9f618bcc | 707 | .. function:: QNameSetRule(set) |
fe77446e RG |
708 | |
709 | .. versionadded:: 1.4.0 | |
710 | ||
711 | Matches if the set contains exact qname. | |
9f618bcc | 712 | |
cc0e7aa9 AD |
713 | To match subdomain names, see :func:`SuffixMatchNodeRule`. |
714 | ||
715 | :param DNSNameSet set: Set with qnames. | |
9f618bcc | 716 | |
20d81666 PL |
717 | .. function:: QNameLabelsCountRule(min, max) |
718 | ||
719 | Matches if the qname has less than ``min`` or more than ``max`` labels. | |
720 | ||
721 | :param int min: Minimum number of labels | |
722 | :param int max: Maximum nimber of labels | |
723 | ||
724 | .. function:: QNameWireLengthRule(min, max) | |
725 | ||
726 | Matches if the qname's length on the wire is less than ``min`` or more than ``max`` bytes. | |
727 | ||
728 | :param int min: Minimum number of bytes | |
729 | :param int max: Maximum nimber of bytes | |
730 | ||
731 | .. function:: QTypeRule(qtype) | |
732 | ||
733 | Matches queries with the specified ``qtype`` | |
734 | ``qtype`` may be specified as an integer or as one of the built-in QTypes. | |
fc16b739 | 735 | For instance ``DNSQType.A``, ``DNSQType.TXT`` and ``DNSQType.ANY``. |
20d81666 PL |
736 | |
737 | :param int qtype: The QType to match on | |
738 | ||
739 | .. function:: RCodeRule(rcode) | |
740 | ||
d83feb68 CH |
741 | Matches queries or responses with the specified ``rcode``. |
742 | ``rcode`` can be specified as an integer or as one of the built-in :ref:`DNSRCode`. | |
743 | Only the non-extended RCode is matched (lower 4bits). | |
744 | ||
745 | :param int rcode: The RCODE to match on | |
746 | ||
20d81666 PL |
747 | .. function:: RDRule() |
748 | ||
749 | .. versionadded:: 1.2.0 | |
750 | ||
751 | Matches queries with the RD flag set. | |
752 | ||
753 | .. function:: RegexRule(regex) | |
754 | ||
755 | Matches the query name against the ``regex``. | |
756 | ||
757 | .. code-block:: Lua | |
758 | ||
759 | addAction(RegexRule("[0-9]{5,}"), DelayAction(750)) -- milliseconds | |
760 | addAction(RegexRule("[0-9]{4,}\\.example$"), DropAction()) | |
761 | ||
762 | This delays any query for a domain name with 5 or more consecutive digits in it. | |
763 | The second rule drops anything with more than 4 consecutive digits within a .EXAMPLE domain. | |
764 | ||
765 | Note that the query name is presented without a trailing dot to the regex. | |
766 | The regex is applied case insensitively. | |
767 | ||
768 | :param string regex: A regular expression to match the traffic on | |
769 | ||
770 | .. function:: RecordsCountRule(section, minCount, maxCount) | |
771 | ||
772 | Matches if there is at least ``minCount`` and at most ``maxCount`` records in the section ``section``. | |
773 | ``section`` can be specified as an integer or as a :ref:`DNSSection`. | |
774 | ||
775 | :param int section: The section to match on | |
776 | :param int minCount: The minimum number of entries | |
777 | :param int maxCount: The maximum number of entries | |
778 | ||
779 | .. function:: RecordsTypeCountRule(section, qtype, minCount, maxCount) | |
780 | ||
781 | Matches if there is at least ``minCount`` and at most ``maxCount`` records of type ``type`` in the section ``section``. | |
4e031caf | 782 | ``section`` can be specified as an integer or as a :ref:`DNSSection`. |
09b45aa8 | 783 | ``qtype`` may be specified as an integer or as one of the :ref:`built-in QTypes <DNSQType>`, for instance ``DNSQType.A`` or ``DNSQType.TXT``. |
20d81666 PL |
784 | |
785 | :param int section: The section to match on | |
786 | :param int qtype: The QTYPE to match on | |
787 | :param int minCount: The minimum number of entries | |
788 | :param int maxCount: The maximum number of entries | |
789 | ||
790 | .. function:: RE2Rule(regex) | |
791 | ||
792 | Matches the query name against the supplied regex using the RE2 engine. | |
793 | ||
794 | For an example of usage, see :func:`RegexRule`. | |
795 | ||
796 | :note: Only available when dnsdist was built with libre2 support. | |
797 | ||
798 | :param str regex: The regular expression to match the QNAME. | |
799 | ||
046bac5c | 800 | .. function:: SNIRule(name) |
6ec3dde9 | 801 | |
046bac5c RG |
802 | .. versionadded:: 1.4.0 |
803 | ||
804 | Matches against the TLS Server Name Indication value sent by the client, if any. Only makes | |
ba45a22c RG |
805 | sense for DoT or DoH, and for that last one matching on the HTTP Host header using :func:`HTTPHeaderRule` |
806 | might provide more consistent results. | |
807 | As of the version 2.3.0-beta of h2o, it is unfortunately not possible to extract the SNI value from DoH | |
808 | connections, and it is therefore necessary to use the HTTP Host header until version 2.3.0 is released. | |
046bac5c RG |
809 | |
810 | :param str name: The exact SNI name to match. | |
811 | ||
20d81666 PL |
812 | .. function:: SuffixMatchNodeRule(smn[, quiet]) |
813 | ||
814 | Matches based on a group of domain suffixes for rapid testing of membership. | |
815 | Pass true as second parameter to prevent listing of all domains matched. | |
816 | ||
cc0e7aa9 AD |
817 | To match domain names exactly, see :func:`QNameSetRule`. |
818 | ||
20d81666 | 819 | :param SuffixMatchNode smb: The SuffixMatchNode to match on |
0d70c2c6 | 820 | :param bool quiet: Do not display the list of matched domains in Rules. Default is false. |
20d81666 | 821 | |
a76b0d63 RG |
822 | .. function:: TagRule(name [, value]) |
823 | ||
87cb3110 PL |
824 | .. versionadded:: 1.3.0 |
825 | ||
a76b0d63 RG |
826 | Matches question or answer with a tag named ``name`` set. If ``value`` is specified, the existing tag value should match too. |
827 | ||
828 | :param bool name: The name of the tag that has to be set | |
829 | :param bool value: If set, the value the tag has to be set to. Default is unset | |
830 | ||
20d81666 PL |
831 | .. function:: TCPRule([tcp]) |
832 | ||
833 | Matches question received over TCP if ``tcp`` is true, over UDP otherwise. | |
834 | ||
835 | :param bool tcp: Match TCP traffic. Default is true. | |
836 | ||
837 | .. function:: TrailingDataRule() | |
838 | ||
839 | Matches if the query has trailing data. | |
840 | ||
4aa51160 MC |
841 | .. function:: PoolAvailableRule(poolname) |
842 | ||
843 | .. versionadded:: 1.3.3 | |
844 | ||
845 | Check whether a pool has any servers available to handle queries | |
846 | ||
847 | .. code-block:: Lua | |
848 | ||
849 | --- Send queries to default pool when servers are available | |
850 | addAction(PoolAvailableRule(""), PoolAction("")) | |
851 | --- Send queries to fallback pool if not | |
852 | addAction(AllRule(), PoolAction("fallback")) | |
853 | ||
854 | :param string poolname: Pool to check | |
855 | ||
20d81666 PL |
856 | Combining Rules |
857 | ~~~~~~~~~~~~~~~ | |
858 | ||
e4b645c4 | 859 | .. function:: AndRule(selectors) |
20d81666 PL |
860 | |
861 | Matches traffic if all ``selectors`` match. | |
862 | ||
863 | :param {Rule} selectors: A table of Rules | |
864 | ||
865 | .. function:: NotRule(selector) | |
866 | ||
867 | Matches the traffic if the ``selector`` rule does not match; | |
868 | ||
869 | :param Rule selector: A Rule | |
870 | ||
871 | .. function:: OrRule(selectors) | |
872 | ||
873 | Matches the traffic if one or more of the the ``selectors`` Rules does match. | |
874 | ||
875 | :param {Rule} selector: A table of Rules | |
876 | ||
2d4783a8 CH |
877 | Convenience Functions |
878 | ~~~~~~~~~~~~~~~~~~~~~ | |
20d81666 PL |
879 | |
880 | .. function:: makeRule(rule) | |
881 | ||
882 | Make a :func:`NetmaskGroupRule` or a :func:`SuffixMatchNodeRule`, depending on it is called. | |
883 | ``makeRule("0.0.0.0/0")`` will for example match all IPv4 traffic, ``makeRule({"be","nl","lu"})`` will match all Benelux DNS traffic. | |
884 | ||
885 | :param string rule: A string to convert to a rule. | |
886 | ||
887 | ||
888 | Actions | |
889 | ------- | |
890 | ||
891 | :ref:`RulesIntro` need to be combined with an action for them to actually do something with the matched packets. | |
892 | Some actions allow further processing of rules, this is noted in their description. | |
893 | The following actions exist. | |
894 | ||
895 | .. function:: AllowAction() | |
896 | ||
897 | Let these packets go through. | |
898 | ||
899 | .. function:: AllowResponseAction() | |
900 | ||
901 | Let these packets go through. | |
902 | ||
2a28db86 RG |
903 | .. function:: ContinueAction(action) |
904 | ||
2f2cbf15 RG |
905 | .. versionadded:: 1.4.0 |
906 | ||
2a28db86 RG |
907 | Execute the specified action and override its return with None, making it possible to continue the processing. |
908 | Subsequent rules are processed after this action. | |
909 | ||
910 | :param int action: Any other action | |
911 | ||
20d81666 PL |
912 | .. function:: DelayAction(milliseconds) |
913 | ||
914 | Delay the response by the specified amount of milliseconds (UDP-only). | |
fe77446e | 915 | Subsequent rules are processed after this action. |
20d81666 PL |
916 | |
917 | :param int milliseconds: The amount of milliseconds to delay the response | |
918 | ||
919 | .. function:: DelayResponseAction(milliseconds) | |
920 | ||
921 | Delay the response by the specified amount of milliseconds (UDP-only). | |
fe77446e | 922 | Subsequent rules are processed after this action. |
20d81666 PL |
923 | |
924 | :param int milliseconds: The amount of milliseconds to delay the response | |
925 | ||
926 | .. function:: DisableECSAction() | |
927 | ||
928 | Disable the sending of ECS to the backend. | |
fe77446e | 929 | Subsequent rules are processed after this action. |
20d81666 PL |
930 | |
931 | .. function:: DisableValidationAction() | |
932 | ||
933 | Set the CD bit in the query and let it go through. | |
934 | ||
82a91ddf CH |
935 | .. function:: DnstapLogAction(identity, logger[, alterFunction]) |
936 | ||
87cb3110 PL |
937 | .. versionadded:: 1.3.0 |
938 | ||
939 | Send the the current query to a remote logger as a :doc:`dnstap <reference/dnstap>` message. | |
82a91ddf | 940 | ``alterFunction`` is a callback, receiving a :class:`DNSQuestion` and a :class:`DnstapMessage`, that can be used to modify the message. |
2a28db86 | 941 | Subsequent rules are processed after this action. |
82a91ddf CH |
942 | |
943 | :param string identity: Server identity to store in the dnstap message | |
944 | :param logger: The :func:`FrameStreamLogger <newFrameStreamUnixLogger>` or :func:`RemoteLogger <newRemoteLogger>` object to write to | |
945 | :param alterFunction: A Lua function to alter the message before sending | |
946 | ||
947 | .. function:: DnstapLogResponseAction(identity, logger[, alterFunction]) | |
948 | ||
87cb3110 PL |
949 | .. versionadded:: 1.3.0 |
950 | ||
951 | Send the the current response to a remote logger as a :doc:`dnstap <reference/dnstap>` message. | |
82a91ddf | 952 | ``alterFunction`` is a callback, receiving a :class:`DNSQuestion` and a :class:`DnstapMessage`, that can be used to modify the message. |
2a28db86 | 953 | Subsequent rules are processed after this action. |
82a91ddf CH |
954 | |
955 | :param string identity: Server identity to store in the dnstap message | |
956 | :param logger: The :func:`FrameStreamLogger <newFrameStreamUnixLogger>` or :func:`RemoteLogger <newRemoteLogger>` object to write to | |
957 | :param alterFunction: A Lua function to alter the message before sending | |
958 | ||
20d81666 PL |
959 | .. function:: DropAction() |
960 | ||
961 | Drop the packet. | |
962 | ||
963 | .. function:: DropResponseAction() | |
964 | ||
965 | Drop the packet. | |
966 | ||
967 | .. function:: ECSOverrideAction(override) | |
968 | ||
969 | Whether an existing EDNS Client Subnet value should be overridden (true) or not (false). | |
fe77446e | 970 | Subsequent rules are processed after this action. |
20d81666 PL |
971 | |
972 | :param bool override: Whether or not to override ECS value | |
973 | ||
974 | .. function:: ECSPrefixLengthAction(v4, v6) | |
975 | ||
976 | Set the ECS prefix length. | |
fe77446e | 977 | Subsequent rules are processed after this action. |
20d81666 PL |
978 | |
979 | :param int v4: The IPv4 netmask length | |
980 | :param int v6: The IPv6 netmask length | |
981 | ||
ca567c4b | 982 | |
d545a872 | 983 | .. function:: ERCodeAction(rcode [, options]) |
ca567c4b RG |
984 | |
985 | .. versionadded:: 1.4.0 | |
986 | ||
d545a872 RG |
987 | .. versionchanged:: 1.5.0 |
988 | Added the optional parameter ``options``. | |
989 | ||
ca567c4b RG |
990 | Reply immediately by turning the query into a response with the specified EDNS extended ``rcode``. |
991 | ``rcode`` can be specified as an integer or as one of the built-in :ref:`DNSRCode`. | |
992 | ||
993 | :param int rcode: The extended RCODE to respond with. | |
d545a872 RG |
994 | :param table options: A table with key: value pairs with options. |
995 | ||
996 | Options: | |
ca567c4b | 997 | |
d545a872 RG |
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:: HTTPStatusAction(status, body, contentType="" [, options]) | |
6ec3dde9 | 1003 | |
13c1fc12 RG |
1004 | .. versionadded:: 1.4.0 |
1005 | ||
d545a872 RG |
1006 | .. versionchanged:: 1.5.0 |
1007 | Added the optional parameter ``options``. | |
1008 | ||
9676d2a9 | 1009 | Return an HTTP response with a status code of ''status''. For HTTP redirects, ''body'' should be the redirect URL. |
13c1fc12 RG |
1010 | |
1011 | :param int status: The HTTP status code to return. | |
9676d2a9 RG |
1012 | :param string body: The body of the HTTP response, or a URL if the status code is a redirect (3xx). |
1013 | :param string contentType: The HTTP Content-Type header to return for a 200 response, ignored otherwise. Default is ''application/dns-message''. | |
d545a872 RG |
1014 | :param table options: A table with key: value pairs with options. |
1015 | ||
1016 | Options: | |
1017 | ||
1018 | * ``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. | |
1019 | * ``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. | |
1020 | * ``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. | |
13c1fc12 | 1021 | |
daa75838 RG |
1022 | .. function:: KeyValueStoreLookupAction(kvs, lookupKey, destinationTag) |
1023 | ||
d81a1d9c RG |
1024 | .. versionadded:: 1.4.0 |
1025 | ||
1026 | As of 1.4.0, this code is considered experimental. | |
daa75838 RG |
1027 | |
1028 | Does a lookup into the key value store referenced by 'kvs' using the key returned by 'lookupKey', | |
1029 | and storing the result if any into the tag named 'destinationTag'. | |
1030 | The store can be a CDB (:func:`newCDBKVStore`) or a LMDB database (:func:`newLMDBKVStore`). | |
1031 | The key can be based on the qname (:func:`KeyValueLookupKeyQName` and :func:`KeyValueLookupKeySuffix`), | |
1032 | source IP (:func:`KeyValueLookupKeySourceIP`) or the value of an existing tag (:func:`KeyValueLookupKeyTag`). | |
1033 | ||
1034 | :param KeyValueStore kvs: The key value store to query | |
1035 | :param KeyValueLookupKey lookupKey: The key to use for the lookup | |
1036 | :param string destinationTag: The name of the tag to store the result into | |
1037 | ||
320b20cd RG |
1038 | .. function:: LogAction([filename[, binary[, append[, buffered[, verboseOnly[, includeTimestamp]]]]]]) |
1039 | ||
1040 | .. versionchanged:: 1.4.0 | |
1041 | Added the optional parameters ``verboseOnly`` and ``includeTimestamp``, made ``filename`` optional. | |
20d81666 | 1042 | |
f6bcb701 | 1043 | 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. |
320b20cd | 1044 | |
6e9f87c0 | 1045 | 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. |
320b20cd RG |
1046 | |
1047 | 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. | |
1048 | ||
20d81666 PL |
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. | |
320b20cd | 1051 | |
fe77446e | 1052 | Subsequent rules are processed after this action. |
20d81666 | 1053 | |
0a28ac9c | 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. |
20d81666 PL |
1055 | :param bool binary: Do binary logging. Default true |
1056 | :param bool append: Append to the log. Default false | |
320b20cd RG |
1057 | :param bool buffered: Use buffered I/O. Default true |
1058 | :param bool verboseOnly: Whether to log only in verbose mode when logging to stdout. Default is true | |
1059 | :param bool includeTimestamp: Whether to include a timestamp for every entry. Default is false | |
20d81666 | 1060 | |
ce6bcbad | 1061 | .. function:: LogResponseAction([filename[, append[, buffered[, verboseOnly[, includeTimestamp]]]]]]) |
1062 | ||
1063 | .. versionadded:: 1.5.0 | |
1064 | ||
1065 | 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. | |
1066 | ||
1067 | 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. | |
1068 | ||
1069 | The ``append`` optional parameter specifies whether we open the file for appending or truncate each time (default). | |
1070 | The ``buffered`` optional parameter specifies whether writes to the file are buffered (default) or not. | |
1071 | ||
1072 | Subsequent rules are processed after this action. | |
1073 | ||
1074 | :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. | |
1075 | :param bool append: Append to the log. Default false | |
1076 | :param bool buffered: Use buffered I/O. Default true | |
1077 | :param bool verboseOnly: Whether to log only in verbose mode when logging to stdout. Default is true | |
1078 | :param bool includeTimestamp: Whether to include a timestamp for every entry. Default is false | |
1079 | ||
a2ff35e3 RG |
1080 | .. function:: LuaAction(function) |
1081 | ||
1082 | Invoke a Lua function that accepts a :class:`DNSQuestion`. | |
1083 | ||
5f23eb98 | 1084 | The ``function`` should return a :ref:`DNSAction`. If the Lua code fails, ServFail is returned. |
a2ff35e3 RG |
1085 | |
1086 | :param string function: the name of a Lua function | |
b774d943 RG |
1087 | |
1088 | .. function:: LuaFFIAction(function) | |
1089 | ||
1090 | .. versionadded:: 1.5.0 | |
1091 | ||
1092 | Invoke a Lua FFI function that accepts a pointer to a ``dnsdist_ffi_dnsquestion_t`` object, whose bindings are defined in ``dnsdist-lua-ffi.hh``. | |
1093 | ||
1094 | The ``function`` should return a :ref:`DNSAction`. If the Lua code fails, ServFail is returned. | |
1095 | ||
1096 | :param string function: the name of a Lua function | |
1097 | ||
1098 | .. function:: LuaFFIResponseAction(function) | |
1099 | ||
1100 | .. versionadded:: 1.5.0 | |
1101 | ||
1102 | Invoke a Lua FFI function that accepts a pointer to a ``dnsdist_ffi_dnsquestion_t`` object, whose bindings are defined in ``dnsdist-lua-ffi.hh``. | |
1103 | ||
1104 | The ``function`` should return a :ref:`DNSResponseAction`. If the Lua code fails, ServFail is returned. | |
1105 | ||
1106 | :param string function: the name of a Lua function | |
a2ff35e3 RG |
1107 | |
1108 | .. function:: LuaResponseAction(function) | |
1109 | ||
1110 | Invoke a Lua function that accepts a :class:`DNSResponse`. | |
1111 | ||
5f23eb98 | 1112 | The ``function`` should return a :ref:`DNSResponseAction`. If the Lua code fails, ServFail is returned. |
a2ff35e3 RG |
1113 | |
1114 | :param string function: the name of a Lua function | |
1115 | ||
20d81666 PL |
1116 | .. function:: MacAddrAction(option) |
1117 | ||
1118 | Add the source MAC address to the query as EDNS0 option ``option``. | |
1119 | This action is currently only supported on Linux. | |
fe77446e | 1120 | Subsequent rules are processed after this action. |
20d81666 PL |
1121 | |
1122 | :param int option: The EDNS0 option number | |
1123 | ||
1124 | .. function:: NoneAction() | |
1125 | ||
1126 | Does nothing. | |
fe77446e | 1127 | Subsequent rules are processed after this action. |
20d81666 PL |
1128 | |
1129 | .. function:: NoRecurseAction() | |
1130 | ||
1131 | Strip RD bit from the question, let it go through. | |
fe77446e | 1132 | Subsequent rules are processed after this action. |
20d81666 PL |
1133 | |
1134 | .. function:: PoolAction(poolname) | |
1135 | ||
1136 | Send the packet into the specified pool. | |
1137 | ||
1138 | :param string poolname: The name of the pool | |
1139 | ||
8499caaf RG |
1140 | .. function:: QPSAction(maxqps) |
1141 | ||
1142 | Drop a packet if it does exceed the ``maxqps`` queries per second limits. | |
1143 | Letting the subsequent rules apply otherwise. | |
1144 | ||
1145 | :param int maxqps: The QPS limit | |
1146 | ||
20d81666 PL |
1147 | .. function:: QPSPoolAction(maxqps, poolname) |
1148 | ||
1149 | Send the packet into the specified pool only if it does not exceed the ``maxqps`` queries per second limits. | |
1150 | Letting the subsequent rules apply otherwise. | |
1151 | ||
1152 | :param int maxqps: The QPS limit for that pool | |
1153 | :param string poolname: The name of the pool | |
1154 | ||
d545a872 RG |
1155 | .. function:: RCodeAction(rcode [, options]) |
1156 | ||
1157 | .. versionchanged:: 1.5.0 | |
1158 | Added the optional parameter ``options``. | |
20d81666 | 1159 | |
ca567c4b | 1160 | Reply immediately by turning the query into a response with the specified ``rcode``. |
d83feb68 | 1161 | ``rcode`` can be specified as an integer or as one of the built-in :ref:`DNSRCode`. |
20d81666 PL |
1162 | |
1163 | :param int rcode: The RCODE to respond with. | |
d545a872 RG |
1164 | :param table options: A table with key: value pairs with options. |
1165 | ||
1166 | Options: | |
1167 | ||
1168 | * ``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. | |
1169 | * ``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. | |
1170 | * ``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. | |
20d81666 | 1171 | |
312a09a6 RG |
1172 | .. function:: RemoteLogAction(remoteLogger[, alterFunction [, options]]) |
1173 | ||
1174 | .. versionchanged:: 1.3.0 | |
1175 | ``options`` optional parameter added. | |
20d81666 | 1176 | |
7d294573 | 1177 | .. versionchanged:: 1.4.0 |
af7afecf RG |
1178 | ``ipEncryptKey`` optional key added to the options table. |
1179 | ||
20d81666 | 1180 | Send the content of this query to a remote logger via Protocol Buffer. |
2a28db86 RG |
1181 | ``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. |
1182 | Subsequent rules are processed after this action. | |
20d81666 | 1183 | |
7747be24 | 1184 | :param string remoteLogger: The :func:`remoteLogger <newRemoteLogger>` object to write to |
20d81666 | 1185 | :param string alterFunction: Name of a function to modify the contents of the logs before sending |
312a09a6 RG |
1186 | :param table options: A table with key: value pairs. |
1187 | ||
1188 | Options: | |
1189 | ||
1190 | * ``serverID=""``: str - Set the Server Identity field. | |
cd74f128 | 1191 | * ``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. |
20d81666 | 1192 | |
312a09a6 RG |
1193 | .. function:: RemoteLogResponseAction(remoteLogger[, alterFunction[, includeCNAME [, options]]]) |
1194 | ||
1195 | .. versionchanged:: 1.3.0 | |
1196 | ``options`` optional parameter added. | |
20d81666 | 1197 | |
7d294573 | 1198 | .. versionchanged:: 1.4.0 |
af7afecf RG |
1199 | ``ipEncryptKey`` optional key added to the options table. |
1200 | ||
20d81666 | 1201 | Send the content of this response to a remote logger via Protocol Buffer. |
2a28db86 | 1202 | ``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. |
20d81666 | 1203 | ``includeCNAME`` indicates whether CNAME records inside the response should be parsed and exported. |
2a28db86 RG |
1204 | The default is to only exports A and AAAA records. |
1205 | Subsequent rules are processed after this action. | |
20d81666 | 1206 | |
7747be24 | 1207 | :param string remoteLogger: The :func:`remoteLogger <newRemoteLogger>` object to write to |
20d81666 PL |
1208 | :param string alterFunction: Name of a function to modify the contents of the logs before sending |
1209 | :param bool includeCNAME: Whether or not to parse and export CNAMEs. Default false | |
312a09a6 RG |
1210 | :param table options: A table with key: value pairs. |
1211 | ||
1212 | Options: | |
1213 | ||
1214 | * ``serverID=""``: str - Set the Server Identity field. | |
cd74f128 | 1215 | * ``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. |
20d81666 | 1216 | |
bd14f087 RG |
1217 | .. function:: SetECSAction(v4 [, v6]) |
1218 | ||
1219 | .. versionadded:: 1.3.1 | |
1220 | ||
1221 | Set the ECS prefix and prefix length sent to backends to an arbitrary value. | |
1222 | If both IPv4 and IPv6 masks are supplied the IPv4 one will be used for IPv4 clients | |
1223 | and the IPv6 one for IPv6 clients. Otherwise the first mask is used for both, and | |
1224 | can actually be an IPv6 mask. | |
fe77446e | 1225 | Subsequent rules are processed after this action. |
bd14f087 RG |
1226 | |
1227 | :param string v4: The IPv4 netmask, for example "192.0.2.1/32" | |
1228 | :param string v6: The IPv6 netmask, if any | |
1229 | ||
ba572120 | 1230 | .. function:: SetNegativeAndSOAAction(nxd, zone, ttl, mname, rname, serial, refresh, retry, expire, minimum [, options]) |
af9f750c RG |
1231 | |
1232 | .. versionadded:: 1.5.0 | |
1233 | ||
1234 | Turn a question into a response, either a NXDOMAIN or a NODATA one based on ''nxd'', setting the QR bit to 1 and adding a SOA record in the additional section. | |
1235 | ||
1236 | :param bool nxd: Whether the answer is a NXDOMAIN (true) or a NODATA (false) | |
1237 | :param string zone: The owner name for the SOA record | |
1238 | :param int ttl: The TTL of the SOA record | |
1239 | :param string mname: The mname of the SOA record | |
1240 | :param string rname: The rname of the SOA record | |
1241 | :param int serial: The value of the serial field in the SOA record | |
1242 | :param int refresh: The value of the refresh field in the SOA record | |
1243 | :param int retry: The value of the retry field in the SOA record | |
1244 | :param int expire: The value of the expire field in the SOA record | |
1245 | :param int minimum: The value of the minimum field in the SOA record | |
ba572120 RG |
1246 | :param table options: A table with key: value pairs with options |
1247 | ||
1248 | Options: | |
1249 | ||
1250 | * ``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. | |
1251 | * ``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. | |
1252 | * ``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. | |
af9f750c | 1253 | |
20d81666 PL |
1254 | .. function:: SkipCacheAction() |
1255 | ||
1256 | Don't lookup the cache for this query, don't store the answer. | |
1257 | ||
1258 | .. function:: SNMPTrapAction([message]) | |
1259 | ||
1260 | Send an SNMP trap, adding the optional ``message`` string as the query description. | |
fe77446e | 1261 | Subsequent rules are processed after this action. |
20d81666 PL |
1262 | |
1263 | :param string message: The message to include | |
1264 | ||
1265 | .. function:: SNMPTrapResponseAction([message]) | |
1266 | ||
1267 | Send an SNMP trap, adding the optional ``message`` string as the query description. | |
fe77446e | 1268 | Subsequent rules are processed after this action. |
20d81666 PL |
1269 | |
1270 | :param string message: The message to include | |
1271 | ||
955b9377 RG |
1272 | .. function:: SpoofAction(ip [, options]) |
1273 | SpoofAction(ips [, options]) | |
1274 | ||
1275 | .. versionchanged:: 1.5.0 | |
1276 | Added the optional parameter ``options``. | |
20d81666 PL |
1277 | |
1278 | Forge a response with the specified IPv4 (for an A query) or IPv6 (for an AAAA) addresses. | |
1279 | If you specify multiple addresses, all that match the query type (A, AAAA or ANY) will get spoofed in. | |
1280 | ||
1281 | :param string ip: An IPv4 and/or IPv6 address to spoof | |
1282 | :param {string} ips: A table of IPv4 and/or IPv6 addresses to spoof | |
955b9377 RG |
1283 | :param table options: A table with key: value pairs with options. |
1284 | ||
1285 | Options: | |
1286 | ||
1287 | * ``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. | |
1288 | * ``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. | |
1289 | * ``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. | |
202c4ab9 | 1290 | * ``ttl``: int - The TTL of the record. |
20d81666 | 1291 | |
955b9377 RG |
1292 | .. function:: SpoofCNAMEAction(cname [, options]) |
1293 | ||
1294 | .. versionchanged:: 1.5.0 | |
1295 | Added the optional parameter ``options``. | |
20d81666 PL |
1296 | |
1297 | Forge a response with the specified CNAME value. | |
1298 | ||
1299 | :param string cname: The name to respond with | |
955b9377 RG |
1300 | :param table options: A table with key: value pairs with options. |
1301 | ||
1302 | Options: | |
1303 | ||
1304 | * ``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. | |
1305 | * ``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. | |
1306 | * ``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. | |
202c4ab9 RG |
1307 | * ``ttl``: int - The TTL of the record. |
1308 | ||
1309 | .. function:: SpoofRawAction(rawAnswer [, options]) | |
1310 | ||
1311 | .. versionadded:: 1.5.0 | |
1312 | ||
1313 | Forge a response with the specified raw bytes as record data. | |
1314 | For example, for a TXT record of "aaa" "bbbb": SpoofRawAction("\003aaa\004bbbb") | |
1315 | ||
1316 | :param string rawAnswer: The raw record data | |
1317 | :param table options: A table with key: value pairs with options. | |
1318 | ||
1319 | Options: | |
1320 | ||
1321 | * ``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. | |
1322 | * ``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. | |
1323 | * ``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. | |
1324 | * ``ttl``: int - The TTL of the record. | |
20d81666 | 1325 | |
a76b0d63 RG |
1326 | .. function:: TagAction(name, value) |
1327 | ||
87cb3110 PL |
1328 | .. versionadded:: 1.3.0 |
1329 | ||
a76b0d63 | 1330 | Associate a tag named ``name`` with a value of ``value`` to this query, that will be passed on to the response. |
2a28db86 | 1331 | Subsequent rules are processed after this action. |
a76b0d63 RG |
1332 | |
1333 | :param string name: The name of the tag to set | |
4cf9bdc5 | 1334 | :param string value: The value of the tag |
a76b0d63 RG |
1335 | |
1336 | .. function:: TagResponseAction(name, value) | |
1337 | ||
87cb3110 PL |
1338 | .. versionadded:: 1.3.0 |
1339 | ||
a76b0d63 | 1340 | Associate a tag named ``name`` with a value of ``value`` to this response. |
2a28db86 | 1341 | Subsequent rules are processed after this action. |
a76b0d63 RG |
1342 | |
1343 | :param string name: The name of the tag to set | |
c852dad5 | 1344 | :param string value: The value of the tag |
a76b0d63 | 1345 | |
20d81666 PL |
1346 | .. function:: TCAction() |
1347 | ||
1348 | Create answer to query with TC and RD bits set, to force the client to TCP. | |
1349 | ||
1350 | .. function:: TeeAction(remote[, addECS]) | |
1351 | ||
1352 | Send copy of query to ``remote``, keep stats on responses. | |
1353 | If ``addECS`` is set to true, EDNS Client Subnet information will be added to the query. | |
1354 | ||
1355 | :param string remote: An IP:PORT conbination to send the copied queries to | |
1356 | :param bool addECS: Whether or not to add ECS information. Default false | |
1357 | ||
a2c4a339 | 1358 | .. function:: TempFailureCacheTTLAction(ttl) |
20d81666 | 1359 | |
a2c4a339 CH |
1360 | Set the cache TTL to use for ServFail and Refused replies. TTL is not applied for successful replies. |
1361 | ||
1362 | :param int ttl: Cache TTL for temporary failure replies |