Reference: rules

This page is the schema reference for the top-level rules: block. For selectors, actions, and evaluation order, see Rules and actions.

rules

Field	Type	Required	Default	Meaning
match_mode	string	no	first_match	Rule evaluation mode. Only first_match is supported today; other modes may be added in a future release.
rules	list of rule objects	no	[]	Ordered list of rules

Rule object

Field	Type	Required	Meaning
name	string	yes	Unique rule name (non-empty)
hook	string	yes	request or response
selectors	list	no	Match conditions; empty list matches all queries on this hook
actions	list	yes	Built-in actions; run in list order

Selector object

Field	Type	Required	Meaning
type	string	yes	Selector type (see groups below)
value	string	yes	Selector-specific match string
key	string	no	sample_percent only: static salt (mutually exclusive with key_from)
key_from	string	no	sample_percent only: qname, rule_name (rules only), or sink_name (event sink selectors only)

Query identity: qname_exact, qname_suffix, qtype, qclass, opcode, edns_option

Response outcome: rcode

Wire-enum selector values (qtype, qclass, opcode, edns_option, rcode) use the same IANA names and numeric aliases as Rule Rhai (A, TYPE1, SERVFAIL, RCODE2, …). Unknown values are rejected at config load.

Transaction metadata: tag, client_cidr (rule-only; value = type: cidr data source name — see Client ACLs and Rules and actions — Selectors)

Sampling and cadence: every_nth_global, every_nth_worker, sample_percent — see Rules and actions — Sampling and cadence

sample_percent expects a float in [0, 100].

every_nth_worker and every_nth_global expect an integer N >= 1.

Full operator-oriented grouping: Rules and actions — Selectors.

Action object

Field	Type	Required	Meaning
type	string	yes	Action name (see below)
value	string	varies	Action argument

Action types

type	Valid hooks	value
clear_drop	request, response	Clear soft-drop intent (value —)
clear_tag	request, response	Tag key to remove (non-empty)
clear_retry	response	Clear soft-retry intent (value —)
clear_pool	request, response	Clears selected_pool — next Route uses the configured default pool (value —)
clear_retry_pool	request, response	Clears retry_pool (value —)
drop	request, response	Soft drop (value —)
drop_now	request, response	Hard drop — stop further actions on this rule (value —)
retry	response	Soft retry in the current pool (value —)
retry_now	response	Hard retry — stop further actions on this rule (value —)
rhai	request, response	Path to .rhai script (non-empty); runs at this position in the action list
set_pool	request	Pool name
set_rcode	response	RCODE name or RCODEN alias (for example SERVFAIL, RCODE2)
set_retry_pool	request, response	Pool name — pool for retry Route if retry occurs; first Route ignores (value required)
set_source_v4	request only	IPv4 address in configured sources_v4 union
set_source_v6	request only	IPv6 address in configured sources_v6 union
set_retry_source_v4	request, response	IPv4 address in configured sources_v4 union (one-shot retry forward)
set_retry_source_v6	request, response	IPv6 address in configured sources_v6 union (one-shot retry forward)
clear_retry_source_v4	request, response	Clears retry_source_override_v4 (value —)
clear_retry_source_v6	request, response	Clears retry_source_override_v6 (value —)
set_tag	request, response	key=value or key

set_source_v4 / set_source_v6 / set_retry_source_v4 / set_retry_source_v6 validation

At config load / validate:

• value must be a valid IPv4 or IPv6 address (standing and retry-source actions).
• The address must appear in the union of forward.sources_v4 / forward.sources_v6 and every pool’s sources_v4 / sources_v6.
• At least one corresponding source list must be non-empty.
• set_source_* — request hook only. set_retry_source_* — request or response hook.

At Forward, standing overrides apply on every attempt unless a one-shot retry_source_override_* wins on retry forwards (attempt_count > 1). Allowed-set check uses the pool in use; disallowed addresses fail open to round-robin.

See Rules and actions — Action order.