From 6ce1c757f6e0607e12f3dcbb7c810d91ef5ccebe Mon Sep 17 00:00:00 2001 From: ErenAri Date: Wed, 24 Jun 2026 17:08:03 +0300 Subject: [PATCH] docs(readme): explain full-VM validation, distros covered, and backports Adds a high-visibility section (right after the CO-RE rationale) covering the three things users keep asking about: - validation is full-VM, not static: boots the real distro kernel in a disposable QEMU/KVM VM and runs the real bpf() load/attach inside the guest (runners: vm/virtme-ng/firecracker/host; leaves serial.log etc.) - a distributions-covered table (Ubuntu, Debian, RHEL family via Alma/Rocky/CentOS, Oracle UEK, Amazon Linux, SUSE, upstream mainline; x86_64 + ARM64), linking docs/profile-catalog.md - kernel version != feature support: enterprise distros heavily backport (Ubuntu 5.4 fails ringbuf, AlmaLinux 8's 4.18 passes; AL2 4.14 no-BTF still loads), linking the 14/14 enterprise case study Co-Authored-By: Claude Opus 4.8 --- README.md | 50 ++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 50 insertions(+) diff --git a/README.md b/README.md index f3bb251..77fdde8 100644 --- a/README.md +++ b/README.md @@ -44,6 +44,56 @@ CO-RE makes a `.bpf.o` *portable in principle*; it does not guarantee it will `bpfcompat` answers the empirical question CO-RE leaves open: *does it actually load and attach here?* — by running the artifact in a real kernel. +## How validation works: full VMs, not static analysis + +bpfcompat does **not** parse your object and guess. For every target it: + +1. boots the **real distro cloud image and its actual kernel** as a disposable + QEMU/KVM virtual machine (default `--runner vm`; `virtme-ng`, `firecracker`, + and `host` are also selectable); +2. copies a **C/libbpf validator and your `.bpf.o` into the guest** over a + per-run SSH key; +3. runs the **real `bpf()` load — and attach, in `load_attach` mode — inside + that kernel**, then copies a structured result back and throws the VM away. + +So a verdict is what the kernel itself accepted or rejected (verifier log, BTF, +CO-RE relocation, map/program/attach support), not a heuristic. Each run leaves +per-target evidence — `serial.log` (the guest kernel boot), `qemu.log`, and +`validator-result.json`. + +### Distributions covered + +A curated, multi-distro, multi-architecture matrix of the kernels enterprises +and cloud fleets actually run (full list in +[docs/profile-catalog.md](docs/profile-catalog.md)): + +| Family | Versions / kernels | +|---|---| +| Ubuntu | 16.04 → 25.10 (5.4, 5.8, 5.15, 6.5, 6.8, 6.11, 6.14, 6.17) | +| Debian | 11 · 12 · 13 | +| RHEL¹ / AlmaLinux / Rocky / CentOS Stream | 8 (4.18) · 9 (5.14) · 10 (6.12) | +| Oracle Linux (UEK) | UEK 7 · UEK 8 | +| Amazon Linux | 2 (4.14, 5.10) · 2023 (6.1) | +| SUSE / openSUSE Leap | 15.6 (6.4) | +| Upstream mainline | kernel.org 5.x–6.x sweeps | + +Architectures: **x86_64 and ARM64**. ¹RHEL itself is a BYO subscription image; +AlmaLinux/Rocky/CentOS Stream are the public, ABI-compatible rebuilds used as the +reproducible RHEL stand-in. + +### Kernel version ≠ feature support (backports) + +Enterprise distros **heavily backport** eBPF features onto old kernel bases, so +the version number alone predicts nothing. Because bpfcompat boots the real +vendor kernel, this is tested directly instead of inferred: + +- A ring-buffer program **fails on Ubuntu's vanilla 5.4** (ring buffer lands + upstream in 5.8) yet **passes on AlmaLinux 8's backported 4.18**. +- **Amazon Linux 2's 4.14 — with no embedded BTF — still loads and attaches.** + +This is proven across a 14/14 enterprise tier: +[docs/case-study-enterprise-kernels.md](docs/case-study-enterprise-kernels.md). + ## Try it in CI without your own KVM box GitHub-hosted Linux runners now expose `/dev/kvm`, so the full QEMU VM