Tailscale Field Guide

Source level

Code lab: read the source, the profile, the packet.

The deepest evidence tier. When the docs run out, the open source codebase, a pprof profile, or a packet capture answers the question. These guides teach each one as an investigation tool for an engineer who operates systems, not someone who writes Go all day.

From a field observation down to the mechanism log line seen in the field grep the repo find its source owning package magicsock, ipnlocal mechanism now you KNOW profiles and packet captures follow the same descent: observation, tool, mechanism
Picking the right instrument for the question read the source Why does it behave this way at all? path selection, state machines, defaults take a profile Where is the CPU or the memory going? high load, growth over time, stuck goroutines capture packets What actually left and arrived? handshakes, probes, relay versus direct using the wrong instrument produces confident nonsense, so pick by the question
  1. 01 Reading Go for investigation How to navigate the tailscale/tailscale codebase to answer field questions, from grepping a log line to its source to building tailscaled with your own print statement.
  2. 02 A guided read of magicsock A file by file tour of wgengine/magicsock, the packet conn that hides path selection from WireGuard, with the disco, DERP, and peer relay machinery traced through current source.
  3. 03 The pprof field kit How to pull CPU, heap, and goroutine profiles out of a running tailscaled and read them like an engineer instead of guessing at high CPU or memory reports.
  4. 04 The packet capture field kit How to capture, filter, and read Tailscale traffic on the wire, from STUN probes and WireGuard handshakes to DERP fallback and path migration.