Updating the Base Linux Version

Relevant source files

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

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

Updating the base Linux version in this repository involves modifying the build orchestration script and the kernel configuration addendum to target a specific Linux kernel release. This project maintains a specialized amd64 kernel for the Tailscale natlab/vmtest environment, specifically to preserve the UDP GSO regression from tailscale/tailscale#19777.

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

The system packages the Linux 7.0 vmlinuz binary as a gokrazy KernelPackage. Developers use the local build script to automate the retrieval, patching, and compilation of the kernel source code.

Sources: README.md:20-22, build-buggy-linux-7_0.bash:1-23

Kernel Build Orchestration

The build process resides in build-buggy-linux-7_0.bash. This script manages the lifecycle of the kernel source, from initial download to the generation of the final vmlinuz image.

Build Workflow Logic

The following diagram illustrates the sequential steps the build script executes to produce the kernel image:

The script uses set -euo pipefail to ensure the process terminates immediately if any command fails.

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

Build Component Locations

Component	Path / Value	Description
Kernel URL	https://cdn.kernel.org/pub/linux/kernel/v7.x/linux-7.0.tar.xz	The remote source for the base Linux kernel.
Source Directory	./linux-7.0	The location where the kernel source is extracted.
Output Image	./vmlinuz	The final bootable kernel image.
Configuration	./config.addendum.txt	Custom kernel parameters appended during the build.

Sources: build-buggy-linux-7_0.bash:5-8, build-buggy-linux-7_0.bash:15, build-buggy-linux-7_0.bash:22

Kernel Configuration and Addendums

The repository uses a two-stage configuration process. It first generates a default configuration and then applies specific overrides defined in config.addendum.txt.

Sources: build-buggy-linux-7_0.bash:18-20

Key Configuration Modules

The addendum enables critical subsystems for gokrazy and Tailscale testing:

• Networking: Enables CONFIG_IPV6, CONFIG_WIREGUARD, and CONFIG_TUN for secure communication.
• Virtualization: Includes CONFIG_VIRTIO_PCI and CONFIG_VIRTIO_NET for QEMU compatibility.
• Diagnostics: Enables CONFIG_IGB and CONFIG_NETLINK_DIAG to facilitate regression testing.
• Filesystem: Provides CONFIG_SQUASHFS for the gokrazy root filesystem.

Sources: config.addendum.txt:1-3, config.addendum.txt:10-14, config.addendum.txt:77-83, config.addendum.txt:90-95

Prohibited Modules

The configuration explicitly disables NAT slipstreaming vectors by setting specific connection tracking helpers to n:

CONFIG_NF_CONNTRACK_FTP=n
CONFIG_NF_CONNTRACK_SIP=n
CONFIG_NF_CONNTRACK_TFTP=n

Sources: config.addendum.txt:59-70

Runtime Environment

The kernel image boots under QEMU q35 and requires specific command-line arguments to function within the gokrazy ecosystem.

Sources: README.md:12-13

Boot Configuration

The cmdline.txt file defines the behavior of the kernel at startup:

• Sets the root partition to /dev/sda2.
• Specifies /gokrazy/init as the initial process.
• Configures the system to panic and reboot after 10 seconds on critical failures (panic=10 oops=panic).

Sources: cmdline.txt:1

Go Integration

The empty.go file establishes the project as a Go module. This allows gokrazy to import the repository as a KernelPackage by referencing github.com/tailscale/gokrazy-kernel-buggy-linux-7_0.

Sources: empty.go:1-7, README.md:20-22

Summary of Version Update Steps

To update the base Linux version, you must perform the following actions:

1. Modify URL: Update the kernel_url variable in build-buggy-linux-7_0.bash to point to a new .tar.xz release.
2. Update Source Path: Change the srcdir variable in the build script to match the new version folder.
3. Review Config: Verify that config.addendum.txt options remain compatible with the new kernel version.
4. Execute Build: Run ./build-buggy-linux-7_0.bash to generate a new vmlinuz.
5. Commit Output: Check in the updated vmlinuz to the repository.

Sources: build-buggy-linux-7_0.bash:5-8, README.md:32-34