MeshanicsDocs
Artifacts & bundles

Linux A/B system updates

Meshanics supports RAUC bundles for Linux devices that already have a qualified RAUC A/B image. Meshanics authorizes and delivers the release. RAUC remains responsible for writing the inactive slot, selecting the next boot, enforcing bundle signatures, and updating the bootloader state.

This path is for the base operating system, kernel, shared libraries, agent, and trust material that cannot be recovered safely as an ordinary file replacement.

What the device image must provide

The device image must already include:

  • RAUC with its system D-Bus service enabled;
  • exactly two rootfs slots with distinct boot names;
  • a supported bootloader backend and bounded boot-attempt policy;
  • the product RAUC certificate keyring;
  • enough persistent Meshanics data storage to retain the verified bundle and recovery journal; and
  • a rollout health probe that represents the product services required before a new slot may be marked good.

The Meshanics installer does not partition disks, install a bootloader, create a RAUC keyring, or convert an existing system into an A/B image.

Enable the adapter only on a prepared image:

MESHANICS_RAUC=true

The equivalent agent flag is -rauc.

Publish and authorize a bundle

Publish the exact .raucb file as an os-bundle. The artifact service measures its SHA-256 digest and size and publishes those exact bytes through TUF. The bundle must also carry a valid RAUC signature accepted by the device keyring.

Authorize the artifact with a customer-signed release manifest. The initial contract allows one OS bundle as the only component in that release. An OS bundle cannot join a multi-component transaction because reboot crosses the transaction boundary.

The device requires both trust layers:

  1. TUF authorizes and verifies the exact delivered bytes.
  2. RAUC verifies the product bundle signature, compatible string, version, and manifest hash against the device image.

The inspected RAUC manifest hash is passed back to InstallBundle as require-manifest-hash. This binds installation to the bundle that passed inspection.

Install and boot confirmation

Before installation, the agent requires an idle installer, a matching compatible string, a working bootloader primary query, one booted and one inactive rootfs slot, and a signed bundle accepted by RAUC.

The agent persists a recovery record before calling InstallBundle. After RAUC selects the inactive slot as primary, the agent records the staged and reboot-pending lifecycle events and asks Linux to reboot.

On the new boot, the signed rollout probe decides what happens:

  • A passing probe marks the booted slot good and commits the release.
  • A failing probe marks the booted slot bad and requests a reboot to the prior good slot.
  • A confirmed return to the prior slot records the rollout as reverted.
  • An ambiguous slot state is quarantined. The agent does not guess or mark it good.

Agent liveness alone is not a valid health authority. Configure a probe that checks the service or workload the product actually needs.

Evidence and integrations

The device-signed release receipt includes the RAUC compatible string, bundle version, manifest hash, previous slot, installed slot, observed boot slot, bootloader primary, mark operation, and final lifecycle phase. Download the exact receipt from Signed releases and verify it with the tenant device CA.

Lifecycle audit and webhook event types are:

  • os_update.staged
  • os_update.reboot_pending
  • os_update.booted
  • os_update.committed
  • os_update.reverted
  • os_update.quarantined

Webhook data contains identifiers, versions, manifest hash, and slot state. It does not contain bundle bytes.

Product qualification

RAUC integration does not establish that a product image or board has a correct bootloader attempt policy. Before production use, qualify the exact image and hardware profile with a successful installation, boot confirmation, deliberately failed health check, automatic return to the prior slot, interrupted installation and power-loss recovery. Repeat the qualification when the bootloader, partition layout, RAUC configuration or health authority changes.

Related