Rules management

Incoming queries

For Rules related to the incoming query:

addAction(DNSrule, action[, options])

Changed in version 1.6.0: Added name to the options.

Changed in version 1.9.0: Passing a string or list of strings instead of a DNSRule is deprecated, use NetmaskGroupRule() or QNameSuffixRule() instead

Add a Rule and Action to the existing rules. If a string (or list of) is passed as the first parameter instead of a DNSRule, it behaves as if the string or list of strings was passed to NetmaskGroupRule() or SuffixMatchNodeRule().

Parameters:
  • rule (DNSrule) – A DNSRule, e.g. an AllRule(), or a compounded bunch of rules using e.g. AndRule(). Before 1.9.0 it was also possible to pass a string (or list of strings) but doing so is now deprecated.
  • action – The action to take
  • options (table) – A table with key: value pairs with options.

Options:

  • uuid: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
  • name: string - Name to assign to the new rule.
clearRules()

Remove all current rules.

getAction(n) → DNSDistRuleAction

Returns the DNSDistRuleAction associated with rule n.

Parameters:n (int) – The rule number
getRule(selector) → DNSDistRuleAction

New in version 1.9.0.

Return the rule corresponding to the selector, if any. The selector can be the position of the rule in the list, as an integer, its name as a string or its UUID as a string as well.

Parameters:or str selector (int) – The position in the list, name or UUID of the rule to return.
mvRule(from, to)

Move rule from to a position where it is in front of to. to can be one larger than the largest rule, in which case the rule will be moved to the last position.

Parameters:
  • from (int) – Rule number to move
  • to (int) – Location to more the Rule to
mvRuleToTop()

New in version 1.6.0.

This function moves the last rule to the first position. Before 1.6.0 this was handled by topRule().

setRules(rules)

Replace the current rules with the supplied list of pairs of DNS Rules and DNS Actions (see newRuleAction())

Parameters:rules ([RuleAction]) – A list of RuleActions
showRules([options])

Show all defined rules for queries, optionally displaying their UUIDs.

Parameters:options (table) – A table with key: value pairs with display options.

Options:

  • showUUIDs=false: bool - Whether to display the UUIDs, defaults to false.
  • truncateRuleWidth=-1: int - Truncate rules output to truncateRuleWidth size. Defaults to -1 to display the full rule.
topRule()

Changed in version 1.6.0: Replaced by mvRuleToTop()

Before 1.6.0 this function used to move the last rule to the first position, which is now handled by mvRuleToTop().

rmRule(id)

Changed in version 1.6.0: id can now be a string representing the name of the rule.

Remove rule id.

Parameters:id (int) – The position of the rule to remove if id is numerical, its UUID or name otherwise

Cache misses

For Rules related to the incoming query after a cache miss:

Warning

While all selectors and actions are available, some actions will no longer be honored at this point. For example changing the backend pool will not trigger a second cache-lookup. Switching from a backend pool that has EDNS Client Subnet enabled to one that doesn’t will result in the EDNS Client Subnet corresponding to the initial server pool to be added to the query.

addCacheMissAction(DNSrule, action[, options])

New in version 1.10.

Add a Rule and Action to the existing cache miss rules. If a string (or list of) is passed as the first parameter instead of a DNSRule, it behaves as if the string or list of strings was passed to NetmaskGroupRule() or SuffixMatchNodeRule().

Parameters:
  • rule (DNSrule) – A DNSRule, e.g. an AllRule(), or a compounded bunch of rules using e.g. AndRule().
  • action – The action to take
  • options (table) – A table with key: value pairs with options.

Options:

  • uuid: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
  • name: string - Name to assign to the new rule.
clearCacheMissRules()

New in version 1.10.

Remove all current cache miss rules.

getCacheMissAction(n) → DNSDistRuleAction

New in version 1.10.

Returns the DNSDistRuleAction associated with cache miss rule n.

Parameters:n (int) – The rule number
getCacheMissRule(selector) → DNSDistRuleAction

New in version 1.10.

Return the cache miss rule corresponding to the selector, if any. The selector can be the position of the rule in the list, as an integer, its name as a string or its UUID as a string as well.

Parameters:or str selector (int) – The position in the list, name or UUID of the rule to return.
mvCacheMissRule(from, to)

New in version 1.10.

Move cache miss rule from to a position where it is in front of to. to can be one larger than the largest rule, in which case the rule will be moved to the last position.

Parameters:
  • from (int) – Rule number to move
  • to (int) – Location to more the Rule to
mvCacheMissRuleToTop()

New in version 1.10.

This function moves the last cache miss rule to the first position.

setCacheMissRules(rules)

New in version 1.10.

Replace the current cache miss rules with the supplied list of pairs of DNS Rules and DNS Actions (see newRuleAction())

Parameters:rules ([RuleAction]) – A list of RuleActions
showCacheMissRules([options])

New in version 1.10.

Show all defined cache miss rules for queries, optionally displaying their UUIDs.

Parameters:options (table) – A table with key: value pairs with display options.

Options:

  • showUUIDs=false: bool - Whether to display the UUIDs, defaults to false.
  • truncateRuleWidth=-1: int - Truncate rules output to truncateRuleWidth size. Defaults to -1 to display the full rule.
rmCacheMissRule(id)

New in version 1.10.

Remove rule id.

Parameters:id (int) – The position of the cache miss rule to remove if id is numerical, its UUID or name otherwise

Responses

For Rules related to responses:

addResponseAction(DNSRule, action[, options])

Changed in version 1.6.0: Added name to the options.

Changed in version 1.9.0: Passing a string or list of strings instead of a DNSRule is deprecated, use NetmaskGroupRule() or QNameSuffixRule() instead

Add a Rule and Action for responses to the existing rules. If a string (or list of) is passed as the first parameter instead of a DNSRule, it behaves as if the string or list of strings was passed to NetmaskGroupRule() or SuffixMatchNodeRule().

Parameters:
  • rule (DNSrule) – A DNSRule, e.g. an AllRule(), or a compounded bunch of rules using e.g. AndRule(). Before 1.9.0 it was also possible to pass a string (or list of strings) but doing so is now deprecated.
  • action – The action to take
  • options (table) – A table with key: value pairs with options.

Options:

  • uuid: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
  • name: string - Name to assign to the new rule.
clearResponseRules()

New in version 1.10.

Remove all current response rules.

getResponseRule(selector) → DNSDistResponseRuleAction

New in version 1.9.0.

Return the response rule corresponding to the selector, if any. The selector can be the position of the rule in the list, as an integer, its name as a string or its UUID as a string as well.

Parameters:or str selector (int) – The position in the list, name or UUID of the rule to return.
mvResponseRule(from, to)

Move response rule from to a position where it is in front of to. to can be one larger than the largest rule, in which case the rule will be moved to the last position.

Parameters:
  • from (int) – Rule number to move
  • to (int) – Location to more the Rule to
mvResponseRuleToTop()

New in version 1.6.0.

This function moves the last response rule to the first position. Before 1.6.0 this was handled by topResponseRule().

rmResponseRule(id)

Changed in version 1.6.0: id can now be a string representing the name of the rule.

Remove response rule id.

Parameters:id (int) – The position of the rule to remove if id is numerical, its UUID or name otherwise
showResponseRules([options])

Show all defined response rules, optionally displaying their UUIDs.

Parameters:options (table) – A table with key: value pairs with display options.

Options:

  • showUUIDs=false: bool - Whether to display the UUIDs, defaults to false.
  • truncateRuleWidth=-1: int - Truncate rules output to truncateRuleWidth size. Defaults to -1 to display the full rule.
topResponseRule()

Changed in version 1.6.0: Replaced by mvResponseRuleToTop()

Before 1.6.0 this function used to move the last response rule to the first position, which is now handled by mvResponseRuleToTop().

Cache hits

Functions for manipulating Cache Hit Response Rules:

addCacheHitResponseAction(DNSRule, action[, options])

Changed in version 1.6.0: Added name to the options.

Changed in version 1.9.0: Passing a string or list of strings instead of a DNSRule is deprecated, use NetmaskGroupRule() or QNameSuffixRule() instead

Add a Rule and ResponseAction for Cache Hits to the existing rules. If a string (or list of) is passed as the first parameter instead of a DNSRule, it behaves as if the string or list of strings was passed to NetmaskGroupRule() or SuffixMatchNodeRule().

Parameters:
  • rule (DNSrule) – A DNSRule, e.g. an AllRule(), or a compounded bunch of rules using e.g. AndRule(). Before 1.9.0 it was also possible to pass a string (or list of strings) but doing so is now deprecated.
  • action – The action to take
  • options (table) – A table with key: value pairs with options.

Options:

  • uuid: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
  • name: string - Name to assign to the new rule.
clearCacheHitResponseRules()

New in version 1.10.

Remove all current cache-hit response rules.

getCacheHitResponseRule(selector) → DNSDistResponseRuleAction

New in version 1.9.0.

Return the cache-hit response rule corresponding to the selector, if any. The selector can be the position of the rule in the list, as an integer, its name as a string or its UUID as a string as well.

Parameters:or str selector (int) – The position in the list, name or UUID of the rule to return.
mvCacheHitResponseRule(from, to)

Move cache hit response rule from to a position where it is in front of to. to can be one larger than the largest rule, in which case the rule will be moved to the last position.

Parameters:
  • from (int) – Rule number to move
  • to (int) – Location to more the Rule to
mvCacheHitResponseRuleToTop()

New in version 1.6.0.

This function moves the last cache hit response rule to the first position. Before 1.6.0 this was handled by topCacheHitResponseRule().

rmCacheHitResponseRule(id)

Changed in version 1.6.0: id can now be a string representing the name of the rule.

Parameters:id (int) – The position of the rule to remove if id is numerical, its UUID or name otherwise
showCacheHitResponseRules([options])

Show all defined cache hit response rules, optionally displaying their UUIDs.

Parameters:options (table) – A table with key: value pairs with display options.

Options:

  • showUUIDs=false: bool - Whether to display the UUIDs, defaults to false.
  • truncateRuleWidth=-1: int - Truncate rules output to truncateRuleWidth size. Defaults to -1 to display the full rule.
topCacheHitResponseRule()

Changed in version 1.6.0: Replaced by mvCacheHitResponseRuleToTop()

Before 1.6.0 this function used to move the last cache hit response rule to the first position, which is now handled by mvCacheHitResponseRuleToTop().

Cache inserted

Functions for manipulating Cache Inserted Response Rules:

addCacheInsertedResponseAction(DNSRule, action[, options])

New in version 1.8.0.

Changed in version 1.9.0: Passing a string or list of strings instead of a DNSRule is deprecated, use NetmaskGroupRule() or QNameSuffixRule() instead

Add a Rule and ResponseAction that is executed after a cache entry has been inserted to the existing rules. If a string (or list of) is passed as the first parameter instead of a DNSRule, it behaves as if the string or list of strings was passed to NetmaskGroupRule() or SuffixMatchNodeRule().

Parameters:
  • rule (DNSrule) – A DNSRule, e.g. an AllRule(), or a compounded bunch of rules using e.g. AndRule(). Before 1.9.0 it was also possible to pass a string (or list of strings) but doing so is now deprecated.
  • action – The action to take
  • options (table) – A table with key: value pairs with options.

Options:

  • uuid: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
  • name: string - Name to assign to the new rule.
clearCacheInsertedResponseRules()

New in version 1.10.

Remove all current cache-inserted response rules.

getCacheInsertedResponseRule(selector) → DNSDistResponseRuleAction

New in version 1.9.0.

Return the cache-inserted response rule corresponding to the selector, if any. The selector can be the position of the rule in the list, as an integer, its name as a string or its UUID as a string as well.

Parameters:or str selector (int) – The position in the list, name or UUID of the rule to return.
mvCacheInsertedResponseRule(from, to)

New in version 1.8.0.

Move cache inserted response rule from to a position where it is in front of to. to can be one larger than the largest rule, in which case the rule will be moved to the last position.

Parameters:
  • from (int) – Rule number to move
  • to (int) – Location to more the Rule to
mvCacheInsertedResponseRuleToTop()

New in version 1.8.0.

This function moves the last cache inserted response rule to the first position.

rmCacheInsertedResponseRule(id)

New in version 1.8.0.

Parameters:id (int) – The position of the rule to remove if id is numerical, its UUID or name otherwise
showCacheInsertedResponseRules([options])

New in version 1.8.0.

Show all defined cache inserted response rules, optionally displaying their UUIDs.

Parameters:options (table) – A table with key: value pairs with display options.

Options:

  • showUUIDs=false: bool - Whether to display the UUIDs, defaults to false.
  • truncateRuleWidth=-1: int - Truncate rules output to truncateRuleWidth size. Defaults to -1 to display the full rule.

Self-answered responses

Functions for manipulating Self-Answered Response Rules:

addSelfAnsweredResponseAction(DNSRule, action[, options])

Changed in version 1.6.0: Added name to the options.

Changed in version 1.9.0: Passing a string or list of strings instead of a DNSRule is deprecated, use NetmaskGroupRule() or QNameSuffixRule() instead

Add a Rule and Action for Self-Answered queries to the existing rules. If a string (or list of) is passed as the first parameter instead of a DNSRule, it behaves as if the string or list of strings was passed to NetmaskGroupRule() or SuffixMatchNodeRule().

Parameters:
  • rule (DNSrule) – A DNSRule, e.g. an AllRule(), or a compounded bunch of rules using e.g. AndRule(). Before 1.9.0 it was also possible to pass a string (or list of strings) but doing so is now deprecated.
  • action – The action to take
  • options (table) – A table with key: value pairs with options.

Options:

  • uuid: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
  • name: string - Name to assign to the new rule.
clearSelfAnsweredResponseRules()

New in version 1.10.

Remove all current self-answered response rules.

getSelfAnsweredResponseRule(selector) → DNSDistResponseRuleAction

New in version 1.9.0.

Return the self-answered response rule corresponding to the selector, if any. The selector can be the position of the rule in the list, as an integer, its name as a string or its UUID as a string as well.

Parameters:or str selector (int) – The position in the list, name or UUID of the rule to return.
mvSelfAnsweredResponseRule(from, to)

Move self answered response rule from to a position where it is in front of to. to can be one larger than the largest rule, in which case the rule will be moved to the last position.

Parameters:
  • from (int) – Rule number to move
  • to (int) – Location to more the Rule to
mvSelfAnsweredResponseRuleToTop()

New in version 1.6.0.

This function moves the last self-answered response rule to the first position. Before 1.6.0 this was handled by topSelfAnsweredResponseRule().

rmSelfAnsweredResponseRule(id)

Changed in version 1.6.0: id can now be a string representing the name of the rule.

Remove self answered response rule id.

Parameters:id (int) – The position of the rule to remove if id is numerical, its UUID or name otherwise
showSelfAnsweredResponseRules([options])

Show all defined self answered response rules, optionally displaying their UUIDs.

Parameters:options (table) – A table with key: value pairs with display options.

Options:

  • showUUIDs=false: bool - Whether to display the UUIDs, defaults to false.
  • truncateRuleWidth=-1: int - Truncate rules output to truncateRuleWidth size. Defaults to -1 to display the full rule.
topSelfAnsweredResponseRule()

Changed in version 1.6.0: Replaced by mvSelfAnsweredResponseRuleToTop()

Before 1.6.0 this function used to move the last self-answered response rule to the first position, which is now handled by mvSelfAnsweredResponseRuleToTop().

Move the last self answered response rule to the first position.

XFR

Functions for manipulating zone transfer (AXFR, IXFR) Response Rules:

Note

Please remember that a zone transfer (XFR) can and will often contain several response packets to a single query packet.

Warning

While almost all existing selectors and Response actions should be usable from the XFR response rules, it is strongly advised to only inspect the content of XFR response packets, and not modify them. Logging the content of response packets can be done via:

addXFRResponseAction(DNSRule, action[, options])

New in version 1.10.

Add a Rule and ResponseAction for zone transfers (XFR) to the existing rules. If a string (or list of) is passed as the first parameter instead of a DNSRule, it behaves as if the string or list of strings was passed to NetmaskGroupRule() or SuffixMatchNodeRule().

Parameters:
  • rule (DNSrule) – A DNSRule, e.g. an AllRule(), or a compounded bunch of rules using e.g. AndRule().
  • action – The action to take
  • options (table) – A table with key: value pairs with options.

Options:

  • uuid: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
  • name: string - Name to assign to the new rule.
mvXFRResponseRule(from, to)

New in version 1.10.

Move XFR response rule from to a position where it is in front of to. to can be one larger than the largest rule, in which case the rule will be moved to the last position.

Parameters:
  • from (int) – Rule number to move
  • to (int) – Location to more the Rule to
mvXFRResponseRuleToTop()

New in version 1.10.

This function moves the last XFR response rule to the first position.

rmXFRResponseRule(id)

New in version 1.10.

Parameters:id (int) – The position of the rule to remove if id is numerical, its UUID or name otherwise
showXFRResponseRules([options])

New in version 1.10.

Show all defined XFR response rules, optionally displaying their UUIDs.

Parameters:options (table) – A table with key: value pairs with display options.

Options:

  • showUUIDs=false: bool - Whether to display the UUIDs, defaults to false.
  • truncateRuleWidth=-1: int - Truncate rules output to truncateRuleWidth size. Defaults to -1 to display the full rule.

Convenience Functions

makeRule(rule)

Changed in version 1.9.0: This function is deprecated, please use NetmaskGroupRule() or QNameSuffixRule() instead

Make a NetmaskGroupRule() or a SuffixMatchNodeRule(), depending on how it is called. The rule parameter can be a string, or a list of strings, that should contain either:

Mixing both netmasks and domain names is not supported, and will result in domain names being ignored!

makeRule("0.0.0.0/0") will for example match all IPv4 traffic, makeRule({"be","nl","lu"}) will match all Benelux DNS traffic.

Parameters:rule (string) – A string, or list of strings, to convert to a rule.
newRuleAction(rule, action[, options])

Changed in version 1.6.0: Added name to the options.

Return a pair of DNS Rule and DNS Action, to be used with setRules().

Parameters:
  • rule (Rule) – A Rule (see Rule selectors)
  • action (Action) – The Action (see Rule Actions) to apply to the matched traffic
  • options (table) – A table with key: value pairs with options.

Options:

  • uuid: string - UUID to assign to the new rule. By default a random UUID is generated for each rule.
  • name: string - Name to assign to the new rule.