[kasper0406]

PR 3 of 3. Depends on #644; please review it after #644. Stacked PRs from a fork all target main, so until #643 and #644 merge this diff also shows their commits. This PR's own commits are the last two: feat(exit_node): port-mapper flags and a one-shot --portmap-probe and docs: record the port mapper in the ledger and roadmap.

1. feat(portmapper): add ts_portmapper, a NAT-PMP and PCP client #643: the ts_portmapper crate.
2. feat(runtime): map the underlay port with NAT-PMP or PCP, as Go does #644: run it in the node.
3. This PR: runner controls, the probe, and the docs.

What it adds

• --portmap-probe runs instead of the node, before any identity, state or control connection exists. It maps a dedicated test port on the LAN gateway with each protocol separately. It can hold the mapping open to count inbound datagrams (--portmap-hold; it counts only, payloads are not read), then deletes the mapping and exits:

  • 0: every protocol mapped and deleted;
  • 2: some did;
  • 1: none did, or there was no usable gateway.

  --portmap-wait retries the gateway lookup for a job started before the network is up. Interrupts end the wait or the hold early, and the delete still runs. The node's own ports (41641, 41642, --port) are refused as test ports, and the probe is refused when TS_DISABLE_PORTMAPPER is set, as Go's debug portmap is. --portmap-hold must be shorter than --portmap-lifetime. The output may contain the router's public address.

• Runner defaults that differ from the library's, which are Go's:

  • A private or CGNAT external address (a double NAT) is kept and renewed but not advertised: it is not reachable from outside that NAT, so advertising it only costs peers failed disco probes. --portmap-advertise-nonpublic restores Go's behaviour.
  • A due mapping is renewed while idle as long as there are peers, so an idle exit node stays directly reachable. Go renews only on activity; --portmap-lazy-renew restores that.

• Other flags: --portmap-gateway GW[,SELF] overrides the gateway, validated like a discovered one. --no-portmapper turns the mapper off.

• Status line: gains the portmap= summary (Go's NetInfo summary; here active- means an advertised mapping, in Go any held mapping; e.g. active-_MC). It also shows the held mapping, marked when it is not advertised.

• Docs:

  • docs/PORTMAPPER.md describes the runner's defaults;
  • PORTING.md maps net/portmapper's NAT-PMP and PCP halves and now counts seven of Go's twelve NetInfo facets as reported (an eighth, UPnP, is modelled but never set);
  • the migration status and parity roadmap mark NAT-PMP and PCP done and keep tsr-x4yg open for UPnP-IGD.

Mapping to Go

The closest Go tool is tailscale debug portmap (feature/debugportmapper), which this repository does not have. --portmap-probe covers the same need for an embedded node. It deletes what it created, can count inbound traffic, and never uses the node's own ports. This PR changes two runner policy defaults relative to Go, and each has a flag that restores Go's default. The library defaults stay Go's. The library's other documented differences (#643, #644) are unaffected by these flags.

Testing

• Unit tests for the argument parsing: the probe needs no state directory; probe-only flags require --portmap-probe; ranges, reserved ports and a hold not shorter than the lifetime are rejected; TS_DISABLE_PORTMAPPER refuses the probe; the runner defaults and the flags that revert them. exit_node is now an [[example]] with test = true, so cargo test runs these in CI.
• The probe itself is tested in feat(portmapper): add ts_portmapper, a NAT-PMP and PCP client #643 against the fake router. The tests cover map and delete per protocol, the hold window, interrupts, a lease shorter than the hold, waiting for a late route, partial and refused service, and reserved ports.
• Branch gates on macOS, cargo +1.95.0, all passing:
  • workspace tests, default and all features;
  • clippy -D warnings across all CI variants, including bin/check-windows;
  • fmt, cargo run -p checks, cargo doc, cargo vet --locked and cargo deny;
  • the fuzz crate builds.

Field results

--portmap-probe against a consumer router running MiniUPnPd: the router answered both NAT-PMP and PCP. Map and delete were acknowledged for both protocols, and datagrams sent from an outside network arrived at the mapped port during the hold.

On Linux (x86_64, kernel 6.8), the same probe found the gateway through /proc/net/route, bound to the interface, and mapped and deleted with both protocols. On that machine the workspace tests passed (2,548 passed, 0 failed; one root-only TUN test ignored), and so did workspace clippy -D warnings.

Hard-NAT client test (2026-10-18): a laptop on a network with endpoint-dependent mapping (tailscale netcheck: MappingVariesByDestIP: true) reached a node running this series directly through the NAT-PMP mapping (tailscale ping: pong … via <mapped address> in 26ms). The node logged the path as direct to a source port the laptop's NAT chose for that destination alone, which only an open inbound mapping can accept. Before the port mapper, the same node was reachable only through DERP from such networks, while a Go client on the same host, which holds its own mapping, was direct. The node also renewed its two-hour lease overnight, and re-mapped by itself after the router rebooted.

Created using Claude Code
The code was written and reviewed with GPT-6.1 (Codex); the split, polish and gates were done with Claude Code.

🤖 Generated with Claude Code

[coderabbitai]

Warning

Review limit reached

You've used all free OSS reviews for now. Wait for the free limit to reset to keep reviewing this public repository.

Next included review available in 58 minutes.

Check out review usage here.

View limit details

Limit details: You’ve used the included review currently available.

Learn how review limits work.

Review configuration:

⚙️ Run configuration

• Configuration used: Repository: GeiserX/tailscale-rs/.coderabbit.yaml
• Review profile: CHILL
• Plan: Advanced
• Run ID: 0a03b7e6-f102-4eac-b4b5-05543fd5089d

📥 Commits

Reviewing files that changed from the base of the PR and between 572d377 and 5d83cba.

⛔ Files ignored due to path filters: 1

• Cargo.lock is excluded by !**/*.lock, !**/Cargo.lock

📒 Files selected for processing: 7

• CHANGELOG.md
• Cargo.toml
• PORTING.md
• docs/MIGRATION_STATUS.md
• docs/PARITY_ROADMAP.md
• docs/PORTMAPPER.md
• examples/exit_node/main.rs

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}