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.
  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(dnsdist.ANY), TCPRule(false)}), TCAction())
  85
  86 .. function:: addDelay(DNSrule, delay)
  87
  88   .. deprecated:: 1.2.0
  89
  90   Delay the query for ``delay`` milliseconds before sending to a backend.
  91   This function is deprecated as of 1.2.0 and will be removed in 1.3.0, please use instead:
  92
  93     addAction(DNSRule, DelayAction(delay))
  94
  95   :param DNSRule: The DNSRule to match traffic
  96   :param int delay: The delay time in milliseconds.
  97
  98 .. function:: addDisableValidationRule(DNSrule)
  99
 100   .. deprecated:: 1.2.0
 101
 102   Set the CD (Checking Disabled) flag to 1 for all queries matching the DNSRule.
 103   This function is deprecated as of 1.2.0 and will be removed in 1.3.0. Please use the :func:`DisableValidationAction` action instead.
 104
 105 .. function:: addDomainBlock(domain)
 106
 107   .. deprecated:: 1.2.0
 108
 109   Drop all queries for ``domain`` and all names below it.
 110   Deprecated as of 1.2.0 and will be removed in 1.3.0, please use instead:
 111
 112     addAction(domain, DropAction())
 113
 114   :param string domain: The domain name to block
 115
 116 .. function:: addDomainSpoof(domain, IPv4[, IPv6])
 117               addDomainSpoof(domain, {IP[,...]})
 118
 119   .. deprecated:: 1.2.0
 120
 121   Generate answers for A/AAAA/ANY queries.
 122   This function is deprecated as of 1.2.0 and will be removed in 1.3.0, please use:
 123
 124     addAction(domain, SpoofAction({IP[,...]}))
 125
 126   or:
 127
 128     addAction(domain, SpoofAction(IPv4[, IPv6]))
 129
 130   :param string domain: Domain name to spoof for
 131   :param string IPv4: IPv4 address to spoof in the reply
 132   :param string IPv6: IPv6 address to spoof in the reply
 133   :param string IP: IP address to spoof in the reply
 134
 135 .. function:: addDomainCNAMESpoof(domain, cname)
 136
 137   .. deprecated:: 1.2.0
 138
 139   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:
 140
 141     addAction(domain, SpoofCNAMEAction(cname))
 142
 143   :param string domain: Domain name to spoof for
 144   :param string cname: Domain name to add CNAME to
 145
 146 .. function:: addLuaAction(DNSrule, function [, options])
 147
 148   .. versionchanged:: 1.3.0
 149     Added the optional parameter ``options``.
 150
 151   .. versionchanged:: 1.3.0
 152     The second argument returned by the ``function`` can be omitted. For earlier releases, simply return an empty string.
 153
 154   Invoke a Lua function that accepts a :class:`DNSQuestion`.
 155   This function works similar to using :func:`LuaAction`.
 156   The ``function`` should return both a :ref:`DNSAction` and its argument `rule`. The `rule` is used as an argument
 157   of the following :ref:`DNSAction`: `DNSAction.Spoof`, `DNSAction.Pool` and `DNSAction.Delay`.
 158   If the Lua code fails, ServFail is returned.
 159
 160   :param DNSRule: match queries based on this rule
 161   :param string function: the name of a Lua function
 162   :param table options: A table with key: value pairs with options.
 163
 164   Options:
 165
 166   * ``uuid``: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
 167
 168   ::
 169
 170     function luarule(dq)
 171       if(dq.qtype==dnsdist.NAPTR)
 172       then
 173         return DNSAction.Pool, "abuse" -- send to abuse pool
 174       else
 175         return DNSAction.None, ""      -- no action
 176         -- return DNSAction.None       -- as of dnsdist version 1.3.0
 177       end
 178     end
 179
 180     addLuaAction(AllRule(), luarule)
 181
 182 .. function:: addLuaResponseAction(DNSrule, function [, options])
 183
 184   .. versionchanged:: 1.3.0
 185     Added the optional parameter ``options``.
 186
 187   .. versionchanged:: 1.3.0
 188     The second argument returned by the ``function`` can be omitted. For earlier releases, simply return an empty string.
 189
 190   Invoke a Lua function that accepts a :class:`DNSResponse`.
 191   This function works similar to using :func:`LuaResponseAction`.
 192   The ``function`` should return both a :ref:`DNSResponseAction` and its argument `rule`. The `rule` is used as an argument
 193   of the `DNSResponseAction.Delay`.
 194   If the Lua code fails, ServFail is returned.
 195
 196   :param DNSRule: match queries based on this rule
 197   :param string function: the name of a Lua function
 198   :param table options: A table with key: value pairs with options.
 199
 200   Options:
 201
 202   * ``uuid``: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
 203
 204 .. function:: addNoRecurseRule(DNSrule)
 205
 206   .. deprecated:: 1.2.0
 207
 208   Clear the RD flag for all queries matching the rule.
 209   This function is deprecated as of 1.2.0 and will be removed in 1.3.0, please use:
 210
 211     addAction(DNSRule, NoRecurseAction())
 212
 213   :param DNSRule: match queries based on this rule
 214
 215 .. function:: addPoolRule(DNSRule, pool)
 216
 217   .. deprecated:: 1.2.0
 218
 219   Send queries matching the first argument to the pool ``pool``.
 220   e.g.::
 221
 222     addPoolRule("example.com", "myPool")
 223
 224   This function is deprecated as of 1.2.0 and will be removed in 1.3.0, this is equivalent to::
 225
 226     addAction("example.com", PoolAction("myPool"))
 227
 228   :param DNSRule: match queries based on this rule
 229   :param string pool: The name of the pool to send the queries to
 230
 231 .. function:: addQPSLimit(DNSrule, limit)
 232
 233   .. deprecated:: 1.2.0
 234
 235   Limit queries matching the DNSRule to ``limit`` queries per second.
 236   All queries over the limit are dropped.
 237   This function is deprecated as of 1.2.0 and will be removed in 1.3.0, please use:
 238
 239     addAction(DNSRule, QPSAction(limit))
 240
 241   :param DNSRule: match queries based on this rule
 242   :param int limit: QPS limit for this rule
 243
 244 .. function:: addQPSPoolRule(DNSRule, limit, pool)
 245
 246   .. deprecated:: 1.2.0
 247
 248   Send at most ``limit`` queries/s for this pool, letting the subsequent rules apply otherwise.
 249   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::
 250
 251     addAction("192.0.2.0/24", QPSPoolAction(15, "myPool")
 252
 253   :param DNSRule: match queries based on this rule
 254   :param int limit: QPS limit for this rule
 255   :param string pool: The name of the pool to send the queries to
 256
 257
 258 Managing Rules
 259 --------------
 260
 261 Active Rules can be shown with :func:`showRules` and removed with :func:`rmRule`::
 262
 263   > addAction("h4xorbooter.xyz.", QPSAction(10))
 264   > addAction({"130.161.0.0/16", "145.14.0.0/16"} , QPSAction(20))
 265   > addAction({"nl.", "be."}, QPSAction(1))
 266   > showRules()
 267   #     Matches Rule                                               Action
 268   0           0 h4xorbooter.xyz.                                   qps limit to 10
 269   1           0 130.161.0.0/16, 145.14.0.0/16                      qps limit to 20
 270   2           0 nl., be.                                           qps limit to 1
 271
 272 For Rules related to the incoming query:
 273
 274 .. function:: addAction(DNSrule, action [, options])
 275
 276   .. versionchanged:: 1.3.0
 277     Added the optional parameter ``options``.
 278
 279   Add a Rule and Action to the existing rules.
 280
 281   :param DNSrule rule: A DNSRule, e.g. an :func:`AllRule` or a compounded bunch of rules using e.g. :func:`AndRule`
 282   :param action: The action to take
 283   :param table options: A table with key: value pairs with options.
 284
 285   Options:
 286
 287   * ``uuid``: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
 288
 289 .. function:: clearRules()
 290
 291   Remove all current rules.
 292
 293 .. function:: getAction(n) -> Action
 294
 295   Returns the Action associated with rule ``n``.
 296
 297   :param int n: The rule number
 298
 299 .. function:: mvRule(from, to)
 300
 301   Move rule ``from`` to a position where it is in front of ``to``.
 302   ``to`` can be one larger than the largest rule, in which case the rule will be moved to the last position.
 303
 304   :param int from: Rule number to move
 305   :param int to: Location to more the Rule to
 306
 307 .. function:: newRuleAction(rule, action[, options])
 308
 309   .. versionchanged:: 1.3.0
 310     Added the optional parameter ``options``.
 311
 312   Return a pair of DNS Rule and DNS Action, to be used with :func:`setRules`.
 313
 314   :param Rule rule: A `Rule <#traffic-matching>`_
 315   :param Action action: The `Action <#actions>`_ to apply to the matched traffic
 316   :param table options: A table with key: value pairs with options.
 317
 318   Options:
 319
 320   * ``uuid``: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
 321
 322 .. function:: setRules(rules)
 323
 324   Replace the current rules with the supplied list of pairs of DNS Rules and DNS Actions (see :func:`newRuleAction`)
 325
 326   :param [RuleAction] rules: A list of RuleActions
 327
 328 .. function:: showRules([options])
 329
 330   .. versionchanged:: 1.3.0
 331     ``options`` optional parameter added
 332
 333   Show all defined rules for queries, optionally displaying their UUIDs.
 334
 335   :param table options: A table with key: value pairs with display options.
 336
 337   Options:
 338
 339   * ``showUUIDs=false``: bool - Whether to display the UUIDs, defaults to false.
 340   * ``truncateRuleWidth=-1``: int - Truncate rules output to ``truncateRuleWidth`` size. Defaults to ``-1`` to display the full rule.
 341
 342 .. function:: topRule()
 343
 344   Move the last rule to the first position.
 345
 346 .. function:: rmRule(id)
 347
 348   .. versionchanged:: 1.3.0
 349     ``id`` can now be an UUID.
 350
 351   Remove rule ``id``.
 352
 353   :param int id: The UUID of the rule to remove if ``id`` is an UUID, its position otherwise
 354
 355 For Rules related to responses:
 356
 357 .. function:: addResponseAction(DNSRule, action [, options])
 358
 359   .. versionchanged:: 1.3.0
 360     Added the optional parameter ``options``.
 361
 362   Add a Rule and Action for responses to the existing rules.
 363
 364   :param DNSRule: A DNSRule, e.g. an :func:`AllRule` or a compounded bunch of rules using e.g. :func:`AndRule`
 365   :param action: The action to take
 366   :param table options: A table with key: value pairs with options.
 367
 368   Options:
 369
 370   * ``uuid``: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
 371
 372 .. function:: mvResponseRule(from, to)
 373
 374   Move response rule ``from`` to a position where it is in front of ``to``.
 375   ``to`` can be one larger than the largest rule, in which case the rule will be moved to the last position.
 376
 377   :param int from: Rule number to move
 378   :param int to: Location to more the Rule to
 379
 380 .. function:: rmResponseRule(id)
 381
 382   .. versionchanged:: 1.3.0
 383     ``id`` can now be an UUID.
 384
 385   Remove response rule ``id``.
 386
 387   :param int id: The UUID of the rule to remove if ``id`` is an UUID, its position otherwise
 388
 389 .. function:: showResponseRules([options])
 390
 391   .. versionchanged:: 1.3.0
 392     ``options`` optional parameter added
 393
 394   Show all defined response rules, optionally displaying their UUIDs.
 395
 396   :param table options: A table with key: value pairs with display options.
 397
 398   Options:
 399
 400   * ``showUUIDs=false``: bool - Whether to display the UUIDs, defaults to false.
 401   * ``truncateRuleWidth=-1``: int - Truncate rules output to ``truncateRuleWidth`` size. Defaults to ``-1`` to display the full rule.
 402
 403 .. function:: topResponseRule()
 404
 405   Move the last response rule to the first position.
 406
 407 Functions for manipulating Cache Hit Respone Rules:
 408
 409 .. function:: addCacheHitResponseAction(DNSRule, action [, options])
 410
 411   .. versionadded:: 1.2.0
 412
 413   .. versionchanged:: 1.3.0
 414     Added the optional parameter ``options``.
 415
 416   Add a Rule and ResponseAction for Cache Hits to the existing rules.
 417
 418   :param DNSRule: A DNSRule, e.g. an :func:`AllRule` or a compounded bunch of rules using e.g. :func:`AndRule`
 419   :param action: The action to take
 420   :param table options: A table with key: value pairs with options.
 421
 422   Options:
 423
 424   * ``uuid``: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
 425
 426 .. function:: mvCacheHitResponseRule(from, to)
 427
 428   .. versionadded:: 1.2.0
 429
 430   Move cache hit response rule ``from`` to a position where it is in front of ``to``.
 431   ``to`` can be one larger than the largest rule, in which case the rule will be moved to the last position.
 432
 433   :param int from: Rule number to move
 434   :param int to: Location to more the Rule to
 435
 436 .. function:: rmCacheHitResponseRule(id)
 437
 438   .. versionadded:: 1.2.0
 439
 440   .. versionchanged:: 1.3.0
 441     ``id`` can now be an UUID.
 442
 443   :param int id: The UUID of the rule to remove if ``id`` is an UUID, its position otherwise
 444
 445 .. function:: showCacheHitResponseRules([options])
 446
 447   .. versionadded:: 1.2.0
 448
 449   .. versionchanged:: 1.3.0
 450     ``options`` optional parameter added
 451
 452   Show all defined cache hit response rules, optionally displaying their UUIDs.
 453
 454   :param table options: A table with key: value pairs with display options.
 455
 456   Options:
 457
 458   * ``showUUIDs=false``: bool - Whether to display the UUIDs, defaults to false.
 459   * ``truncateRuleWidth=-1``: int - Truncate rules output to ``truncateRuleWidth`` size. Defaults to ``-1`` to display the full rule.
 460
 461 .. function:: topCacheHitResponseRule()
 462
 463   .. versionadded:: 1.2.0
 464
 465   Move the last cache hit response rule to the first position.
 466
 467 Functions for manipulating Self-Answered Response Rules:
 468
 469 .. function:: addSelfAnsweredResponseAction(DNSRule, action [, options])
 470
 471   .. versionadded:: 1.3.0
 472
 473   Add a Rule and Action for Self-Answered queries to the existing rules.
 474
 475   :param DNSRule: A DNSRule, e.g. an :func:`AllRule` or a compounded bunch of rules using e.g. :func:`AndRule`
 476   :param action: The action to take
 477
 478 .. function:: mvSelfAnsweredResponseRule(from, to)
 479
 480   .. versionadded:: 1.3.0
 481
 482   Move self answered response rule ``from`` to a position where it is in front of ``to``.
 483   ``to`` can be one larger than the largest rule, in which case the rule will be moved to the last position.
 484
 485   :param int from: Rule number to move
 486   :param int to: Location to more the Rule to
 487
 488 .. function:: rmSelfAnsweredResponseRule(id)
 489
 490   .. versionadded:: 1.3.0
 491
 492   Remove self answered response rule ``id``.
 493
 494   :param int id: The UUID of the rule to remove if ``id`` is an UUID, its position otherwise
 495
 496 .. function:: showSelfAnsweredResponseRules([options])
 497
 498   .. versionadded:: 1.3.0
 499
 500   Show all defined self answered response rules, optionally displaying their UUIDs.
 501
 502   :param table options: A table with key: value pairs with display options.
 503
 504   Options:
 505
 506   * ``showUUIDs=false``: bool - Whether to display the UUIDs, defaults to false.
 507   * ``truncateRuleWidth=-1``: int - Truncate rules output to ``truncateRuleWidth`` size. Defaults to ``-1`` to display the full rule.
 508
 509 .. function:: topSelfAnsweredResponseRule()
 510
 511   .. versionadded:: 1.3.0
 512
 513   Move the last self answered response rule to the first position.
 514
 515 Function for pool related rules
 516
 517 .. function:: PoolAvailableRule(poolname)
 518
 519   .. versionadded:: 1.3.3
 520
 521   Check whether a pool has any servers available to handle queries
 522
 523   :param string poolname: Pool to check
 524
 525 .. _RulesIntro:
 526
 527 Matching Packets (Selectors)
 528 ----------------------------
 529
 530 Packets can be matched by selectors, called a ``DNSRule``.
 531 These ``DNSRule``\ s be one of the following items:
 532
 533   * A string that is either a domain name or netmask
 534   * A list of strings that are either domain names or netmasks
 535   * A :class:`DNSName`
 536   * A list of :class:`DNSName`\ s
 537   * A (compounded) ``Rule``
 538
 539 .. versionadded:: 1.2.0
 540    A DNSRule can also be a :class:`DNSName` or a list of these
 541
 542 .. function:: AllRule()
 543
 544   Matches all traffic
 545
 546 .. function:: DNSSECRule()
 547
 548   Matches queries with the DO flag set
 549
 550 .. function:: DSTPortRule(port)
 551
 552   Matches questions received to the destination port.
 553
 554   :param int port: Match destination port.
 555
 556 .. function:: EDNSOptionRule(optcode)
 557
 558   .. versionadded:: 1.4.0
 559
 560   Matches queries or responses with the specified EDNS option present.
 561   ``optcode`` is specified as an integer, or a constant such as `EDNSOptionCode.ECS`.
 562
 563 .. function:: EDNSVersionRule(version)
 564
 565   .. versionadded:: 1.4.0
 566
 567   Matches queries or responses with an OPT record whose EDNS version is greater than the specified EDNS version.
 568
 569   :param int version: The EDNS version to match on
 570
 571 .. function:: ERCodeRule(rcode)
 572
 573   Matches queries or responses with the specified ``rcode``.
 574   ``rcode`` can be specified as an integer or as one of the built-in :ref:`DNSRCode`.
 575   The full 16bit RCode will be matched. If no EDNS OPT RR is present, the upper 12 bits are treated as 0.
 576
 577   :param int rcode: The RCODE to match on
 578
 579 .. function:: MaxQPSIPRule(qps[, v4Mask[, v6Mask[, burst[, expiration[, cleanupDelay[, scanFraction]]]]]])
 580   .. versionchanged:: 1.3.1
 581     Added the optional parameters ``expiration``, ``cleanupDelay`` and ``scanFraction``.
 582
 583   Matches traffic for a subnet specified by ``v4Mask`` or ``v6Mask`` exceeding ``qps`` queries per second up to ``burst`` allowed.
 584   This rule keeps track of QPS by netmask or source IP. This state is cleaned up regularly if  ``cleanupDelay`` is greater than zero,
 585   removing existing netmasks or IP addresses that have not been seen in the last ``expiration`` seconds.
 586
 587   :param int qps: The number of queries per second allowed, above this number traffic is matched
 588   :param int v4Mask: The IPv4 netmask to match on. Default is 32 (the whole address)
 589   :param int v6Mask: The IPv6 netmask to match on. Default is 64
 590   :param int burst: The number of burstable queries per second allowed. Default is same as qps
 591   :param int expiration: How long to keep netmask or IP addresses after they have last been seen, in seconds. Default is 300
 592   :param int cleanupDelay: The number of seconds between two cleanups. Default is 60
 593   :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%
 594
 595 .. function:: MaxQPSRule(qps)
 596
 597   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.
 598   This can be used to enforce a global QPS limit.
 599
 600   :param int qps: The number of queries per second allowed, above this number the traffic is **not** matched anymore
 601
 602 .. function:: NetmaskGroupRule(nmg[, src])
 603
 604   Matches traffic from/to the network range specified in ``nmg``.
 605
 606   Set the ``src`` parameter to false to match ``nmg`` against destination address instead of source address.
 607   This can be used to differentiate between clients
 608
 609   :param NetMaskGroup nmg: The NetMaskGroup to match on
 610   :param bool src: Whether to match source or destination address of the packet. Defaults to true (matches source)
 611
 612 .. function:: OpcodeRule(code)
 613
 614   Matches queries with opcode ``code``.
 615   ``code`` can be directly specified as an integer, or one of the :ref:`built-in DNSOpcodes <DNSOpcode>`.
 616
 617   :param int code: The opcode to match
 618
 619 .. function:: ProbaRule(probability)
 620
 621   .. versionadded:: 1.3.0
 622
 623   Matches queries with a given probability. 1.0 means "always"
 624
 625   :param double probability: Probability of a match
 626
 627 .. function:: QClassRule(qclass)
 628
 629   Matches queries with the specified ``qclass``.
 630   ``class`` can be specified as an integer or as one of the built-in :ref:`DNSQClass`.
 631
 632   :param int qclass: The Query Class to match on
 633
 634 .. function:: QNameRule(qname)
 635
 636   .. versionadded:: 1.2.0
 637
 638    Matches queries with the specified qname exactly.
 639
 640    :param string qname: Qname to match
 641
 642 .. function:: QNameLabelsCountRule(min, max)
 643
 644   Matches if the qname has less than ``min`` or more than ``max`` labels.
 645
 646   :param int min: Minimum number of labels
 647   :param int max: Maximum nimber of labels
 648
 649 .. function:: QNameWireLengthRule(min, max)
 650
 651   Matches if the qname's length on the wire is less than ``min`` or more than ``max`` bytes.
 652
 653   :param int min: Minimum number of bytes
 654   :param int max: Maximum nimber of bytes
 655
 656 .. function:: QTypeRule(qtype)
 657
 658   Matches queries with the specified ``qtype``
 659   ``qtype`` may be specified as an integer or as one of the built-in QTypes.
 660   For instance ``dnsdist.A``, ``dnsdist.TXT`` and ``dnsdist.ANY``.
 661
 662   :param int qtype: The QType to match on
 663
 664 .. function:: RCodeRule(rcode)
 665
 666   Matches queries or responses with the specified ``rcode``.
 667   ``rcode`` can be specified as an integer or as one of the built-in :ref:`DNSRCode`.
 668   Only the non-extended RCode is matched (lower 4bits).
 669
 670   :param int rcode: The RCODE to match on
 671
 672 .. function:: RDRule()
 673
 674   .. versionadded:: 1.2.0
 675
 676   Matches queries with the RD flag set.
 677
 678 .. function:: RegexRule(regex)
 679
 680   Matches the query name against the ``regex``.
 681
 682   .. code-block:: Lua
 683
 684     addAction(RegexRule("[0-9]{5,}"), DelayAction(750)) -- milliseconds
 685     addAction(RegexRule("[0-9]{4,}\\.example$"), DropAction())
 686
 687   This delays any query for a domain name with 5 or more consecutive digits in it.
 688   The second rule drops anything with more than 4 consecutive digits within a .EXAMPLE domain.
 689
 690   Note that the query name is presented without a trailing dot to the regex.
 691   The regex is applied case insensitively.
 692
 693   :param string regex: A regular expression to match the traffic on
 694
 695 .. function:: RecordsCountRule(section, minCount, maxCount)
 696
 697   Matches if there is at least ``minCount`` and at most ``maxCount`` records in the section ``section``.
 698   ``section`` can be specified as an integer or as a :ref:`DNSSection`.
 699
 700   :param int section: The section to match on
 701   :param int minCount: The minimum number of entries
 702   :param int maxCount: The maximum number of entries
 703
 704 .. function:: RecordsTypeCountRule(section, qtype, minCount, maxCount)
 705
 706   Matches if there is at least ``minCount`` and at most ``maxCount`` records of type ``type`` in the section ``section``.
 707   ``section`` can be specified as an integer or as a ref:`DNSSection`.
 708   ``qtype`` may be specified as an integer or as one of the built-in QTypes, for instance ``dnsdist.A`` or ``dnsdist.TXT``.
 709
 710   :param int section: The section to match on
 711   :param int qtype: The QTYPE to match on
 712   :param int minCount: The minimum number of entries
 713   :param int maxCount: The maximum number of entries
 714
 715 .. function:: RE2Rule(regex)
 716
 717   Matches the query name against the supplied regex using the RE2 engine.
 718
 719   For an example of usage, see :func:`RegexRule`.
 720
 721   :note: Only available when dnsdist was built with libre2 support.
 722
 723   :param str regex: The regular expression to match the QNAME.
 724
 725 .. function:: SuffixMatchNodeRule(smn[, quiet])
 726
 727   Matches based on a group of domain suffixes for rapid testing of membership.
 728   Pass true as second parameter to prevent listing of all domains matched.
 729
 730   :param SuffixMatchNode smb: The SuffixMatchNode to match on
 731   :param bool quiet: Do not return the list of matched domains. Default is false.
 732
 733 .. function:: TagRule(name [, value])
 734
 735   .. versionadded:: 1.3.0
 736
 737   Matches question or answer with a tag named ``name`` set. If ``value`` is specified, the existing tag value should match too.
 738
 739   :param bool name: The name of the tag that has to be set
 740   :param bool value: If set, the value the tag has to be set to. Default is unset
 741
 742 .. function:: TCPRule([tcp])
 743
 744   Matches question received over TCP if ``tcp`` is true, over UDP otherwise.
 745
 746   :param bool tcp: Match TCP traffic. Default is true.
 747
 748 .. function:: TrailingDataRule()
 749
 750   Matches if the query has trailing data.
 751
 752 Combining Rules
 753 ~~~~~~~~~~~~~~~
 754
 755 .. function:: AndRule(selectors)
 756
 757   Matches traffic if all ``selectors`` match.
 758
 759   :param {Rule} selectors: A table of Rules
 760
 761 .. function:: NotRule(selector)
 762
 763   Matches the traffic if the ``selector`` rule does not match;
 764
 765   :param Rule selector: A Rule
 766
 767 .. function:: OrRule(selectors)
 768
 769   Matches the traffic if one or more of the the ``selectors`` Rules does match.
 770
 771   :param {Rule} selector: A table of Rules
 772
 773 Convenience Functions
 774 ~~~~~~~~~~~~~~~~~~~~~
 775
 776 .. function:: makeRule(rule)
 777
 778   Make a :func:`NetmaskGroupRule` or a :func:`SuffixMatchNodeRule`, depending on it is called.
 779   ``makeRule("0.0.0.0/0")`` will for example match all IPv4 traffic, ``makeRule({"be","nl","lu"})`` will match all Benelux DNS traffic.
 780
 781   :param string rule: A string to convert to a rule.
 782
 783
 784 Actions
 785 -------
 786
 787 :ref:`RulesIntro` need to be combined with an action for them to actually do something with the matched packets.
 788 Some actions allow further processing of rules, this is noted in their description.
 789 The following actions exist.
 790
 791 .. function:: AllowAction()
 792
 793   Let these packets go through.
 794
 795 .. function:: AllowResponseAction()
 796
 797   Let these packets go through.
 798
 799 .. function:: DelayAction(milliseconds)
 800
 801   Delay the response by the specified amount of milliseconds (UDP-only).
 802   Subsequent rules are processed after this rule.
 803
 804   :param int milliseconds: The amount of milliseconds to delay the response
 805
 806 .. function:: DelayResponseAction(milliseconds)
 807
 808   Delay the response by the specified amount of milliseconds (UDP-only).
 809   Subsequent rules are processed after this rule.
 810
 811   :param int milliseconds: The amount of milliseconds to delay the response
 812
 813 .. function:: DisableECSAction()
 814
 815   Disable the sending of ECS to the backend.
 816   Subsequent rules are processed after this rule.
 817
 818 .. function:: DisableValidationAction()
 819
 820   Set the CD bit in the query and let it go through.
 821
 822 .. function:: DnstapLogAction(identity, logger[, alterFunction])
 823
 824   .. versionadded:: 1.3.0
 825
 826   Send the the current query to a remote logger as a :doc:`dnstap <reference/dnstap>` message.
 827   ``alterFunction`` is a callback, receiving a :class:`DNSQuestion` and a :class:`DnstapMessage`, that can be used to modify the message.
 828
 829   :param string identity: Server identity to store in the dnstap message
 830   :param logger: The :func:`FrameStreamLogger <newFrameStreamUnixLogger>` or :func:`RemoteLogger <newRemoteLogger>` object to write to
 831   :param alterFunction: A Lua function to alter the message before sending
 832
 833 .. function:: DnstapLogResponseAction(identity, logger[, alterFunction])
 834
 835   .. versionadded:: 1.3.0
 836
 837   Send the the current response to a remote logger as a :doc:`dnstap <reference/dnstap>` message.
 838   ``alterFunction`` is a callback, receiving a :class:`DNSQuestion` and a :class:`DnstapMessage`, that can be used to modify the message.
 839
 840   :param string identity: Server identity to store in the dnstap message
 841   :param logger: The :func:`FrameStreamLogger <newFrameStreamUnixLogger>` or :func:`RemoteLogger <newRemoteLogger>` object to write to
 842   :param alterFunction: A Lua function to alter the message before sending
 843
 844 .. function:: DropAction()
 845
 846   Drop the packet.
 847
 848 .. function:: DropResponseAction()
 849
 850   Drop the packet.
 851
 852 .. function:: ECSOverrideAction(override)
 853
 854   Whether an existing EDNS Client Subnet value should be overridden (true) or not (false).
 855   Subsequent rules are processed after this rule.
 856
 857   :param bool override: Whether or not to override ECS value
 858
 859 .. function:: ECSPrefixLengthAction(v4, v6)
 860
 861   Set the ECS prefix length.
 862   Subsequent rules are processed after this rule.
 863
 864   :param int v4: The IPv4 netmask length
 865   :param int v6: The IPv6 netmask length
 866
 867
 868 .. function:: ERCodeAction(rcode)
 869
 870   .. versionadded:: 1.4.0
 871
 872   Reply immediately by turning the query into a response with the specified EDNS extended ``rcode``.
 873   ``rcode`` can be specified as an integer or as one of the built-in :ref:`DNSRCode`.
 874
 875   :param int rcode: The extended RCODE to respond with.
 876
 877 .. function:: LogAction([filename[, binary[, append[, buffered]]]])
 878
 879   Log a line for each query, to the specified ``file`` if any, to the console (require verbose) otherwise.
 880   When logging to a file, the ``binary`` optional parameter specifies whether we log in binary form (default) or in textual form.
 881   The ``append`` optional parameter specifies whether we open the file for appending or truncate each time (default).
 882   The ``buffered`` optional parameter specifies whether writes to the file are buffered (default) or not.
 883   Subsequent rules are processed after this rule.
 884
 885   :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.
 886   :param bool binary: Do binary logging. Default true
 887   :param bool append: Append to the log. Default false
 888   :param bool buffered: Use buffered I/O. default true
 889
 890 .. function:: LuaAction(function)
 891
 892   Invoke a Lua function that accepts a :class:`DNSQuestion`.
 893
 894   The ``function`` should return a :ref:`DNSAction`. If the Lua code fails, ServFail is returned.
 895
 896   :param string function: the name of a Lua function
 897
 898 .. function:: LuaResponseAction(function)
 899
 900   Invoke a Lua function that accepts a :class:`DNSResponse`.
 901
 902   The ``function`` should return a :ref:`DNSResponseAction`. If the Lua code fails, ServFail is returned.
 903
 904   :param string function: the name of a Lua function
 905
 906 .. function:: MacAddrAction(option)
 907
 908   Add the source MAC address to the query as EDNS0 option ``option``.
 909   This action is currently only supported on Linux.
 910   Subsequent rules are processed after this rule.
 911
 912   :param int option: The EDNS0 option number
 913
 914 .. function:: NoneAction()
 915
 916   Does nothing.
 917   Subsequent rules are processed after this rule.
 918
 919 .. function:: NoRecurseAction()
 920
 921   Strip RD bit from the question, let it go through.
 922   Subsequent rules are processed after this rule.
 923
 924 .. function:: PoolAction(poolname)
 925
 926   Send the packet into the specified pool.
 927
 928   :param string poolname: The name of the pool
 929
 930 .. function:: QPSAction(maxqps)
 931
 932   Drop a packet if it does exceed the ``maxqps`` queries per second limits.
 933   Letting the subsequent rules apply otherwise.
 934
 935   :param int maxqps: The QPS limit
 936
 937 .. function:: QPSPoolAction(maxqps, poolname)
 938
 939   Send the packet into the specified pool only if it does not exceed the ``maxqps`` queries per second limits.
 940   Letting the subsequent rules apply otherwise.
 941
 942   :param int maxqps: The QPS limit for that pool
 943   :param string poolname: The name of the pool
 944
 945 .. function:: RCodeAction(rcode)
 946
 947   Reply immediately by turning the query into a response with the specified ``rcode``.
 948   ``rcode`` can be specified as an integer or as one of the built-in :ref:`DNSRCode`.
 949
 950   :param int rcode: The RCODE to respond with.
 951
 952 .. function:: RemoteLogAction(remoteLogger[, alterFunction [, options]])
 953
 954   .. versionchanged:: 1.3.0
 955     ``options`` optional parameter added.
 956
 957   Send the content of this query to a remote logger via Protocol Buffer.
 958   ``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
 959
 960   :param string remoteLogger: The :func:`remoteLogger <newRemoteLogger>` object to write to
 961   :param string alterFunction: Name of a function to modify the contents of the logs before sending
 962   :param table options: A table with key: value pairs.
 963
 964   Options:
 965
 966   * ``serverID=""``: str - Set the Server Identity field.
 967
 968 .. function:: RemoteLogResponseAction(remoteLogger[, alterFunction[, includeCNAME [, options]]])
 969
 970   .. versionchanged:: 1.3.0
 971     ``options`` optional parameter added.
 972
 973   Send the content of this response to a remote logger via Protocol Buffer.
 974   ``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
 975   ``includeCNAME`` indicates whether CNAME records inside the response should be parsed and exported.
 976   The default is to only exports A and AAAA records
 977
 978   :param string remoteLogger: The :func:`remoteLogger <newRemoteLogger>` object to write to
 979   :param string alterFunction: Name of a function to modify the contents of the logs before sending
 980   :param bool includeCNAME: Whether or not to parse and export CNAMEs. Default false
 981   :param table options: A table with key: value pairs.
 982
 983   Options:
 984
 985   * ``serverID=""``: str - Set the Server Identity field.
 986
 987 .. function:: SetECSAction(v4 [, v6])
 988
 989   .. versionadded:: 1.3.1
 990
 991   Set the ECS prefix and prefix length sent to backends to an arbitrary value.
 992   If both IPv4 and IPv6 masks are supplied the IPv4 one will be used for IPv4 clients
 993   and the IPv6 one for IPv6 clients. Otherwise the first mask is used for both, and
 994   can actually be an IPv6 mask.
 995   Subsequent rules are processed after this rule.
 996
 997   :param string v4: The IPv4 netmask, for example "192.0.2.1/32"
 998   :param string v6: The IPv6 netmask, if any
 999
1000 .. function:: SkipCacheAction()
1001
1002   Don't lookup the cache for this query, don't store the answer.
1003
1004 .. function:: SNMPTrapAction([message])
1005
1006   Send an SNMP trap, adding the optional ``message`` string as the query description.
1007   Subsequent rules are processed after this rule.
1008
1009   :param string message: The message to include
1010
1011 .. function:: SNMPTrapResponseAction([message])
1012
1013   Send an SNMP trap, adding the optional ``message`` string as the query description.
1014   Subsequent rules are processed after this rule.
1015
1016   :param string message: The message to include
1017
1018 .. function:: SpoofAction(ip[, ip[...]])
1019               SpoofAction(ips)
1020
1021   Forge a response with the specified IPv4 (for an A query) or IPv6 (for an AAAA) addresses.
1022   If you specify multiple addresses, all that match the query type (A, AAAA or ANY) will get spoofed in.
1023
1024   :param string ip: An IPv4 and/or IPv6 address to spoof
1025   :param {string} ips: A table of IPv4 and/or IPv6 addresses to spoof
1026
1027 .. function:: SpoofCNAMEAction(cname)
1028
1029   Forge a response with the specified CNAME value.
1030
1031   :param string cname: The name to respond with
1032
1033 .. function:: TagAction(name, value)
1034
1035   .. versionadded:: 1.3.0
1036
1037   Associate a tag named ``name`` with a value of ``value`` to this query, that will be passed on to the response.
1038
1039   :param string name: The name of the tag to set
1040   :param string cname: The value of the tag
1041
1042 .. function:: TagResponseAction(name, value)
1043
1044   .. versionadded:: 1.3.0
1045
1046   Associate a tag named ``name`` with a value of ``value`` to this response.
1047
1048   :param string name: The name of the tag to set
1049   :param string cname: The value of the tag
1050
1051 .. function:: TCAction()
1052
1053   Create answer to query with TC and RD bits set, to force the client to TCP.
1054
1055 .. function:: TeeAction(remote[, addECS])
1056
1057   Send copy of query to ``remote``, keep stats on responses.
1058   If ``addECS`` is set to true, EDNS Client Subnet information will be added to the query.
1059
1060   :param string remote: An IP:PORT conbination to send the copied queries to
1061   :param bool addECS: Whether or not to add ECS information. Default false
1062
1063 .. function:: TempFailureCacheTTLAction(ttl)
1064
1065   Set the cache TTL to use for ServFail and Refused replies. TTL is not applied for successful replies.
1066
1067   :param int ttl: Cache TTL for temporary failure replies