Documentation

Appearance

RAUC image OTA requirements #

Use this checklist before enabling managed RAUC image updates for a Device Class. Dataplicity OS supplies a ready-made CM5 implementation of this contract. You can also use your own Linux image and boot chain. Both paths use the same qualification requirements and managed delivery.

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. Your image and boot chain must implement the complete contract.

Qualification checklist #

These requirements apply to the exact image and boot chain you ship, whether you start from Dataplicity OS or build your own Yocto, Buildroot, or distribution image.

  • [ ] 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.
  • [ ] data_root in agent.yaml resolves to that persistent mount, while volatile_dir resolves to tmpfs or ramfs for high-rate no-retention data. Any durable_mount is an explicit, endurance-qualified OEM choice.
  • [ ] 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.
  • [ ] casync is present in both A/B root filesystems when you want chunked delta downloads for OS images and Class Software container artefacts (same class of image requirement as A/B slots for the delta path; without it the agent falls back to the full artefact). Non-RAUC fleets that only ship Containers still need casync on the image for container deltas.
  • [ ] 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 required 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.

Run the on-device qualifier #

After a full (supervisor) Dataplicity install, the installer prints an informational RAUC image check. The report never fails the install: devices without RAUC remain valid Dataplicity devices.

Re-run it any time:

sh
dataplicity rauc-ready
prelude-agent rauc-ready
dp-rauc-ready

Each check prints PASS, FAIL, or UNKNOWN, plus a one-line fix when something is missing. Missing casync is reported but does not make the host “not ready”: full artefact download still works. Use dataplicity rauc-ready --require only in CI or imaging scripts that must stop when A/B layout, persistence, or bootloader evidence fail. The one-line installer accepts DP_REQUIRE_RAUC=1 for the same gate.

The qualifier cannot replace the physical failed-boot test below. It proves what userspace can see on this boot.

Required image layout #

Your 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.

Use the complete storage example and component matrix in Integrate Dataplicity with your Linux image. RAUC does not require Class Software, and Class Software does not require RAUC. If both are enabled, the persistent agent and container paths must survive a slot switch while the volatile path remains RAM-backed.

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 of customer-built images that can qualify, not a hardware whitelist and not Dataplicity-supplied OS images:

  • 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 you ship. The protocol is the same regardless of CPU architecture or silicon vendor. This is validation of your image; Dataplicity does not perform it for you.

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 your quality system.

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

Automatic delta downloads #

Chunked/delta downloads require casync on the customer image. Include casync in both A/B root filesystems (or in the single root filesystem for non-RAUC fleets) for bandwidth savings on both OS images (.raucb) and Class Software container artefacts (OCI/docker tarballs). Without it, the agent falls back to the full artefact URL. That full-artefact path remains correct; it simply transfers more bytes.

Operators upload one big file. After verification (RAUC signature for .raucb, digest/size for Software), Dataplicity indexes the artefact server-side with the same casync make pipeline into a shared chunk store (per Device Class for OS images; per microservice for Software). You do not run casync make, generate .caibx files, or upload chunk stores.

Devices reconstruct with casync extract when the binary is present, seeding from cached artefacts and readable local bytes when possible. Without casync, or if reconstruction fails, the agent downloads the full artefact. Either path must still match catalog size and SHA-256 before install or container import. RAUC CMS signature checks remain mandatory for OS images.

There is no native agent chunk reader yet. Putting casync in your image is the supported way to get delta savings for OS images and Containers. Fleets that leave image_ota off still get Software/container deltas when they upload container artefacts and include casync on the device image.

OS images and Containers #

Managed RAUC updates are the OS images line. Class Software remains the Containers line. They are independent pins with independent version history.

On a Device Class that has image OTA enabled, the operator UI separates:

  • OS images - signed .raucb catalog, image pins, and image rollouts
  • Containers - Class Software compose sets and container pins

Device status shows both when image OTA is not off, for example Software <set> · Image <version> slot A good. Do not collapse them into one firmware number. See Software and firmware boundaries.

Staged rollouts by device tag #

Image rollouts use the same device-tag cohort model as Software rollout groups. Target a wave with tags (for example canary, region, or hardware revision), limit concurrency, pause when needed, and expand to the next tag cohort after the previous wave looks healthy.

Image rollback does not change the Software pin. Software rollback does not switch RAUC slots. Leave image_ota off until the class is qualified; enabling manage authorises installation, not automatic fleet-wide push.

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.