image-rota

image v7.0.0

Immutable GPT A/B layout for rotational OTA updates, boot/system redundancy, and a shared persistent data partition.

Additional Documentation

Immutable root and mount points

This system uses an A/B, read‑only root with all writable state on a single persistent partition.

Mount point Backing Type Notes

/

/dev/disk/by-slot/active/system

erofs or ext4

ro System root (active slot A or B)

/boot/firmware

/dev/disk/by-slot/active/boot

vfat

ro Boot files (active slot A or B)

/bootfs

BOOTFS

vfat

rw Boot metadata

/persistent

PERSISTENT

ext4

rw Shared persistent storage

The persistent mount point is set by IGconf_image_persistent_dir (default /persistent). The partition is checked and mounted in the initramfs.

  • Rationale (immutable root + A/B)

    • Supports delta/incremental OTA updates by treating root as a static image.

    • Reliable rollbacks: slot can be flipped if a new root fails health checks.

    • Reduced write amplification and storage wear, clearer separation of state.

    • Preserves SBOM accuracy: executing software matches the manifest exactly.

    • Blocks on-device package installs, preventing SBOM drift.

    • Enables auditable, reproducible releases and stronger supply-chain assurances.

State on the persistent partition is handled by layer slot-state.

Slot Selection (run-time)

Handled entirely by layer rpi-ab-slot-mapper.

Slot Pairing (build-time)

Definition

This layer generates an image which has bit-for-bit identical A/B slot members:

  • Both a.boot and b.boot contain the exact same vfat filesystem.

  • Both a.system and b.system contain the exact same ext4 filesystem.

  • Filesystem UUIDs are intentionally identical across slots.

  • GPT partition GUIDs (PARTUUID) are unique per partition.

  • GPT partition labels (PARTLABEL) are unique per partition.

Rationale and benefits

  • Faster image creation: only a single slot pair is produced.

  • Simpler updates: only a single slot pair is built, tested, and distributed.

  • Update generation: operating on a single slot pair is unambiguous.

  • Smaller CI/storage footprint: fewer images to store.

Requirements and constraints

  • Does not use UUID= anywhere. Duplicate filesystem UUIDs make /dev/disk/by-uuid/* ambiguous.

  • Uses stable identifiers instead, e.g. /dev/disk/by-slot/{active,other}/{boot,system}.

Encrypted (LUKS) Provisioning Map layouts

  • Identical content inside LUKS is supported. Slot mapping can use GPT labels or static map triplets to identify mapper:<name>:<part> slot components.

Relationships

Depends on:

image-base device-base rpi-ab-slot-mapper systemd-min slot-state

Provides: image, boot:slotted

Configuration Variables

References: IGconf_device_storage_type, IGconf_device_class

Declares (prefix: image):

Variable Description Default Validation Policy
IGconf_image_boot_part_size Boot partition size per-slot. 96M Size value with optional unit (bytes, k/K/M/G/s) or percentage immediate
IGconf_image_system_part_size System partition size per-slot. 512M Size value with optional unit (bytes, k/K/M/G/s) or percentage immediate
IGconf_image_data_part_size Writable data partition retained across slot rotations. 1G Size value with optional unit (bytes, k/K/M/G/s) or percentage immediate
IGconf_image_persistent_dir Mount point of the data partition. /persistent Must match regex pattern: ^(?!/(var|home)(/|$))(/[A-Za-z0-9_][A-Za-z0-9._-]*)+$ immediate
IGconf_image_rootfs_type Root filesystem type for each system partition. erofs Must be one of: ext4, erofs immediate
IGconf_image_assetdir Image specific asset directory ${DIRECTORY} Path to an existing directory immediate
IGconf_image_pmap Provisioning Map type for this image layout. clear: All partitions will be provisioned unencrypted. crypt: All non-boot partitions will be provisioned encrypted. cryptslots: Only system OS partitions will be provisioned encrypted. cryptdata: Only the data partition will be provisioned encrypted. clear Must be one of: clear, crypt, cryptslots, cryptdata immediate
IGconf_image_ptable_protect Enable eMMC Power-On Write Protect of the partition table. If enabled, the first 8MB of the boot storage device will be protected. Applies to eMMC only. n Boolean value - accepts: true/false, 1/0, yes/no, y/n (case insensitive) lazy
IGconf_image_compression Compression scheme used for update payloads. zstd Non-empty string value immediate
IGconf_image_updatefmt Format of the update bundle produced for this image. none: No update bundle. otamaker: Raspberry Pi Connect Remote Update bundle. none Must be one of: none, otamaker lazy
IGconf_image_updatetpl otamaker contents template used to pack the update bundle. References of the form ${IGconf_<name>} are substituted from the build environment. Payload sources are resolved relative to the image output directory. ${DOTD}/device/otamaker-full.yaml Path to an existing non-empty regular file lazy

mmdebstrap

Packages

Installs:

Overlays

Phase Overlay
customize customize.overlay

Hooks

Phase Hooks
customize customize03-emmc-ops, customize05-pmap, customize10-kernel, customize10-templates, customize15-cryptroot
preimage preimage05-templates, preimage10-immutable-root, preimage15-persistent-skel
postimage postimage05-pack-update
deploy deploy05-update

Attributes

File: gpt/ab_userdata/image.yaml

Type: static