TX-UDP-Segmentation & GSO-Partial
Relevant source files
The following files were used as context for generating this wiki page:TX-UDP-Segmentation and GSO-Partial represent specific network offloading features within the Linux kernel that are the focus of this diagnostic kernel package. This repository provides a Linux 7.0 amd64 kernel for Tailscale's natlab/vmtest environment, specifically designed to preserve a UDP Generic Segmentation Offload (GSO) regression identified in tailscale/tailscale#19777.
The kernel facilitates the testing of software-based mitigations by exposing these offloading capabilities on emulated hardware. By advertising these flags, the kernel allows diagnostic tools to verify that a system behaves correctly even when the underlying network driver contains known GSO bugs.
Sources: README.md:1-12, empty.go:5-9
Kernel Architecture and Driver Support
The system uses a Linux 7.0 kernel configured to support QEMU q35 environments. It includes specific drivers for network and block device emulation to ensure compatibility with vmtest images.
Network Driver Configuration
The kernel explicitly enables the Intel igb network driver and Virtio networking. The igb driver is the primary target for testing because it advertises the relevant segmentation features.
The diagram above shows the relationship between the Linux kernel, the specific network drivers, and the advertised hardware offloading features.
Sources: README.md:10-15, config.addendum.txt:87-94
Key Kernel Configuration Parameters
The config.addendum.txt file specifies the necessary flags to enable the diagnostic environment and the buggy offloading paths.
| Configuration Flag | Value | Purpose |
|---|---|---|
CONFIG_IGB | y | Enables Intel Gigabit Ethernet support for igb NICs. |
CONFIG_VIRTIO_NET | y | Enables Virtio network device support for QEMU. |
CONFIG_NET_UDP_TUNNEL | y | Supports UDP tunneling, required for WireGuard. |
CONFIG_WIREGUARD | y | Includes WireGuard support for Tailscale testing. |
CONFIG_TUN | y | Enables TUN/TAP device support. |
Sources: config.addendum.txt:81-91, config.addendum.txt:75-78
GSO Regression and Mitigation Testing
The primary purpose of this module is to provide a "buggy" environment. The guest igb interface advertises tx-udp-segmentation and tx-gso-partial to trigger the regression logic during tests.
Diagnostic Flow
The vmtest image performs a check on the interface capabilities before initiating mitigation tests. If the flags are not present, the environment is considered invalid for this specific test case.
This sequence illustrates how the vmtest environment verifies the presence of the buggy flags before proceeding with regression testing.
Sources: README.md:12-15, empty.go:7-9
Build and Deployment Process
The kernel is built using a custom bash script that downloads the upstream Linux 7.0 source and applies specific configuration addendums to ensure the bug remains present.
Build Steps
- Download the Linux 7.0 source tarball.
- Unpack the source tree.
- Copy
config.addendum.txtto the source directory. - Generate the initial configuration using
make defconfig. - Append the addendum to
.configand runmake olddefconfig. - Compile the
bzImage. - Copy the resulting
vmlinuzto the repository root.
Sources: build-buggy-linux-7_0.bash:4-22
Integration with Gokrazy
The package is structured as a Gokrazy KernelPackage. It includes a cmdline.txt file that defines the boot parameters for the guest environment.
root=/dev/sda2 ro init=/gokrazy/init panic=10 oops=panic
Sources: cmdline.txt:1, README.md:17-19, empty.go:5-6
Summary of Subsystems
The kernel includes several subsystems required for both the network bug and the general operation of the natlab environment.
- Networking: Includes
nftables,bridge,veth, andBPFsupport for network plumbing. - Storage: Supports
Squashfsfor the root file system andVirtio Blockfor QEMU storage. - Congestion Control: Defaults to
TCP BBR.
Sources: config.addendum.txt:9-14, config.addendum.txt:28-66, config.addendum.txt:115-117