Go Module Structure (empty.go)

Relevant source files

The following files were used as context for generating this wiki page:

• empty.go
• README.md
• build-buggy-linux-7_0.bash
• config.addendum.txt
• cmdline.txt

The gokrazy-kernel-buggy-linux-7_0 module provides a specialized Linux 7.0 kernel image for the gokrazy appliance ecosystem. It functions primarily as a delivery vehicle for a kernel binary (vmlinuz) specifically configured to retain a UDP Generic Segmentation Offload (GSO) regression. This regression allows Tailscale's natlab/vmtest environment to verify mitigation behaviors even if the host machine uses a fixed kernel.

The module enables gokrazy to integrate the kernel by defining a Go package that identifies the repository as a KernelPackage. The project includes build automation to recreate the kernel from source using specific hardware and networking configurations required for virtualized testing environments.

Sources: empty.go:5-9, README.md:1-6

Module Integration and Package Definition

The empty.go file defines the Go package named kernel. This package name allows gokrazy to select and use this module as a KernelPackage when building appliance images. The file contains no executable code and serves purely as a structural marker for the Go toolchain.

Sources: empty.go:5-9, README.md:16-18

The diagram shows how the Go package definition in empty.go enables gokrazy to identify and include the kernel binary during the build process.

Kernel Build and Deployment Process

The build-buggy-linux-7_0.bash script automates the creation of the kernel binary. It performs the following sequential actions:

1. Defines the source URL for Linux 7.0.
2. Downloads the kernel tarball from kernel.org if it is not present.
3. Unpacks the source tree into a local directory.
4. Applies a default configuration (make defconfig).
5. Appends custom configurations from config.addendum.txt to the .config file.
6. Compiles the kernel using make bzImage.
7. Copies the resulting bzImage to the repository root as vmlinuz.

Sources: build-buggy-linux-7_0.bash:4-23, README.md:25-27

Build Configuration Steps

Step	Action	Command/File
1	Download Source	curl linux-7.0.tar.xz
2	Prepare Config	make defconfig
3	Apply Addendum	cat config.addendum.txt >> .config
4	Finalize Config	make olddefconfig
5	Compile	make bzImage -j$(nproc)
6	Output	cp arch/x86/boot/bzImage ./vmlinuz

Sources: build-buggy-linux-7_0.bash:4-23

Kernel Capabilities and Subsystems

The kernel is configured via config.addendum.txt to support specific networking, filesystem, and virtualization features. A critical component is the igb network driver, which is required by the vmtest image to advertise tx-udp-segmentation and tx-gso-partial.

Sources: README.md:10-14, config.addendum.txt:1-100

Networking and Firewalling

The configuration enables comprehensive support for nftables, IPv6, and virtual networking devices. It explicitly disables certain Netfilter connection tracking helpers (e.g., FTP, SIP) to prevent NAT slipstreaming attacks.

• Enabled Features: CONFIG_NF_TABLES=y, CONFIG_WIREGUARD=y, CONFIG_TUN=y, CONFIG_BRIDGE=y.
• Disabled Features: CONFIG_NF_CONNTRACK_FTP=n, CONFIG_NF_CONNTRACK_SIP=n.

Sources: config.addendum.txt:1-2, 21-65, 75-77, 88-89

Virtualization and Storage

To operate within QEMU and natlab environments, the kernel includes drivers for virtio devices and the Squashfs filesystem, which gokrazy uses for the root partition.

• Storage: CONFIG_SQUASHFS=y, CONFIG_VIRTIO_BLK=y.
• Virtualization: CONFIG_VIRTIO_PCI=y, CONFIG_VIRTIO_NET=y, CONFIG_HW_RANDOM_VIRTIO=y.

Sources: config.addendum.txt:10-13, 79-85

Boot Configuration

The cmdline.txt file defines the parameters passed to the kernel at boot time. These parameters specify the root device, initialization path, and error handling behavior.

Sources: cmdline.txt:1

The diagram represents the kernel command line parameters used to initialize the gokrazy environment.

Command Line Parameter Descriptions

Parameter	Value	Description
root	/dev/sda2	Specifies the partition containing the root filesystem.
ro	N/A	Mounts the root filesystem as read-only.
init	/gokrazy/init	Sets the first process to be executed by the kernel.
panic	10	Reboots the system 10 seconds after a kernel panic.
oops	panic	Forces a full kernel panic when a kernel "oops" occurs.

Sources: cmdline.txt:1

Summary of Regression Testing Role

This module is purpose-built to facilitate testing of the UDP GSO regression documented in tailscale/tailscale#19777. By packaging an intentionally "buggy" Linux 7.0 kernel, it ensures that automated tests in natlab can consistently verify that software mitigations function correctly across different host environments.

Sources: README.md:1-6, empty.go:7-9