Pantavisor Manifest Audit
pv-manifest-audit.bbclass produces a deterministic listing of every entry in
an image rootfs (path, type, mode, ownership, symlink targets, device nodes)
and compares it against a reference checked into a layer. Drift is surfaced as
a unified-diff patch — printed to the bitbake log, written to the deploy
directory, and (in strict mode) used to fail the build.
This catches a class of regressions that ordinary CI does not:
- a package starts shipping a setuid binary it never had before,
- a recipe accidentally drops a previously-installed file,
- ownership flips from
root:roottomessagebus:messagebus, - a new symlink is introduced in
/etc, - a postinst leaves stray files in
/var.
None of these break the build. All of them change device behaviour in the field.
Two modes
The class is inherited only when one of the feature flags is set in
PANTAVISOR_FEATURES:
| Flag | Behaviour on drift | Use in |
|---|---|---|
pv-manifest-audit | Patch + WARNING (build proceeds) | Dev distros, default in panta |
pv-manifest-strict | Patch + ERROR (build fails) | Release / CI distros |
pv-manifest-strict implies pv-manifest-audit. Setting both is fine — strict wins.
The default panta and panta-appengine distros enable advisory mode out of
the box; flip to strict in a release config:
PANTAVISOR_FEATURES:append = " pv-manifest-strict"
Reference filename
In this layer, references live in a pv-manifests/ directory next to the
recipe (recipes-pv/images/pv-manifests/ for the initramfs,
dynamic-layers/virtualization-layer/recipes-pv/images/pv-manifests/ for the
appengine); downstream .bbappends conventionally use files/. Either way
they are pulled into ${WORKDIR} via SRC_URI:
${PV_MANIFEST_PREFIX}_${DISTRO}-${MACHINE}-${DISTRO_CODENAME}.manifest.reference.txt
PV_MANIFEST_PREFIX is set per recipe (pv-initramfs for the initramfs image,
pv-appengine for the appengine image). Concrete examples:
pv-initramfs_panta-raspberrypi-armv8-scarthgap.manifest.reference.txt
pv-initramfs_panta-bananapi-m2-berry-scarthgap.manifest.reference.txt
pv-appengine_panta-appengine-docker-x86_64-scarthgap.manifest.reference.txt
The underscore separates the recipe prefix from the distro/machine/codename
triple — both halves can themselves contain dashes, so the underscore makes
the boundary unambiguous. The -${DISTRO_CODENAME} segment is dropped when
DISTRO_CODENAME is unset.
How to add a reference for a new MACHINE / DISTRO
The reference is a normal SRC_URI file:// entry. Add it from this layer
(for upstream-supported machines) or from a downstream .bbappend:
# pantavisor-initramfs.bbappend in your layer
FILESEXTRAPATHS:prepend := "${THISDIR}/files:"
SRC_URI += "file://pv-initramfs_panta-<MACHINE>-<CODENAME>.manifest.reference.txt"
Drop the file under <your-layer>/files/. Normal Yocto override semantics
apply: FILESEXTRAPATHS:prepend in a bbappend wins over the upstream layer's
copy.
Bootstrapping a brand-new MACHINE:
-
Build with advisory mode (
pv-manifest-auditset, nopv-manifest-strict). -
The build prints a full-add patch to the bitbake log and writes
${DEPLOY_DIR_IMAGE}/${IMAGE_NAME}.manifest.patch(also copied to the finaldeploy/images/<MACHINE>/directory). -
Apply the patch under your layer's reference directory (
pv-manifests/in this layer,files/in a downstream bbappend):cd <layer>/filespatch < <build>/tmp-scarthgap/.../pantavisor-initramfs-<MACHINE>-<TS>.manifest.patch -
Add the matching
SRC_URI += "file://..."line and rebuild. The nextdo_rootfsshould match cleanly.
Output artifacts
Two files land in the image deploy dir for every build:
| File | When written |
|---|---|
${IMAGE_NAME}.manifest.txt | Always |
${IMAGE_NAME}.manifest.patch | Only when there is a drift to record |
Each is accompanied by a stable, build-id-free symlink
(${IMAGE_LINK_NAME}.manifest.txt / .manifest.patch) pointing at the latest
versioned file, so tooling can reference a fixed path.
The patch is also dumped in full into the bitbake log via bb.plain so it
shows in CI output without any extra plumbing. Look for the banner:
=== pv-manifest-audit PATCH (<MACHINE>, audit|STRICT) ===
# patch file: tmp-<codename>/.../...manifest.patch (relative to TOPDIR)
# manifest: tmp-<codename>/.../...manifest.txt (relative to TOPDIR)
# apply with: cd <layer>/files && patch < $TOPDIR/<patch>
--- <reference name>
+++ <reference name>
...
=== end pv-manifest-audit PATCH ===
Manifest format
# pv-manifest-audit v1
# format: type mode uid gid path[ -> symlink-target | major,minor]
# machine: <MACHINE>
# distro: <DISTRO> (<DISTRO_CODENAME>)
# prefix: <PV_MANIFEST_PREFIX>
# exclude: <space-separated paths excluded from the walk>
<entries, sorted by path>
Each entry is <type> <mode> <uid> <gid> <path>[<tail>] where tail is
-> <target> for a symlink, <major>,<minor> for a device node, or empty.
Types: f regular, d directory, l symlink, c char device, b block
device, p fifo, s socket.
File size is intentionally omitted: it would diff on every dependency version bump (busybox, mbedtls, kernel modules) without reflecting a meaningful behavioural change. Adding or removing a file is still detected via its presence or absence.
Excludes
PV_MANIFEST_EXCLUDES is a space-separated list of rootfs-relative path
prefixes to skip. Defaults cover package-manager state files whose contents
flip on every rebuild without indicating real change:
/var/lib/rpm
/var/lib/dnf
/var/lib/opkg
/usr/lib/opkg
/var/cache/ldconfig
/var/cache/dnf
/var/cache/yum
Package add/remove is still detectable via the actual installed files
(binaries, libs, configs in /usr, /etc, etc.); only the package-manager
bookkeeping is filtered.
A recipe or downstream layer can extend the list:
PV_MANIFEST_EXCLUDES:append = " /etc/ssh/ssh_host_keys /etc/machine-id"
The exclude list is part of the task's input hash (vardeps), so changes
trigger a do_rootfs rerun.
Class variables
| Variable | Default | Purpose |
|---|---|---|
PV_MANIFEST_PREFIX | ${PN} | Recipe-stable label embedded in the reference filename |
PV_MANIFEST_REFERENCE_NAME | ${PV_MANIFEST_PREFIX}_${DISTRO}-${MACHINE}-${DISTRO_CODENAME}.manifest.reference.txt (the -${DISTRO_CODENAME} segment is dropped when DISTRO_CODENAME is unset) | Basename of the reference fetched into ${WORKDIR} |
PV_MANIFEST_EXCLUDES | (see above) | Rootfs-relative path prefixes to omit from the manifest |
Inheriting the class
Recipes inherit the class conditionally so it is a no-op when neither feature flag is set:
inherit ${@bb.utils.contains_any('PANTAVISOR_FEATURES', \
'pv-manifest-audit pv-manifest-strict', 'pv-manifest-audit', '', d)}
PV_MANIFEST_PREFIX = "pv-initramfs" # or pv-appengine, etc.
Currently inherited by:
recipes-pv/images/pantavisor-initramfs.bbdynamic-layers/virtualization-layer/recipes-pv/images/pantavisor-appengine.inc
Implementation
classes/pv-manifest-audit.bbclass adds pv_manifest_audit as the last
ROOTFS_POSTPROCESS_COMMAND, so the audit runs inside do_rootfs, under
pseudo. The uid/gid recorded in the manifest are the ones that end up in the
cpio or tarball.
A strict deviation keeps failing until the reference is updated, on every
build. It fails do_rootfs, which then has no stamp and re-runs next time.
The function, the variables it reads (PANTAVISOR_FEATURES, and so the
audit/strict mode, PV_MANIFEST_REFERENCE_NAME, PV_MANIFEST_EXCLUDES) and
the reference file (through SRC_URI) are all part of the do_rootfs
signature. So a valid rootfs stamp, or an image restored from sstate, always
stands for a run where the same audit passed in the same mode against the same
reference.
It deliberately is not a separate task. With rm_work, a task between
do_rootfs and do_image re-runs over a rootfs that rm_work already
deleted, and drags do_image along. The earlier [nostamp] task did exactly
that: every incremental build packed an empty image, for example a 505-byte
initramfs whose kernel panics with No working init found. Check a deployed
initramfs with:
zcat build/tmp-scarthgap/deploy/images/<machine>/pantavisor-initramfs-<machine>.cpio.gz | cpio -t | wc -l
A real one lists several hundred entries; a handful means an empty image.