mirrors/tailscale
1
0
Fork 0
mirror of https://github.com/tailscale/tailscale.git synced 2026-05-05 20:26:47 +02:00
Code Issues Packages Projects Releases Wiki Activity
tailscale/cmd/derper
History
James Tucker 7448f6fc9a net/{connreject,tstun},feature/connreject,wgengine,client/local: add connection-rejection diagnostics 
Adds an opt-in, in-memory aggregator of recent connection-rejection
events (TSMP rejects received from peers, outbound TSMP rejects we emit
on ACL-blocked inbound flows, and pendopen timeouts) keyed by
(direction, proto, peer-address, reason). The aggregated data is exposed
over a new debug-rejects LocalAPI endpoint and a GET /debug/rejects c2n
endpoint, intended for future GUI/CLI consumption when diagnosing why a
connection failed.

Architecture:
 - net/connreject holds the data types and a per-LocalBackend
   Aggregator (LRU-bounded, default 256 entries on desktop / 32 on
   mobile, per direction).
 - feature/connreject is a self-registering ipnext.Extension that owns
   one Aggregator per LocalBackend, installs note callbacks on the
   tundev and engine, subscribes to OnSelfChange to flip the runtime
   gate, and serves the LocalAPI/c2n endpoints.
 - wgengine.Engine and *tstun.Wrapper each gain a SetConnRejectNote
   setter; data-plane sites use a single atomic.Pointer load + nil
   check, so the cost when no consumer is installed is one MOV.

Gating:
 - Compile-time: ts_omit_connreject build tag (standard
   feature/buildfeatures + condregister plumbing). Trims ~41 KB.
 - Runtime: tailcfg.NodeAttrConnReject node attribute, off by default
   at the control plane. May be removed once the feature is enabled
   by default.

Updates CapabilityVersion to 139 (clients understand NodeAttrConnReject
and can serve GET /debug/rejects).

Adds Proto/Src/Dst accessors on flowtrack.Tuple (used by pendopen to
construct events without exposing the tuple's internals to the
aggregator).

Updates #1094
Updates #14802

Signed-off-by: James Tucker <james@tailscale.com>
2026-05-05 17:03:44 +00:00
..
ace.go
all: remove AUTHORS file and references to it
2026-01-23 15:49:45 -08:00
bootstrap_dns_test.go
cmd/derper: fix TestLookupMetric to pass when run alone
2026-04-13 17:20:43 -07:00
bootstrap_dns.go
all: remove AUTHORS file and references to it
2026-01-23 15:49:45 -08:00
cert_test.go
all: remove AUTHORS file and references to it
2026-01-23 15:49:45 -08:00
cert.go
all: remove AUTHORS file and references to it
2026-01-23 15:49:45 -08:00
depaware.txt
net/{connreject,tstun},feature/connreject,wgengine,client/local: add connection-rejection diagnostics
2026-05-05 17:03:44 +00:00
derper_test.go
cmd/vet: add subtestnames analyzer; fix all existing violations
2026-04-05 15:52:51 -07:00
derper.go
cmd/derper,derp: add metrics for rate limit hits (#19560)
2026-04-29 10:29:09 -07:00
mesh.go
all: use Go 1.26 things, run most gofix modernizers
2026-03-06 13:32:03 -08:00
README.md
cmd/derper: clarify that derper and tailscaled need to be in sync
2024-06-26 19:46:42 -07:00
websocket.go
all: remove AUTHORS file and references to it
2026-01-23 15:49:45 -08:00

README.md

DERP

This is the code for the Tailscale DERP server.

In general, you should not need to or want to run this code. The overwhelming majority of Tailscale users (both individuals and companies) do not.

In the happy path, Tailscale establishes direct connections between peers and data plane traffic flows directly between them, without using DERP for more than acting as a low bandwidth side channel to bootstrap the NAT traversal. If you find yourself wanting DERP for more bandwidth, the real problem is usually the network configuration of your Tailscale node(s), making sure that Tailscale can get direction connections via some mechanism.

If you've decided or been advised to run your own derper, then read on.

Caveats

  • Node sharing and other cross-Tailnet features don't work when using custom DERP servers.

  • DERP servers only see encrypted WireGuard packets and thus are not useful for network-level debugging.

  • The Tailscale control plane does certain geo-level steering features and optimizations that are not available when using custom DERP servers.

Guide to running cmd/derper

  • You must build and update the cmd/derper binary yourself. There are no packages. Use go install tailscale.com/cmd/derper@latest with the latest version of Go. You should update this binary approximately as regularly as you update Tailscale nodes. If using --verify-clients, the derper binary and tailscaled binary on the machine must be built from the same git revision. (It might work otherwise, but they're developed and only tested together.)

  • The DERP protocol does a protocol switch inside TLS from HTTP to a custom bidirectional binary protocol. It is thus incompatible with many HTTP proxies. Do not put derper behind another HTTP proxy.

  • The tailscaled client does its own selection of the fastest/nearest DERP server based on latency measurements. Do not put derper behind a global load balancer.

  • DERP servers should ideally have both a static IPv4 and static IPv6 address. Both of those should be listed in the DERP map so the client doesn't need to rely on its DNS which might be broken and dependent on DERP to get back up.

  • A DERP server should not share an IP address with any other DERP server.

  • Avoid having multiple DERP nodes in a region. If you must, they all need to be meshed with each other and monitored. Having two one-node "regions" in the same datacenter is usually easier and more reliable than meshing, at the cost of more required connections from clients in some cases. If your clients aren't mobile (battery constrained), one node regions are definitely preferred. If you really need multiple nodes in a region for HA reasons, two is sufficient.

  • Monitor your DERP servers with cmd/derpprobe.

  • If using --verify-clients, a tailscaled must be running alongside the derper, and all clients must be visible to the derper tailscaled in the ACL.

  • If using --verify-clients, a tailscaled must also be running alongside your derpprobe, and derpprobe needs to use --derp-map=local.

  • The firewall on the derper should permit TCP ports 80 and 443 and UDP port 3478.

  • Only LetsEncrypt certs are rotated automatically. Other cert updates require a restart.

  • Don't use a firewall in front of derper that suppresses RSTs upon receiving traffic to a dead or unknown connection.

  • Don't rate-limit UDP STUN packets.

  • Don't rate-limit outbound TCP traffic (only inbound).

Diagnostics

This is not a complete guide on DERP diagnostics.

Running your own DERP services requires exeprtise in multi-layer network and application diagnostics. As the DERP runs multiple protocols at multiple layers and is not a regular HTTP(s) server you will need expertise in correlative analysis to diagnose the most tricky problems. There is no "plain text" or "open" mode of operation for DERP.

  • The debug handler is accessible at URL path /debug/. It is only accessible over localhost or from a Tailscale IP address.

  • Go pprof can be accessed via the debug handler at /debug/pprof/

  • Prometheus compatible metrics can be gathered from the debug handler at /debug/varz.

  • cmd/stunc in the Tailscale repository provides a basic tool for diagnosing issues with STUN.

  • cmd/derpprobe provides a service for monitoring DERP cluster health.

  • tailscale debug derp and tailscale netcheck provide additional client driven diagnostic information for DERP communications.

  • Tailscale logs may provide insight for certain problems, such as if DERPs are unreachable or peers are regularly not reachable in their DERP home regions. There are many possible misconfiguration causes for these problems, but regular log entries are a good first indicator that there is a problem.