Linux 7.0 Kernel Emulation
Relevant source files
The following files were used as context for generating this wiki page:
The Linux 7.0 Kernel Emulation package provides a specialized amd64 kernel for the gokrazy ecosystem, specifically designed for Tailscale natlab/vmtest environments. It intentionally preserves a specific UDP Generic Segmentation Offload (GSO) regression to allow testing of mitigation behaviors in guest environments even when the host kernel is corrected.
Sources: README.md:1-5, empty.go:6-8
Kernel Build Pipeline
The kernel build process utilizes a bash script to automate the retrieval, configuration, and compilation of the Linux 7.0 source code. The script ensures the environment is consistent for reproducing the specific buggy behavior required for testing.
Build Stages
- Source Acquisition: The script downloads the
linux-7.0.tar.xztarball from the official kernel repository. - Configuration Initialization: It generates a base configuration using
make defconfig. - Configuration Modification: It appends specialized requirements from
config.addendum.txtto the.configfile. - Compilation: The script compiles the kernel using the
bzImagetarget, utilizing all available CPU cores. - Artifact Deployment: It copies the resulting
bzImageto the project root asvmlinuz.
Sources: build-buggy-linux-7_0.bash:4-20, README.md:28-32
The following flowchart illustrates the automated build process:
The diagram shows the sequence of operations from downloading source code to generating the final bootable kernel image.
Sources: build-buggy-linux-7_0.bash:4-21
Kernel Configuration and Drivers
The kernel includes specific configurations to support gokrazy requirements, containerization tools, and virtualization drivers.
Feature Support Table
| Category | Components | Key Configuration Flags |
|---|---|---|
| Networking | IPv6, nftables, WireGuard, TUN | CONFIG_IPV6, CONFIG_NF_TABLES, CONFIG_WIREGUARD, CONFIG_TUN |
| Storage | Squashfs | CONFIG_SQUASHFS, CONFIG_SQUASHFS_ZLIB |
| Virtualization | Virtio (Block, Net, PCI) | CONFIG_VIRTIO_BLK, CONFIG_VIRTIO_NET, CONFIG_VIRTIO_PCI |
| Diagnostics | Dynamic Debug, Netlink Diag | CONFIG_DYNAMIC_DEBUG, CONFIG_NETLINK_DIAG |
| Network Testing | Intel igb, Bridge, Veth | CONFIG_IGB, CONFIG_BRIDGE, CONFIG_VETH |
Sources: config.addendum.txt:1-120
Bug Reproduction Logic
The kernel configuration enables the Intel igb network driver. In vmtest environments, the diagnostic checks that the guest igb interface advertises tx-udp-segmentation and tx-gso-partial. This advertisement is necessary to trigger and test the UDP GSO regression mitigation.
Sources: README.md:12-16, config.addendum.txt:76
Boot Configuration
The kernel uses a specific command line for initialization and error handling during the boot process.
Boot Parameters
- Root Device: Sets
/dev/sda2as the root filesystem. - Init System: Directs execution to
/gokrazy/init. - Error Handling: Configures the system to panic after 10 seconds on error and treats kernel "oops" as panics.
Sources: cmdline.txt:1
The relationship between the kernel package and the testing infrastructure is shown below:
The diagram represents how the kernel image is integrated into the Tailscale development workflow and executed within a QEMU virtual machine to test network drivers.
Sources: README.md:7-21
Implementation for gokrazy Integration
The repository includes a Go package structure that allows the gokrazy build system to recognize the module as a KernelPackage.
// 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 define the module path: github.com/tailscale/gokrazy-kernel-buggy-linux-7_0. Local development is supported through go.mod replacement directives.
Sources: README.md:18-26
The Linux 7.0 Kernel Emulation package serves as a critical testing tool by providing a controlled, buggy environment. By packaging the kernel source with specific addendum configurations and gokrazy-compatible boot parameters, the project ensures that network regressions remain detectable and their mitigations verifiable.