Documentation

Appearance

RAUC image OTA requirements ​

Use this checklist before enabling managed RAUC image updates for a Device Class. The requirements are platform-agnostic: a Raspberry Pi, Compute Module, industrial ARM board, x86 computer, or custom SoC can qualify. Hardware alone does not qualify. The image and boot chain must implement the complete contract.

Qualification checklist ​

  • [ ] The image has two real RAUC root filesystem slots, A and B.
  • [ ] A separate data partition is mounted at /var/lib/dataplicity. It is not part of either root filesystem slot.
  • [ ] Rescue, supervisor, and dp-converge are baked into /opt/dataplicity/venv on every slot.
  • [ ] Device identity, state, cache, config/current, content-addressed storage (CAS), image OTA state, and managed container storage are on the persistent data mount.
  • [ ] RAUC is connected to the bootloader used by this Device Class.
  • [ ] The bootloader counts failed attempts, persists the count across power loss, and automatically returns to the previous good slot.
  • [ ] The exact board, bootloader, and image-layout revision has passed the physical lab protocol below.

Hardware is not the image

A capable board is only the hardware starting point. A stock single-root operating-system image does not qualify, even when the board itself supports a valid RAUC design. Stock Raspberry Pi OS is one example: its normal single-root layout is not a RAUC A/B image with automatic slot rollback.

image_ota=manage is not safe until every checklist item is true. Most Dataplicity fleets do not use RAUC image management and need none of this layout. Leave image_ota off for those Device Classes.

Required image layout ​

The image must provide two independently bootable RAUC root filesystem slots. An update is installed to the inactive slot; the currently booted slot must never be the install target.

Every slot must contain the complete Dataplicity runtime:

text
/opt/dataplicity/venv

That runtime includes rescue, supervisor, and the fixed privileged helper /opt/dataplicity/venv/bin/dp-converge. Keeping the binaries in each signed root filesystem means an OS rollback also restores the matching Dataplicity runtime. Do not move these binaries onto the persistent partition.

Mount a separate data partition at:

text
/var/lib/dataplicity

The mount must be available before Dataplicity services start. Keep all data that must survive a slot change there, including:

  • device identity and agent state
  • downloaded image cache and image OTA state
  • features and config/current
  • content-addressed storage (CAS)
  • managed container images, layers, volumes, and other runtime state

Keep container storage off the RAUC root filesystem

On a dual-use image that runs Class Software, do not place the Docker, containerd, Podman, or equivalent container store on either RAUC root filesystem. A slot switch would lose or fork container state. Put the store, config/current, and CAS on /var/lib/dataplicity.

See Dataplicity agent for the wider on-device layout and Software and firmware boundaries for the distinction between an OS image and Class Software.

Bootloader rollback ​

RAUC must use the bootloader integration configured for the Device Class. Valid families include:

  • Raspberry Pi tryboot on supported Pi 4, Pi 5, and Compute Module designs
  • U-Boot with persistent, preferably redundant, boot environment
  • barebox bootchooser
  • EFI or GRUB with persistent slot selection and bounded attempts
  • a vendor bootloader that exposes equivalent RAUC slot control

The family is not important; its behaviour is. After an update selects the new slot, the boot chain must decrement a finite attempt counter before each boot. If the new slot never reaches the point at which Dataplicity can mark it good, the bootloader must exhaust those attempts and boot the previous good slot without help from the failed userspace.

The attempt counter and slot selection must remain coherent across abrupt power loss. Dataplicity deliberately waits for the new image to boot and reconnect before marking it good. The agent cannot replace bootloader-level rollback.

Examples ​

These are examples, not a hardware whitelist:

  • A Raspberry Pi Compute Module 5 with a purpose-built RAUC A/B image, persistent /var/lib/dataplicity, and correctly integrated tryboot can qualify. The same board running stock Raspberry Pi OS does not.
  • An industrial ARM gateway using U-Boot can qualify when RAUC slot names map to its real partitions and U-Boot automatically falls back after bounded failed attempts.
  • An x86 appliance using EFI can qualify when the EFI boot path persists its attempt counter and returns to the previous good entry automatically.
  • A custom SoC can qualify through its vendor bootloader when it provides the same RAUC slot selection, failed-boot counting, and automatic fallback guarantees.

Stock or vendor images with one root filesystem do not qualify on any board. Adding the RAUC package to such an image does not turn it into an A/B system.

Physical lab validation ​

Repeat this protocol for every board, bootloader, and image-layout revision. The protocol is the same regardless of CPU architecture or silicon vendor.

1. Healthy install and mark-good ​

  1. Boot known-good slot A and record RAUC status, including booted, primary, and inactive slots.
  2. Install a correctly signed test bundle into inactive slot B.
  3. Reboot into B and confirm the device reconnects through the Dataplicity rescue path.
  4. Confirm B is marked good only after the cloud connection succeeds.
  5. Confirm device identity, config/current, CAS, containers, and OTA state survived the slot change.

2. Failed-boot automatic rollback ​

  1. From known-good A, install a correctly signed B image that intentionally fails before Dataplicity can mark it good.
  2. Reboot and observe the bootloader decrement its persistent attempt counter.
  3. Power-cycle during an attempt and confirm the count and slot selection remain coherent.
  4. Let the attempts expire without userspace assistance.
  5. Confirm the bootloader automatically returns to A, RAUC reports A as the booted good slot, and Dataplicity rescue reconnects.

3. Short rescue soak ​

After the healthy update and rollback tests, run a short soak that includes normal reboots and at least one power interruption. Keep the rescue connection reachable and verify that identity and persistent state remain stable. Record the tested board revision, bootloader family and configuration, image-layout revision, maximum attempts, and results in the OEM quality system.

Unit tests and simulated RAUC output are useful engineering checks, but they do not replace this physical release gate.

Decide whether to enable image management ​

Enable image_ota=manage only for a Device Class whose production image and boot chain satisfy this page and whose physical qualification evidence is current. A class that only needs visibility can use the available observation mode without authorising installation.

For the non-RAUC majority, leave image OTA off. /var/lib/dataplicity remains an ordinary directory, and no A/B partition or bootloader change is required.