# DNS Rule - sing-box
The universal proxy platform.
Author: nekohasekai

Skip to content

# DNS Rule

Changes in sing-box 1.14.0

source_mac_address
source_hostname
preferred_by
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

ip_accept_any
outbound

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

rule_set
source_ip_is_private
geoip
geosite

### 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"
            ],
            "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"
          }
        ]
      }
    }

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.

#### preferred_by

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
`resolved` | Match split DNS and search domains from systemd-resolved links

#### 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.