Holepunch monitor falsely reports direct success when peer endpoint is reachable via the tunnel's own routed subnet, causing connection flap

[krmbluek]

Describe the Bug

Summary

When a Newt site registers with an endpoint IP that falls inside a subnet the CLI also routes through the WireGuard tunnel, the holepunch monitor's test packets are routed through the tunnel itself (via the relay), receive responses, and are misclassified as successful direct holepunches. The CLI then switches the peer to direct mode, the data plane fails because the registered endpoint isn't reachable over the underlying network, and the connection cycles between relay and broken-direct indefinitely.

The --holepunch=false flag is documented but does not stop this behavior — only the initial rapid startup test honors the flag, while the ongoing holepunch monitor continues to run and trigger the cycle.

Topology

• Two Newt sites configured on the Pangolin server:
  • Site 3 registered with the office WAN IP — works fine, stays on relay, no flap
  • Site 6 registered with a LAN IP 10.1.10.16:63047 — flaps continuously
• Site 6's LAN IP got registered automatically because the Newt host shares a LAN with the Pangolin server, so gerbil saw the registration arrive from the LAN-side source IP. No explicit endpoint advertisement was set on Newt — this is default-configuration behavior.
• The CLI is running on a roaming client on a completely separate network (10.0.120.0/24) with no underlying-network path to either the Pangolin server's WAN IP or to 10.1.10.16.
• The CLI installs a route for 10.1.0.0/16 via the pangolin interface, which covers the misregistered Site 6 endpoint.

Environment

• Pangolin CLI version: 0.6.2 (latest at time of filing)
• OS: Ubuntu 24.04 LTS, x86_64 (Surface Pro 9, linux-surface kernel)
• Pangolin server version: 1.17.0
• Newt version on peer site: 1.11.0, native binary running as systemd service, no explicit endpoint flag (default args: --id <redacted> --secret <redacted> --endpoint https://pangolin.example.com)

To Reproduce

1. Configure a Newt site such that its registered endpoint is a private IP. This happens automatically when the Newt host shares a LAN with the Pangolin server.
2. Configure a resource that pushes a route covering that private IP through the tunnel (e.g. 10.1.0.0/16).
3. From a network with no underlying path to either the Pangolin server's WAN or the registered LAN IP, run pangolin up (or pangolin up --holepunch=false).
4. Run pangolin logs client --follow and observe the cycle.

Expected Behavior

Expected behavior

Holepunch test fails because there is no underlying-network path to the endpoint. Peer stays on relay. Connection is stable.

Additionally, --holepunch=false should disable holepunch attempts entirely, including the ongoing monitor.

Actual behavior

The startup rapid-test correctly fails (it tests via the underlying socket before the tunnel is up). But once the tunnel is up and the relay is working, the holepunch connection monitor sends test packets to the registered endpoint via the standard kernel routing table. Those packets match the 10.1.0.0/16 tunnel route, traverse the tunnel via the relay, reach the legitimate Newt peer (which actually is at 10.1.10.16 on its own LAN), and get a response. The monitor reports "CONNECTED" with a relay-roundtrip RTT and switches the peer to direct mode.

The data plane then fails because the WireGuard endpoint can't be reached over the underlying network. After ~5 seconds of timeout, the CLI falls back to relay. The monitor immediately succeeds again (same recursive path), switches back to direct, fails again. The cycle repeats indefinitely every 15-30 seconds.

This happens whether --holepunch is true or false.

[krmbluek]

Update with deeper diagnosis after further investigation:
--holepunch=false is a no-op in 0.6.2. The flag is parsed but the holepunch connection monitor runs regardless. Confirmed by testing — the cycle is identical with and without the flag.
--disable-holepunch (referenced in the official client docs at https://docs.pangolin.net/manage/clients/configure-client) is not implemented in pangolin up or pangolin up client:
$ pangolin up --disable-holepunch
Error: unknown flag: --disable-holepunch
The deeper bug is in the holepunch monitor's path validation, not just the flag. Even if the flag worked, the underlying issue would remain for any other code path that probes the registered endpoint:
The holepunch test sends its probe packet via the standard kernel routing table. When the destination IP falls inside a subnet the CLI itself has routed through the WireGuard tunnel (e.g. 10.1.0.0/16 via the pangolin interface), the probe packet is encrypted and sent through the tunnel to the relay, decapsulated by gerbil, and forwarded to the legitimate Newt peer (which actually does live at the registered LAN IP on its own LAN). The peer responds, the response returns through the same path, and the monitor interprets a relay-roundtrip RTT (~30ms in my testing) as direct-path success.
A correct holepunch test must validate that the response arrived via the underlying network path, not via the tunnel that's currently configured. Possible approaches: bind the probe socket to the underlying physical interface explicitly, mark probe packets so iptables/routing can exclude them from the tunnel route, or compare the observed RTT against the known relay RTT and reject suspiciously similar values.
Topology context (in case it helps reproduce):

Pangolin server: VPS at a public hosting provider
Newt site (1.11.0, native binary, no -prefer-endpoint set): on-prem host 10.1.10.16, behind office NAT
Resource configured to route 10.1.0.0/16 through the tunnel
Newt advertises 10.1.10.16:63047 to gerbil — this is its own listen address (ss -ulnp confirms *:63047 bound by the newt process), not gerbil's observed source IP
CLI client roaming on a totally separate network (10.0.120.0/24) with no underlying-network path to either the Pangolin VPS or 10.1.10.16
Result: holepunch monitor probe to 10.1.10.16:63047 matches the 10.1.0.0/16 route, traverses the tunnel via relay, gets a response, false-success → switch to direct → tunnel breaks → fallback to relay → repeat every ~25 seconds

Note for users hitting this: Newt 1.11.0 has no flag to override what it advertises as its endpoint, only a -prefer-endpoint flag for the inverse direction (overriding what the server tells Newt). So there is no clean workaround on the Newt side either — the fix has to be in the CLI's holepunch monitor logic.