kerf: Record load provenance and show it in kerf show - #15
Merged
Conversation
congwang-mk
force-pushed
the
kimage-metadata
branch
from
August 13, 2026 23:03
b10b98d to
2c47660
Compare
The Kernel Image section of kerf show only displays what the kernel exposes in /proc/kimage (id, type, start address, segments, mode, cmdline). The source image file is unknown to the kernel, since kexec_file_load takes a bare fd, so nothing identified which kernel an instance is actually running. Record the provenance in userspace instead. On a successful load, kerf load writes /var/lib/kerf/instances/<name>.json with the kernel path, image format, compression, version string, size, sha256, initrd path, and load time. The version comes from the kernel_version setup header field for a bzImage, or from the "Linux version" banner for a vmlinux. kerf show merges these fields into the Kernel Image section, and both kerf unload and kerf delete remove the record. Signed-off-by: Cong Wang <cwang@multikernel.io>
Inspect the optional initrd the same way as the kernel image and store its path, size, sha256, and compression format in the instance record. Unlike the kernel image, a compressed initrd needs no extraction: kexec treats it as an opaque blob and the spawn kernel decompresses it at boot, so this is purely informational for kerf show. The initrd field changes from a bare path string to an object; kerf show still renders records written in the old form. Signed-off-by: Cong Wang <cwang@multikernel.io>
An instance loaded with a Docker image or rootfs directory records which image or directory it is running, the resolved entrypoint, and the daxfs physical placement, all known at load time but visible nowhere afterwards. kerf show renders them in a new Rootfs section, with the Docker extraction path shown under --verbose. Instances loaded without a rootfs are unaffected. Signed-off-by: Cong Wang <cwang@multikernel.io>
congwang-mk
force-pushed
the
kimage-metadata
branch
from
August 14, 2026 16:25
2c47660 to
73cb69a
Compare
Taking the instances_dir fixture as a test parameter shadows the fixture function name and trips pylint W0621. The fixture already redirects the store to tmp_path, so use tmp_path directly. Signed-off-by: Cong Wang <cwang@multikernel.io>
A tag like nginx:latest names different bytes over time, so the reference alone cannot tell which image an instance is actually running. Have extract_image() also return the image ID, the sha256 digest of the config blob it already parses for the entrypoint, and record it as rootfs.image_id. kerf show displays it under --verbose. Pin the layer extraction to the fully_trusted tar filter it relies on today: a rootfs needs setuid bits, device nodes, and absolute symlinks, which the restrictive default coming in Python 3.14 rejects. Signed-off-by: Cong Wang <cwang@multikernel.io>
congwang-mk
force-pushed
the
kimage-metadata
branch
from
August 14, 2026 16:34
73cb69a to
194c5f1
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
The Kernel Image section of
kerf showonly displays what the kernel exposes in/proc/kimage(id, type, start address, segments, mode, cmdline). The source image file is unknown to the kernel, sincekexec_file_loadtakes a bare fd, so nothing identified which kernel, initrd, or rootfs an instance is actually running.This PR records that provenance in userspace at load time and displays it in
kerf show. Stacked on #14 (base branchbzimage-support) because it reuses thevmlinuzmodule for bzImage parsing; it retargets tomainautomatically when #14 merges.What gets recorded
On a successful load,
kerf loadwrites/var/lib/kerf/instances/<name>.json(consistent with the existing/var/lib/kerf/rootfsand/var/lib/kerf/daxfsstate directories):kernel_versionsetup header field for a bzImage, or theLinux versionbanner for a vmlinux.--image/--rootfs-dir): source kind, image reference or directory path, resolved entrypoint, and daxfs physical address and size.kerf show
The recorded fields merge into the Kernel Image section, with a new Rootfs section when applicable:
--verboseadds sha256 rows and the Docker extraction path. A metadata write failure only warns and never fails the load.kerf unloadandkerf deleteremove the record so it cannot go stale.Testing
30 tests in
tests/test_metadata.pycover the store round-trip, corrupt-file handling, kernel/initrd inspection across formats, and thekerf showrendering including optional-field omission and verbose-only rows. Full suite: 119 passed.🤖 Generated with Claude Code