Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Experimental composefs aboot support

This page covers booting the composefs backend with an Android-style A/B boot image. For the repository layout, fsverity modes, and general composefs installation model, see the composefs backend documentation. Both the aboot integration and its on-disk state format are experimental.

Boot layouts

There are two supported ways to consume a /boot/aboot-<kernel-version>.img artifact:

Artifact encodingBootloader and boot partitions
Android boot image v2none; Android boot_a and boot_b, with no ESP
ukiboot imageukiboot; ESP with ukiboot, plus A/B boot images

The real Android layout deliberately has no ESP. For that payload, bootc infers bootloader none and does not install an EFI bootloader; the platform firmware and aboot-deploy manage the A/B boot partitions. Both layouts use the composefs backend for the root filesystem. They cannot be switched in place to or from the BLS/UKI layouts managed by GRUB or systemd-boot. Android and ukiboot layouts also cannot be switched in place.

Building an image

bootc container aboot computes the V1 and V2 composefs digests of the rootfs, adds both to the kernel command line, and invokes aboot-update to create the artifact. See EROFS formats for why both digests are included. /etc/aboot.cfg controls whether aboot-update emits an Android boot image or a ukiboot image (as well as other details). As with building a composefs UKI, split the kernel and initramfs from the rootfs before generating the boot artifact, then copy the generated aboot-<kernel-version>.img into the final image's /boot.

bootc container aboot --rootfs /target \
  --kernel-dir /kernel/KVER --out /out

The command checks that the generated artifact contains both expected composefs arguments. It requires aboot-update in the build environment; the installed system needs aboot-deploy for updates and rollbacks. If the root filesystem cannot enforce fsverity, pass --allow-missing-verity when building the artifact. This produces an unsealed image, as explained in composefs integrity modes.

Bootc automatically selects the native composefs backend, and bootloader none from an Android boot v2 payload and ukiboot from a ukiboot payload. An explicit bootloader setting is optional, but must agree with the payload. bootc container inspect --json reports "type": "aboot" for Android payloads and "type": "aboot-efi" for ukiboot payloads; image-builder uses this to select UEFI boot mode for ukiboot without a bootloader configuration file.

Modern aboot artifacts are discovered only under /boot. An aboot.img under /usr/lib/modules/<kernel-version> belongs to the legacy OSTree integration and does not select this backend. A matching vbmeta-<kernel-version>.img may accompany an Android payload. ukiboot payloads do not use vbmeta.

When installing the running container image, bootc install to-disk selects the backend and layout from its boot artifact and reads repart definitions from that same container. With --source-imgref, the source image's root filesystem is not available during preparation, so no aboot disk layout is inferred. The normally pulled image must match the selected encoding. Existing repart definitions are preserved. Supplied boot partition definitions must use the artifact's slot labels and partition type GUIDs. Bootc adds definitions for missing boot partitions and generates a root definition only when none is supplied. In that case, specify the root filesystem in the install configuration or with --filesystem. Android uses boot_a, boot_b, vbmeta_a, and vbmeta_b; ukiboot uses ukiboot_a, ukiboot_b, ukibootctl, and an ESP. Both layouts include a root filesystem and initialize both boot slots. Platform-specific sizing, device trees, and /etc/aboot.cfg settings remain the image builder's responsibility.

Prebuilt aboot command lines are immutable. Additional installation --karg arguments are rejected; include them when building the artifact.

Updates, rollback, and recovery

An update stores the new boot image (and optional vbmeta image) under /state/deploy/<deployment-id>/aboot/. A persistent pending record under /state/boot/aboot/ tracks those artifacts and their hashes. Staging does not write either boot partition. At shutdown, bootc verifies the artifacts, records the attempt, and requires an unambiguous booted slot and calls aboot-deploy to flash the inactive slot.

On the next boot, bootc records the observed androidboot.slot_suffix kernel commandline option and reconciles the attempted deployment. The previous slot becomes the rollback deployment; bootc rollback queues it through aboot-deploy --rollback. bootc status indicates when a rollback is queued.

After a failed flash or firmware fallback, bootc retains the attempted update for inspection. Bootc does not automatically retry the flash, including on subsequent reboots. Starting with the first boot after the failed attempt, bootc upgrade or bootc switch discards that staged update before preparing a new one. This also allows explicitly retrying the same image. bootc upgrade --check leaves the failed attempt untouched. During the boot that recorded the attempt, replacing or discarding it is blocked because its boot outcome is not yet known.

bootc rollback also discards the failed pending update when a valid rollback deployment is available. A failed flash may have overwritten the inactive slot, so discarding the attempt does not necessarily restore a rollback deployment.

The firmware's slot-selection and success-marking behavior is outside bootc. For example, the ukiboot enables ukiboot-set-success.service to mark a successful boot. Validate that behavior on the target hardware before relying on automatic fallback.


The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.