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

Skip to content

# Tun

Changes in sing-box 1.14.0

include_mac_address
exclude_mac_address
dns_mode
dns_address

Changes in sing-box 1.13.3

strict_route

Changes in sing-box 1.13.0

auto_redirect_reset_mark
auto_redirect_nfqueue
exclude_mptcp
auto_redirect_iproute2_fallback_rule_index

Changes in sing-box 1.12.0

loopback_address

Changes in sing-box 1.11.0

gso
route_address_set
route_exclude_address_set

Changes in sing-box 1.10.0

address
inet4_address
inet6_address
route_address
inet4_route_address
inet6_route_address
route_exclude_address
inet4_route_exclude_address
inet6_route_exclude_address
iproute2_table_index
iproute2_rule_index
auto_redirect
auto_redirect_input_mark
auto_redirect_output_mark
route_address_set
route_exclude_address_set

Changes in sing-box 1.9.0

platform.http_proxy.bypass_domain
platform.http_proxy.match_domain

Changes in sing-box 1.8.0

gso
stack

Only supported on Linux, Windows and macOS.

### Structure

    {
      "type": "tun",
      "tag": "tun-in",
      "interface_name": "tun0",
      "address": [
        "172.18.0.1/30",
        "fdfe:dcba:9876::1/126"
      ],
      "mtu": 9000,
      "dns_mode": "hijack",
      "dns_address": [
        "172.18.0.2",
        "fdfe:dcba:9876::2"
      ],
      "auto_route": true,
      "iproute2_table_index": 2022,
      "iproute2_rule_index": 9000,
      "auto_redirect": true,
      "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,
      "loopback_address": [
        "10.7.0.1"
      ],
      "strict_route": true,
      "route_address": [
        "0.0.0.0/1",
        "128.0.0.0/1",
        "::/1",
        "8000::/1"
      ],
      "route_exclude_address": [
        "192.168.0.0/16",
        "fc00::/7"
      ],
      "route_address_set": [
        "geoip-cloudflare"
      ],
      "route_exclude_address_set": [
        "geoip-cn"
      ],
      "endpoint_independent_nat": false,
      "udp_timeout": "5m",
      "stack": "system",
      "include_interface": [
        "lan0"
      ],
      "exclude_interface": [
        "lan1"
      ],
      "include_uid": [
        0
      ],
      "include_uid_range": [
        "1000:99999"
      ],
      "exclude_uid": [
        1000
      ],
      "exclude_uid_range": [
        "1000:99999"
      ],
      "include_android_user": [
        0,
        10
      ],
      "include_package": [
        "com.android.chrome"
      ],
      "exclude_package": [
        "com.android.captiveportallogin"
      ],
      "include_mac_address": [
        "00:11:22:33:44:55"
      ],
      "exclude_mac_address": [
        "66:77:88:99:aa:bb"
      ],
      "platform": {
        "http_proxy": {
          "enabled": false,
          "server": "127.0.0.1",
          "server_port": 8080,
          "bypass_domain": [],
          "match_domain": []
        }
      },
      // Deprecated
      "gso": false,
      "inet4_address": [
        "172.19.0.1/30"
      ],
      "inet6_address": [
        "fdfe:dcba:9876::1/126"
      ],
      "inet4_route_address": [
        "0.0.0.0/1",
        "128.0.0.0/1"
      ],
      "inet6_route_address": [
        "::/1",
        "8000::/1"
      ],
      "inet4_route_exclude_address": [
        "192.168.0.0/16"
      ],
      "inet6_route_exclude_address": [
        "fc00::/7"
      ],
      ...
      // Listen Fields
    }

You can ignore the JSON Array [] tag when the content is only one item

If tun is running in non-privileged mode, addresses and MTU will not be configured automatically, please make sure the settings are accurate.

### Fields

#### interface_name

Virtual device name, automatically selected if empty.

#### address

Since sing-box 1.10.0

IPv4 and IPv6 prefix for the tun interface.

#### inet4_address

Deprecated in sing-box 1.10.0

`inet4_address` is merged to `address` and will be removed in sing-box 1.12.0.

IPv4 prefix for the tun interface.

#### inet6_address

Deprecated in sing-box 1.10.0

`inet6_address` is merged to `address` and will be removed in sing-box 1.12.0.

IPv6 prefix for the tun interface.

#### mtu

The maximum transmission unit.

#### dns_mode

Since sing-box 1.14.0

How DNS is handled on the TUN interface.

Mode | Description
--- | ---
`disabled` | Do not configure native DNS and do not hijack DNS traffic.
`native` | Set the platform's native interface DNS where possible: per-interface DNS on Windows and Apple platforms, and `systemd-resolved` interface DNS on Linux.
`hijack` | Same as `native`, with additional port 53 hijacking described below. Used by default.

`hijack` adds the following on top of `native`:

On Linux: only DNS sent to non-local destinations can be intercepted. Traffic destined to addresses on the host's own interfaces (such as `127.0.0.53` or the host's LAN-side IP) is delivered through the kernel `local` routing table before any user rule applies, and `OUTPUT` NAT cannot redirect packets going through `lo`.

- Without `auto_redirect`, an `iproute2` rule makes port 53 skip the `main` table's specific-route lookup, forcing DNS that would otherwise be delivered through a directly-attached subnet through the TUN. Destination addresses are not rewritten.
- With `auto_redirect`, an nftables rule DNATs port 53 traffic directly to `dns_address`.

On Windows with `strict_route`: a WFP filter blocks port 53 traffic going through interfaces other than the TUN.

#### dns_address

Since sing-box 1.14.0

List of DNS server addresses used by `dns_mode`.

When unset, sing-box derives one address per family by taking the next IP after the first IPv4/IPv6 entry in `address`. Connections toward those derived addresses are additionally hijacked into the sing-box DNS module, equivalent to a `hijack-dns` route action; this preserves the behaviour from before this option was added.

When set, this auto-hijack is not applied; configure an explicit `hijack-dns` route rule if the behaviour is still required.

#### gso

Deprecated in sing-box 1.11.0

GSO has no advantages for transparent proxy scenarios, is deprecated and no longer works, and will be removed in sing-box 1.12.0.

Since sing-box 1.8.0

Only supported on Linux with `auto_route` enabled.

Enable generic segmentation offload.

#### auto_route

Set the default route to the Tun.

To avoid traffic loopback, set `route.auto_detect_interface` or `route.default_interface` or `outbound.bind_interface`

Use with Android VPN

By default, VPN takes precedence over tun. To make tun go through VPN, enable `route.override_android_vpn`.

Also enable `auto_redirect`

`auto_redirect` is always recommended on Linux, it provides better routing, higher performance (better than tproxy), and avoids conflicts between TUN and Docker bridge networks.

#### iproute2_table_index

Since sing-box 1.10.0

Linux iproute2 table index generated by `auto_route`.

`2022` is used by default.

#### iproute2_rule_index

Since sing-box 1.10.0

Linux iproute2 rule start index generated by `auto_route`.

`9000` is used by default.

#### auto_redirect

Since sing-box 1.10.0

Only supported on Linux with `auto_route` enabled.

Improve TUN routing and performance using nftables.

`auto_redirect` is always recommended on Linux, it provides better routing, higher performance (better than tproxy), and avoids conflicts between TUN and Docker bridge networks.

Note that `auto_redirect` also works on Android, but due to the lack of `nftables` and `ip6tables`, only simple IPv4 TCP forwarding is performed. To share your VPN connection over hotspot or repeater on Android, use VPNHotspot.

`auto_redirect` also automatically inserts compatibility rules into the OpenWrt fw4 table, i.e. it will work on routers without any extra configuration.

Conflict with `route.default_mark` and `[dialOptions].routing_mark`.

#### auto_redirect_input_mark

Since sing-box 1.10.0

Connection input mark used by `auto_redirect`.

`0x2023` is used by default.

#### auto_redirect_output_mark

Since sing-box 1.10.0

Connection output mark used by `auto_redirect`.

`0x2024` is used by default.

#### auto_redirect_reset_mark

Since sing-box 1.13.0

Connection reset mark used by `auto_redirect` pre-matching.

`0x2025` is used by default.

#### auto_redirect_nfqueue

Since sing-box 1.13.0

NFQueue number used by `auto_redirect` pre-matching.

`100` is used by default.

#### auto_redirect_iproute2_fallback_rule_index

Since sing-box 1.12.18

Linux iproute2 fallback rule index generated by `auto_redirect`.

This rule is checked after system default rules (32766: main, 32767: default), routing traffic to the sing-box table only when no route is found in system tables.

`32768` is used by default.

#### exclude_mptcp

Since sing-box 1.13.0

Only supported on Linux with nftables and requires `auto_route` and `auto_redirect` enabled.

MPTCP cannot be transparently proxied due to protocol limitations.

Such traffic is usually created by Apple systems.

When enabled, MPTCP connections will bypass sing-box and connect directly, otherwise, will be rejected to avoid errors by default.

#### loopback_address

Since sing-box 1.12.0

Loopback addresses make TCP connections to the specified address connect to the source address.

Setting option value to `10.7.0.1` achieves the same behavior as SideStore/StosVPN.

When `auto_redirect` is enabled, the same behavior can be achieved for LAN devices (not just local) as a gateway.

#### strict_route

Enforce strict routing rules when `auto_route` is enabled:

In Linux:

- Let unsupported network unreachable
- For legacy reasons, when neither `strict_route` nor `auto_redirect` are enabled, all ICMP traffic will not go through TUN.
- When `auto_redirect` is enabled, `strict_route` also affects `SO_BINDTODEVICE` traffic:
  - Enabled: `SO_BINDTODEVICE` traffic is redirected through sing-box.
  - Disabled: `SO_BINDTODEVICE` traffic bypasses sing-box.

In Windows:

- Let unsupported network unreachable
- prevent DNS leak caused by Windows' ordinary multihomed DNS resolution behavior

It may prevent some Windows applications (such as VirtualBox) from working properly in certain situations.

#### route_address

Since sing-box 1.10.0

Use custom routes instead of default when `auto_route` is enabled.

#### inet4_route_address

Deprecated in sing-box 1.10.0

`inet4_route_address` is deprecated and will be removed in sing-box 1.12.0, please use route_address instead.

Use custom routes instead of default when `auto_route` is enabled.

#### inet6_route_address

Deprecated in sing-box 1.10.0

`inet6_route_address` is deprecated and will be removed in sing-box 1.12.0, please use route_address instead.

Use custom routes instead of default when `auto_route` is enabled.

#### route_exclude_address

Since sing-box 1.10.0

Exclude custom routes when `auto_route` is enabled.

#### inet4_route_exclude_address

Deprecated in sing-box 1.10.0

`inet4_route_exclude_address` is deprecated and will be removed in sing-box 1.12.0, please use route_exclude_address instead.

Exclude custom routes when `auto_route` is enabled.

#### inet6_route_exclude_address

Deprecated in sing-box 1.10.0

`inet6_route_exclude_address` is deprecated and will be removed in sing-box 1.12.0, please use route_exclude_address instead.

Exclude custom routes when `auto_route` is enabled.

#### route_address_set

With `auto_redirect` enabledWithout `auto_redirect` enabled

Since sing-box 1.10.0

Only supported on Linux with nftables and requires `auto_route` and `auto_redirect` enabled.

Add the destination IP CIDR rules in the specified rule-sets to the firewall. Unmatched traffic will bypass the sing-box routes.

Conflict with `route.default_mark` and `[dialOptions].routing_mark`.

Since sing-box 1.11.0

Add the destination IP CIDR rules in the specified rule-sets to routes, equivalent to adding to `route_address`. Unmatched traffic will bypass the sing-box routes.

Note that it doesn't work on the Android graphical client due to the Android VpnService not being able to handle a large number of routes (DeadSystemException), but otherwise it works fine on all command line clients and Apple platforms.

#### route_exclude_address_set

With `auto_redirect` enabledWithout `auto_redirect` enabled

Since sing-box 1.10.0

Only supported on Linux with nftables and requires `auto_route` and `auto_redirect` enabled.

Add the destination IP CIDR rules in the specified rule-sets to the firewall. Matched traffic will bypass the sing-box routes.

Since sing-box 1.11.0

Add the destination IP CIDR rules in the specified rule-sets to routes, equivalent to adding to `route_exclude_address`. Matched traffic will bypass the sing-box routes.

Note that it doesn't work on the Android graphical client due to the Android VpnService not being able to handle a large number of routes (DeadSystemException), but otherwise it works fine on all command line clients and Apple platforms.

#### endpoint_independent_nat

This item is only available on the gvisor stack, other stacks are endpoint-independent NAT by default.

Enable endpoint-independent NAT.

Performance may degrade slightly, so it is not recommended to enable on when it is not needed.

#### udp_timeout

UDP NAT expiration time.

`5m` will be used by default.

#### stack

Changes in sing-box 1.8.0

The legacy LWIP stack has been deprecated and removed.

TCP/IP stack.

Stack | Description
--- | ---
`system` | Perform L3 to L4 translation using the system network stack
`gvisor` | Perform L3 to L4 translation using gVisor's virtual network stack
`mixed` | Mixed `system` TCP stack and `gvisor` UDP stack

Defaults to the `mixed` stack if the gVisor build tag is enabled, otherwise defaults to the `system` stack.

#### include_interface

Interface rules are only supported on Linux and require auto_route.

Limit interfaces in route. Not limited by default.

Conflict with `exclude_interface`.

#### exclude_interface

When `strict_route` enabled, return traffic to excluded interfaces will not be automatically excluded, so add them as well (example: `br-lan` and `pppoe-wan`).

Exclude interfaces in route.

Conflict with `include_interface`.

#### include_uid

UID rules are only supported on Linux and require auto_route.

Limit users in route. Not limited by default.

#### include_uid_range

Limit users in route, but in range.

#### exclude_uid

Exclude users in route.

#### exclude_uid_range

Exclude users in route, but in range.

#### include_android_user

Android user and package rules are only supported on Android and require auto_route.

Limit android users in route.

Common user | ID
--- | ---
Main | 0
Work Profile | 10

#### include_package

Limit android packages in route.

#### exclude_package

Exclude android packages in route.

#### include_mac_address

Since sing-box 1.14.0

Only supported on Linux with `auto_route` and `auto_redirect` enabled.

Limit MAC addresses in route. Not limited by default.

Conflict with `exclude_mac_address`.

#### exclude_mac_address

Since sing-box 1.14.0

Only supported on Linux with `auto_route` and `auto_redirect` enabled.

Exclude MAC addresses in route.

Conflict with `include_mac_address`.

#### platform

Platform-specific settings, provided by client applications.

#### platform.http_proxy

System HTTP proxy settings.

#### platform.http_proxy.enabled

Enable system HTTP proxy.

#### platform.http_proxy.server

Required

HTTP proxy server address.

#### platform.http_proxy.server_port

Required

HTTP proxy server port.

#### platform.http_proxy.bypass_domain

On Apple platforms, `bypass_domain` items matches hostname suffixes.

Hostnames that bypass the HTTP proxy.

#### platform.http_proxy.match_domain

Only supported in graphical clients on Apple platforms.

Hostnames that use the HTTP proxy.

### Listen Fields

See Listen Fields for details.