UDP GSO Mitigation Tests

Relevant source files

The following files were used as context for generating this wiki page:

• README.md
• config.addendum.txt
• build-buggy-linux-7_0.bash
• empty.go
• cmdline.txt

The gokrazy-kernel-buggy-linux-7_0 package provides a specialized Linux 7.0 amd64 kernel environment for Tailscale natlab/vmtest infrastructure. This environment intentionally preserves a UDP Generic Segmentation Offload (GSO) regression to facilitate the testing of software-level mitigation behaviors.

By maintaining this regression, the project ensures that mitigation logic remains functional even when the underlying host kernel is patched or updated. The kernel includes specific drivers for QEMU q35 emulation, including PCI support, virtio block devices, and the Intel igb network driver.

Sources: README.md:1-5, empty.go:5-9

Test Environment Architecture

The test environment relies on QEMU emulation to create a controlled space where the UDP GSO bug is present. The igb network driver acts as the primary interface for exercising the regression.

Hardware Emulation and Drivers

The system targets the QEMU q35 machine type. It enables specific kernel configurations to support this virtualized hardware:

• Intel igb NIC: The diagnostic path uses the emulated Intel igb network interface.
• Virtio Suite: The kernel includes VIRTIO_PCI, VIRTIO_BLK, and VIRTIO_NET for efficient disk and network I/O in the virtual machine.
• Framebuffers: Basic display support is provided via FB_EFI and FB_SIMPLE.

Sources: README.md:11-15, config.addendum.txt:72-84

Network Configuration for Testing

The kernel configuration includes extensive networking features to simulate complex environments:

• UDP Tunneling: Supports NET_UDP_TUNNEL, WIREGUARD, and TUN devices for Tailscale-specific testing.
• Traffic Shaping: NET_SCH_TBF enables Token Bucket Filter for traffic control tests.
• Diagnostics: INET_DIAG and NETLINK_DIAG allow inspection of socket states via tools like ss.

Sources: config.addendum.txt:60-70, config.addendum.txt:6-8

Build and Deployment Logic

The kernel is built from a standard Linux 7.0 source tree modified by a configuration addendum.

Build Process Flow

The build-buggy-linux-7_0.bash script automates the retrieval, configuration, and compilation of the kernel.

The diagram shows the sequential steps required to generate the bootable kernel image from upstream sources.
Sources: build-buggy-linux-7_0.bash:4-22

Boot Configuration

The kernel uses a specific command line defined in cmdline.txt to initialize the gokrazy environment.

Parameter	Value	Description
root	/dev/sda2	Specifies the second partition of the first SCSI disk as root.
ro	N/A	Mounts the root filesystem as read-only.
init	/gokrazy/init	Sets the custom gokrazy init process.
panic	10	Reboots the system 10 seconds after a kernel panic.
oops	panic	Forces a panic on kernel oops.

Sources: cmdline.txt:1

UDP GSO Regression Diagnostics

The primary purpose of this kernel is to trigger and verify UDP GSO mitigation. The vmtest diagnostic suite performs specific checks on the network interface before initiating tests.

Interface Requirements

For mitigation tests to execute, the guest igb interface must report specific offloading capabilities.

The sequence diagram illustrates the requirement check for GSO-related flags before the test suite starts.
Sources: README.md:15-18

Critical Kernel Flags

The following flags in config.addendum.txt are essential for the buggy diagnostic path and general test functionality:

Config Option	Status	Purpose
CONFIG_IGB	y	Enables the Intel igb driver for the buggy path.
CONFIG_NF_TABLES	y	Enables nftables for network filtering tests.
CONFIG_NET_UDP_TUNNEL	y	Required for WireGuard and UDP encapsulation tests.
CONFIG_BPF_SYSCALL	y	Supports modern network plumbing and container-style tests.
CONFIG_IKCONFIG_PROC	y	Exposes kernel config at /proc/config.gz for runtime verification.

Sources: config.addendum.txt:23, config.addendum.txt:56, config.addendum.txt:62, config.addendum.txt:93, config.addendum.txt:87

Implementation Details

The project defines the kernel as a gokrazy KernelPackage via a Go module.

// Package kernel exists so gokrazy can select this module as a KernelPackage.
//
// This module packages a Linux 7.0 vmlinuz that contains the UDP GSO bug from
// tailscale/tailscale#19777 for natlab/vmtest.
package kernel

Sources: empty.go:1-8

To use this kernel in a Tailscale environment, you reference the module path github.com/tailscale/gokrazy-kernel-buggy-linux-7_0. For local development, a go.mod replace directive points to the local directory.

Sources: README.md:20-28

This kernel ensures that the Tailscale client continues to correctly identify and mitigate UDP GSO issues by providing a consistent, reproducible "broken" environment for automated testing.