Gokrazy Deployment Process

Relevant source files

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

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

The Gokrazy deployment process for this repository involves building and packaging a specific Linux 7.0 amd64 kernel for use in Tailscale natlab/vmtest environments. This kernel intentionally includes a UDP GSO regression to facilitate testing mitigation behaviors in guest environments even when the host kernel is patched.

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

Kernel Build Pipeline

The build process automates the acquisition, configuration, and compilation of the Linux kernel source to produce a bootable vmlinuz image.

Build Workflow Logic

1. Environment Setup: The script identifies the repository directory and defines the target kernel version (Linux 7.0).
2. Source Acquisition: curl downloads the kernel tarball from kernel.org if it is not already present in the local directory.
3. Extraction: The script extracts the tarball into a linux-7.0 subdirectory.
4. Configuration Injection: The script copies config.addendum.txt into the source tree and appends its contents to the base .config generated by make defconfig.
5. Compilation: The system executes make bzImage using all available CPU cores to generate the compressed kernel image.
6. Artifact Deployment: The process copies the resulting bzImage from the architecture-specific boot directory to the repository root as vmlinuz.

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

Build Process Flow

The following diagram illustrates the sequence of operations within the build-buggy-linux-7_0.bash script.

Kernel Configuration and Features

The deployment utilizes a specific set of kernel configurations to support Gokrazy operations and specific hardware emulation in QEMU.

Core Component Support

Component	Configuration Requirement	Purpose
File System	CONFIG_SQUASHFS	Supports the Gokrazy root file system.
Networking	CONFIG_IGB, CONFIG_VIRTIO_NET	Enables Intel igb and Virtio network drivers for VM testing.
Virtualization	CONFIG_VIRTIO_PCI, CONFIG_VIRTIO_BLK	Provides support for QEMU virtio block devices.
Diagnostics	CONFIG_IKCONFIG_PROC	Enables access to kernel config via /proc/config.gz.
Tailscale	CONFIG_WIREGUARD, CONFIG_TUN	Supports WireGuard and TUN devices.

Sources: config.addendum.txt:10-15, config.addendum.txt:60-70, config.addendum.txt:90-100

Boot Configuration

The kernel uses a specific command line defined in cmdline.txt to control boot behavior and error handling.

• Root Partition: The kernel mounts /dev/sda2 as the root device in read-only (ro) mode.
• Init Process: The kernel executes /gokrazy/init as the primary userspace entry point.
• Error Handling: The system is configured to panic on "oops" and reboot after 10 seconds following a panic.

Sources: cmdline.txt:1

Integration as a Gokrazy Package

To use this kernel in a Gokrazy environment, it must be referenced as a KernelPackage within a Go module context.

Go Module Inclusion

The file empty.go exists solely to allow the Go toolchain to recognize the directory as a package. This enables Gokrazy to select the module as a KernelPackage.

In a Tailscale environment, the package is referenced as:
github.com/tailscale/gokrazy-kernel-buggy-linux-7_0

Sources: empty.go:5-9, README.md:20-22

Component Relationships

The following diagram shows how the Go package and the compiled artifacts interact within the Gokrazy ecosystem.

Local Development and Overrides

For development before publishing a module version, the deployment process supports local overrides using go.mod replacements.

1. Local Replace: Use replace github.com/tailscale/gokrazy-kernel-buggy-linux-7_0 => ../path/to/local/repo in your go.mod.
2. Rebuild: Execute ./build-buggy-linux-7_0.bash to refresh the local vmlinuz artifact.

Sources: README.md:24-33