Repository navigation
This release reorganises how layers ship their content around a per-layer .d/ directory and drop-ins. It also improves reproducible build support, adds signed boot images and a minimal RAM only boot base. Custom layers will probably need updating.
What's new
Layers and engine
- Per-layer work directories:
${WORKDIR}in metadata,$LAYER_WORKDIRin hooks. - Late hooks (
hooks/late/), which run after every layer's normal hooks for the same phase. - Drop-ins for other layers:
<stem>.d/for/<layer>[@major]/<dir>/, viaforeach_dropin. - New placeholders:
${DOTD},${NAME},${VERSION},${UUID}(stable across builds) and${WORKDIR}. - Layers can ship executables for the build host, either for the whole build (
<stem>.d/host/bin,<stem>.d/<DEB_BUILD_GNU_TYPE>/bin) or for their own hooks only (under<stem>.d/self/). - A pathlist variable type.
- A boot:slotted trait.
Reproducible builds
- SOURCE_DATE_EPOCH is set during the build and published with its outputs.
- Build metadata, boot.img and the erofs verity salt are reproducible.
- The project's revision is recorded as BUILD_ID.
Boot and security
- Signed boot.img support (bin/bootimg), wired into
image-rota. - cryptroot locks HMAC key access after unlocking (needs rpi-eeprom 2026-06-17 or later).
Images, bases and examples
- microboot: a minimal busybox base that boots entirely from RAM, with a mass-storage gadget example.
- image-rpios gains a devid_scheme option to use PARTUUIDs, as pi-gen images do.
- device-user-admin can create a second, non-sudo account (user2).
StaticPath=for image-owned files insideslot-sharedpaths.- New examples
Notable fixes
- cm5-jig-growfs never expanded the root filesystem on by-slot images.
- The IDP archive now bundles only the sparse images it references.
- The size validator now accepts only the unit suffixes genimage understands.
- console-setup.service no longer fails on a read-only
/etc. - initramfs-tools waits for the root device, and the cryptroot partprobe now runs in local-block.
- runenv strips only the wrapping quotes from values.
- Layer hooks no longer inherit the plan on stdin.
XDG_RUNTIME_DIRis passed through to sanitised commands.- Raspberry Pi kernels are ordered after the distribution base layer.
- The Raspbian suite and archive keyring have been updated.
Breaking changes
- Hook phases renamed: pre-build/post-build/pre-image/post-image are now prebuild/postbuild/preimage/postimage.
- Layer content lives only in
<layer-stem>.d/, eghooks/,hooks/late/,<phase>.overlay/,device/. The old fixed name scripts (pre-image.sh, post-image.sh) and thedevice/rootfs-overlay,<stem>.rootfs-overlay/andbdebstrap/directories are no longer used, and nothing reports that. scripts/moved tobuiltin/.IGconf_deploy_hook removed: usedeploy*hooks instead.- Output artefacts renamed to a single base name from the image name and version.
- config.txt and cmdline.txt are generated from layer fragments. A directly installed config.txt is overwritten, the boot-firmware templates are gone, and boot firmware packages now come from layer
rpi-boot-bsp. AfterProvideronly orders now: addRequiresProviderwhere presence is required.- Tools and hooks no longer inherit variables from the calling shell.
Upgrade notes
- Move all hooks to the new format, eg
pre-image.sh->preimage* - Layer content moves to
<layer-stem>.d/. Hooks (hooks/, hooks/late/), phase-named overlays (<phase>.overlay/) and generator content (dracut/initramfs-tools) are now found by walking the build plan, not through fixed tables or assetdir lookups. Shared scripts and hooks have moved underbuiltin/. X-Env-Layer-AfterProvidernow only orders. It no longer fails the build when the provider is missing. Add the provider toRequiresProviderif you relied on that check.- Boot configuration is assembled from fragments:
- config.txt is built from config.txt.d/ drop-ins provided by layers
- kernel command line fragments now live in for/linux-base/cmdline.d/
- the templates/rpi/boot-firmware templates and rpi-image-base have been removed
- Hooks and tools run with a sanitised environment. Layers that relied on variables inherited from the calling shell must declare them.
- IDP generation is opt-in through IGconf_image_idp_enable. It's switched on automatically for Raspberry Pi devices.
- Deployed artefacts all share one base name, taken from the image name and version. This fixes doubled versions, an unnamed OTA bundle, and the IDP bundle missing from the manifest.
slot-sharedno longer overwrites shared files at boot. Use the newStaticPath=for content the image should own.- The EEPROM auto-updater is off by default on slotted (A/B) boots, such as
image-rota. - erofs-utils is now 1.9.4. Images built with it differ from 2.8.0 builds of the same content.
What's Changed
- CM5 Jig Refinements by @tdewey-rpi in #312
- contrib: add sample cloud-init skeleton by @danielfdickinson in #309
- pkg: update util-linux url by @learmj in #315
- Unification of hooks and overlays around a layer-driven, per-layer .d/ convention by @learmj in #314
- per-layer work dir, doc improvements by @learmj in #317
- Documentation improvements by @learmj in #319
- Hook execution fix and doc updates by @learmj in #320
- Localised hook tidy ups: sbom, deploy & image-rota by @learmj in #321
- Unify build artefact basename, fix postimage by @learmj in #323
- Automatically enable IDP for Raspberry Pi device builds, opt-in for others by @learmj in #324
- webkiosk: Don't persist Chromium run-time data by @learmj in #325
- Add microboot image support by @learmj in #326
- Deploy SOURCE_DATE_EPOCH and make build metadata reproducible by @learmj in #327
- Add boot.img signing command support and reproducible generation by @learmj in #330
- doc: autogen by @learmj in #331
- image-rota: seed the erofs system slot verity salt by @learmj in #332
- Fix size validator suffix compatibility with genimage by @kvnloo in #333
- Declare fetch and xz unpack dependencies by @kvnloo in #334
- webkiosk: add seatd to packages by @learmj in #343
- builtin: write SOURCE_DATE_EPOCH in setup by @learmj in #344
- Add late hooks and fragment assembly by @learmj in #341
- image-rpios: Add devid_scheme for PARTUUID device identification by @XECDesign in #328
- examples: fix the SSH public key examples by @XECDesign in #350
- core: strip only the wrapping quotes in runenv by @XECDesign in #348
- device-user-admin: add multi-user account creation by @learmj in #351
- examples: Add multi-user switchable desktop/kiosk by @learmj in #352
- contrib/net: update example networks for current base and verify builds by @devopsbob in #353
- Improve robustness of initramfs-tools root device probe and wait by @learmj in #347
- cryptroot: Implement hw key locking by @learmj in #356
- lib: pass XDG_RUNTIME_DIR through runsafe by @learmj in #359
- core: record the project revision as BUILD_ID by @learmj in #362
- raspbian and container build fixes by @learmj in #363
- engine: AfterProvider is now order-only by @learmj in #364
- contrib/net: reconcile example networks with order-only AfterProvider by @devopsbob in #365
- Clarify cloud-init example scope and Imager boundary by @kvnloo in #338
- Assemble config.txt from layer drop-in fragments by @learmj in #358
- slot-shared: stop overwriting shared files at boot, add StaticPath by @learmj in #360
- examples: fix merged-usr firmware paths by @PaulMarisOUMary in #283
- package: Update erofs-utils to 1.9.4 by @learmj in #366
- core: allow layers to ship host executables by @learmj in #367
- engine: add pathlist validator by @learmj in #368
- locale-base: don't start console-setup service on readonly /etc by @learmj in #369
- trait: add boot:slotted and turn off EEPROM updates for slotted boots by @learmj in #370
- Document merged-usr paths for dpkg filters by @kvnloo in #339
- doc: autogen by @learmj in #371
New Contributors
- @danielfdickinson made their first contribution in #309
- @kvnloo made their first contribution in #333
- @XECDesign made their first contribution in #328
- @PaulMarisOUMary made their first contribution in #283
Full Changelog: v2.8.0...v2.9.0