Resolving Go Module Integration Issues
Relevant source files
The following files were used as context for generating this wiki page:
Integrating a specialized kernel into a Go-based environment requires specific module pathing and structural configurations. The gokrazy-kernel-buggy-linux-7_0 repository provides a Linux 7.0 amd64 kernel package designed for Tailscale regression testing. This system allows the gokrazy build system to select and use a kernel that preserves specific UDP GSO bugs. Sources: README.md:1-5, empty.go:4-8
Module Pathing and Recognition
To allow gokrazy to recognize this repository as a KernelPackage, the project includes a placeholder Go file. The empty.go file defines the kernel package, which serves as the entry point for the Go module system. Sources: empty.go:1-8
Referencing the Kernel Package
In a standard Go environment or Tailscale checkout, you reference the kernel using its full module path.
github.com/tailscale/gokrazy-kernel-buggy-linux-7_0
Sources: README.md:16-18
Local Development and Overrides
To use a local version of the kernel module before publishing, apply a replace directive in your go.mod file. This resolves pathing issues when testing local kernel modifications or build script changes.
replace github.com/tailscale/gokrazy-kernel-buggy-linux-7_0 => ../github.com/tailscale/gokrazy-kernel-buggy-linux-7_0
Sources: README.md:20-22
Kernel Build and Integration Pipeline
The kernel build process transforms the raw Linux 7.0 source into a bootable vmlinuz image compatible with gokrazy and QEMU.
Build Workflow
The build script automates the retrieval, configuration, and compilation of the kernel. It specifically appends technical requirements defined in config.addendum.txt to the default configuration. Sources: build-buggy-linux-7_0.bash:4-22
The diagram shows the sequential steps to generate the kernel image from source. Sources: build-buggy-linux-7_0.bash:1-22
Configuration and Compatibility
The kernel includes specific drivers and features to support the natlab/vmtest environment. It supports QEMU q35 machine types and provides necessary drivers for networking and storage. Sources: README.md:7-14
Integrated Subsystems
The following table summarizes the primary subsystems enabled via config.addendum.txt to ensure module compatibility with testing tools.
| Subsystem | Key Configuration | Purpose |
|---|---|---|
| Networking | CONFIG_WIREGUARD, CONFIG_TUN | Supports Tailscale and WireGuard tunnels |
| Virtualization | CONFIG_VIRTIO_NET, CONFIG_IGB | Enables QEMU and Intel NIC drivers |
| Firewall | CONFIG_NF_TABLES, CONFIG_NFT_NAT | Supports nftables and NAT operations |
| Storage | CONFIG_SQUASHFS, CONFIG_OVERLAY_FS | Supports the gokrazy root filesystem |
| Diagnostics | CONFIG_DYNAMIC_DEBUG, CONFIG_IKCONFIG | Enables kernel debugging and config access |
Sources: config.addendum.txt:1-118
Boot Parameters
The cmdline.txt file defines the kernel's behavior during the boot process. It specifies the root partition and the initialization path for gokrazy.
root=/dev/sda2 ro init=/gokrazy/init panic=10 oops=panic
Sources: cmdline.txt:1
Conclusion
Integrating this kernel module requires aligning the Go module path with the gokrazy KernelPackage selection logic. By using the replace directive and maintaining the empty.go package structure, developers can successfully incorporate the buggy Linux 7.0 kernel into their automated testing pipelines to verify network regression mitigations. Sources: README.md:1-24, empty.go:4-8