claude-skills
/
singboxer
1
0
Fork 0
Code Issues 1 Pull Requests Packages Projects Releases Wiki Activity
singboxer/references/ref-tun-system.md

6.6 KiB
Raw Blame History

sing-box TUN & System Settings Reference

TUN Inbound Configuration

{
  "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:

{
  "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)

{
  "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)

{
  "inbounds": [
    {
      "type": "redirect",
      "tag": "redirect-in",
      "listen": "::",
      "listen_port": 12345
    }
  ]
}

Requires iptables rule:

iptables -t nat -A OUTPUT -p tcp -j REDIRECT --to-port 12345

Option 3: tproxy (TCP + UDP)

{
  "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

# 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

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

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

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

Required capabilities

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

systemd service

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

ExecStart=/usr/bin/sing-box run -C /etc/sing-box/

System Tuning — macOS

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

{
  "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:

{
  "route": {
    "default_mark": 255
  }
}

Or per-outbound:

{
  "type": "direct",
  "tag": "direct",
  "routing_mark": 255
}

Dial Fields (Common to All Outbounds)

{
  "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)

{
  "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
}