DNS Rule Action

Changes in sing-box 1.14.0

strategy
evaluate
respond
disable_optimistic_cache
timeout
race
speculative

Changes in sing-box 1.12.0

Since sing-box 1.11.0

Structure

{
  "action": "",
  "race": false,

  ... // Action Fields
}

action

The action to perform. route will be used by default.

race

Since sing-box 1.14.0

Only available with route, respond, reject and predefined actions.

Requires match_response (for logical rules, in sub-rules). Conflict with speculative.

By default, rules are matched one after another in listed order: a rule with match_response waits for its referenced responses, and no later rule is matched until it has been judged.

A rule with race enabled does not hold this order: rule matching continues past it while its referenced responses are still pending, so the matching of race rules runs in parallel — with each other and with the rules after them. Each race rule is judged once its referenced responses are available, and the first race rule that matches terminates rule evaluation immediately; the remaining queries are canceled.

Rules without race still take effect strictly in listed order: while a preceding race rule is not yet judged, the action of any other matched rule is held until none of the race rules matched. The result may therefore depend on server speed only among race rules.

route

{
  "action": "route",  // default
  "server": "",
  "speculative": false,
  "strategy": "",
  "disable_cache": false,
  "disable_optimistic_cache": false,
  "rewrite_ttl": null,
  "timeout": "",
  "client_subnet": null
}

route inherits the classic rule behavior of routing DNS requests to the specified server.

server

Required

Tag of target server.

speculative

Since sing-box 1.14.0

Conflict with race. Has no effect without a preceding race rule.

By default, no query is sent in parallel with pending race rules: a matched route action holds its query until none of the race rules matched.

When speculative is enabled, the query is sent as soon as the rule matches, in parallel with the pending race rules, and may be wasted: its response is still used only after none of the race rules matched.

strategy

Since sing-box 1.12.0

Deprecated in sing-box 1.14.0

strategy is deprecated in sing-box 1.14.0 and will be removed in sing-box 1.16.0.

Set domain strategy for this query.

One of prefer_ipv4 prefer_ipv6 ipv4_only ipv6_only.

disable_cache

Disable cache and save cache in this query.

disable_optimistic_cache

Since sing-box 1.14.0

Disable optimistic DNS caching in this query.

rewrite_ttl

Rewrite TTL in DNS responses.

timeout

Since sing-box 1.14.0

Override the DNS query timeout for matched queries.

Will override dns.timeout.

client_subnet

Append a edns0-subnet OPT extra record with the specified IP prefix to every query by default.

If value is an IP address instead of prefix, /32 or /128 will be appended automatically.

Will override dns.client_subnet.

evaluate

Since sing-box 1.14.0

{
  "action": "evaluate",
  "server": "",
  "tag": "",
  "speculative": false,
  "disable_cache": false,
  "disable_optimistic_cache": false,
  "rewrite_ttl": null,
  "timeout": "",
  "client_subnet": null
}

evaluate sends a DNS query to the specified server and saves the evaluated response for subsequent rules to match against using match_response and response fields. Unlike route, it does not terminate rule evaluation.

Only allowed on top-level DNS rules (not inside logical sub-rules). Rules that use match_response or Response Match Fields require a preceding top-level rule with evaluate action. A rule's own evaluate action does not satisfy this requirement, because matching happens before the action runs.

server

Required

Tag of target server.

tag

Tag of the evaluated response.

A tagged response is only referenced via match_response with the tag; match_response: true references the response of the latest evaluate action without tag.

speculative

Since sing-box 1.14.0

Has no effect without a preceding race rule.

By default, no query is sent in parallel with pending race rules: a matched evaluate action holds its query, and rule matching stops there, until none of the race rules matched.

When speculative is enabled, the query is sent as soon as the rule matches, in parallel with the pending race rules, and may be wasted: rule matching continues without waiting for them.

disable_cache

Disable cache and save cache in this query.

disable_optimistic_cache

Since sing-box 1.14.0

Disable optimistic DNS caching in this query.

rewrite_ttl

Rewrite TTL in DNS responses.

timeout

Since sing-box 1.14.0

Override the DNS query timeout for matched queries.

Will override dns.timeout.

client_subnet

Append a edns0-subnet OPT extra record with the specified IP prefix to every query by default.

If value is an IP address instead of prefix, /32 or /128 will be appended automatically.

Will override dns.client_subnet.

respond

Since sing-box 1.14.0

{
  "action": "respond"
}

respond terminates rule evaluation and returns the evaluated response from a preceding evaluate action.

This action does not send a new DNS query.

Only allowed after a preceding top-level evaluate rule. If the action is reached without an evaluated response at runtime, the request fails with an error instead of falling through to later rules.

route-options

{
  "action": "route-options",
  "disable_cache": false,
  "disable_optimistic_cache": false,
  "rewrite_ttl": null,
  "timeout": "",
  "client_subnet": null
}

route-options set options for routing.

reject

{
  "action": "reject",
  "method": "",
  "no_drop": false
}

reject reject DNS requests.

method

default: Reply with REFUSED.
drop: Drop the request.

default will be used by default.

no_drop

If not enabled, method will be temporarily overwritten to drop after 50 triggers in 30s.

Not available when method is set to drop.

predefined

Since sing-box 1.12.0

{
  "action": "predefined",
  "rcode": "",
  "answer": [],
  "ns": [],
  "extra": []
}

predefined responds with predefined DNS records.

rcode

The response code.

Value	Value in the legacy rcode server	Description
`NOERROR`	`success`	Ok
`FORMERR`	`format_error`	Bad request
`SERVFAIL`	`server_failure`	Server failure
`NXDOMAIN`	`name_error`	Not found
`NOTIMP`	`not_implemented`	Not implemented
`REFUSED`	`refused`	Refused

NOERROR will be used by default.

answer

List of text DNS record to respond as answers.

Examples:

Record Type	Example
`A`	`localhost. IN A 127.0.0.1`
`AAAA`	`localhost. IN AAAA ::1`
`TXT`	`localhost. IN TXT \"Hello\"`

ns

List of text DNS record to respond as name servers.

extra

List of text DNS record to respond as extra records.