Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions clanker/INDEX.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 |
Expand Down
24 changes: 24 additions & 0 deletions clanker/net/a-held-test-port-must-be-wildcard-on-macos.md
Original file line number Diff line number Diff line change
@@ -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.
8 changes: 7 additions & 1 deletion src/net/link.rs
Original file line number Diff line number Diff line change
Expand Up @@ -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<socket2::Socket>, 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::<std::net::SocketAddr>().unwrap().into()).unwrap();
hold.bind(&"0.0.0.0:0".parse::<std::net::SocketAddr>().unwrap().into()).unwrap();
let port = hold.local_addr().unwrap().as_socket().unwrap().port();
let hold = cfg!(unix).then_some(hold);
let config = GatewayConfig {
Expand Down
Loading