# sing-box TUN & System Settings Reference

## TUN Inbound Configuration

```json
{
  "type": "tun",
  "tag": "tun-in",

  "interface_name": "",
  "mtu": 9000,
  "gso": false,
  "address": [
    "172.19.0.1/30",
    "fdfe:dcba:9876::1/126"
  ],
  "auto_route": true,
  "auto_redirect": false,
  "strict_route": true,
  "route_address": [],
  "route_address_set": [],
  "route_exclude_address": [],
  "route_exclude_address_set": [],

  "stack": "mixed",
  "udp_timeout": "5m",

  // Linux nftables (auto_redirect)
  "auto_redirect_input_mark": "0x2023",
  "auto_redirect_output_mark": "0x2024",
  "auto_redirect_reset_mark": "0x2025",
  "auto_redirect_nfqueue": 100,
  "auto_redirect_iproute2_fallback_rule_index": 32768,
  "exclude_mptcp": false,

  // Linux iproute2
  "iproute2_table_index": 2022,
  "iproute2_rule_index": 9000,

  // Linux UID filtering
  "include_uid": [],
  "include_uid_range": ["1000:65534"],
  "exclude_uid": [0],
  "exclude_uid_range": [],

  // Interface filtering
  "include_interface": [],
  "exclude_interface": ["docker0", "br-*"],

  // Android
  "include_android_user": [0],
  "include_package": [],
  "exclude_package": ["com.android.captiveportallogin"],

  // Apple (iOS/macOS)
  "platform": {
    "http_proxy": {
      "enabled": false,
      "server": "127.0.0.1",
      "server_port": 1080,
      "match_domain": []
    }
  },

  // Network namespace (Linux)
  "netns": ""
}
```

## TCP/IP Stack Options

| Stack | Description | Best For |
|-------|-------------|----------|
| `system` | Uses OS network stack | Compatibility, low overhead |
| `gvisor` | Userspace TCP/IP (Google gVisor) | Stability, no kernel dependency |
| `mixed` | TCP=system, UDP=gvisor | **Recommended default** — best balance |

## TUN auto_route Behavior

When `auto_route: true`:
- **Linux**: Creates iproute2 rules and routes in table `iproute2_table_index` (default 2022)
- **macOS**: Adds routes via `route` command
- **Windows**: Uses WFP (Windows Filtering Platform) for traffic redirect

When `strict_route: true` (recommended with auto_route):
- **Linux**: Adds rules to prevent traffic leaking outside TUN
- **Windows**: Blocks non-TUN traffic via WFP
- Prevents DNS and other leaks

## auto_redirect (Linux nftables)

Alternative to `tproxy` inbound. Uses nftables to redirect all traffic to TUN:

```json
{
  "type": "tun",
  "auto_route": true,
  "auto_redirect": true,
  "auto_redirect_input_mark": "0x2023",
  "auto_redirect_output_mark": "0x2024"
}
```

Requires: `nftables` available, `CAP_NET_ADMIN` capability.

## Linux Transparent Proxy Alternatives

### Option 1: TUN (recommended)
```json
{
  "inbounds": [
    {
      "type": "tun",
      "tag": "tun-in",
      "address": ["172.19.0.1/30", "fdfe:dcba:9876::1/126"],
      "auto_route": true,
      "strict_route": true,
      "stack": "mixed"
    }
  ]
}
```

### Option 2: redirect (TCP only)
```json
{
  "inbounds": [
    {
      "type": "redirect",
      "tag": "redirect-in",
      "listen": "::",
      "listen_port": 12345
    }
  ]
}
```
Requires iptables rule:
```bash
iptables -t nat -A OUTPUT -p tcp -j REDIRECT --to-port 12345
```

### Option 3: tproxy (TCP + UDP)
```json
{
  "inbounds": [
    {
      "type": "tproxy",
      "tag": "tproxy-in",
      "listen": "::",
      "listen_port": 12345,
      "network": "udp"
    },
    {
      "type": "tproxy",
      "tag": "tproxy-in-tcp",
      "listen": "::",
      "listen_port": 12345,
      "network": "tcp"
    }
  ]
}
```
Requires iptables TPROXY rules and ip rule/route for marking.

## System Tuning — Linux

### sysctl settings
```bash
# Enable IP forwarding (for gateway/router mode)
sysctl -w net.ipv4.ip_forward=1
sysctl -w net.ipv6.conf.all.forwarding=1

# Disable reverse path filtering (needed for tproxy/TUN)
sysctl -w net.ipv4.conf.all.rp_filter=0
sysctl -w net.ipv4.conf.default.rp_filter=0

# TCP optimizations
sysctl -w net.core.rmem_max=16777216
sysctl -w net.core.wmem_max=16777216
sysctl -w net.ipv4.tcp_fastopen=3      # Enable TFO client+server
sysctl -w net.ipv4.tcp_mtu_probing=1   # For Hysteria/QUIC MTU discovery

# Increase conntrack for high-connection scenarios
sysctl -w net.netfilter.nf_conntrack_max=131072

# BBR congestion control (recommended)
sysctl -w net.core.default_qdisc=fq
sysctl -w net.ipv4.tcp_congestion_control=bbr
```

### Persist sysctl
```bash
# /etc/sysctl.d/99-sing-box.conf
net.ipv4.ip_forward = 1
net.ipv6.conf.all.forwarding = 1
net.ipv4.conf.all.rp_filter = 0
net.core.default_qdisc = fq
net.ipv4.tcp_congestion_control = bbr
net.ipv4.tcp_fastopen = 3
```

### File descriptor limits
```bash
# /etc/security/limits.d/sing-box.conf
*    soft    nofile    65535
*    hard    nofile    131072

# Or for systemd service
# [Service]
# LimitNOFILE=131072
```

### Required capabilities
```bash
# Instead of running as root:
sudo setcap cap_net_admin,cap_net_raw,cap_net_bind_service+ep /usr/bin/sing-box
```

### systemd service
```ini
# /etc/systemd/system/sing-box.service
[Unit]
Description=sing-box service
Documentation=https://sing-box.sagernet.org
After=network.target nss-lookup.target

[Service]
Type=simple
ExecStart=/usr/bin/sing-box run -c /etc/sing-box/config.json
Restart=on-failure
RestartSec=10s
LimitNOFILE=131072
CapabilityBoundingSet=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE
AmbientCapabilities=CAP_NET_ADMIN CAP_NET_RAW CAP_NET_BIND_SERVICE
NoNewPrivileges=true

[Install]
WantedBy=multi-user.target
```

### systemd with config directory
```ini
ExecStart=/usr/bin/sing-box run -C /etc/sing-box/
```

## System Tuning — macOS

```bash
# Enable IP forwarding
sudo sysctl -w net.inet.ip.forwarding=1
sudo sysctl -w net.inet6.ip6.forwarding=1
```

## Network Namespace (Linux)

Run sing-box in an isolated network namespace:
```json
{
  "type": "tun",
  "netns": "sing-box-ns"
}
```
Or use a path: `"netns": "/run/netns/custom-ns"`

## Routing Mark (Linux)

Prevent routing loops by marking sing-box's own traffic:
```json
{
  "route": {
    "default_mark": 255
  }
}
```
Or per-outbound:
```json
{
  "type": "direct",
  "tag": "direct",
  "routing_mark": 255
}
```

## Dial Fields (Common to All Outbounds)

```json
{
  "bind_interface": "",
  "inet4_bind_address": "",
  "inet6_bind_address": "",
  "routing_mark": 0,
  "reuse_addr": false,
  "connect_timeout": "5s",
  "tcp_fast_open": false,
  "tcp_multi_path": false,
  "udp_fragment": false,
  "domain_strategy": "",
  "network_strategy": "",
  "network_type": [],
  "fallback_network_type": [],
  "fallback_delay": "300ms"
}
```

## Listen Fields (Common to All Inbounds)

```json
{
  "listen": "0.0.0.0",
  "listen_port": 1080,
  "tcp_fast_open": false,
  "tcp_multi_path": false,
  "udp_fragment": false,
  "udp_timeout": "5m",
  "proxy_protocol": false,
  "proxy_protocol_accept_no_header": false
}
```