Tailscale Field Guide

Unofficial field guide and lab notebook

How Tailscale actually works.

Mechanism first, marketing never. This site explains the mesh from the WireGuard handshake up: the control plane, NAT traversal, DERP, MagicDNS, ACLs, and what every CLI command really tells you. Every factual claim traces to an official source with a checked date, and the lab material is tested on a real tailnet before it is published.

13 modules · 15 drills · 8 guides · 106,900 words · every claim sourced

Tailscale wordmark

The subject of this guide. The Tailscale name and logo belong to Tailscale Inc.; this independent site uses them only to identify the product it documents.

The shape of a tailnet: direct paths first, relay as fallback DERP node-a phone cloud-1 node-b direct

The curriculum

Numbered modules, meant to be read in order. Each one explains its layer three ways (an analogy, the mechanism, the failure modes), shows what the layer looks like on the wire, and ends with scenario questions that have real answers.

00 The shape of Tailscale What Tailscale actually is, a WireGuard mesh data plane coordinated by a centralized control plane, and the mental model every later module builds on. 19 min read 01 WireGuard foundations How WireGuard actually works at the layer Tailscale builds on, and the three problems it deliberately leaves unsolved. 20 min read 02 The control plane How the Tailscale coordination server registers nodes, distributes keys and policy, and what freezes when it goes away. 19 min read 03 NAT traversal, STUN, DERP, and Peer Relays How two Tailscale nodes behind NATs find each other, punch through, relay when they cannot, and upgrade the moment they can. 20 min read 04 Identity and auth How users, devices, and workloads prove who they are in a tailnet, from SSO delegation through auth keys, tags, OAuth clients, and workload identity federation. 23 min read 05 Policy: ACLs and grants How the tailnet policy file works, from HuJSON and legacy ACLs through grants, autogroups, tags, SSH rules, posture, and the tests that gate every save. 20 min read 06 MagicDNS and split DNS How Tailscale's Quad100 resolver, MagicDNS names, per-platform OS resolver rewiring, split DNS, and exit node DNS behavior actually work, and how they fail. 20 min read 07 Routing How a tailnet reaches networks and destinations that cannot run Tailscale, through subnet routers, exit nodes, site-to-site links, 4via6, and app connectors. 19 min read 08 Exposing services How to publish services on and beyond your tailnet with serve, Funnel, HTTPS certificates, Tailscale Services, and tsnet, and how to choose between them. 19 min read 09 The platform matrix Where Tailscale runs, what is identical on every platform, and what each operating system decides differently. 19 min read 10 Enterprise operations How to run a tailnet at organization scale, covering admin surfaces, audit and flow logging, SCIM, roles, device approval, Tailnet Lock, GitOps for the policy file, and the Aperture AI gateway. 19 min read 11 Troubleshooting and observability How to read tailscale status, ping, netcheck, bugreport, client logs, and metrics, and a symptom-driven playbook for the six ways a tailnet visibly breaks. 20 min read 12 The codebase A guided tour of the tailscale/tailscale repository for engineers who want to read the source, follow a packet or a login through the code, and build it themselves. 22 min read

Full curriculum index, including what is still in the workshop.

The tracks

Four ways into the same machine. Everything linked below is live; the one remaining track is described honestly as unbuilt.

  1. Curriculum. Thirteen numbered modules from orientation through WireGuard, the control plane, NAT traversal, identity, policy, DNS, routing, services, platforms, operations, troubleshooting, and a tour of the codebase.
  2. Drills. Written escalation case studies worked end to end: the ticket, the evidence, a hypothesis tree, an investigation that rules things out, the root cause, and the engineering handoff package.
  3. Fieldcraft. The craft itself: evidence collection, reproduction construction, the handoff package template, and live incident work.
  4. Code lab. The deepest evidence tier: reading the open source Go codebase, pprof profiles, and packet captures as investigation tools.
Four tracks, four different questions curriculum How does it work? 13 modules drills Why is this one broken? 15 cases fieldcraft How do I prove it, and hand it over? 4 guides code lab What does the source actually say? 4 guides narrower means deeper, not smaller

Still in the workshop, described but not yet built: the feature encyclopedia, one reference page per feature plus a complete CLI tour. It will appear in the navigation only when it is real.

How to read this site

Modules use five recurring callouts. They mark the paragraphs worth slowing down for:

Claims carry receipts. The sources ledger lists every reference with the date it was last checked against the official documentation.