Commit Graph
17 Commits
Author SHA1 Message Date
Brad Fitzpatrick 0b23989672 kernel/linux/DESIGN.md: document the event-driven kernel data plane
Record how the kernel data plane now runs without polling: config
changes trigger full syncs, magicsock's kernel path hook (with a trust
expiry timer for idle sessions) triggers per-peer endpoint updates, and
the module's peer events drive disco key advertisements and activity
feedback, all applied by one goroutine.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: I8c555a623e8bba7cf7561fe94e4bc9d17fd40003
2026-11-07 05:37:17 +00:00
Brad Fitzpatrick 1b969a6b3a kernel/linux/src: multicast peer events so that userspace needn't poll
tailscaled was dumping the device every second to notice new sessions
(to send its disco key advertisement, as wireguard-go does) and traffic
on direct paths (to keep magicsock heartbeating active sessions).

Instead, multicast TSWG_CMD_PEER_EVENT messages on a new "events"
genetlink group, in the device's network namespace: one when a new
session is established (from wg_timers_session_derived), and TX and RX
activity notices, each rate limited to one per peer every 2 seconds with
a single comparison on the packet path. Messages are only built when
someone is listening.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: I08bdaa23a9f9b01a0bb3a4404296cae5961cde86
2026-11-07 05:37:16 +00:00
Brad Fitzpatrick f7c80e0a32 kernel/linux/DESIGN.md: document TSMP and peer restarts in kernel mode
Record how tailscaled exchanges TSMP and its other generated packets with
peers in kernel mode (raw sockets on the tswg device, and a tstun
outbound inject hook), how it emulates wireguard-go's disco key
advertisement on session establishment, how it clears the kernel session
when a peer restarts, and that wireguard-go must never get peers in
kernel mode. Mark the packet filter and MagicDNS as deliberately
deferred.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: I632c5a75b1c2e1dc74680faaa34bbd799e52fe74
2026-11-07 05:00:05 +00:00
Brad Fitzpatrick c32ba694d1 kernel/linux/src: let userspace clear a peer's session
When tailscaled learns that a peer restarted (its disco key changed), the
peer has lost its WireGuard keys, but the kernel would keep sending with
the dead session until WireGuard's own timers start a new handshake about
15 seconds later.

Add TSWGPEER_A_CLEAR_SESSION, an NLA_FLAG in the nested WGPEER_A_TSWG
attribute, which forgets the peer's keypairs and any handshake in
progress, as wg_pm_notification does for every peer before suspend, and
resets the handshake rate limit, so that the next packet to the peer is
staged and starts a new handshake right away.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: Ia9821a47e6c8114bbabd81d8d5a2be528295e74f
2026-11-07 05:00:03 +00:00
Brad Fitzpatrick fe0c4864e9 kernel/linux/DESIGN.md: document the loopback bridge and tailscaled integration
DERP via 127.0.0.0/8 loopback endpoints turned out to need no kernel
changes; record how the bridge works (including peer relays and the
untrusted-path spray) and how tailscaled now drives tswg on the
tailscale.com bradfitz/tswg branch, with its known gaps, the biggest
being that kernel mode has no packet filter yet.

Also record that Tailscale's wireguard-go is about to start using a
hybrid post-quantum handshake, which tswg doesn't implement, so the
assumption that tswg is wire-compatible with every Tailscale peer no
longer holds, and the options for dealing with that.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: I2447db2494bfd1a572f8ce4d093a42a1949aa3d4
2026-11-07 00:09:41 +00:00
Brad Fitzpatrick 189b463b86 kernel/linux/src: add a per-peer flag to stop roaming
Upstream WireGuard moves a peer's endpoint to the source of each
authenticated packet. In Tailscale, disco picks the path, so that would
fight it: a packet that arrives via DERP would steal the endpoint from a
good direct path.

Add TSWGPEER_F_NO_ROAM, set through TSWGPEER_A_FLAGS nested in a new
WGPEER_A_TSWG attribute (numbered 64, like WGDEVICE_A_TSWG) and reported
in dumps. With it set, the endpoint learned from handshake initiations,
handshake responses and data packets is ignored once the peer has an
endpoint, and only userspace changes it. A peer with no endpoint yet
still gets one from its first authenticated packet, so it stays
reachable if it contacts us before userspace has configured one.

The gate, tswg_peer_may_roam, sits at the two learned-endpoint paths
rather than in wg_socket_set_peer_endpoint, which netlink also uses for
explicit updates. The flag is applied before WGPEER_A_ENDPOINT in the
same request, so pinning and setting an endpoint are one step.

Tested by TestTSWG{Gokrazy,Ubuntu}NoRoam in tailscale.com's natlab
vmtests, which fail as expected with the gate disabled.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: I621a6e86d3947e154c4cfa582aa845bb49d42b2f
2026-11-06 23:07:32 +00:00
Brad Fitzpatrick 7398e67950 kernel/linux/DESIGN.md: make performance the primary goal, with its own TODOs
Performance is why we're doing this, so say so in the Goal section and
add a Performance section: what we inherit from upstream WireGuard (inner
GSO on send, inner GRO via NAPI on receive, parallel crypto), what's
missing (outer UDP GSO on send and outer UDP GRO on receive, the kernel
analogues of what makes wireguard-go fast), why tailscaled shouldn't set
UDP_GRO on the shared socket in kernel mode, and how to measure.

Group the performance work at the top of the TODO list.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: If844d30a81f5f2fe52bc2fbf2b31d7bbbb9359c7
2026-11-06 23:00:12 +00:00
Brad Fitzpatrick 4c916c40ab kernel/linux/src: let userspace share its UDP socket with a tswg device
Tailscale needs disco, STUN and WireGuard to share one UDP 4-tuple, so
that the NAT mappings disco discovers are the ones WireGuard uses. So let
tailscaled create and bind the socket itself and hand its fd to the
device, as L2TP allows for its tunnel sockets.

The new TSWGDEVICE_A_SOCK_FD4 and TSWGDEVICE_A_SOCK_FD6 attributes, nested
in a new WGDEVICE_A_TSWG attribute numbered 64 to stay clear of future
upstream attributes, take the fd of a bound UDP socket (IPV6_V6ONLY for
IPv6). The device hooks the socket's UDP encap_rcv, consumes WireGuard
messages (a first byte of 1 through 4 and three zero bytes), and returns
everything else to the normal UDP path for userspace to read. Userspace
can send its own datagrams on the socket as usual.

The device keeps a reference to the struct sock, not the file, and drops
the socket from its encap_destroy hook when userspace closes it, so the
socket lives exactly as long as userspace's fd. Passing -1 detaches the
socket, restoring it to plain UDP, and the device goes back to creating
its own sockets. User sockets persist across ifdown/ifup, and changing
the listen port while one is attached fails with EBUSY. Dumps report
which families have a user socket in TSWGDEVICE_A_FLAGS.

A global mutex serializes attach and detach, including detach from
encap_destroy, which runs from the user's close() with none of our locks
held.

Tested by TestTSWGGokrazySharedSocket (7.2.8) and
TestTSWGUbuntuSharedSocket (6.8) in tailscale.com's natlab vmtests.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: I2e7a97952ced03df4bc954ba398a49daf9128d41
2026-11-06 22:13:43 +00:00
Brad Fitzpatrick 7fccee622e kernel/linux/DESIGN.md: note that the gokrazy test kernel is bumped by bots
A gokrazy bot bumps github.com/gokrazy/kernel.amd64 to new kernel
releases and a tailscale.com cron bot bumps that go.mod dependency, so
the gokrazy vmtests follow upstream kernels automatically. Record that,
and that a failure after such a bump most likely means kernel API churn
needing a new compat shim.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: I12428a124604edb65a61f101b72c87caed6c9332
2026-11-06 21:59:18 +00:00
Brad Fitzpatrick d3c49a3c40 kernel/linux/DESIGN.md: make gokrazy the primary test guest
Record the decision to test primarily on natlab's gokrazy image, which
boots a recent upstream kernel and has no userspace tools, as in the end
state where tailscaled drives the kernel entirely. Describe how its
module build tree is recreated and how the test agent loads and
configures tswg. Keep Ubuntu 24.04 as a secondary guest for distro and
DKMS-style coverage.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: I89714b58c944be4f373f23471e3aeef11942b1f6
2026-11-06 21:50:15 +00:00
Brad Fitzpatrick 309157b88f kernel/linux/scripts: build tswg.ko for gokrazy kernels
The natlab gokrazy image runs a recent upstream kernel (7.2.8 today) that
gokrazy rebuilds and tailscale.com bumps regularly, which makes it a
better primary test target than a distro kernel: it keeps us honest
against new kernel APIs, and gokrazy has no userspace tools, as in the
end state where tailscaled drives the kernel entirely.

gokrazy kernels are kernel.org releases plus the patches in
_build/series, built with an embedded config and without MODVERSIONS or
module signing. gokrazy-kdir.sh downloads the release, applies the
patches, installs the config pulled out of vmlinuz with the kernel's
extract-ikconfig (vendored), and runs modules_prepare, caching the
result by release and config hash. It takes about 20 seconds the first
time. The only config differences after olddefconfig with the host's gcc
13 (gokrazy uses Debian 12's gcc 12) are toolchain capability bits.

Factor the generic part of build-for-ubuntu.sh into build.sh, which now
copies only sources (not objects from an in-place build in src/), and
sets KBUILD_MODPOST_WARN=1 for trees without a Module.symvers. Add
build-for-gokrazy.sh.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: Id28d9c013bdfaa7cec28aeff846f7f6087e25518
2026-11-06 21:44:29 +00:00
Brad Fitzpatrick d095c5b6ef kernel/linux/DESIGN.md: record compat, Go client and testbed decisions
Document the feature-probe compat framework, that the Go netlink client
and tswgctl live in tailscale.com on the bradfitz/tswg branch, and how
the natlab vmtests build, install and exercise tswg.ko. Update the TODO
list: TestTSWGManualTunnel now passes against Ubuntu 24.04's stock
6.8.0-106-generic kernel.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: Ie279a07e251d1ee81cdc91478f3eec9d0dd46afb
2026-11-06 21:07:52 +00:00
Brad Fitzpatrick 370c6a69ea kernel/linux/scripts: add build-for-ubuntu.sh and vmtest.sh
build-for-ubuntu.sh builds tswg.ko for a given Ubuntu kernel release in a
private copy of src/, so test builds for different guest kernels don't
share object files with each other or with a developer's in-place build.
The Makefile's SRC is now overridable to allow that.

vmtest.sh runs the tswg natlab vmtests, which live in a tailscale.com
checkout (on the bradfitz/tswg branch) because they use its natlab
framework and the Go tswg netlink client there.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: I00eb5cbf8df5a203d6d39d541779060db74da9a1
2026-11-06 21:06:08 +00:00
Brad Fitzpatrick ff6f9e8409 kernel/linux/{src/compat,scripts}: add feature-probe compat layer for 6.8 and 7.0
The fork tracks the newest upstream WireGuard (7.4-rc1), but has to build
on distro kernels. Our first target is the natlab Ubuntu 24.04 guest
(6.8.0-106-generic) and the dev host is on 7.0.

Rather than LINUX_VERSION_CODE checks, which lie on heavily backported
kernels such as RHEL's, scripts/probe.sh compile-tests each
src/compat/probes/HAVE_*.c against the target kernel's build directory
(in parallel, about one second in total) and writes
src/compat/generated/autoconf.h. Kbuild force-includes src/compat/compat.h,
which shims whatever is missing: udp_get_len_short, the struct sock
udp_tunnel APIs, the ipcb_flags xmit arguments, the blake2s_ctx API,
WQ_PERCPU, netif_threaded_enable, rtnl_newlink_params, sockaddr_inet, the
kmalloc_obj family and timer_container_of.

Three spots in device.c can't be shimmed from a header (the lltx bit, the
old rtnl newlink signature, and pernet exit_rtnl) and get small #ifdefs
marked TSWG_COMPAT. device.c also always sets ndo_get_stats64 to
dev_get_tstats64, since older kernels don't fold tstats in
dev_get_stats(). That is equivalent on new kernels.

tswg.ko now builds against both 6.8.0-106-generic and 7.0.0-1009-aws.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: I0ed279318b4f623688d1f178a9b8fbcc0b585219
2026-11-06 21:01:41 +00:00
Brad Fitzpatrick af92b849a7 kernel/linux/src: fork WireGuard as the out-of-tree tswg module
Copy upstream/drivers/net/wireguard into src and rename only the
user-visible identifiers: the module (and thus the rtnl link kind and
device type, which come from KBUILD_MODNAME) is now tswg, and the
genetlink family is "tswg". The uapi header moves to
src/include/uapi/linux/tswg.h so it can't collide with the kernel's.
Internal wg_ symbols keep their names to keep upstream merges easy; they
aren't exported, so tswg.ko can coexist with wireguard.ko.

Add an out-of-tree Kbuild and top-level Makefile, plus
scripts/ubuntu-headers.sh, which fetches and unpacks an Ubuntu kernel's
headers so we can build for the natlab Ubuntu guest without installing
anything.

This still only builds against 7.4-era kernels; compat shims follow.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: Ia36ef82a53efbbcdb301ed069785162372efda55
2026-11-06 20:55:25 +00:00
Brad Fitzpatrick 24131ef7cd kernel/linux/DESIGN.md: add initial design and TODO list
Record the decisions made so far: an out-of-tree C fork of in-tree
WireGuard (no Rust, no upstreaming), a shared UDP socket passed in from
tailscaled, explicit endpoints with auto-roaming disabled, DERP via
127.0.0.0/8 loopback endpoints, and userspace spray. Also describe the
natlab vmtest testbed and the TODO list.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: Ie18d356974a0a0d8fce19674b590861144be8cea
2026-11-06 20:53:38 +00:00
Brad Fitzpatrick e6b80dad42 kernel/linux: add the GPL-2.0 license for the tswg kernel module
The tswg kernel module, under kernel/linux, is derived from Linux's WireGuard,
and so is GPL-2.0, unlike the rest of this repository.

Updates #426

Signed-off-by: Brad Fitzpatrick <[email protected]>
Change-Id: I8cab6152232f771364a06d79ecd8b406f3ef01dc
2026-11-06 20:52:49 +00:00