From 640ce2f9d940760029a3b3679edf891209b2be0d Mon Sep 17 00:00:00 2001 From: steigr Date: Fri, 20 Nov 2026 14:28:51 +0100 Subject: [PATCH] net: hold a forward test's port on the wildcard address, so macOS binds the forward Link::forward_on_a_held_port held 127.0.0.1:P with SO_REUSEADDR and the NAT forward then bound 127.0.0.1:P. Linux allows that while the hold is not listening; macOS refuses an identical second bind unless both sockets set SO_REUSEPORT, so the five NIC restart/drop port-forward tests failed there with "the forward never listened". Holding 0.0.0.0:P lets the forward bind 127.0.0.1:P on both systems, and the kernel still hands the held port to no other test. Co-Authored-By: Claude Opus 5.5 --- clanker/INDEX.md | 1 + ...eld-test-port-must-be-wildcard-on-macos.md | 24 +++++++++++++++++++ src/net/link.rs | 8 ++++++- 3 files changed, 32 insertions(+), 1 deletion(-) create mode 100644 clanker/net/a-held-test-port-must-be-wildcard-on-macos.md diff --git a/clanker/INDEX.md b/clanker/INDEX.md index cb6e76d06..ac4afadea 100644 --- a/clanker/INDEX.md +++ b/clanker/INDEX.md @@ -193,6 +193,7 @@ The NAT stack and its built-in services: DNS, TCP, NFS, rsh, BOOTP/TFTP. | [nat-dns-host-resolver.md](net/nat-dns-host-resolver.md) | rule | NAT DNS follows the host's DNS server | | [nat-tcp-slow-host-reader.md](net/nat-tcp-slow-host-reader.md) | rule | NAT TCP: a slow host reader must not lose the guest's data | | [a-nic-restart-must-join-its-old-backend.md](net/a-nic-restart-must-join-its-old-backend.md) | rule | Every NIC runs its backend through `net::link::Session`: a restart joins the old backend before the new one binds, or a reset loses the port forwards | +| [a-held-test-port-must-be-wildcard-on-macos.md](net/a-held-test-port-must-be-wildcard-on-macos.md) | rule | A test that holds a forward's port must hold the wildcard address: macOS refuses a second bind of the same address and port without SO_REUSEPORT | | [nat-throughput-and-latency.md](net/nat-throughput-and-latency.md) | measure | NAT throughput and latency: what actually limited it | | [nfs-irix-6530-mount.md](net/nfs-irix-6530-mount.md) | rule | IRIX 6.5.30 asks for mountd over TCP; the share is UDP only, so mount with `-o proto=udp` (a plain mount fails); MOUNT v3 must list AUTH_UNIX | | [nfs-dot-and-dotdot-must-resolve-server-side.md](net/nfs-dot-and-dotdot-must-resolve-server-side.md) | rule | NFS LOOKUP `..` must resolve on the server — the client does not synthesize it | diff --git a/clanker/net/a-held-test-port-must-be-wildcard-on-macos.md b/clanker/net/a-held-test-port-must-be-wildcard-on-macos.md new file mode 100644 index 000000000..887a1b945 --- /dev/null +++ b/clanker/net/a-held-test-port-must-be-wildcard-on-macos.md @@ -0,0 +1,24 @@ +# A test that holds a forward's port must hold it on the wildcard address, or macOS refuses the forward + +Status: rule (2026-11-20). + +**Symptom.** On macOS the restart tests for every NIC +(`a_restart_keeps_the_port_forwards` on bcm5701, daynaport, ioc3 eth and +seeq8003, and mec's `a_dropped_mec_frees_its_port_forwards`) panicked with +"the forward never listened"; the forward logged `failed to bind: Address +already in use`. On Linux they passed. + +**Cause.** `Link::forward_on_a_held_port` keeps a SO_REUSEADDR socket bound, +not listening, on the port so no other test is handed it, and the NAT +forward binds the same port with `std::net::TcpListener::bind`, which sets +SO_REUSEADDR only. Linux lets two SO_REUSEADDR sockets share an exact +address and port while neither listens. macOS, like the BSDs, refuses a +second bind of the identical address and port unless both sockets set +SO_REUSEPORT. It does let a specific address share a port with a wildcard +bind. + +**Rule.** Hold the port on `0.0.0.0` and let the forward bind `127.0.0.1`. +Both systems accept that, and neither hands the held port out as an +ephemeral port. Do not add SO_REUSEPORT to the forward listener to make +the tests pass: it would let a second emulator bind the same forward port +and share its connections. diff --git a/src/net/link.rs b/src/net/link.rs index 7001ca9b4..36f1869dd 100644 --- a/src/net/link.rs +++ b/src/net/link.rs @@ -229,13 +229,19 @@ impl Link { /// not listening, by the returned socket, so no other test is handed the /// port meanwhile. Where a held port cannot be bound twice (not Unix) the /// socket is let go first. + /// + /// The hold is on the wildcard address and the forward binds localhost: + /// macOS, like the BSDs, refuses a second bind of the very same address + /// and port unless both sockets set SO_REUSEPORT, which the forward + /// listener does not, but lets a specific address share a port with a + /// wildcard bind. Linux allows either while the hold is not listening. #[cfg(test)] pub(crate) fn forward_on_a_held_port() -> (Option, u16, GatewayConfig) { use crate::config::{ForwardBind, ForwardProto, PortForwardConfig}; let hold = socket2::Socket::new(socket2::Domain::IPV4, socket2::Type::STREAM, None).unwrap(); #[cfg(unix)] hold.set_reuse_address(true).unwrap(); - hold.bind(&"127.0.0.1:0".parse::().unwrap().into()).unwrap(); + hold.bind(&"0.0.0.0:0".parse::().unwrap().into()).unwrap(); let port = hold.local_addr().unwrap().as_socket().unwrap().port(); let hold = cfg!(unix).then_some(hold); let config = GatewayConfig {