How does OTA update with RAUC work?

The agent uses RAUC for OTA A/B image updates. It supports both regular file transfer as well as streaming. The image can be created as a delta update or as a full update bundle.

We provide you with some tutorials and additional information about this functionality:

• This RAUC tutorial explains how to create a real image for a real device.

• We also have a tutorial that allows to test all this in a Docker container environment on a virtual device.

• Here we show an example how this can be implemented for the Raspberry Pi 5.

The RAUC configure UI

The basic UI is described in the configuration UI.

The pre-condition functionality is explained here. It controls when the update happens such that it does not happen while devices are in use.

The reboot condition works alongside the pre-condition. It is a shell command that runs on the device after a successful install: if it exits with status 0 the device reboots, otherwise it keeps running. Leaving the reboot condition empty means the device always reboots after a successful install. How the two fields interact, and why it matters, is explained in Controlling when updates apply.

The RAUC update image bundle has to be uploaded into the file manager. Then pressing the folder icon opens the dialogue to pick the relevant update bundle.

Some systems support RAUC streaming while others only allow full bundle downloads. If your system does not support streaming then please select "Download RAUC bundle".

The default path for bundle downloads is /tmp/bundle.raucb. If for some reason this differs in your system it is easy to adopt this in the UI.

Controlling when updates apply

RAUC writes the new image to the inactive partition. The new image only becomes active when the device reboots and switches to that partition, so without a reboot the update is installed but not running. After a successful install, if the reboot condition passed, the agent schedules a reboot at the end of the agent run (shutdown -r +1, roughly one minute later). The reboot is scheduled, not immediate.

There is no separate update-scheduling feature in Qbee. Update timing is controlled through the pre-condition and the reboot condition, combined with device groups and tags. The pre-condition is re-evaluated on every agent poll, so it is the primary hook for time-based or state-based gating. The reboot condition is evaluated only once, on the run that performs the install (see the warning below).

Maintenance windows

To restrict updates to a maintenance window, set a pre-condition script that returns 0 only during the window (for example, checking the current time against an allowed range) and reference it from the pre-condition field. The script is distributed and wired up exactly as for package updates; see Update with pre-condition, which includes a ready-made time-window script and the file-distribution steps. Use the pre-condition for time-based gating, not the reboot condition (see the warning below for why).

Staged rollout (delay after release)

There is no built-in mechanism to delay an update by a fixed number of days after it is committed. Staged rollout is done through device groups and tags: commit the RAUC configuration to a small test group first, verify the rollout on those devices, then commit the same configuration to broader groups as you gain confidence.

User-controlled update

To let an update proceed only on an explicit trigger, set a pre-condition that checks for a flag file or environment variable on the device. The update runs only when the flag is present, and the flag can be created through file distribution, remote access, or a local process. See the "check if a file or environment variable exists" example under Update with pre-condition.

The reboot condition is evaluated only once

The reboot condition runs only on the agent run that performs the install. If it returns non-zero on that run, it is not re-checked on later polls. The reason is that once the image is installed, RAUC marks the newly-written slot as the one to boot next, and that slot's hash now matches the bundle; on every later poll the agent sees nothing left to install, skips the install block, and never reaches the reboot condition again. The device is left with the new image staged as the next-boot target but not rebooted, and it will not reboot until something else triggers it.

If you need to gate reboot timing, make sure the reboot condition returns 0 during the install run itself, or gate the whole flow (install and reboot together) with the pre-condition instead. This is why maintenance windows must use the pre-condition rather than the reboot condition: the pre-condition is re-evaluated every poll, so the window will eventually open, the install will proceed, and the default (empty) reboot condition will trigger the reboot in the same run.