Files
shenleiandClaude Code 5b7523fc4f Fix desktop TUN address leak that broke VPN rebuilds
sing-tun creates its utun control socket without SOCK_CLOEXEC
(tun_darwin.go), so any child the unified helper spawns while the
engine runs - the DnsGuard scutil process, route commands - inherits
that socket and pins the utun interface past engine stop. The
announcement-driven rebuild then fails with "desktop TUN address
already in use" and tears down the whole VPN session.

Mark every utun socket in the process close-on-exec as soon as the
engine starts. Stop now only warns when Darwin still holds the
retiring address (classified via cleanupFailure), and Start waits
bounded for an address this engine itself retained while failing fast
on any other owner.

Adds a root-only drain diagnostic with a real-profile pass, a
child-guard regression test that reproduced the production failure
before the fix, and a --self-test-unified-rebuild helper self-test
that forces stop/start cycles in combined mode end to end.

Co-Authored-By: Claude Code <noreply@anthropic.com>
2026-10-15 13:47:52 +09:00

313 lines
9.4 KiB
Go

// Package bridge provides an explicitly managed sing-box lifecycle. Platform
// TUN integration and ordinary internet proxy profiles are separate milestones.
package bridge
import (
"context"
"errors"
"fmt"
"github.com/sagernet/sing-box/adapter"
"github.com/sagernet/sing/common/control"
"github.com/sagernet/sing/service"
"net"
"os"
"path/filepath"
"runtime"
"strconv"
"sync"
"time"
box "github.com/sagernet/sing-box"
"github.com/sagernet/sing-box/adapter/certificate"
"github.com/sagernet/sing-box/adapter/endpoint"
"github.com/sagernet/sing-box/adapter/inbound"
"github.com/sagernet/sing-box/adapter/outbound"
boxservice "github.com/sagernet/sing-box/adapter/service"
"github.com/sagernet/sing-box/dns"
"github.com/sagernet/sing-box/dns/transport"
"github.com/sagernet/sing-box/dns/transport/fakeip"
"github.com/sagernet/sing-box/dns/transport/local"
"github.com/sagernet/sing-box/log"
"github.com/sagernet/sing-box/option"
"github.com/sagernet/sing-box/protocol/direct"
"github.com/sagernet/sing-box/protocol/http"
"github.com/sagernet/sing-box/protocol/shadowsocks"
"github.com/sagernet/sing-box/protocol/trojan"
"github.com/sagernet/sing-box/protocol/tun"
"github.com/sagernet/sing-box/protocol/vless"
"github.com/sagernet/sing-box/protocol/vmess"
sjson "github.com/sagernet/sing/common/json"
"golang.org/x/sys/unix"
)
func registryContext(ctx context.Context) context.Context {
in := inbound.NewRegistry()
registerTrackedInbound(in)
tun.RegisterInbound(in)
out := outbound.NewRegistry()
registerMeshOutbound(out)
shadowsocks.RegisterOutbound(out)
vmess.RegisterOutbound(out)
vless.RegisterOutbound(out)
trojan.RegisterOutbound(out)
http.RegisterOutbound(out)
direct.RegisterOutbound(out) // Required for sing-box's internal defaults.
dnsRegistry := dns.NewTransportRegistry()
local.RegisterTransport(dnsRegistry)
transport.RegisterUDP(dnsRegistry)
transport.RegisterHTTPS(dnsRegistry)
transport.RegisterTLS(dnsRegistry)
fakeip.RegisterTransport(dnsRegistry)
return box.Context(ctx, in, out, endpoint.NewRegistry(), dnsRegistry,
boxservice.NewRegistry(), certificate.NewRegistry())
}
type Snapshot struct {
State string `json:"state"`
Version string `json:"version"`
RuntimeEvents []RuntimeEvent `json:"runtime_events,omitempty"`
}
type Engine struct {
runtimeLogs runtimeLogs
selfTestTrace bool
startupCause error // Private diagnostic for package tests; never returned over ABI.
// Protector must be installed before starting a host TUN.
CacheRoot string
cacheDir string
Protect func(int) error
mu sync.Mutex
box *box.Box
state string
cancel context.CancelFunc
ctx context.Context
desktopTun bool
// Set when Stop returned while Darwin still held the retiring utun address.
tunRetained bool
}
func (e *Engine) Snapshot() Snapshot {
e.mu.Lock()
defer e.mu.Unlock()
state := e.state
if state == "" {
state = "Stopped"
}
if state == "Running" && e.ctx.Err() != nil {
state = "Failed"
}
return Snapshot{State: state, Version: "1.14.3", RuntimeEvents: e.runtimeLogs.snapshot()}
}
func (e *Engine) Start(parent context.Context, config Config) error {
e.mu.Lock()
defer e.mu.Unlock()
if e.box != nil {
return errors.New("engine already started; stop before applying configuration")
}
if parent.Err() != nil {
return errors.New("engine context is canceled")
}
if config.DesktopTun && (runtime.GOOS != "darwin" || os.Geteuid() != 0) {
return errors.New("desktop TUN requires macOS privileged helper")
}
if config.DesktopTun {
if err := e.awaitDesktopTunAddress(desktopTunRetainedWait); err != nil {
return err
}
}
data, err := config.managedJSON()
if err != nil {
return err
}
e.selfTestTrace = config.selfTestTrace()
e.desktopTun = config.DesktopTun
e.state = "Starting"
ctx, cancel := context.WithCancel(parent)
ctx = registryContext(ctx)
if config.Tun != nil {
if e.Protect == nil {
cancel()
e.state = "Failed"
return errors.New("platform socket protection required")
}
physical := &control.Interface{Name: config.Tun.Interface, Index: config.Tun.Index, MTU: 1500, Flags: net.FlagUp}
ctx = service.ContextWith[adapter.PlatformInterface](ctx, &hostPlatform{config: *config.Tun, protect: e.Protect, monitor: &hostMonitor{physical: physical}})
}
options, err := sjson.UnmarshalExtendedContext[option.Options](ctx, data)
if err != nil {
cancel()
e.state = "Failed"
return startupFailure("decode_configuration", err)
}
if config.FakeIP || len(config.RuleSets) > 0 {
if e.cacheDir == "" {
e.cacheDir, err = os.MkdirTemp(e.CacheRoot, "meshport-fakeip-")
if err != nil {
cancel()
e.state = "Failed"
return errors.New("cannot create private DNS cache")
}
}
options.Experimental = &option.ExperimentalOptions{CacheFile: &option.CacheFileOptions{Enabled: true, Path: filepath.Join(e.cacheDir, "fakeip.db"), StoreFakeIP: config.FakeIP}}
}
e.runtimeLogs.configure(config.Proxy)
// Collect bounded, credential-redacted warning/error events in memory.
// Raw upstream logs must never go to stderr or a user's log file.
if !e.selfTestTrace {
options.Log = &option.LogOptions{Level: "info", Output: os.DevNull}
}
instance, err := box.New(box.Options{Options: options, Context: ctx})
if err != nil {
e.startupCause = err
cancel()
e.state = "Failed"
return startupFailure("initialize_engine", err)
}
instance.LogFactory().AttachPlatformWriter(&e.runtimeLogs)
if err = instance.Start(); err != nil {
e.startupCause = err
_ = instance.Close()
cancel()
e.state = "Failed"
return startupFailure("start_engine", err)
}
if config.DesktopTun {
markDesktopTunCloseOnExec()
}
e.box, e.cancel, e.ctx, e.state = instance, cancel, ctx, "Running"
return nil
}
// sing-tun creates its utun control socket without SOCK_CLOEXEC (tun_darwin).
// Any process the host spawns while the engine runs — the unified helper's
// scutil DNS guard or route commands — inherits that socket and pins the utun
// interface past engine stop, so announcement-driven rebuilds cannot reattach
// the desktop address. Mark every utun socket in this process close-on-exec
// as soon as the engine owns it.
func markDesktopTunCloseOnExec() {
if runtime.GOOS != "darwin" {
return
}
directory, err := os.Open("/dev/fd")
if err != nil {
return
}
defer directory.Close()
entries, err := directory.Readdirnames(-1)
if err != nil {
return
}
for _, entry := range entries {
fd, err := strconv.Atoi(entry)
if err != nil || fd <= 2 {
continue
}
if _, err := unix.GetsockoptString(fd,
2 /* SYSPROTO_CONTROL */, 2 /* UTUN_OPT_IFNAME */); err == nil {
unix.CloseOnExec(fd)
}
}
}
func (e *Engine) Stop() error {
e.mu.Lock()
defer e.mu.Unlock()
if e.box == nil {
e.state = "Stopped"
return nil
}
e.state = "Stopping"
err := e.box.Close()
e.cancel()
e.box, e.cancel, e.ctx = nil, nil, nil
if e.desktopTun && err == nil {
// Darwin can retain the utun address until its last kernel reference
// drains. Reusing that address immediately can attach the new routes
// to the retiring interface and remove them when it finally disappears.
deadline := time.Now().Add(2 * time.Second)
for {
attached, inspectErr := desktopTunAddressAttached()
if inspectErr != nil {
err = fmt.Errorf("%w: %v", errTunAddressInspect, inspectErr)
break
}
if !attached {
break
}
if time.Now().After(deadline) {
// The engine is already closed, so a retained address only delays reusing
// 172.19.0.1; the next Start waits for it. Warn instead of failing the stop.
e.tunRetained = true
e.runtimeLogs.WriteMessage(log.LevelWarn, "desktop TUN address still retained after stop")
break
}
time.Sleep(20 * time.Millisecond)
}
}
if err != nil {
e.state = "Failed"
if e.selfTestTrace {
fmt.Fprintf(os.Stderr, "self-test cleanup cause: %v\n", err)
}
return cleanupFailure(err)
}
e.state = "Stopped"
return nil
}
// Announcement-driven rebuilds stop and start immediately. If the address
// belongs to this engine's own retiring utun, wait for the kernel to drain it;
// any other owner still fails fast.
func (e *Engine) awaitDesktopTunAddress(wait time.Duration) error {
deadline := time.Now().Add(wait)
for {
attached, err := desktopTunAddressAttached()
if err != nil {
return errors.New("cannot inspect desktop TUN address")
}
if !attached {
e.tunRetained = false
return nil
}
if !e.tunRetained || time.Now().After(deadline) {
return errors.New("desktop TUN address already in use")
}
time.Sleep(50 * time.Millisecond)
}
}
// Bounded so a utun that never drains still surfaces as a startup failure
// well inside the helper's 30s reply and 60s watchdog limits.
const desktopTunRetainedWait = 10 * time.Second
// Variable so lifecycle tests can simulate Darwin's delayed address release.
var desktopTunAddressAttached = func() (bool, error) {
addresses, err := net.InterfaceAddrs()
if err != nil {
return false, err
}
for _, address := range addresses {
ip, _, err := net.ParseCIDR(address.String())
if err == nil && ip.Equal(net.ParseIP("172.19.0.1")) {
return true, nil
}
}
return false, nil
}
// Close releases the session's private cache only after the engine is stopped.
func (e *Engine) Close() error {
err := e.Stop()
e.mu.Lock()
defer e.mu.Unlock()
if e.cacheDir != "" {
removeErr := os.RemoveAll(e.cacheDir)
e.cacheDir = ""
if err == nil {
err = removeErr
}
}
return err
}