OTA Connect Developer Guide

Selectively trigger aktualizr

Aktualizr normally runs as a systemd service and regularly polls for updates. The default polling interval is set at 10s, and this should be increased by a few orders of magnitude in a production system.

It is also possible to trigger the update cycle, or individual parts of the update cycle, manually or programmatically. This is done by using aktualizr’s --run-mode option, or just supplying the operation name as a subcommand.

For production use, however, we recommend using a wrapper around libaktualizr instead.

To selectively trigger aktualizr, you should disable the systemd service. If aktualizr runs continuously, it interferes with the manual triggering.

To run the update cycle manually, first stop and disable the aktualizr background service:

systemctl stop aktualizr && systemctl disable aktualizr

Assuming aktualizr is being built using Yocto and meta-updater, the systemd service can also be disabled by default by adding the following to local.conf:

SYSTEMD_AUTO_ENABLE_aktualizr = "disable"

Triggering an entire update cycle

An update cycle consists of:

  1. Polling the server for updates and downloading (and verifying) update metadata.

  2. Downloading (and verifying) any update binaries available.

  3. Installing the update.

  4. Reporting the install results.

To trigger the whole cycle, use the following command:

aktualizr once

Triggering individual update stages

It might not be desirable to always trigger a complete update cycle. For example, you may want to check for updates and download them, but get user permission before installing. Or, you may want to download an update when there is network connectivity then perform the installation later, without relying on the network. (Note that aktualizr is always safe against network drops. The worst that can happen if the network becomes unavailable is that the update will fail and need to be retried later.)

Triggering an update check

Fetch the Uptane metadata:

aktualizr check

Downloading an available update

Download an update:

aktualizr download

Installing downloaded update(s)

aktualizr install

Reporting installation results

Installation reports are sent when aktualizr polls the server for updates, so the check run-mode should be used again after installing:

aktualizr check

Check for campaigns that target the device

Campaigns provide a way to target software updates to specific groups of devices. You can set up campaigns in the OTA Connect web app. When a device comes online that matches the targeting criteria of a campaign, the OTA Connect server notifies the device that new software updates are available.

aktualizr campaign_check

If the device is targeted by one or more campaigns, aktualizr prints details of each applicable campaign including the campaign ID. You can then use the campaign ID for the campaign_accept command.

Accept campaigns that target the device

This run mode works together with the campaign_check mode. After you have received a list of applicable campaigns, you can accept the campaigns so that they are included in the software update process.

aktualizr campaign_accept --campaign-id=<CAMPAIGN_ID>

For example:

aktualizr campaign_accept --campaign-id=4df1a199-59d4-47f6-a261-d79b83020f65

Once aktualizr has accepted the campaign, the scheduled update becomes available to the device. The device can then install the update during a normal full update cycle or when the device runs in check mode.