TUN inbound: Refine gateway and autoSystemRoutingTable on macOS (#6434)

https://github.com/XTLS/Xray-core/pull/6434#issuecomment-4885521586
2026-07-08 20:58:44 +00:00 · 2026-07-07 08:28:50 +08:00
parent 65f6f0a43b
commit 0495b17650
3 changed files with 118 additions and 20 deletions
@@ -15,8 +15,9 @@ Plainly enabling it in the config probably will result nothing, or lock your rou
 ## DETAILS

 By default, enabling the feature will only bring the tun interface up. \
-When configured explicitly, Windows and Linux can also apply interface addresses from `gateway` and on-link routes from `autoSystemRoutingTable`.
-Linux does not configure system DNS from the `dns` field; system DNS remains managed by the OS or distribution-specific network services. \
+When configured explicitly, Windows and Linux can apply interface addresses from `gateway`, while macOS uses the first IPv4 prefix from `gateway` to configure the utun point-to-point address. \
+Windows, Linux and macOS can also apply system routes from `autoSystemRoutingTable`.
+Linux and macOS do not configure system DNS from the `dns` field; system DNS remains managed by the OS or distribution-specific network services. \
 For more advanced routing policies or rules, OS level configuration can still manage the named interface (e.g. xray0) when it appears.
 This keeps complex system level routing and rules in a single place of responsibility - the OS itself. \
 Examples of how to achieve this on a simple Linux system (Ubuntu with systemd-networkd) can be found at the end of this README.
@@ -206,6 +207,11 @@ ifconfig
 Produced list will have all system interfaces listed, from which you will see how many "utun" ones already exists.
 It's not required to select next available number, e.g. if you have utun1-utun7 interfaces, it's not required to have "utun8" in the config. You can choose any available name, even utun20, to get surely available interface number.

+macOS requires the utun interface to have a point-to-point IPv4 address before IPv4 routes can use it. \
+By default Xray uses `169.254.10.1/30` as the remote gateway address and assigns the next address in the prefix to the local utun side. \
+You can override this by setting `gateway`; macOS uses the first IPv4 prefix in the list. IPv6 `gateway` entries are not used for utun addressing, and IPv6 routes use the interface route instead. \
+The `dns` field does not change macOS system DNS.
+
 To attach routing to the interface, route command like following can be executed:
 ```
 sudo route add -net 1.1.1.0/24 -iface utun10
@@ -214,6 +220,7 @@ sudo route add -net 1.1.1.0/24 -iface utun10
 sudo route add -inet6 -host 2606:4700:4700::1111 -iface utun10
 sudo route add -inet6 -host 2606:4700:4700::1001 -iface utun10
 ```
+Alternatively, configure `autoSystemRoutingTable` and Xray will add and remove those system routes while it is running.
 Important to remember that everything written above about Linux routing concept, also apply to Mac OS X. If you simply route default route through utun interface, that will result network loop and immediate network failure.

 ## ANDROID SUPPORT
@@ -24,11 +24,11 @@ import (
 )

 const (
-	utunControlName = "com.apple.net.utun_control"
-	sysprotoControl = 2
-	gateway         = "169.254.10.1/30"
-	utunHeaderSize  = 4
-	UTUN_OPT_IFNAME = 2
+	utunControlName      = "com.apple.net.utun_control"
+	sysprotoControl      = 2
+	defaultDarwinGateway = "169.254.10.1/30"
+	utunHeaderSize       = 4
+	UTUN_OPT_IFNAME      = 2
 )

 const (
@@ -50,6 +50,7 @@ type DarwinTun struct {
 	routeMonitor     *os.File
 	routeMonitorOnce sync.Once
 	systemRoutes     []netip.Prefix
+	gateway          netip.Prefix
 }

 var (
@@ -85,7 +86,13 @@ func NewTun(options *Config) (Tun, error) {
 		return nil, err
 	}

-	err = setup(options.Name, options.MTU)
+	gateway, err := selectDarwinGateway(options.Gateway)
+	if err != nil {
+		_ = tunFile.Close()
+		return nil, err
+	}
+
+	err = setup(options.Name, options.MTU, gateway)
 	if err != nil {
 		_ = tunFile.Close()
 		return nil, err
@@ -96,6 +103,7 @@ func NewTun(options *Config) (Tun, error) {
 		options: options,
 		tunFd:   int(tunFile.Fd()),
 		ownsFd:  true,
+		gateway: gateway,
 	}, nil
 }

@@ -281,24 +289,56 @@ func open(name string) (*os.File, error) {
 }

 // setup the interface by name
-func setup(name string, MTU uint32) error {
+func setup(name string, MTU uint32, gateway netip.Prefix) error {
 	if err := setMTU(name, MTU); err != nil {
 		return err
 	}

 	/*
 	 * Darwin routing require tunnel type interface to have local and remote address, to be routable.
-	 * To simplify inevitable task, assign the interface static ip address, which in current implementation
-	 * is just some random ip from link-local pool, allowing to not bother about existing routing intersection.
+	 * To simplify inevitable task, assign the interface static ip address.
 	 */
-	syntheticIP, _ := netip.ParsePrefix(gateway)
-	if err := setIPAddress(name, syntheticIP); err != nil {
+	if err := setIPAddress(name, gateway); err != nil {
 		return err
 	}

 	return nil
 }

+func selectDarwinGateway(configured []string) (netip.Prefix, error) {
+	if len(configured) == 0 {
+		return netip.ParsePrefix(defaultDarwinGateway)
+	}
+
+	for _, value := range configured {
+		prefix, err := netip.ParsePrefix(value)
+		if err != nil {
+			return netip.Prefix{}, xerrors.New("invalid macOS gateway ", value).Base(err)
+		}
+		if !prefix.Addr().Is4() {
+			continue
+		}
+		local, ok := nextDarwinLocalIPv4(prefix)
+		if !ok || !prefix.Contains(local) {
+			return netip.Prefix{}, xerrors.New("macOS gateway ", value, " must contain at least one usable local IPv4 address after the gateway address")
+		}
+		return prefix, nil
+	}
+
+	return netip.Prefix{}, xerrors.New("macOS gateway requires at least one IPv4 prefix")
+}
+
+func nextDarwinLocalIPv4(gateway netip.Prefix) (netip.Addr, bool) {
+	local4 := gateway.Addr().As4()
+	for i := len(local4) - 1; i >= 0; i-- {
+		local4[i]++
+		if local4[i] != 0 {
+			return netip.AddrFrom4(local4), true
+		}
+	}
+	return netip.Addr{}, false
+}
+
 // setMTU sets MTU on the interface by given name
 func setMTU(name string, mtu uint32) error {
 	socket, err := unix.Socket(unix.AF_INET, unix.SOCK_DGRAM, 0)
@@ -344,8 +384,11 @@ func setIPAddress(name string, gateway netip.Prefix) error {
 	defer unix.Close(socket4)

 	// assume local ip address is next one from the remote address
-	local4 := gateway.Addr().As4()
-	local4[3]++
+	local, ok := nextDarwinLocalIPv4(gateway)
+	if !ok || !gateway.Contains(local) {
+		return xerrors.New("macOS gateway ", gateway.String(), " must contain at least one usable local IPv4 address after the gateway address")
+	}
+	local4 := local.As4()

 	// fill the configuration for ipv4
 	ifReq4 := ifAliasReq4{
@@ -534,7 +577,7 @@ func (t *DarwinTun) setSystemRoutes() error {
 		return err
 	}
 	for _, destination := range routes {
-		if err := execDarwinRoute(unix.RTM_ADD, tunIndex, destination); err != nil {
+		if err := execDarwinRoute(unix.RTM_ADD, tunIndex, destination, t.gateway); err != nil {
 			_ = t.unsetSystemRoutes()
 			return xerrors.New("failed to add system route ", destination).Base(err)
 		}
@@ -551,7 +594,7 @@ func (t *DarwinTun) unsetSystemRoutes() error {
 	}
 	for i := len(t.systemRoutes) - 1; i >= 0; i-- {
 		destination := t.systemRoutes[i]
-		if err := execDarwinRoute(unix.RTM_DELETE, tunIndex, destination); err != nil && !errors.Is(err, unix.ESRCH) {
+		if err := execDarwinRoute(unix.RTM_DELETE, tunIndex, destination, t.gateway); err != nil && !errors.Is(err, unix.ESRCH) {
 			errs = append(errs, xerrors.New("failed to delete system route ", destination).Base(err))
 		}
 	}
@@ -606,7 +649,7 @@ func darwinProtectedDefaultRoutes(ipv4 bool) []netip.Prefix {
 	return routes
 }

-func execDarwinRoute(messageType int, interfaceIndex int, destination netip.Prefix) error {
+func execDarwinRoute(messageType int, interfaceIndex int, destination netip.Prefix, gateway netip.Prefix) error {
 	message := route.RouteMessage{
 		Type:    messageType,
 		Version: unix.RTM_VERSION,
@@ -618,11 +661,10 @@ func execDarwinRoute(messageType int, interfaceIndex int, destination netip.Pref
 	}

 	if destination.Addr().Is4() {
-		gatewayPrefix := netip.MustParsePrefix(gateway)
 		message.Addrs = []route.Addr{
 			unix.RTAX_DST:     &route.Inet4Addr{IP: destination.Addr().As4()},
 			unix.RTAX_NETMASK: &route.Inet4Addr{IP: prefixMask4(destination.Bits())},
-			unix.RTAX_GATEWAY: &route.Inet4Addr{IP: gatewayPrefix.Addr().As4()},
+			unix.RTAX_GATEWAY: &route.Inet4Addr{IP: gateway.Addr().As4()},
 		}
 	} else {
 		message.Flags &^= unix.RTF_GATEWAY
@@ -0,0 +1,49 @@
+//go:build darwin
+
+package tun
+
+import (
+	"testing"
+)
+
+func TestSelectDarwinGatewayDefault(t *testing.T) {
+	gateway, err := selectDarwinGateway(nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := gateway.String(); got != defaultDarwinGateway {
+		t.Fatalf("unexpected default gateway: got %s, want %s", got, defaultDarwinGateway)
+	}
+}
+
+func TestSelectDarwinGatewayConfiguredIPv4(t *testing.T) {
+	gateway, err := selectDarwinGateway([]string{"198.18.0.1/15"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := gateway.String(); got != "198.18.0.1/15" {
+		t.Fatalf("unexpected gateway: got %s", got)
+	}
+}
+
+func TestSelectDarwinGatewaySkipsIPv6(t *testing.T) {
+	gateway, err := selectDarwinGateway([]string{"fc00::1/64", "198.18.0.1/15"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if got := gateway.String(); got != "198.18.0.1/15" {
+		t.Fatalf("unexpected gateway: got %s", got)
+	}
+}
+
+func TestSelectDarwinGatewayRequiresIPv4(t *testing.T) {
+	if _, err := selectDarwinGateway([]string{"fc00::1/64"}); err == nil {
+		t.Fatal("expected error")
+	}
+}
+
+func TestSelectDarwinGatewayRequiresUsableLocalAddress(t *testing.T) {
+	if _, err := selectDarwinGateway([]string{"198.18.0.1/32"}); err == nil {
+		t.Fatal("expected error")
+	}
+}