Writing Tests for vmtest
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 for the Tailscale natlab/vmtest environment. It intentionally includes a UDP GSO regression. This allows developers to test software mitigation behavior even when host kernels are fixed.
Sources: README.md:1-5, empty.go:6-8
Kernel Architecture and Build Flow
The kernel build process combines the standard Linux 7.0 source with specific configuration addendums. This ensures the resulting vmlinuz binary contains the necessary drivers for virtualized testing environments.
Build Sequence
The build script automates the retrieval and compilation of the kernel.
The build script utilizes make olddefconfig to reconcile the addendum with the base configuration.
Sources: build-buggy-linux-7_0.bash:4-24
Testing Hardware and Drivers
The kernel supports the QEMU q35 machine type. It includes specific drivers required by the vmtest image.
Required Drivers and Features
| Category | Component | Configuration |
|---|---|---|
| Network | Intel igb | CONFIG_IGB=y |
| Network | Virtio Net | CONFIG_VIRTIO_NET=y |
| Storage | Virtio Block | CONFIG_VIRTIO_BLK=y |
| Bus | PCI / MSI | CONFIG_PCI=y, CONFIG_PCI_MSI=y |
| Filesystem | Squashfs | CONFIG_SQUASHFS=y |
Sources: README.md:13-17, config.addendum.txt:11-14, config.addendum.txt:69-78, config.addendum.txt:80-85
UDP GSO Mitigation Testing
The diagnostic path for vmtest specifically checks for hardware features on the igb interface. The guest must advertise tx-udp-segmentation and tx-gso-partial. If these features are present, the test environment exercises the regression mitigation logic.
Sources: README.md:17-20
Network Configuration for Tests
The kernel configuration supports advanced networking features required for natlab test cases.
Networking Stack Capabilities
- WireGuard and TUN: Supports VPN and tunneling tests via
CONFIG_WIREGUARDandCONFIG_TUN. - Nftables: Provides full NAT and filtering capabilities for firewall testing.
- Bridge and Veth: Enables complex network topologies and container-style plumbing.
- BPF: Supports socket filtering and cgroup-based network control.
Sources: config.addendum.txt:26-58, config.addendum.txt:63-67, config.addendum.txt:87-88, config.addendum.txt:91-95
Boot Parameters
The cmdline.txt file defines the default kernel execution environment.
root=/dev/sda2 ro init=/gokrazy/init panic=10 oops=panic
Sources: cmdline.txt:1
Integrating the Kernel Package
You use this module as a KernelPackage within a Tailscale gokrazy project.
Dependency Management
To use the kernel in a local development environment, use a replace directive in your go.mod file:
replace github.com/tailscale/gokrazy-kernel-buggy-linux-7_0 => ../github.com/tailscale/gokrazy-kernel-buggy-linux-7_0
Sources: README.md:22-29
Execution Flow in vmtest
Conclusion
This kernel package enables deterministic testing of UDP GSO regressions by providing a controlled, buggy environment. It includes the necessary drivers and networking stacks to support complex virtualized network simulations within the vmtest framework.