Container Development
Creating Example Containers
Example containers live in recipes-containers/pv-examples/. Each container needs:
1. Recipe file (pv-example-foo_1.0.bb)
SUMMARY = "Example Foo Container"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
inherit core-image container-pvrexport
IMAGE_BASENAME = "pv-example-foo"
PVRIMAGE_AUTO_MDEV = "0"
IMAGE_INSTALL += "busybox"
SRC_URI += "file://${PN}.services.json \
file://${PN}.args.json"
PVR_APP_ADD_EXTRA_ARGS += "--config=Entrypoint=/bin/sh"
2. services.json (providers)
Declares the services this container exports. The #spec versioning field is required:
{
"#spec": "service-manifest-xconnect@1",
"services": [
{"name": "my-service", "type": "unix", "socket": "/run/my-service.sock"}
]
}
Note: The parser supports both the new object format and the legacy array format for backwards compatibility.
3. args.json (consumers)
Declares which services this container needs:
{
"PV_SERVICES_REQUIRED": [
{"name": "my-service", "target": "/run/pv/services/my-service.sock"}
]
}
For xconnect service manifest details and supported service types (unix, rest, dbus, drm, wayland), see the pantavisor xconnect reference or pantavisor xconnect overview.
Placing a container in the app group
Set PVR_APP_ADD_GROUP = "app" in the recipe to inherit the group's default auto_recovery policy. Containers in the app group automatically get restart-on-failure with backoff behaviour unless they provide their own PV_AUTO_RECOVERY in args.json.
Building Containers
./kas-container build kas/build-configs/release/docker-x86_64-scarthgap.yaml:kas/with-workspace.yaml \
--target pv-example-foo
Output: build/tmp-scarthgap/deploy/images/docker-x86_64/pv-example-foo.pvrexport.tgz
Protecting Volumes with dm-verity
Set PVR_DM_VERITY = "1" in a container recipe to protect its volumes with dm-verity. At build time pvr writes a hash file next to each volume and points run.json at it as dm:<volume>, so pantavisor checks the volume when it mounts it. By default only root.squashfs is protected; list other volumes in PVR_DM_VERITY_VOLUMES.
PVR_DM_VERITY = "1"
# optional, default is "root.squashfs"
PVR_DM_VERITY_VOLUMES = "root.squashfs"
The flag also adds cryptsetup-native (which provides veritysetup) to the recipe's DEPENDS. The device needs a pantavisor built with the dm-verity feature, which is on by default in PANTAVISOR_FEATURES.
The device only mounts dm: volumes through the dm-verity handler when PV_SECUREBOOT_HANDLERS=1 in /etc/pantavisor.config. Without it the volume is loop-mounted and not checked. The layer sets it to 1 whenever dm-verity is in PANTAVISOR_FEATURES (the default) and to 0 otherwise. To turn it off, for example in your distro include or local.conf:
PANTAVISOR_CONFIG[PV_SECUREBOOT_HANDLERS] = "0"
The appengine configuration (/etc/pantavisor-appengine.config) keeps it off; this is not changed.
pv-example-verity (recipes-containers/pv-examples/pv-example-verity_1.0.bb) is a minimal example: it sets PVR_DM_VERITY = "1" and signals READY once it runs.
On a device, the dm-verity mount script (scripts/volmount/verity/dm in pantavisor) names the device pv--dmverity--<container>-<volume>. A protected root volume should therefore show up like this (taken from the script, not tested on a device):
mount | grep dmverity
# /dev/mapper/pv--dmverity--<container>-root on /volumes/<container>/root.squashfs ...
To check the result, look at the container directory of the built state (pvstate/<container>/ in the recipe work directory):
grep root-volume run.json # "root-volume":"dm:root.squashfs"
cat _dm/root.squashfs.json # type dm-verity, data_device, hash_device, root_hash, salt, uuid
ls root.squashfs.hash # the hash file
The container signature covers _dm/root.squashfs.json and root.squashfs.hash.
The work directory is removed after the build unless the recipe is listed in RM_WORK_EXCLUDE.
Adding a New Example Container (full workflow)
# 1. Create recipe
cat > recipes-containers/pv-examples/pv-example-mytest_1.0.bb << 'EOF'
SUMMARY = "My Test Container"
LICENSE = "MIT"
LIC_FILES_CHKSUM = "file://${COMMON_LICENSE_DIR}/MIT;md5=0835ade698e0bcf8506ecda2f7b4f302"
inherit core-image container-pvrexport
IMAGE_BASENAME = "pv-example-mytest"
PVRIMAGE_AUTO_MDEV = "0"
IMAGE_INSTALL += "busybox"
SRC_URI += "file://${PN}.args.json"
PVR_APP_ADD_EXTRA_ARGS += "--config=Entrypoint=/bin/sh"
EOF
# 2. Create args.json
cat > recipes-containers/pv-examples/files/pv-example-mytest.args.json << 'EOF'
{
"PV_SERVICES_REQUIRED": [
{"name": "raw", "target": "/run/pv/services/raw.sock"}
]
}
EOF
# 3. Build and deploy for testing
./kas-container build kas/build-configs/release/docker-x86_64-scarthgap.yaml:kas/with-workspace.yaml \
--target pv-example-mytest
cp build/tmp-scarthgap/deploy/images/docker-x86_64/pv-example-mytest.pvrexport.tgz pvtx.d/
Inspecting Pvrexports
Use pvr tools to inspect pvrexports — do not manually extract tarballs:
# Quick inspection — show state JSON
pvr inspect /path/to/container.pvrexport.tgz
# Clone to directory for detailed inspection
pvr clone /path/to/container.pvrexport.tgz /tmp/inspect-dir
cat /tmp/inspect-dir/<container-name>/run.json
Common Issues
Pseudo Path Mismatch Errors
Errors like path mismatch [1 link]: ino XXXXX db '...' req '...' during image builds indicate pseudo database corruption, typically triggered by pvr file operations.
Fix:
kas shell <config.yaml> -c "bitbake -c cleansstate <recipe-name>"
kas build <config.yaml>
The pvroot-image.bbclass includes PSEUDO_IGNORE_PATHS entries to mitigate this for pvr working directories.
Multiconfig TMPDIR Conflicts
When using BBMULTICONFIG, each config must have a separate TMPDIR to avoid conflicts with package feeds, sstate, and deploy directories:
TMPDIR = "${TOPDIR}/tmp-${DISTRO_CODENAME}-${MULTICONFIG_NAME}-${MACHINE}"