singboxer/references/ref-routing.md

# sing-box Routing Reference

## Route Options

```json
{
  "route": {
    "rules": [],
    "rule_set": [],
    "final": "direct",
    "auto_detect_interface": true,
    "override_android_vpn": false,
    "default_interface": "",
    "default_mark": 0,
    "find_process": false,
    "find_neighbor": false,
    "default_domain_resolver": {
      "server": "dns-tag",
      "strategy": "prefer_ipv4"
    },
    "default_network_strategy": "",
    "default_network_type": [],
    "default_fallback_network_type": [],
    "default_fallback_delay": "300ms"
  }
}
```

## Route Rule Structure

Each rule has **match criteria** and an **action**. First matching rule wins.

### Default Rule (flat criteria)

```json
{
  "type": "default",
  "action": "route",

  // --- Match criteria (all are optional, combined with AND) ---

  // Traffic source
  "inbound": ["tun-in"],
  "auth_user": ["user1"],
  "client": ["client-tag"],

  // Network
  "ip_version": 4,
  "network": ["tcp", "udp"],

  // Domain matching
  "domain": ["example.com"],
  "domain_suffix": [".cn", ".ir"],
  "domain_keyword": ["google"],
  "domain_regex": ["^ad\\."],

  // IP matching
  "ip_cidr": ["10.0.0.0/8"],
  "source_ip_cidr": ["192.168.1.0/24"],
  "ip_is_private": false,
  "source_ip_is_private": false,

  // Port matching
  "port": [80, 443],
  "port_range": ["1000:2000"],
  "source_port": [1234],
  "source_port_range": [],

  // Protocol detection (requires sniff action first)
  "protocol": ["http", "tls", "quic", "stun", "dns", "bittorrent"],

  // Process matching (requires find_process: true)
  "process_name": ["curl"],
  "process_path": ["/usr/bin/curl"],
  "process_path_regex": [],

  // Android
  "package_name": ["com.android.chrome"],

  // Linux
  "user": ["proxy"],
  "user_id": [1000],

  // Network type
  "wifi_ssid": ["HomeWiFi"],
  "wifi_bssid": [],
  "network_type": ["wifi", "cellular", "ethernet"],
  "network_is_expensive": false,
  "network_is_constrained": false,

  // Rule sets
  "rule_set": ["geoip-cn", "geosite-cn"],
  "rule_set_ip_cidr_match_source": false,

  // Clash mode
  "clash_mode": "Rule",

  // Invert match
  "invert": false,

  // --- Action ---
  "action": "route",
  "outbound": "proxy"
}
```

### Logical Rule (nested with AND/OR)

```json
{
  "type": "logical",
  "mode": "and",
  "rules": [
    { "network": "udp" },
    { "port": [443] }
  ],
  "invert": false,
  "action": "route",
  "outbound": "block"
}
```

## Rule Actions

### `route` — Route to outbound
```json
{
  "action": "route",
  "outbound": "proxy",
  "override_address": "",
  "override_port": 0,
  "network_strategy": "",
  "network_type": [],
  "fallback_network_type": [],
  "fallback_delay": "300ms",
  "udp_disable_domain_unmapping": false,
  "udp_connect": false,
  "tls_fragment": {
    "enabled": true,
    "size": "10-30",
    "sleep": "2-8",
    "fallback_delay": "300ms"
  },
  "tls_record_fragment": {
    "enabled": true,
    "size": "100-200"
  }
}
```

### `route-options` — Modify routing options without changing outbound
```json
{
  "action": "route-options",
  "network_strategy": "prefer_ipv4",
  "udp_disable_domain_unmapping": true,
  "udp_connect": true
}
```

### `direct` — Direct connection with custom dialer
```json
{
  "action": "direct",
  "override_address": "1.2.3.4",
  "override_port": 53
}
```

### `reject` — Reject connection
```json
{
  "action": "reject",
  "method": "default",
  "no_drop": false
}
```
Methods: `default` (TCP RST / ICMP unreachable), `drop` (silent drop), `reply` (for DNS)

### `hijack-dns` — Intercept DNS queries
```json
{
  "action": "hijack-dns"
}
```

### `sniff` — Protocol sniffing
```json
{
  "action": "sniff",
  "sniffer": ["http", "tls", "quic", "stun", "dns", "bittorrent", "dtls", "ssh", "rdp"],
  "timeout": "300ms"
}
```

### `resolve` — DNS resolution
```json
{
  "action": "resolve",
  "server": "dns-server-tag",
  "strategy": "prefer_ipv4",
  "disable_cache": false,
  "rewrite_ttl": 0,
  "client_subnet": ""
}
```

## Rule Sets

### Remote rule set (auto-updating)
```json
{
  "type": "remote",
  "tag": "geoip-cn",
  "format": "binary",
  "url": "https://raw.githubusercontent.com/SagerNet/sing-geoip/rule-set/geoip-cn.srs",
  "download_detour": "direct",
  "update_interval": "1d"
}
```

### Local rule set
```json
{
  "type": "local",
  "tag": "custom-rules",
  "format": "source",
  "path": "/etc/sing-box/rules/custom.json"
}
```

### Inline rule set
```json
{
  "type": "inline",
  "tag": "my-rules",
  "rules": [
    { "domain_suffix": [".example.com"] }
  ]
}
```

### Rule set source format (.json)
```json
{
  "version": 1,
  "rules": [
    {
      "domain_suffix": [".cn", ".中国"],
      "ip_cidr": ["223.5.5.5/32"]
    }
  ]
}
```

## Common Routing Patterns

### Pattern: DNS Hijack for TUN mode
```json
{
  "route": {
    "rules": [
      { "action": "sniff" },
      { "protocol": "dns", "action": "hijack-dns" },
      // ... other rules
    ]
  }
}
```

### Pattern: Bypass LAN
```json
{ "ip_is_private": true, "action": "route", "outbound": "direct" }
```

### Pattern: Block ads via rule set
```json
{ "rule_set": ["adblock"], "action": "reject", "method": "default" }
```

### Pattern: Route by process
```json
{
  "route": {
    "find_process": true,
    "rules": [
      { "process_name": ["telegram"], "action": "route", "outbound": "proxy" }
    ]
  }
}
```

### Pattern: Split tunnel by domain
```json
{
  "rules": [
    { "rule_set": ["geosite-cn"], "action": "route", "outbound": "direct" },
    { "rule_set": ["geosite-category-ads-all"], "action": "reject" }
  ],
  "final": "proxy"
}
```

### Pattern: TLS fragment for anti-censorship
```json
{
  "domain_keyword": ["blocked-site"],
  "action": "route",
  "outbound": "direct",
  "tls_fragment": {
    "enabled": true,
    "size": "1-5",
    "sleep": "10-20"
  }
}
```