Tailscale natlab/vmtest Integration

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

Tailscale natlab/vmtest Integration provides a specialized gokrazy kernel package for automated testing environments. It packages a Linux 7.0 amd64 kernel that intentionally preserves a UDP GSO regression (specifically from tailscale/tailscale#19777). This environment allows tests to verify that Tailscale software mitigations function correctly even when the underlying host kernel contains known bugs.

Sources: README.md:1-6, empty.go:6-8

System Architecture

The integration functions as a gokrazy KernelPackage. It generates a bootable vmlinuz image compatible with QEMU q35 virtual machines. The architecture relies on specific driver support for virtualization and network diagnostics, primarily utilizing the Intel igb network driver to trigger and observe buggy GSO behavior.

This diagram illustrates the relationship between the Tailscale source code, this kernel package, and the diagnostic test environment.

Sources: README.md:14-23, empty.go:4-8

Kernel Build Process

The project includes a bash script to automate the retrieval and compilation of the Linux 7.0 kernel. The build process integrates custom configuration parameters defined in config.addendum.txt into the standard Linux defconfig.

Build Steps

1. The script downloads the Linux 7.0 source tarball from the official kernel CDN.
2. It extracts the source into a local directory.
3. It copies config.addendum.txt into the kernel source tree.
4. It generates the initial .config via make defconfig.
5. It appends the addendum parameters to the .config.
6. It runs make olddefconfig to resolve dependencies.
7. It compiles the bzImage using all available CPU cores.
8. It moves the resulting binary to vmlinuz.

The build workflow ensures the custom "buggy" configurations are applied to a fresh Linux 7.0 source tree.

Sources: build-buggy-linux-7_0.bash:1-24, README.md:28-32

Configuration Parameters

The kernel configuration includes specific modules for networking, virtualization, and diagnostic capabilities. It explicitly disables certain nftables helper modules to prevent NAT slipstreaming attacks while enabling advanced networking features like TCP BBR and WireGuard support.

Key Configuration Groups

Category	Essential Config Options	Purpose
Network Hardware	CONFIG_IGB, CONFIG_VIRTIO_NET	Supports Intel igb and Virtio NICs for testing.
Virtualization	CONFIG_VIRTIO_PCI, CONFIG_VIRTIO_BLK	Enables QEMU guest support.
Networking	CONFIG_WIREGUARD, CONFIG_TUN, CONFIG_IPV6	Core requirements for Tailscale operation.
Firewall/NAT	CONFIG_NF_TABLES, CONFIG_NF_NAT_IPV4	Provides packet filtering and NAT capabilities.
Diagnostics	CONFIG_DYNAMIC_DEBUG, CONFIG_NETLINK_DIAG	Enables detailed debugging of network paths.

Sources: config.addendum.txt:1-118

Diagnostic Path Logic

The vmtest diagnostic path relies on the Intel igb driver to simulate hardware-level networking features. The guest environment verifies specific hardware offload advertisements before initiating mitigation tests.

The diagnostic path confirms that the virtualized Intel igb interface is correctly advertising the features needed to exercise the GSO bug.

Sources: README.md:18-21, config.addendum.txt:81-87

Integration Usage

To use this kernel in a Tailscale environment, the module is defined as the KernelPackage. If local development is required, a go.mod replace directive points to the local directory.

// From README.md and empty.go
// Package kernel allows gokrazy to select this as a KernelPackage
package kernel

Sources: empty.go:1-8, README.md:23-27

Boot Configuration

The kernel uses a specific command line to define the root filesystem location and initialization behavior. It points to /dev/sda2 as the root device and designates /gokrazy/init as the init process.

root=/dev/sda2 ro init=/gokrazy/init panic=10 oops=panic

Sources: cmdline.txt:1

Summary

The Tailscale natlab/vmtest integration provides a controlled "buggy" kernel environment. By maintaining the UDP GSO regression in a Linux 7.0 image, Tailscale ensures its software remains resilient against specific kernel-level regressions. The system leverages gokrazy for deployment, QEMU for execution, and a specific Intel igb driver configuration for diagnostic verification.