Preserve real client source IP in builtin port driver via IP_TRANSPARENT

Use IP_TRANSPARENT socket option in the child process to bind outgoing
connections to the real client IP:port, so backend services see the
original source address instead of 127.0.0.1. This leverages
CAP_NET_ADMIN in the user namespace (Linux 4.18+) and policy routing
to complete TCP handshakes without iptables. Falls back gracefully to
normal dial on older kernels or when routing setup fails.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Signed-off-by: Akihiro Suda <akihiro.suda.cz@hco.ntt.co.jp>

Author: AkihiroSuda

pkg/port/builtin/builtin_test.go

@@ -29,4 +29,5 @@ func TestBuiltIn(t *testing.T) {
 		return d
 	}
 	testsuite.Run(t, pf)
+	testsuite.RunTCPTransparent(t, pf)
 }

pkg/port/builtin/child/child.go

@@ -6,8 +6,12 @@ import (
 	"io"
 	"net"
 	"os"
+	"os/exec"
 	"strconv"
 	"strings"
+	"sync"
+	"syscall"
+	"time"
 
 	"golang.org/x/sys/unix"
 
@@ -25,7 +29,8 @@ func NewDriver(logWriter io.Writer) port.ChildDriver {
 }
 
 type childDriver struct {
-	logWriter io.Writer
+	logWriter    io.Writer
+	routingSetup sync.Once
 }
 
 func (d *childDriver) RunChildDriver(opaque map[string]string, quit <-chan struct{}, detachedNetNSPath string) error {
@@ -119,7 +124,6 @@ func (d *childDriver) handleConnectRequest(c *net.UnixConn, req *msg.Request) er
 	}
 	// dialProto does not need "4", "6" suffix
 	dialProto := strings.TrimSuffix(strings.TrimSuffix(req.Proto, "6"), "4")
-	var dialer net.Dialer
 	ip := req.IP
 	if ip == "" {
 		ip = "127.0.0.1"
@@ -135,9 +139,24 @@ func (d *childDriver) handleConnectRequest(c *net.UnixConn, req *msg.Request) er
 		}
 		ip = p.String()
 	}
-	targetConn, err := dialer.Dial(dialProto, net.JoinHostPort(ip, strconv.Itoa(req.Port)))
-	if err != nil {
-		return err
+	targetAddr := net.JoinHostPort(ip, strconv.Itoa(req.Port))
+
+	var targetConn net.Conn
+	var err error
+	if req.SourceIP != "" && req.SourcePort != 0 && dialProto == "tcp" && !net.ParseIP(req.SourceIP).IsLoopback() {
+		d.routingSetup.Do(func() { d.setupTransparentRouting() })
+		targetConn, err = transparentDial(dialProto, targetAddr, req.SourceIP, req.SourcePort)
+		if err != nil {
+			fmt.Fprintf(d.logWriter, "transparent dial failed, falling back: %v\n", err)
+			targetConn, err = nil, nil
+		}
+	}
+	if targetConn == nil {
+		var dialer net.Dialer
+		targetConn, err = dialer.Dial(dialProto, targetAddr)
+		if err != nil {
+			return err
+		}
 	}
 	defer targetConn.Close() // no effect on duplicated FD
 	targetConnFiler, ok := targetConn.(filer)
@@ -164,6 +183,72 @@ func (d *childDriver) handleConnectRequest(c *net.UnixConn, req *msg.Request) er
 	return err
 }
 
+// setupTransparentRouting sets up policy routing so that response packets
+// destined to transparent-bound source IPs are delivered locally.
+//
+// Transparent sockets (IP_TRANSPARENT) bind to non-local addresses (the real
+// client IP). Response packets to these addresses must be routed locally instead
+// of being sent out through the TAP device (slirp4netns).
+//
+// The transparent SYN goes through OUTPUT (where we tag it with CONNMARK) and
+// then either:
+//
+//  1. Gets DNAT'd to the container (nerdctl/CNI): the SYN-ACK arrives via the
+//     bridge in PREROUTING, where we restore connmark to fwmark.
+//
+//  2. Goes through loopback to a userspace proxy like docker-proxy: the SYN
+//     enters PREROUTING on loopback with connmark, which sets fwmark. With
+//     tcp_fwmark_accept=1, the accepted socket inherits the fwmark. The proxy's
+//     SYN-ACK is then routed via the fwmark table (local delivery) instead of
+//     the default route (TAP), allowing it to reach the transparent socket.
+func (d *childDriver) setupTransparentRouting() {
+	cmds := [][]string{
+		// Table 100: treat all addresses as local (for delivery to transparent sockets)
+		{"ip", "route", "add", "local", "default", "dev", "lo", "table", "100"},
+		{"ip", "-6", "route", "add", "local", "default", "dev", "lo", "table", "100"},
+		// Route fwmark-100 packets via table 100
+		{"ip", "rule", "add", "fwmark", "100", "lookup", "100", "priority", "100"},
+		{"ip", "-6", "rule", "add", "fwmark", "100", "lookup", "100", "priority", "100"},
+		// Inherit fwmark from SYN to accepted socket (needed for userspace proxies
+		// like docker-proxy, so that SYN-ACK routing uses table 100)
+		{"sysctl", "-w", "net.ipv4.tcp_fwmark_accept=1"},
+		// In OUTPUT: tag transparent connections (non-local source) with CONNMARK
+		{"iptables", "-t", "mangle", "-A", "OUTPUT", "-p", "tcp", "-m", "addrtype", "!", "--src-type", "LOCAL", "-j", "CONNMARK", "--set-mark", "100"},
+		{"ip6tables", "-t", "mangle", "-A", "OUTPUT", "-p", "tcp", "-m", "addrtype", "!", "--src-type", "LOCAL", "-j", "CONNMARK", "--set-mark", "100"},
+		// In PREROUTING: restore connmark to fwmark for routing
+		{"iptables", "-t", "mangle", "-A", "PREROUTING", "-p", "tcp", "-m", "connmark", "--mark", "100", "-j", "MARK", "--set-mark", "100"},
+		{"ip6tables", "-t", "mangle", "-A", "PREROUTING", "-p", "tcp", "-m", "connmark", "--mark", "100", "-j", "MARK", "--set-mark", "100"},
+	}
+	for _, args := range cmds {
+		if out, err := exec.Command(args[0], args[1:]...).CombinedOutput(); err != nil {
+			fmt.Fprintf(d.logWriter, "transparent routing setup: %v: %s\n", err, out)
+		}
+	}
+}
+
+// transparentDial dials targetAddr using IP_TRANSPARENT, binding to the given
+// source IP and port so the backend service sees the real client address.
+func transparentDial(dialProto, targetAddr, sourceIP string, sourcePort int) (net.Conn, error) {
+	dialer := net.Dialer{
+		Timeout:   time.Second,
+		LocalAddr: &net.TCPAddr{IP: net.ParseIP(sourceIP), Port: sourcePort},
+		Control: func(network, address string, c syscall.RawConn) error {
+			var sockErr error
+			if err := c.Control(func(fd uintptr) {
+				if strings.Contains(network, "6") {
+					sockErr = unix.SetsockoptInt(int(fd), unix.SOL_IPV6, unix.IPV6_TRANSPARENT, 1)
+				} else {
+					sockErr = unix.SetsockoptInt(int(fd), unix.SOL_IP, unix.IP_TRANSPARENT, 1)
+				}
+			}); err != nil {
+				return err
+			}
+			return sockErr
+		},
+	}
+	return dialer.Dial(dialProto, targetAddr)
+}
+
 // filer is implemented by *net.TCPConn and *net.UDPConn
 type filer interface {
 	File() (f *os.File, err error)

pkg/port/builtin/msg/msg.go

@@ -25,6 +25,8 @@ type Request struct {
 	Port          int
 	ParentIP      string
 	HostGatewayIP string
+	SourceIP      string `json:",omitempty"` // real client IP for IP_TRANSPARENT
+	SourcePort    int    `json:",omitempty"` // real client port for IP_TRANSPARENT
 }
 
 // Reply may contain FD as OOB
@@ -69,7 +71,9 @@ func hostGatewayIP() string {
 
 // ConnectToChild connects to the child UNIX socket, and obtains TCP or UDP socket FD
 // that corresponds to the port spec.
-func ConnectToChild(c *net.UnixConn, spec port.Spec) (int, error) {
+// sourceAddr is the real client address (e.g., from net.Conn.RemoteAddr()) for IP_TRANSPARENT support.
+// Pass nil to skip source IP preservation.
+func ConnectToChild(c *net.UnixConn, spec port.Spec, sourceAddr net.Addr) (int, error) {
 	req := Request{
 		Type:          RequestTypeConnect,
 		Proto:         spec.Proto,
@@ -78,6 +82,10 @@ func ConnectToChild(c *net.UnixConn, spec port.Spec) (int, error) {
 		ParentIP:      spec.ParentIP,
 		HostGatewayIP: hostGatewayIP(),
 	}
+	if tcpAddr, ok := sourceAddr.(*net.TCPAddr); ok && tcpAddr != nil {
+		req.SourceIP = tcpAddr.IP.String()
+		req.SourcePort = tcpAddr.Port
+	}
 	if _, err := lowlevelmsgutil.MarshalToWriter(c, &req); err != nil {
 		return 0, err
 	}
@@ -114,21 +122,21 @@ func ConnectToChild(c *net.UnixConn, spec port.Spec) (int, error) {
 }
 
 // ConnectToChildWithSocketPath wraps ConnectToChild
-func ConnectToChildWithSocketPath(socketPath string, spec port.Spec) (int, error) {
+func ConnectToChildWithSocketPath(socketPath string, spec port.Spec, sourceAddr net.Addr) (int, error) {
 	var dialer net.Dialer
 	conn, err := dialer.Dial("unix", socketPath)
 	if err != nil {
 		return 0, err
 	}
 	defer conn.Close()
 	c := conn.(*net.UnixConn)
-	return ConnectToChild(c, spec)
+	return ConnectToChild(c, spec, sourceAddr)
 }
 
 // ConnectToChildWithRetry retries ConnectToChild every (i*5) milliseconds.
-func ConnectToChildWithRetry(socketPath string, spec port.Spec, retries int) (int, error) {
+func ConnectToChildWithRetry(socketPath string, spec port.Spec, retries int, sourceAddr net.Addr) (int, error) {
 	for i := 0; i < retries; i++ {
-		fd, err := ConnectToChildWithSocketPath(socketPath, spec)
+		fd, err := ConnectToChildWithSocketPath(socketPath, spec, sourceAddr)
 		if i == retries-1 && err != nil {
 			return 0, err
 		}

pkg/port/builtin/parent/tcp/tcp.go

@@ -59,7 +59,7 @@ func Run(socketPath string, spec port.Spec, stopCh <-chan struct{}, stoppedCh ch
 func copyConnToChild(c net.Conn, socketPath string, spec port.Spec, stopCh <-chan struct{}) error {
 	defer c.Close()
 	// get fd from the child as an SCM_RIGHTS cmsg
-	fd, err := msg.ConnectToChildWithRetry(socketPath, spec, 10)
+	fd, err := msg.ConnectToChildWithRetry(socketPath, spec, 10, c.RemoteAddr())
 	if err != nil {
 		return err
 	}

pkg/port/builtin/parent/udp/udp.go

@@ -26,7 +26,7 @@ func Run(socketPath string, spec port.Spec, stopCh <-chan struct{}, stoppedCh ch
 		Listener:  c,
 		BackendDial: func() (*net.UDPConn, error) {
 			// get fd from the child as an SCM_RIGHTS cmsg
-			fd, err := msg.ConnectToChildWithRetry(socketPath, spec, 10)
+			fd, err := msg.ConnectToChildWithRetry(socketPath, spec, 10, nil)
 			if err != nil {
 				return nil, err
 			}