Update Management

Overview

The BCA reference design uses RAUC (Robust Auto-Update Controller) as the update framework for both Open World and Bunker OS. RAUC is pre-integrated into the reference design meta-layers. All configuration variables, partition definitions, U-Boot environment integration, and a simplified development key-pair generation are already provided out of the box.

Key properties of BCA software updates:

• Full rootfs only. Incremental or delta updates are not currently supported. Each update bundle replaces the entire root filesystem of the target domain.

• Always signed. Every bundle is signed with an RSA key/certificate pair. RAUC verifies the signature before writing anything to storage.

• Always encrypted. Bundle encryption protects the update payload during download and transit. Bunker OS performs additional hardware-backed verification during installation.

• A/B partition scheme with automatic rollback. Each domain maintains two rootfs slots (A and B). A failed update or a system that does not successfully boot is automatically rolled back to the previously committed slot.

• Reboot required. The new rootfs only becomes active after a reboot. RAUC handles the bootloader slot selection (U-Boot A/B environment variables) and marks the slot good or bad after the next successful boot.

Update Domains

Open World and Bunker OS are updated independently. They each have their own RAUC configuration, their own bundle recipe, and their own signing keys.

Domain	Updated slots	Who installs the bundle
Open World	rootfs A/B	Open World (rdfm-client or manual rauc install)
Bunker OS	rootfs A/B and boot partition	Bunker OS (receives bundle from Open World via AuthFS)

        graph TD
    subgraph Build["CI / Developer Machine"]
        BuildOW["bitbake open-world-bundle"]
        BuildBOS["bitbake bunker-os-bundle"]
        BundleOW["open-world-update.raucb"]
        BundleBOS["bunker-os-update.raucb"]
        BuildOW --> BundleOW
        BuildBOS --> BundleBOS
    end

    subgraph Device["Reference Design Device"]
        subgraph OW["Open World"]
            Client["rdfm-client / manual install"]
            RAUCOW["RAUC (Open World)"]
            RootfsOW["rootfs A / rootfs B"]
            Client -->|"1. download bundle"| BundleOW
            Client -->|"2. rauc install"| RAUCOW
            RAUCOW --> RootfsOW
        end
        subgraph BOS["Bunker OS"]
            AuthFS["AuthFS receive"]
            RAUCBOS["RAUC (Bunker OS)"]
            RootfsBOS["rootfs A / rootfs B + boot partition"]
            OW -->|"3. share bundle via AuthFS"| AuthFS
            AuthFS -->|"4. rauc install"| RAUCBOS
            RAUCBOS --> RootfsBOS
        end
    end

    BundleOW --> Client
    BundleBOS --> OW
    

Bunker OS Update Flow

Bunker OS does not have a direct internet connection. The standard delivery path for a Bunker OS bundle is:

1. Build. The Bunker OS bundle (bunker-os-update.raucb) is built as part of the Yocto build. It contains the rootfs image, boot partition image (hypervisor, OP-TEE, U-Boot), and the signed manifest.

2. Download by Open World. Open World (which has network connectivity) downloads the Bunker OS bundle from the fleet management server or a local artifact store using rdfm-client or a custom mechanism.

3. Transfer via AuthFS. The bundle is placed in a shared AuthFS volume that Bunker OS can access. AuthFS guarantees integrity and authenticity of the data crossing the domain boundary; Bunker OS can trust that the file it reads has not been tampered with by Open World.

4. Install by Bunker OS. A service in Bunker OS calls rauc install against the received bundle. RAUC verifies the bundle signature and, if valid, writes the new rootfs to the inactive A/B slot and updates the boot partition.

5. Reboot. The system reboots. U-Boot selects the new slot as primary. RAUC’s rauc-mark-good service runs after userspace comes up and marks the slot good. If the system fails to boot correctly, U-Boot decrements the retry counter and eventually falls back to the previously committed slot.

Note

The boot partition update (hypervisor, OP-TEE, firmware) is unique to Bunker OS. Open World only updates its own rootfs and does not touch the boot partition. This is by design: Bunker OS controls the root of trust for the entire platform.

Open World Update Flow

Open World updates follow a simpler path because Open World has direct network connectivity and updates only its own rootfs A/B partitions.

The reference design uses rdfm-client to check for new packages from the RDFM fleet management server and trigger RAUC installation automatically. See Ship OTA Updates for the RDFM-managed workflow.

For manual or custom deployments, you can install a bundle directly:

rauc install /path/to/open-world-update.raucb

Note

Open World is free to adopt a different update tool or schema if your deployment requires it. RAUC is the reference implementation and is pre-integrated, but you can substitute your own mechanism as long as the A/B partition layout and U-Boot environment variables are maintained correctly. Contact support if you need guidance on integrating a different update client.

Filesystem Safety During Updates

Bunker OS runs with an immutable, integrity-verified rootfs. The filesystem is mounted read-only and protected by dm-verity. RAUC writes the new image to the inactive A/B slot while the running system remains on the active (read-only) slot. The active rootfs is never modified during an update.

The data partition (read/write) is separate from the rootfs slots and is never touched by a RAUC update. User data, configuration state, and runtime files stored on the data partition persist across updates.

Bunker OS storage layout (example eMMC):

/dev/mmcblk0p1  -> boot partition  (hypervisor, OP-TEE, U-Boot - updated by RAUC)
/dev/mmcblk0p2  -> U-Boot environment
/dev/mmcblk0p3  -> rootfs A  (RAUC slot, read-only + dm-verity)
/dev/mmcblk0p4  -> rootfs B  (RAUC slot, read-only + dm-verity)
/dev/mmcblk0p5  -> data partition  (read/write, untouched by updates)

Open World storage layout (example eMMC):

/dev/mmcblk1p1  -> U-Boot environment
/dev/mmcblk1p2  -> rootfs A  (RAUC slot)
/dev/mmcblk1p3  -> rootfs B  (RAUC slot)

See Storage Models for full partition layout details and the trade-offs between single-storage and dual-storage configurations.

Building Update Bundles

Bundle recipes are included in the BCA reference design meta-layers. To build a bundle you only need to run a bitbake command. All variables (RAUC_BUNDLE_COMPATIBLE, RAUC_BUNDLE_SLOTS, RAUC_BUNDLE_FORMAT, RAUC_KEY_FILE, RAUC_CERT_FILE) are already set for each image type.

# Build the Bunker OS update bundle
source oe-init-build-env build
bitbake bunker-os-bundle

# Build the Open World update bundle
bitbake open-world-bundle

The signed .raucb bundle files are placed in tmp/deploy/images/<machine>/ in your build directory.

Bundle Recipe Structure

The bundle recipes inherit bundle.bbclass from meta-rauc and declare the slot contents. A minimal example of what such a recipe looks like in the reference design:

# recipes-core/bundles/bunker-os-bundle.bb
inherit bundle

RAUC_BUNDLE_COMPATIBLE = "bunker-os-<machine>"
RAUC_BUNDLE_FORMAT     = "verity"
RAUC_BUNDLE_SLOTS      = "rootfs boot"

RAUC_SLOT_rootfs       = "bunker-os-image"
RAUC_SLOT_boot         = "boot-image"
RAUC_SLOT_boot[type]   = "boot"

RAUC_KEY_FILE  = "${COREBASE}/meta-bunker/files/development.key.pem"
RAUC_CERT_FILE = "${COREBASE}/meta-bunker/files/development.cert.pem"

Important

The development key/certificate pair shipped with the reference design is for development use only. Replace RAUC_KEY_FILE and RAUC_CERT_FILE with production keys protected by your PKI before releasing a product. See Meta Layers Reference for guidance on key configuration in the meta-layers.

Using the RAUC Host Tool

The RAUC native binary can be built and used on the host machine for manual bundle creation, inspection, or testing:

# Build the RAUC native binary
bitbake rauc-native

# The binary is placed in tmp/deploy/tools/
tmp/deploy/tools/rauc --version

# Inspect a bundle
tmp/deploy/tools/rauc info my-update.raucb

# Manually create a bundle (advanced use)
tmp/deploy/tools/rauc bundle \
    --cert=cert.pem \
    --key=key.pem \
    install-content/ \
    my-update.raucb

For full documentation on manual bundle creation and the manifest format, see the RAUC bundle generation guide.

Installing Bundles

Bundles are installed by calling rauc install on the target system. RAUC determines which slot is currently inactive, writes the new image there, and updates the bootloader state.

# Install a bundle (on the target, in Open World or Bunker OS)
rauc install /path/to/update.raucb

# Reboot to activate
reboot

RAUC validates the bundle signature against the keyring installed at /etc/rauc/ca.cert.pem before writing anything. If the signature is invalid, the installation is rejected and the running system is unaffected.

Checking Update Status

# Show current slot status, active slot, and boot state
rauc status

# Show detailed slot information
rauc status --detailed

# Mark the currently booted slot as good (normally done automatically at boot)
rauc status mark-good

Example output:

=== System Info ===
Compatible:  bunker-os-qemuarm64
Variant:
Booted from: rootfs.0 (A)

=== Slot States ===
[rootfs.0] (/dev/mmcblk0p3, ext4, installed)
  bootname: A
  boot status: good
[rootfs.1] (/dev/mmcblk0p4, ext4, installed)
  bootname: B
  boot status: good

Rollback Behaviour

If the system fails to boot from the newly installed slot (for example, the rootfs is corrupted, or the rauc-mark-good.service does not run), U-Boot decrements the BOOT_<slot>_LEFT counter on each failed attempt. When the counter reaches zero, U-Boot falls back to the other slot automatically. No manual intervention is required.

This means a failed update is safe: the device always returns to a known-good software version.

Key Management

RAUC enforces bundle signing. The reference design ships a development RSA key/certificate pair suitable for local testing. For production you must generate and protect your own keys.

The reference design meta-layers provide a helper script for generating development keys:

# From within the meta-bca layer (see meta_layers_reference for exact path)
./scripts/create-development-keys.sh

# This produces:
#   development.key.pem   — private signing key (keep secret)
#   development.cert.pem  — public certificate  (deployed to device keyring)

The certificate is installed into the target rootfs as /etc/rauc/ca.cert.pem by the rauc-conf recipe. Any bundle signed with the corresponding private key will be accepted on that device.

Important

In production, generate keys using a proper CA infrastructure, store private keys in an HSM or secret management system, and distribute only the certificate to the device keyring. Refer to the RAUC security documentation for certificate authority configuration options.

For all meta-layer variables, recipe locations, and customization guidance, see Meta Layers Reference.

Next Steps

• Storage Models — Partition layouts, single vs. dual storage, and the storage principles underpinning update safety

• Ship OTA Updates — RDFM-managed OTA delivery: packages, device groups, update policies, and automated rollout

• Fleet Management Overview — Fleet management architecture and the RDFM component stack

• Boot Flow — Secure boot, hypervisor verification, and how the root of trust relates to update integrity

• Meta Layers Reference — Meta-layer structure, RAUC recipe variables, and key configuration