docs/configuration/dns/rule.md
!!! quote "Changes in sing-box 1.14.0"
:material-plus: [source_mac_address](#source_mac_address)
:material-plus: [source_hostname](#source_hostname)
:material-plus: [preferred_by](#preferred_by)
:material-plus: [match_response](#match_response)
:material-delete-clock: [rule_set_ip_cidr_accept_empty](#rule_set_ip_cidr_accept_empty)
:material-plus: [response_rcode](#response_rcode)
:material-plus: [response_answer](#response_answer)
:material-plus: [response_ns](#response_ns)
:material-plus: [response_extra](#response_extra)
:material-plus: [package_name_regex](#package_name_regex)
:material-plus: [query_client_subnet](#query_client_subnet)
:material-plus: [query_dnssec](#query_dnssec)
:material-alert: [ip_version](#ip_version)
:material-alert: [query_type](#query_type)
!!! quote "Changes in sing-box 1.13.0"
:material-plus: [interface_address](#interface_address)
:material-plus: [network_interface_address](#network_interface_address)
:material-plus: [default_interface_address](#default_interface_address)
!!! quote "Changes in sing-box 1.12.0"
:material-plus: [ip_accept_any](#ip_accept_any)
:material-delete-clock: [outbound](#outbound)
!!! quote "Changes in sing-box 1.11.0"
:material-plus: [action](#action)
:material-alert: [server](#server)
:material-alert: [disable_cache](#disable_cache)
:material-alert: [rewrite_ttl](#rewrite_ttl)
:material-alert: [client_subnet](#client_subnet)
:material-plus: [network_type](#network_type)
:material-plus: [network_is_expensive](#network_is_expensive)
:material-plus: [network_is_constrained](#network_is_constrained)
!!! quote "Changes in sing-box 1.10.0"
:material-delete-clock: [rule_set_ipcidr_match_source](#rule_set_ipcidr_match_source)
:material-plus: [rule_set_ip_cidr_match_source](#rule_set_ip_cidr_match_source)
:material-plus: [rule_set_ip_cidr_accept_empty](#rule_set_ip_cidr_accept_empty)
:material-plus: [process_path_regex](#process_path_regex)
!!! quote "Changes in sing-box 1.9.0"
:material-plus: [geoip](#geoip)
:material-plus: [ip_cidr](#ip_cidr)
:material-plus: [ip_is_private](#ip_is_private)
:material-plus: [client_subnet](#client_subnet)
:material-plus: [rule_set_ipcidr_match_source](#rule_set_ipcidr_match_source)
!!! quote "Changes in sing-box 1.8.0"
:material-plus: [rule_set](#rule_set)
:material-plus: [source_ip_is_private](#source_ip_is_private)
:material-delete-clock: [geoip](#geoip)
:material-delete-clock: [geosite](#geosite)
{
"dns": {
"rules": [
{
"inbound": [
"mixed-in"
],
"ip_version": 6,
"query_type": [
"A",
"HTTPS",
32768
],
"query_client_subnet": [
"10.0.0.0/24",
"192.168.0.1"
],
"query_dnssec": false,
"network": "tcp",
"auth_user": [
"usera",
"userb"
],
"protocol": [
"tls",
"http",
"quic"
],
"domain": [
"test.com"
],
"domain_suffix": [
".cn"
],
"domain_keyword": [
"test"
],
"domain_regex": [
"^stun\\..+"
],
"source_ip_cidr": [
"10.0.0.0/24",
"192.168.0.1"
],
"source_ip_is_private": false,
"source_port": [
12345
],
"source_port_range": [
"1000:2000",
":3000",
"4000:"
],
"port": [
80,
443
],
"port_range": [
"1000:2000",
":3000",
"4000:"
],
"process_name": [
"curl"
],
"process_path": [
"/usr/bin/curl"
],
"process_path_regex": [
"^/usr/bin/.+"
],
"package_name": [
"com.termux"
],
"package_name_regex": [
"^com\\.termux.*"
],
"user": [
"sekai"
],
"user_id": [
1000
],
"clash_mode": "direct",
"network_type": [
"wifi"
],
"network_is_expensive": false,
"network_is_constrained": false,
"interface_address": {
"en0": [
"2000::/3"
]
},
"network_interface_address": {
"wifi": [
"2000::/3"
]
},
"default_interface_address": [
"2000::/3"
],
"source_mac_address": [
"00:11:22:33:44:55"
],
"source_hostname": [
"my-device"
],
"preferred_by": [
"local",
"ts-dns"
],
"wifi_ssid": [
"My WIFI"
],
"wifi_bssid": [
"00:00:00:00:00:00"
],
"rule_set": [
"geoip-cn",
"geosite-cn"
],
"rule_set_ip_cidr_match_source": false,
"match_response": false,
"ip_cidr": [
"10.0.0.0/24",
"192.168.0.1"
],
"ip_is_private": false,
"ip_accept_any": false,
"response_rcode": "",
"response_answer": [],
"response_ns": [],
"response_extra": [],
"invert": false,
"outbound": [
"direct"
],
"action": "route",
"server": "local",
// Deprecated
"rule_set_ip_cidr_accept_empty": false,
"rule_set_ipcidr_match_source": false,
"geosite": [
"cn"
],
"source_geoip": [
"private"
],
"geoip": [
"cn"
]
},
{
"type": "logical",
"mode": "and",
"rules": [],
"action": "route",
"server": "local"
}
]
}
}
!!! note ""
You can ignore the JSON Array [] tag when the content is only one item
!!! note ""
The default rule uses the following matching logic:
(`domain` || `domain_suffix` || `domain_keyword` || `domain_regex` || `geosite` || `ip_cidr` || `ip_is_private` || `ip_accept_any`) &&
(`port` || `port_range`) &&
(`source_geoip` || `source_ip_cidr` || `source_ip_is_private`) &&
(`source_port` || `source_port_range`) &&
`other fields`
When a rule-set contains only a single default rule without `invert`, its fields are considered merged into the outer rule per the logic above; otherwise, it is matched as an `other field`; different rule-sets always keep OR semantics.
Tags of Inbound.
!!! quote "Changes in sing-box 1.14.0"
This field now also applies when a DNS rule is matched from an internal
domain resolution that does not target a specific DNS server, such as a
[`resolve`](../../route/rule_action/#resolve) route rule action without a
`server` set. In earlier versions, only DNS queries received from a
client evaluated this field. See
[Migration](/migration/#ip_version-and-query_type-behavior-changes-in-dns-rules)
for the full list.
Setting this field makes the DNS rule incompatible in the same DNS
configuration with Legacy Address Filter Fields in DNS rules, the Legacy
`strategy` DNS rule action option, and the Legacy
`rule_set_ip_cidr_accept_empty` DNS rule item. To combine with
address-based filtering, use the [`evaluate`](../rule_action/#evaluate)
action and [`match_response`](#match_response).
4 (A DNS query) or 6 (AAAA DNS query).
Not limited if empty.
!!! quote "Changes in sing-box 1.14.0"
This field now also applies when a DNS rule is matched from an internal
domain resolution that does not target a specific DNS server, such as a
[`resolve`](../../route/rule_action/#resolve) route rule action without a
`server` set. In earlier versions, only DNS queries received from a
client evaluated this field. See
[Migration](/migration/#ip_version-and-query_type-behavior-changes-in-dns-rules)
for the full list.
Setting this field makes the DNS rule incompatible in the same DNS
configuration with Legacy Address Filter Fields in DNS rules, the Legacy
`strategy` DNS rule action option, and the Legacy
`rule_set_ip_cidr_accept_empty` DNS rule item. To combine with
address-based filtering, use the [`evaluate`](../rule_action/#evaluate)
action and [`match_response`](#match_response).
DNS query type. Values can be integers or type name strings.
!!! question "Since sing-box 1.14.0"
Match the edns0-subnet OPT extra record (EDNS Client Subnet) in the query.
A listed prefix matches when it is no more specific than the received client subnet and contains its address.
If value is an IP address instead of prefix, /32 or /128 will be appended automatically.
!!! question "Since sing-box 1.14.0"
Match queries with the DNSSEC OK (DO) bit set.
tcp or udp.
Username, see each inbound for details.
Sniffed protocol, see Sniff for details.
Match full domain.
Match domain suffix.
Match domain using keyword.
Match domain using regular expression.
!!! failure "Deprecated in sing-box 1.8.0"
Geosite is deprecated and will be removed in sing-box 1.12.0, check [Migration](/migration/#migrate-geosite-to-rule-sets).
Match geosite.
!!! failure "Deprecated in sing-box 1.8.0"
GeoIP is deprecated and will be removed in sing-box 1.12.0, check [Migration](/migration/#migrate-geoip-to-rule-sets).
Match source geoip.
Match source IP CIDR.
!!! question "Since sing-box 1.8.0"
Match non-public source IP.
Match source port.
Match source port range.
Match port.
Match port range.
!!! quote ""
Only supported on Linux, Windows, and macOS.
Match process name.
!!! quote ""
Only supported on Linux, Windows, and macOS.
Match process path.
!!! question "Since sing-box 1.10.0"
!!! quote ""
Only supported on Linux, Windows, and macOS.
Match process path using regular expression.
Match android package name.
!!! question "Since sing-box 1.14.0"
Match android package name using regular expression.
!!! quote ""
Only supported on Linux.
Match user name.
!!! quote ""
Only supported on Linux.
Match user id.
Match Clash mode.
!!! question "Since sing-box 1.11.0"
!!! quote ""
Only supported in graphical clients on Android and Apple platforms.
Match network type.
Available values: wifi, cellular, ethernet and other.
!!! question "Since sing-box 1.11.0"
!!! quote ""
Only supported in graphical clients on Android and Apple platforms.
Match if network is considered Metered (on Android) or considered expensive, such as Cellular or a Personal Hotspot (on Apple platforms).
!!! question "Since sing-box 1.11.0"
!!! quote ""
Only supported in graphical clients on Apple platforms.
Match if network is in Low Data Mode.
!!! question "Since sing-box 1.13.0"
!!! quote ""
Only supported on Linux, Windows, and macOS.
Match interface address.
!!! question "Since sing-box 1.13.0"
!!! quote ""
Only supported in graphical clients on Android and Apple platforms.
Matches network interface (same values as network_type) address.
!!! question "Since sing-box 1.13.0"
!!! quote ""
Only supported on Linux, Windows, and macOS.
Match default interface address.
!!! question "Since sing-box 1.14.0"
!!! quote ""
Only supported on Linux, macOS, or in graphical clients on Android and macOS. See [Neighbor Resolution](/configuration/shared/neighbor/) for setup.
Match source device MAC address.
!!! question "Since sing-box 1.14.0"
!!! quote ""
Only supported on Linux, macOS, or in graphical clients on Android and macOS. See [Neighbor Resolution](/configuration/shared/neighbor/) for setup.
Match source device hostname from DHCP leases.
!!! question "Since sing-box 1.14.0"
Match specified DNS servers' preferred domains.
| Type | Match |
|---|---|
hosts | Match predefined entries and entries in hosts files |
local | Match hosts entries, neighbor-resolved hosts, and mDNS local domains |
mdns | Match mDNS local domains (*.local. and IPv4/IPv6 link-local reverse zones) |
tailscale | Match MagicDNS hosts and DNS route suffixes |
openconnect | Match split DNS and search domains pushed by the VPN server |
resolved | Match split DNS and search domains from systemd-resolved links |
!!! quote ""
Only supported in graphical clients on Android and Apple platforms, or on Linux.
Match WiFi SSID.
!!! quote ""
Only supported in graphical clients on Android and Apple platforms, or on Linux.
Match WiFi BSSID.
!!! question "Since sing-box 1.8.0"
Match rule-set.
!!! question "Since sing-box 1.9.0"
!!! failure "Deprecated in sing-box 1.10.0"
`rule_set_ipcidr_match_source` is renamed to `rule_set_ip_cidr_match_source` and will be remove in sing-box 1.11.0.
Make ip_cidr rule items in rule-sets match the source IP.
!!! question "Since sing-box 1.10.0"
Make ip_cidr rule items in rule-sets match the source IP.
!!! question "Since sing-box 1.14.0"
Enable response-based matching. When enabled, this rule matches against the evaluated response
(set by a preceding evaluate action)
instead of only matching the original query.
true or the tag of an evaluate action: true matches against the response of the latest
evaluate action without tag; a tag matches against the response of the evaluate action with the tag.
The evaluated response can also be returned directly by a later respond action;
in a rule with a match_response tag, respond returns the tagged response.
Required for Response Match Fields (response_rcode, response_answer, response_ns, response_extra).
Also required for ip_cidr, ip_is_private, and ip_accept_any when used with evaluate or Response Match Fields.
!!! question "Since sing-box 1.12.0"
Match when the DNS query response contains at least one address.
Invert match result.
!!! failure "Deprecated in sing-box 1.12.0"
`outbound` rule items are deprecated and will be removed in sing-box 1.14.0, check [Migration](/migration/#migrate-outbound-dns-rule-items-to-domain-resolver).
Match outbound.
any can be used as a value to match any outbound.
==Required==
See DNS Rule Actions for details.
!!! failure "Deprecated in sing-box 1.11.0"
Moved to [DNS Rule Action](../rule_action#route).
!!! failure "Deprecated in sing-box 1.11.0"
Moved to [DNS Rule Action](../rule_action#route).
!!! failure "Deprecated in sing-box 1.11.0"
Moved to [DNS Rule Action](../rule_action#route).
!!! failure "Deprecated in sing-box 1.11.0"
Moved to [DNS Rule Action](../rule_action#route).
!!! failure "Deprecated in sing-box 1.14.0"
Legacy Address Filter Fields are deprecated and will be removed in sing-box 1.16.0,
check [Migration](/migration/#migrate-address-filter-fields-to-response-matching).
Only takes effect for address requests (A/AAAA/HTTPS). When the query results do not match the address filtering rule items, the current rule will be skipped.
!!! info ""
`ip_cidr` items in included rule-sets also takes effect as an address filtering field.
!!! note ""
Enable `experimental.cache_file.store_rdrc` to cache results.
!!! failure "Removed in sing-box 1.12.0"
GeoIP is deprecated in sing-box 1.8.0 and removed in sing-box 1.12.0, check [Migration](/migration/#migrate-geoip-to-rule-sets).
Match GeoIP with query response.
!!! question "Since sing-box 1.9.0"
Match IP CIDR with query response.
As a Legacy Address Filter Field, deprecated. Use with match_response instead,
check Migration.
!!! question "Since sing-box 1.9.0"
Match private IP with query response.
As a Legacy Address Filter Field, deprecated. Use with match_response instead,
check Migration.
!!! question "Since sing-box 1.10.0"
!!! failure "Deprecated in sing-box 1.14.0"
`rule_set_ip_cidr_accept_empty` is deprecated and will be removed in sing-box 1.16.0,
check [Migration](/migration/#migrate-address-filter-fields-to-response-matching).
Make ip_cidr rules in rule-sets accept empty query response.
!!! question "Since sing-box 1.14.0"
Match fields for the evaluated response. Require match_response to be set to true
and a preceding rule with evaluate action to populate the response.
That evaluated response may also be returned directly by a later respond action.
Match DNS response code.
Accepted values are the same as in the predefined action rcode.
Match DNS answer records.
Record format is the same as in predefined action answer.
Match DNS name server records.
Record format is the same as in predefined action ns.
Match DNS extra records.
Record format is the same as in predefined action extra.
logical
and or or
Included rules.