Gokrazy Kernel Package Architecture
Relevant source files
The following files were used as context for generating this wiki page:
The Gokrazy Kernel Package provides a specific Linux 7.0 amd64 kernel image designed for the Tailscale natlab/vmtest environment. This package intentionally retains a known UDP Generic Segmentation Offload (GSO) regression to facilitate the testing of mitigation behaviors in Tailscale software.
Sources: README.md:1-6, empty.go:5-7
Build System and Pipeline
The build process automates the retrieval, configuration, and compilation of the Linux 7.0 kernel. It produces a vmlinuz binary compatible with Gokrazy's deployment model.
Build Workflow
The architecture utilizes a bash script to coordinate the build steps:
- Download: Fetches the Linux 7.0 source tarball from the official kernel repository.
- Unpack: Extracts the source into a local directory.
- Configure: Combines the default kernel configuration (
defconfig) with project-specific overrides found inconfig.addendum.txt. - Compile: Executes
make bzImageto generate the compressed kernel image. - Export: Copies the resulting
bzImageto the root directory asvmlinuz.
The diagram shows the sequential steps taken by the build script to transform raw kernel source into a Gokrazy-compatible binary.
Sources: build-buggy-linux-7_0.bash:4-22
Kernel Configuration and Features
The kernel configuration is tailored for virtualized testing environments, specifically QEMU q35. It includes drivers for network hardware and virtualization protocols.
Key Subsystems
The configuration explicitly enables several critical subsystems required for the vmtest image:
| Subsystem | Configuration Key | Purpose |
|---|---|---|
| Networking | CONFIG_IGB | Intel network driver used for UDP GSO diagnostic paths. |
| Virtualization | CONFIG_VIRTIO_PCI | Support for QEMU virtio devices (block, net, rng). |
| Filesystem | CONFIG_SQUASHFS | Support for the Gokrazy root file system. |
| Tunneling | CONFIG_WIREGUARD | Native WireGuard support for Tailscale testing. |
| Diagnostics | CONFIG_IKCONFIG_PROC | Enables /proc/config.gz for runtime configuration audits. |
Sources: config.addendum.txt:10-13, config.addendum.txt:58-66, config.addendum.txt:72-74, README.md:12-16
UDP GSO Regression Path
The package targets a specific regression (tailscale/tailscale#19777). To exercise this, the kernel must advertise specific features via the igb driver:
tx-udp-segmentationtx-gso-partial
Sources: README.md:3-5, README.md:14-16, config.addendum.txt:70-71
Boot Configuration
The kernel uses a specific command line to define its behavior during the boot process within the Gokrazy environment.
Command Line Arguments
The cmdline.txt file defines the following parameters:
root=/dev/sda2: Specifies the second partition of the first SCSI disk as the root device.ro: Mounts the root filesystem as read-only.init=/gokrazy/init: Points to the custom Gokrazy init system.panic=10: Reboots the system 10 seconds after a kernel panic.oops=panic: Forces a panic (and subsequent reboot) on kernel "oops" conditions.
Sources: cmdline.txt:1
Go Module Integration
The repository is structured as a Go module, allowing it to be imported as a KernelPackage in Gokrazy configurations.
Package Structure
- empty.go: This file serves as the Go package entry point. It contains no functional code but allows the Go toolchain to recognize the directory as a valid module named
kernel. - Module Path: The package is referenced as
github.com/tailscale/gokrazy-kernel-buggy-linux-7_0.
The diagram illustrates how the Go module structure allows Gokrazy projects to consume the kernel binary through standard Go dependency management.
Sources: empty.go:1-7, README.md:18-20
Conclusion
The Gokrazy Kernel Package Architecture provides a reproducible, specialized kernel environment for network testing. By bundling a specific Linux 7.0 version with a tailored configuration addendum, it ensures that Tailscale's diagnostic tools can reliably trigger and test mitigations for UDP GSO regressions in a virtualized QEMU environment.
Sources: README.md:3-6, config.addendum.txt:70-75