Immutable GPT A/B layout for rotational OTA updates, boot/system redundancy, and a shared persistent data partition.
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.
Handled entirely by layer rpi-ab-slot-mapper.
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.
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.
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}.
Identical content inside LUKS is supported. Slot mapping can use GPT labels or static map triplets to identify mapper:<name>:<part> slot components.
Depends on:
Provides: image, boot:slotted
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 |
Installs:
dosfstoolse2fsprogsdracut| Phase | Overlay |
|---|---|
customize |
customize.overlay |
| 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 |
File: gpt/ab_userdata/image.yaml
Type: static