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 live · 59,500 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.

What this site will grow into

Four tracks, publishing in deliberate order. Nothing here links until it exists, and nothing ships as a stub.

  1. Curriculum. The internals, live now above: orientation, WireGuard, the control plane, NAT traversal, troubleshooting. Identity, ACLs, DNS, routing, Serve and Funnel, the platform matrix, enterprise operations, and a codebase tour follow in numbered order.
  2. Feature encyclopedia. One reference page per feature and a complete CLI tour, for the reader with 30 seconds and a specific question.
  3. Fieldcraft and drills. Evidence collection, reproduction construction, engineering handoff packages, and written case study drills: symptom, evidence, hypothesis tree, root cause.
  4. Code lab. Guided reads of the open source Go codebase, pprof exercises, and annotated packet captures.

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.