DNS Rule
Changes in sing-box 1.14.0
source_mac_address
source_hostname
match_response
rule_set_ip_cidr_accept_empty
response_rcode
response_answer
response_ns
response_extra
package_name_regex
ip_version
query_type
Changes in sing-box 1.13.0
interface_address
network_interface_address
default_interface_address
Changes in sing-box 1.12.0
Changes in sing-box 1.11.0
action
server
disable_cache
rewrite_ttl
client_subnet
network_type
network_is_expensive
network_is_constrained
Changes in sing-box 1.10.0
rule_set_ipcidr_match_source
rule_set_ip_cidr_match_source
rule_set_ip_cidr_accept_empty
process_path_regex
Changes in sing-box 1.9.0
geoip
ip_cidr
ip_is_private
client_subnet
rule_set_ipcidr_match_source
Changes in sing-box 1.8.0
Structure
{
"dns": {
"rules": [
{
"inbound": [
"mixed-in"
],
"ip_version": 6,
"query_type": [
"A",
"HTTPS",
32768
],
"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"
],
"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"
}
]
}
}
You can ignore the JSON Array [] tag when the content is only one item
Default Fields
The default rule uses the following matching logic:
(domain || domain_suffix || domain_keyword || domain_regex || geosite) &&
(port || port_range) &&
(source_geoip || source_ip_cidr ｜｜ source_ip_is_private) &&
(source_port || source_port_range) &&
other fields
Additionally, each branch inside an included rule-set can be considered merged into the outer rule, while different branches keep OR semantics.
inbound
Tags of Inbound.
ip_version
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 without a
server set. In earlier versions, only DNS queries received from a
client evaluated this field. See
Migration
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
action and match_response.
4 (A DNS query) or 6 (AAAA DNS query).
Not limited if empty.
query_type
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 without a
server set. In earlier versions, only DNS queries received from a
client evaluated this field. See
Migration
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
action and match_response.
DNS query type. Values can be integers or type name strings.
network
tcp or udp.
auth_user
Username, see each inbound for details.
protocol
Sniffed protocol, see Sniff for details.
domain
Match full domain.
domain_suffix
Match domain suffix.
domain_keyword
Match domain using keyword.
domain_regex
Match domain using regular expression.
geosite
Deprecated in sing-box 1.8.0
Geosite is deprecated and will be removed in sing-box 1.12.0, check Migration.
Match geosite.
source_geoip
Deprecated in sing-box 1.8.0
GeoIP is deprecated and will be removed in sing-box 1.12.0, check Migration.
Match source geoip.
source_ip_cidr
Match source IP CIDR.
source_ip_is_private
Since sing-box 1.8.0
Match non-public source IP.
source_port
Match source port.
source_port_range
Match source port range.
port
Match port.
port_range
Match port range.
process_name
Only supported on Linux, Windows, and macOS.
Match process name.
process_path
Only supported on Linux, Windows, and macOS.
Match process path.
process_path_regex
Since sing-box 1.10.0
Only supported on Linux, Windows, and macOS.
Match process path using regular expression.
package_name
Match android package name.
package_name_regex
Since sing-box 1.14.0
Match android package name using regular expression.
user
Only supported on Linux.
Match user name.
user_id
Only supported on Linux.
Match user id.
clash_mode
Match Clash mode.
network_type
Since sing-box 1.11.0
Only supported in graphical clients on Android and Apple platforms.
Match network type.
Available values: wifi, cellular, ethernet and other.
network_is_expensive
Since sing-box 1.11.0
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).
network_is_constrained
Since sing-box 1.11.0
Only supported in graphical clients on Apple platforms.
Match if network is in Low Data Mode.
interface_address
Since sing-box 1.13.0
Only supported on Linux, Windows, and macOS.
Match interface address.
network_interface_address
Since sing-box 1.13.0
Only supported in graphical clients on Android and Apple platforms.
Matches network interface (same values as network_type) address.
default_interface_address
Since sing-box 1.13.0
Only supported on Linux, Windows, and macOS.
Match default interface address.
source_mac_address
Since sing-box 1.14.0
Only supported on Linux, macOS, or in graphical clients on Android and macOS. See Neighbor Resolution for setup.
Match source device MAC address.
source_hostname
Since sing-box 1.14.0
Only supported on Linux, macOS, or in graphical clients on Android and macOS. See Neighbor Resolution for setup.
Match source device hostname from DHCP leases.
wifi_ssid
Only supported in graphical clients on Android and Apple platforms, or on Linux.
Match WiFi SSID.
wifi_bssid
Only supported in graphical clients on Android and Apple platforms, or on Linux.
Match WiFi BSSID.
rule_set
Since sing-box 1.8.0
Match rule-set.
rule_set_ipcidr_match_source
Since sing-box 1.9.0
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.
rule_set_ip_cidr_match_source
Since sing-box 1.10.0
Make ip_cidr rule items in rule-sets match the source IP.
match_response
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.
The evaluated response can also be returned directly by a later respond action.
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.
ip_accept_any
Since sing-box 1.12.0
Match when the DNS query response contains at least one address.
invert
Invert match result.
outbound
Deprecated in sing-box 1.12.0
outbound rule items are deprecated and will be removed in sing-box 1.14.0, check Migration.
Match outbound.
any can be used as a value to match any outbound.
action
Required
See DNS Rule Actions for details.
server
Deprecated in sing-box 1.11.0
Moved to DNS Rule Action.
disable_cache
Deprecated in sing-box 1.11.0
Moved to DNS Rule Action.
rewrite_ttl
Deprecated in sing-box 1.11.0
Moved to DNS Rule Action.
client_subnet
Deprecated in sing-box 1.11.0
Moved to DNS Rule Action.
Legacy Address Filter Fields
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.
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.
ip_cidr items in included rule-sets also takes effect as an address filtering field.
Enable experimental.cache_file.store_rdrc to cache results.
geoip
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.
Match GeoIP with query response.
ip_cidr
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.
ip_is_private
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.
rule_set_ip_cidr_accept_empty
Since sing-box 1.10.0
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.
Make ip_cidr rules in rule-sets accept empty query response.
Response Match Fields
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.
response_rcode
Match DNS response code.
Accepted values are the same as in the predefined action rcode.
response_answer
Match DNS answer records.
Record format is the same as in predefined action answer.
response_ns
Match DNS name server records.
Record format is the same as in predefined action ns.
response_extra
Match DNS extra records.
Record format is the same as in predefined action extra.
Logical Fields
type
logical
mode
and or or
rules
Included rules.