Cross Kernel Portability

Cross-Kernel Portability

KB is designed to run on any Linux kernel offering sufficient eBPF support, without maintaining kernel-specific builds. This is achieved through BPF Compile Once – Run Everywhere (CO-RE), BTF (BPF Type Format), libbpf, runtime capability detection, and capability-based fallbacks. KB targets kernel capabilities, not specific kernel version numbers.

Compile Once – Run Everywhere (CO-RE)

Traditional eBPF programs hardcode kernel memory layout assumptions, e.g.:

task->real_parent->tgid

This assumes real_parent exists at a fixed offset and task_struct's layout is stable — assumptions that break whenever kernel developers reorganize internal structures.

CO-RE eliminates the dependency: instead of embedding offsets, LLVM emits relocation records (structure name, field name, type info). At load time, libbpf resolves these relocations against the target kernel's BTF metadata.

Always use CO-RE accessors, never direct dereferences:

// Incorrect — direct pointer dereference, offset baked in at compile time
task->real_parent->tgid;
// Correct — offset resolved at load time via BTF
BPF_CORE_READ(task, real_parent, tgid);

BTF (BPF Type Format)

BTF exposes compact, semantic kernel type metadata (field names, offsets, sizes, types) that libbpf uses to resolve CO-RE relocations before the verifier runs. Without BTF, CO-RE relocation cannot occur and CO-RE programs cannot be safely loaded.

BTF discovery order at startup:

1. /sys/kernel/btf/vmlinux
2. Configured external BTF directory
3. Bundled BTF archive
4. → Abort initialization if none found

Runtime Feature Detection (not just version numbers)

Kernel version alone is insufficient — enterprise distributions frequently backport functionality without bumping the reported version:

Distribution	Reported Kernel	Effective Capability
Ubuntu 22.04	5.15 LTS	Modern CO-RE support
RHEL 9	5.14	Extensive enterprise backports
Amazon Linux 2023	6.x	Modern eBPF feature set

Runtime Initialization Sequence

Process Startup (kbd)
        │
        ▼
Load Configuration & Module Manifests
        │
        ▼
Detect Host Environment (kernel, arch, distro, privileges)
        │
        ▼
Discover BTF  ──── not found ────► Abort
        │ found
        ▼
Load CO-RE Objects (open skeletons, parse ELF + relocations)
        │
        ▼
Probe Kernel Capabilities (prog types, map types, helpers, LSM/tracing/XDP, ring buf)
        │
        ▼
Build Capability Profile
        │
        ▼
Module Compatibility Pass (requirements vs. detected capabilities)
        │
        ▼
Resolve Fallbacks (LSM→fentry→tracepoint→kprobe, RingBuf→PerfBuffer)
        │
        ▼
Apply CO-RE Relocations
        │
        ▼
Verifier Preparation (maps, links, globals)
        │
        ▼
Kernel Verification  ──── failed ────► Log Failure & Exit
        │ passed
        ▼
Attach eBPF Programs (tracepoints, kprobes, LSM, XDP)
        │
        ▼
Runtime Ready → Begin Telemetry Collection

Portability Guidelines for New Modules

Mandatory:

• Use CO-RE relocation helpers (BPF_CORE_READ, etc.)
• Avoid hardcoded kernel offsets
• Probe optional kernel features before use
• Declare module capability requirements
• Provide fallbacks whenever technically feasible
• Assume vendor kernels may differ from upstream
• Target capabilities, not kernel versions

Prohibited:

• Hardcoded structure offsets
• Direct kernel pointer dereferencing
• Version-only compatibility checks
• Architecture-specific assumptions
• Compile-time selection of kernel implementations

See also: Kernel Hook Points, kb-core.