The UDP GSO Regression
Relevant source files
The following files were used as context for generating this wiki page:
The gokrazy-kernel-buggy-linux-7_0 package provides a Linux 7.0 amd64 kernel specifically for Tailscale natlab/vmtest environments. It maintains a known UDP Generic Segmentation Offload (GSO) regression from tailscale/tailscale#19777 to allow software to test mitigation strategies against buggy host kernels.
The kernel includes specific drivers for QEMU q35 environments, including virtio and Intel igb network drivers. It functions as a KernelPackage within the gokrazy ecosystem, allowing developers to simulate network hardware failures in a controlled virtual environment.
Sources: README.md:1-12, empty.go:6-9
Kernel Build Architecture
The build system automates the retrieval and compilation of the Linux 7.0 kernel source. It merges a standard default configuration with a specialized addendum to ensure the presence of the UDP GSO bug and necessary diagnostic drivers.
Build Pipeline
The build-buggy-linux-7_0.bash script executes the following workflow:
- Downloads the Linux 7.0 source tarball from the official kernel archives.
- Unpacks the source into a local directory.
- Applies
defconfigto establish base settings. - Appends the
config.addendum.txtto the.configfile. - Compiles the
bzImageusing all available CPU cores. - Exports the resulting binary as
vmlinuzto the repository root.
The diagram shows the sequential steps from source acquisition to the final kernel image generation.
Sources: build-buggy-linux-7_0.bash:4-21
Network Interface Configuration
The regression specifically targets the interaction between the kernel and network interface hardware. The configuration enables the Intel igb driver, which serves as the primary diagnostic path for observing the UDP GSO bug.
Diagnostic Feature Detection
For mitigation tests to proceed, the vmtest environment verifies that the igb interface advertises specific offloading capabilities despite the underlying regression.
| Feature | Configuration Required | Description |
|---|---|---|
tx-udp-segmentation | CONFIG_IGB=y | UDP segmentation offloading to hardware |
tx-gso-partial | CONFIG_IGB=y | Partial generic segmentation offloading |
virtio-net | CONFIG_VIRTIO_NET=y | Support for QEMU default networking |
Sources: README.md:13-17, config.addendum.txt:77-84
Network Stack Modules
The kernel includes extensive networking support to facilitate complex testing scenarios:
- WireGuard and TUN: Enabled via
CONFIG_WIREGUARD=yandCONFIG_TUN=yfor encrypted tunneling tests. - Traffic Shaping: Uses
CONFIG_NET_SCH_TBF=yfor token bucket filter shaping viatc. - Netfilter/nftables: Provides a full suite of NAT and packet filtering options, though specific helper modules like
CONFIG_NF_CONNTRACK_FTPare disabled to prevent NAT slipstreaming.
Sources: config.addendum.txt:1-103
System Boot and Execution
The kernel utilizes a specific command line to define its initialization behavior and root file system handling.
Boot Parameters
The cmdline.txt file defines how the kernel initializes:
root=/dev/sda2 ro init=/gokrazy/init panic=10 oops=panic
- root: Sets the second partition of the first SCSI disk as the root device.
- ro: Mounts the root file system as read-only.
- init: Points to the gokrazy init system.
- panic/oops: Configures the system to reboot 10 seconds after a kernel panic or immediately on an "oops".
Sources: cmdline.txt:1
Execution Environment Flow
The kernel is designed to run within a QEMU virtual machine, typically using the q35 machine type.
The sequence diagram illustrates the handoff from the virtual hardware to the kernel and the subsequent diagnostic checks performed by the testing suite.
Sources: README.md:10-15, cmdline.txt:1
Kernel Configuration Summary
The config.addendum.txt contains critical overrides for the standard kernel configuration to support the gokrazy environment and the bug reproduction.
| Category | Key Configurations | Purpose |
|---|---|---|
| File Systems | CONFIG_SQUASHFS=y, CONFIG_OVERLAY_FS=y | Supports gokrazy root and container-style networking |
| Diagnostics | CONFIG_DYNAMIC_DEBUG=y, CONFIG_IKCONFIG_PROC=y | Enables runtime debugging and config visibility |
| Performance | CONFIG_TCP_CONG_BBR=y, CONFIG_DEFAULT_BBR=y | Sets BBR as the default congestion control |
| Virtualization | CONFIG_VIRTIO_PCI=y, CONFIG_VIRTIO_BLK=y | Enables storage and bus support in QEMU |
Sources: config.addendum.txt:10-25, config.addendum.txt:62-75, config.addendum.txt:115-117
Conclusion
The gokrazy-kernel-buggy-linux-7_0 project provides a specialized environment for network reliability testing. By intentionally including the Linux 7.0 UDP GSO regression and necessary drivers for Intel and VirtIO hardware, it allows the Tailscale natlab suite to validate that networking software correctly identifies and mitigates known kernel-level packet segmentation bugs.
Sources: README.md:1-5, empty.go:6-9