kernel

Documentation

Overview

Package kernel fetches and caches guest kernels for [machine.DirectKernel] boot.

The default source is the clawk guest kernel published on the clawkwork/clawk releases (see DefaultKernelURLs): a raw, bootable vmlinux built from Kata Containers' known-good config plus the clawk fragments — CONFIG_NET_9P_FD (9p-over-vsock, so the toolchain caches avoid Apple's fd-leaking virtio-fs), fscache, and sound. It boots fast with no initrd and keeps everything the clawk shape needs: virtio-fs (the worktree + config shares), vsock (agent transport), overlayfs and cgroups.

For an arch we don't publish — and when a caller pins an explicit Version/URL — Fetch falls back to the stock Kata Containers static release (the same kernel Apple's `container machine` boots, see third_party/misc/container ContainerSystemConfig.swift), extracting only the vmlinux member from its ~hundreds-of-MB tar.zst without touching disk. Results are cached as

<CacheDir>/kernels/clawk-<version>-<arch>/vmlinux   (default)
<CacheDir>/kernels/kata-<version>-<arch>/vmlinux    (Kata fallback)
<CacheDir>/kernels/override-<hash>/vmlinux          (clawk.mod override)

Index

• Constants
• Variables
• func CachedPath(opts Options) (string, bool)
• func Fetch(ctx context.Context, opts Options) (string, error)
• type Options

Constants

const DefaultBinaryPath = "opt/kata/share/kata-containers/vmlinux-6.18.15-186"

DefaultBinaryPath is the vmlinux member inside the kata-static archive for DefaultKataVersion.

const DefaultKataVersion = "3.28.0"

DefaultKataVersion is the pinned Kata Containers release. Bump together with DefaultBinaryPath — the vmlinux member name embeds the kernel version shipped by that release.

const DefaultKernelVersion = "6.18.15-snd"

DefaultKernelVersion identifies the clawk guest-kernel release used by default. It maps to the git tag guest-kernel-<DefaultKernelVersion> and to the cache path, so bumping the kernel is a one-line change here (plus a new release build). revalidateDownload also re-fetches if the asset at a given tag is republished with new bytes, so a rebuilt-in-place release is picked up without a version bump.

Variables

var DefaultKernelURLs = map[string]string{
	"arm64": "https://github.com/clawkwork/clawk/releases/download/guest-kernel-" + DefaultKernelVersion + "/vmlinux-arm64",
}

DefaultKernelURLs maps a guest arch to the clawk guest-kernel release asset: a raw, bootable kernel built from Kata's config plus the clawk fragments (CONFIG_NET_9P_FD for 9p-over-vsock caches, fscache, and sound). This is the default boot kernel — unlike the stock Kata kernel it carries the 9p fd transport, so the toolchain caches mount over 9p instead of Apple's fd-leaking virtio-fs. An arch not listed here falls back to the Kata static archive (DefaultKataVersion), so an unpublished arch still boots.

Functions

func CachedPath

func CachedPath(opts Options) (string, bool)

CachedPath returns where Fetch(opts) stores its vmlinux and whether it is already present — callers use it to skip "fetching" narration for what is actually a stat.

func Fetch

func Fetch(ctx context.Context, opts Options) (string, error)

Fetch returns the path to a cached vmlinux, downloading and extracting it on first use. Safe to call concurrently for different cache dirs; concurrent calls for the same cache dir may download twice but converge via atomic rename.

Types

type Options

type Options struct {
	// CacheDir is the root cache directory. Required.
	CacheDir string

	// Arch is the guest architecture ("arm64", "amd64"). Required —
	// callers usually pass runtime.GOARCH.
	Arch string

	// Version is the Kata release to pin. Default DefaultKataVersion.
	Version string

	// URL overrides the archive URL derived from Version and Arch.
	URL string

	// BinaryPath is the archive member to extract. Default
	// DefaultBinaryPath. Must be overridden together with URL/Version
	// when they name a release shipping a different kernel version.
	BinaryPath string

	// Override, when set, replaces the default Kata kernel with a
	// user-supplied raw vmlinux — a local file path (returned as-is) or
	// an http(s) URL (downloaded once and cached). Used by the clawk.mod
	// `vm ( kernel <path|url> )` directive / `--kernel` flag, chiefly to
	// boot a KVM-enabled kernel for nested virtualization (the stock Kata
	// kernel ships with KVM disabled, so the guest has no /dev/kvm).
	// Unlike URL, this points at a bare vmlinux, not a kata-static
	// archive. When set, Version/URL/BinaryPath are ignored.
	Override string
}

Options control a Fetch.