Ship OTA Updates

Overview

The RDFM OTA update system for the reference design provides full-image A/B partition updates. A package is a complete rootfs binary artifact that a device installs to advance its software to a new version. A device is any system running the rdfm-client daemon that regularly checks in with the management server. A group is a collection of devices that share an update assignment, an update policy which specifies the target software version all members should be updated to.

All updates use an A/B partition layout managed by RAUC (Robust Auto-Update Controller). The reference design implementation uses RAUC instead of the upstream Mender system. When a device polls for a new version, the server checks if a newer package exists that is compatible with the device’s type. If found, the device downloads and installs it to the passive partition. If the update installation fails or the newly installed system fails its health checks, RAUC automatically rolls back to the previously committed partition without any manual intervention.

Key Concepts

Packages

A package is any file that can be consumed by a compatible RDFM device client to update the running system. From the server’s perspective, packages are opaque binary blobs; the server enforces no structure on their contents. Each package carries a mandatory set of metadata that drives the update resolution logic:

  • rdfm.software.version: the software version this package installs.

  • rdfm.hardware.devtype: the device type this package is compatible with; packages are never offered to devices of a different type.

Devices

From the server’s point of view, a device is any system running an RDFM-compatible client. Each device actively reports its metadata at every update check. The mandatory fields are:

  • rdfm.hardware.macaddr: the MAC address of the device’s primary network interface, used as the unique device identifier throughout the system.

  • rdfm.software.version: the version string of the currently running software.

  • rdfm.hardware.devtype: the hardware device type, used to restrict package compatibility.

Devices appear in the management server as soon as they successfully authenticate for the first time. Before a newly registered device can interact with the update API, an administrator must explicitly authorize it through the frontend or REST API. This authorization step ensures that unknown or unconfigured devices do not automatically receive software from the fleet.

Groups

A group is a named collection of devices that all share the same update assignment. Devices can be members of at most one group at a time. Each group has an associated update policy that declares the target version all member devices should be updated to. Groups also carry arbitrary metadata fields: name, description, and any custom key/value pairs, that can be used by custom frontends or automation scripts.

Update Policy

The update policy is a string field on a group that controls what the server returns to devices polling for updates. Two policies are available:

no_update (default)

The server treats all devices in the group as up-to-date and returns no package for installation. This is the default for newly created groups and is useful for temporarily pausing updates to a specific fleet segment.

exact_match,<version>

The server checks if a package with the specified target version exists in the group. If found and the device is not already running that version, the package is offered for installation. If no package matches the target version, no update is offered.

Update Process

When a device polls for updates, the server checks its current version against the group’s update policy target. If a newer package exists that is compatible with the device type, the server provides a signed download URL. The device downloads the package and writes it to the passive partition via RAUC. If installation succeeds and the system boots successfully from the new partition, RAUC commits the update. If installation fails or the new system fails its health checks, RAUC automatically rolls back to the previously running partition.

Devices already running the target version receive no update. If the group policy target does not match any available package, devices receive no update until a matching package is uploaded or the policy is changed.

Update Scenarios

Simple Update Assignment

A single package is uploaded and assigned to a group. Its rdfm.hardware.devtype matches the device type of all group members and its rdfm.software.version is set to the target version in the group policy. Every group member running any version other than the target will receive this package during its next update poll. Members already at the target receive nothing.

Version Downgrade

Downgrades work the same as upgrades. If the group policy target is set to an older version v2 and a package version=v2 exists in the group, devices running any other version will receive it during the next poll. No special configuration is required.

Managing Packages and Groups

Package Upload

Packages are uploaded to the management server over the REST API or through the web frontend. The upload endpoint accepts the package binary and its metadata as a multipart form. The metadata fields rdfm.software.version and rdfm.hardware.devtype must be present in every upload request. Optional requires: fields are provided as additional metadata key/value pairs.

For rootfs image artifacts, the uploader must hold the rdfm_upload_rootfs_image OAuth2 scope (or full rdfm_admin_rw access). Delta artifacts require the same scope. Single-file artifacts require rdfm_upload_single_file. See Server Deployment for the full access control model.

Group Management

Groups are created, modified, and deleted through the frontend or REST API. Creating a group requires the rdfm_create_group scope. Once created, packages are assigned to the group individually. A single group can hold an unlimited number of packages; the resolution algorithm considers all of them when calculating the shortest update path.

The group’s update policy is set through the same API. Changing the policy takes effect immediately: devices polling after the change will receive the new target version. Setting the policy to no_update pauses updates for the entire group without removing any package assignments.

Device Authorization

Devices register themselves automatically on first contact with the server by submitting their metadata and a signed authentication request. Until an administrator explicitly authorizes the device through the frontend or API, the device is in a pending state and receives no updates. Authorization can be revoked at any time; a revoked device is rejected on its next authentication attempt and falls back to polling behaviour. Pending and revoked device lists are visible in the web frontend under the Devices section.

Next Steps