tailscale / wgengine/magicsock / v1.103.0-pre, 2026-09-18

Magicsock Path States

How a Tailscale node decides, per peer and per direction, whether to send over the direct UDP path or through its DERP relay, and how long each decision takes to change.

States and transitions

direct UDP carries traffic
direct and a DERP copy of every packet
DERP carries traffic

Per peer, per direction. The direct path is used alone only while a trust window opened by the last pong is still running. Stale means the window closed but the address is kept: every packet goes both ways until a ping to that address times out. DERP only lasts until any candidate answers a probe. Nothing measures loss or throughput, and DERP replies never take part in choosing the best address. When nothing has been sent for 45 s the heartbeat stops, the state freezes, and the next packet restarts probing. Before v1.98 (May 2026) the timeout edge did not exist: a stale address was kept, with every packet copied to DERP, until a pong on it or a strictly better candidate arrived, and DERP only was reached solely through link changes and send errors.

One outage on the clock

The same 8.5 s outage, beginning 1 s after a successful heartbeat, with traffic flowing throughout, drawn once per behaviour.

v1.98 and later. The heartbeats at 3 s and 6 s are lost. Trust expires at 6.5 s: every packet is now copied to DERP and the other candidates are probed, also without answer. At 8 s the lost 3 s ping times out and the address is cleared, so only DERP carries traffic and the heartbeat has no target. The WiFi returns at 9.5 s, but the LAN address was last pinged at 6 s and the per-candidate limit holds it until 11 s. That probe is answered, the direct path is restored on the next send, and the 3 s heartbeat rhythm resumes at 12 s. A CallMeMaybe from the peer would trigger the probe sooner.

v1.96 and earlier, same outage. Trust expires at 6.5 s exactly as above and packets are copied to DERP, but nothing ever clears the stale address: the 8 s timeout only logs. The heartbeat keeps pinging the LAN address every 3 s, so the 9 s ping is lost inside the outage and the 12 s ping is answered, which refreshes trust on the same address. Direct plus a DERP copy lasts 5.5 s, and DERP never carries traffic alone. Recovery rides the 3 s heartbeat cadence rather than the 5 s discovery limit, which is why this older client recovers at 12 s where the newer one recovers at 11 s.

In both cases, outages shorter than about 3 s never trip the fallback and outages longer than 6 s always do. Both show a relay in tailscale status for the whole stale period, because that column reports only a trusted direct address.

The timers

Constant	Value	What it governs	Source
`trustUDPAddrDuration`	6.5 s	How long a direct address is used alone after its last pong.	`magicsock.go:4014`
`heartbeatInterval`	3 s	Ping cadence to the best address while the session is active.	`magicsock.go:4010`
`pingTimeoutDuration`	5 s	Wait for a pong before a ping counts as lost; a lost ping to a stale best address clears it.	`tsconst/ping.go:11`
`discoPingInterval`	5 s	Minimum gap between discovery probes of the same candidate.	`tsconst/ping.go:15`
`sessionActiveTimeout`	45 s	Outbound silence after which heartbeats stop.	`magicsock.go:3994`
`upgradeUDPDirectInterval`	60 s	How often a trusted but slow path re-probes every candidate looking for a better one.	`magicsock.go:3998`
`goodEnoughLatency`	5 ms	At or under this, the upgrade probes are skipped entirely.	`magicsock.go:4018`
`endpointsFreshEnoughDuration`	27 s	Age at which this node re-STUNs before sending a CallMeMaybe.	`magicsock.go:4023`

All of these are compile-time constants in wgengine/magicsock. No tailscale set or tailscale up flag changes them.

Where each transition lives

Transition	Trigger	Source
trusted -> trusted	A pong arrives for a ping to the best address; trust becomes now plus 6.5 s.	`endpoint.go:2006`
trusted -> stale	The trust window passes with no pong. The send path starts returning both the direct and the DERP address.	`endpoint.go:632`
stale -> DERP only	A ping to the best address times out while the window is closed. The address is cleared.	`endpoint.go:1236`
stale or DERP only -> trusted	A pong arrives from any direct candidate; it becomes the best address.	`endpoint.go:1987`
probing while not trusted	Every outbound packet and every 3 s heartbeat tick runs a discovery round, limited to one probe per candidate per 5 s, and queues a CallMeMaybe over DERP.	`endpoint.go:1101`, `endpoint.go:869`, `endpoint.go:1415`
peer's CallMeMaybe	Its endpoints are added as candidates and all of them are probed at once, ignoring the 5 s limit.	`endpoint.go:2138`
any -> DERP only	A major link change, a rebind, or a listening port change wipes the path state of every peer.	`magicsock.go:3834`, `net/netmon/netmon.go:199`
any -> DERP only	A UDP send to the best address fails with an unreachable-type error.	`endpoint.go:1848`
heartbeat stops	Nothing sent for 45 s. The next packet sent restarts probing on the send path itself.	`endpoint.go:869`, `endpoint.go:1014`

What changed, and when

Mechanism	Landed	First stable release
Disco pings, the trust window, send-to-both while stale, the idle cutoff	2020-07	v0.100
Timer values retuned once: heartbeat 2 s to 3 s, trust 5 s to 6.5 s, idle 2 min to 45 s. Unchanged since.	2022-01	v1.20
Private addresses preferred over public ones, with 1% latency hysteresis, in the candidate scoring	2023-05	v1.44
Silent disco toggle, off unless control enables it	2023-11	v1.54
UDP path lifetime probing after a session goes idle	2024-01	v1.60
Link-local addresses preferred over private ones	2024-03	v1.62
Peer relay servers as a tier between direct and DERP	2025-05	v1.84 to v1.86
Home DERP region kept through short packet loss until two keepalives fail	2025-06	v1.86
Ping timeout clears a stale peer-relay address	2025-06	v1.86
Ping timeout clears a stale direct address too, so traffic goes DERP only; any answering candidate replaces an untrusted best address	2026-04	v1.98
Trust reset when a peer rotates its disco key, forcing a re-probe	2026-08	unreleased, on main

The v1.98 change is the one that alters behaviour on a lossy link. Its commit message gives the reason: without it, a stale direct address that blackholes could be kept forever. Everything else in magicsock during 2026 concerns disco key rotation and advertisement over TSMP, netmap caching, and peer relay details, none of which touch the timers or the direct-versus-DERP decision.

Things the diagram leaves out

Each direction is independent. A can be direct to B while B still relays to A until B's own probe is answered, usually within a round trip.
Silent disco removes the heartbeat edge. Trust is then renewed by any WireGuard packet received from the best address, and the rest of the machine is unchanged. It is a control-plane or debug-only switch.
Peer relay paths are a fourth option that sits between direct and DERP in preference. They are probed with the same pings and expire on the same 6.5 s window, so they flap the same way over a bad link.
An OS-level WiFi drop that changes the interface address is a major link change: every peer resets to DERP only and STUN reruns, then normal discovery brings the LAN path back within a few seconds of the link returning.
tailscale ping probes every candidate immediately, ignoring the 5 s limit, and reports which path answered.
A relay shown for minutes while traffic is flowing is not this cycle. It means no candidate ever answers, which is a UDP reachability problem rather than a transient one.
Mixed-version fleets look the same in tailscale status but behave differently: a v1.96 node in the stale state is still moving most of its traffic over the LAN, while a v1.98 node is genuinely on DERP until a probe is answered.