banger/docs/kernel-catalog.md

Kernel catalog

The kernel catalog ships pre-built Firecracker-ready kernel bundles so users don't have to compile anything. The catalog is embedded into the banger binary and updated each release.

End-user flow:

banger kernel list --available       # browse the catalog
banger kernel pull generic-6.12      # download a bundle (no sudo, no make)
banger image register --name myimg --rootfs … --kernel-ref generic-6.12

Architecture

Two parts:

1. internal/kernelcat/catalog.json — a JSON manifest embedded into the banger binary via go:embed. Each entry carries a name, distro, arch, kernel version, tarball URL, and tarball SHA256. Updating the catalog means editing this file in the repo and rebuilding banger.

2. Tarballs at https://kernels.thaloco.com/ — Cloudflare R2 bucket banger-kernels, fronted by a public custom domain. Each tarball is <name>-<arch>.tar.zst and contains vmlinux, optional initrd.img, and an optional modules/ tree at the archive root.

The banger kernel pull flow streams the tarball, verifies its SHA256 against the embedded catalog entry, decompresses it (zstd), extracts it into ~/.local/state/banger/kernels/<name>/, and writes a manifest. Path traversal entries and unsafe symlinks are rejected.

Kernel types

generic-<version> — built from upstream kernel.org sources with Firecracker's official config. All essential drivers (virtio_blk, virtio_net, ext4, vsock) compiled in — no modules, no initramfs. This is the kernel the golden image pairs with and the recommended kernel for OCI-pulled images. Build with scripts/make-generic-kernel.sh.

Adding or updating an entry

The repo has no CI for kernel publishing yet. Catalog updates are manual and infrequent (kernel version bumps every few weeks at most).

# 1. Build the kernel locally.
scripts/make-generic-kernel.sh

# 2. Import it into the local catalog so the canonical layout exists.
banger kernel import generic-6.12 \
  --from build/manual/generic-kernel \
  --distro generic \
  --arch x86_64

# 3. Package, upload, patch catalog.json.
scripts/publish-kernel.sh generic-6.12 \
  --description "Generic Firecracker kernel 6.12 (all drivers built-in, no initrd)"

# 4. Review and commit the catalog change.
git diff -- internal/kernelcat/catalog.json
git add internal/kernelcat/catalog.json
git commit -m 'kernel catalog: add/update generic-6.12'

# 5. Rebuild so the new catalog is embedded.
make build

scripts/publish-kernel.sh reads the locally-imported entry under ~/.local/state/banger/kernels/<name>/, builds a tar+zstd archive, uploads it to R2 via rclone, HEAD-checks the public URL, and patches internal/kernelcat/catalog.json with the new URL, SHA256, and size.

Environment overrides if the defaults need to change: RCLONE_REMOTE, RCLONE_BUCKET, BASE_URL, BANGER_KERNELS_DIR.

Removing an entry

1. Delete the line from internal/kernelcat/catalog.json and commit.
2. Delete the tarball from R2: rclone delete r2:banger-kernels/<name>-<arch>.tar.zst.
3. Rebuild banger.

Already-pulled local copies on user machines are not invalidated — they keep working until the user runs banger kernel rm <name>. That's intentional: pulling is idempotent, removing should not break anyone in the middle of a workflow.

Versioning conventions

• Entry names: <family>-<major.minor> (e.g. generic-6.12). The major.minor is the kernel line. Patch-level bumps reuse the entry name and replace the tarball; minor bumps create a new entry (generic-6.13).
• Architecture: only x86_64 is published today. The arch field in the catalog schema is additive — adding arm64 later is a config change, not a schema change.
• Tarball layout: contents at the archive root (no top-level versioned directory). vmlinux is required; initrd.img and modules/ are optional. Symlinks inside modules/ are allowed but must resolve within the archive.

Trust model

The embedded catalog.json carries the SHA256 of each tarball. banger kernel pull rejects any download whose hash doesn't match. This protects against transport corruption and against an attacker swapping a tarball on R2 without also pushing a banger release.

It does not protect against a compromise of the banger source repo itself — an attacker who can land a commit can change both the catalog SHA256 and the tarball. GPG/sigstore signing is deferred until banger is public and the threat model justifies the operational overhead.

Hosting

Tarballs live in Cloudflare R2 (bucket banger-kernels), served at the custom domain kernels.thaloco.com. The bucket is publicly readable; writes require the banger-kernels-publish API token (kept locally, never committed). R2's free tier covers the expected traffic comfortably (zero egress fees, generous storage).

If hosting ever moves, catalog entries can be migrated by reuploading the tarballs and editing the URLs in catalog.json — no other code changes required.

Tech debt

• Kernel publishing is manual; there is no CI yet. scripts/make-generic-kernel.sh plus scripts/publish-kernel.sh is fine while refreshes are infrequent and maintainer-only. CI becomes relevant once banger goes public.
• make lint-shell runs at --severity=error only. Tightening to --severity=warning is a nice-to-have but low priority.