wangjia/sing-box
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
testing
sing-box/docs/configuration/dns/rule_action.md
T

326 lines
8.1 KiB
Markdown
Raw Permalink Blame History

---
icon: material/new-box
---
!!! quote "Changes in sing-box 1.14.0"
:material-delete-clock: [strategy](#strategy)
:material-plus: [evaluate](#evaluate)
:material-plus: [respond](#respond)
:material-plus: [disable_optimistic_cache](#disable_optimistic_cache)
:material-plus: [timeout](#timeout)
:material-plus: [race](#race)
:material-plus: [speculative](#speculative)
!!! quote "Changes in sing-box 1.12.0"
:material-plus: [strategy](#strategy)
:material-plus: [predefined](#predefined)
!!! question "Since sing-box 1.11.0"
### Structure
```json
{
"action": "",
"race": false,
... // Action Fields
}
```
#### action
The action to perform. `route` will be used by default.
#### race
!!! question "Since sing-box 1.14.0"
Only available with `route`, `respond`, `reject` and `predefined` actions.
Requires [`match_response`](/configuration/dns/rule/#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
```json
{
"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
!!! question "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
!!! question "Since sing-box 1.12.0"
!!! failure "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
!!! question "Since sing-box 1.14.0"
Disable optimistic DNS caching in this query.
#### rewrite_ttl
Rewrite TTL in DNS responses.
#### timeout
!!! question "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
!!! question "Since sing-box 1.14.0"
```json
{
"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`](/configuration/dns/rule/#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`](/configuration/dns/rule/#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`](/configuration/dns/rule/#match_response) with the tag;
`match_response: true` references the response of the latest `evaluate` action without `tag`.
#### speculative
!!! question "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
!!! question "Since sing-box 1.14.0"
Disable optimistic DNS caching in this query.
#### rewrite_ttl
Rewrite TTL in DNS responses.
#### timeout
!!! question "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
!!! question "Since sing-box 1.14.0"
```json
{
"action": "respond"
}
```
`respond` terminates rule evaluation and returns the evaluated response from a preceding [`evaluate`](/configuration/dns/rule_action/#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
```json
{
"action": "route-options",
"disable_cache": false,
"disable_optimistic_cache": false,
"rewrite_ttl": null,
"timeout": "",
"client_subnet": null
}
```
`route-options` set options for routing.
### reject
```json
{
"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
!!! question "Since sing-box 1.12.0"
```json
{
"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.
Reference in New Issue View Git Blame Copy Permalink