Introduction

Aktualizr is an implementation of Uptane OTA update client. Uptane is an open and secure software update system design which protects software delivered over-the-air. The aktualizr client is intended to be installed on devices that wish to receive OTA updates from an Uptane-compatible OTA server such as Torizon OTA, and it is already integrated in TorizonCore.

Prepare for Production

We recommend that you use the TorizonCore Builder Tool to apply customization options to TorizonCore, once you are satisfied with tweaking the device configuration.

Intended Audience

If you just want to use the Torizon OTA with default settings, it will abstract the use of Aktualizr for you, therefore you can skip this article. If you want to learn more, or if you plan to only use the Aktualizr capabilities from TorizonCore, but you don't plan to use Torizon OTA, then this article may be useful for you.

This article is also useful for learning how to modify some useful configurations, such as how to block updates, update the server polling time, disable the automatic reboot, among others.

This article complies to the Typographic Conventions for Torizon Documentation.

Prerequisites

• A Computer on Module with Torizon installed.
• Learn more about Aktualizr, by reading the Torizon OTA article.

Preparing the Device for Updates

Attention: You will need to execute the commands as root. You can login as root or (better) use the sudo command when logged in with a regular user to do it.

First, make sure that aktualizr is stopped on the board so it won't interfere while creating configuration files:

# systemctl stop aktualizr

Provisioning and configuring the device

The first step to start receiving updates from an Uptane-compatible OTA server is to provision the device, importing credentials and generating certificates that will be used to communicate with the server.

For that, you may need to read the documentation of the Uptane-compatible OTA server you are using, such as Torizon OTA.

If your OTA server provides a credentials.zip file, you can use the aktualizr-cert-provider tool to import the security information from the file and provision the device:

Attention: You should not copy this file to the device because it contains your private keys, during device setup you may access it from a USB thumbdrive or SD card. If you have to copy it, ensure that you delete the file after you executed the command below.

# aktualizr-cert-provider -c <path to removable media>/credentials.zip -l / -u -r

Attention: Note the device id in the first line of output of aktualizr-cert-provider command. Your device will probably show as this id in the OTA server Web interface.

Configuring the serial number

Optionally, you can configure the serial number of your device, that will help differentiate it from other devices in the OTA server Web interface. For that, run the commands below:

# cp /usr/lib/sota/conf.d/40-hardware-id.toml /etc/sota/conf.d/
# echo primary_ecu_serial = $(tr -d '\0' </proc/device-tree/serial-number) >> /etc/sota/conf.d/40-hardware-id.toml

Configuring secondaries

Secondary is a concept in Uptane-compatible OTA systems that make it possible to update not only the main operating system, but also other firmware and devices connected to it. TorizonCore uses secondaries to update containers via docker-compose files.

By default, TorizonCore is already configured to update containers via secondaries, as we can see from the output of the commands below:

# cat /usr/lib/sota/conf.d/50-docker-compose.toml 
[uptane]
secondary_config_file = "/usr/lib/sota/docker-compose.json"

# cat /usr/lib/sota/docker-compose.json
{
    "docker-compose": [
        {
            "partial_verifying": false,
            "ecu_hardware_id": "docker-compose",
            "full_client_dir": "/var/sota/storage/docker-compose",
            "ecu_private_key": "sec.private",
            "ecu_public_key": "sec.public",
            "firmware_path": "/var/sota/storage/docker-compose/docker-compose.yml",
            "target_name_path": "/var/sota/storage/docker-compose/target_name",
            "metadata_path": "/var/sota/storage/docker-compose/metadata"
        }
    ]
}

Allow/block updates

Before applying an update, aktualizr will attempt to acquire a lock on /run/lock/aktualizr-lock using flock. You can have custom code in your application(s) that acquire and release this lock to help control when updates are applied (see flock (2) man page).

In the command line, it is possible to apply an advisory lock on a open file using the command flock. For example, the command below will apply an advisory lock on /run/lock/aktualizr-lock for 30 seconds:

# sudo flock --verbose -x /run/lock/aktualizr-lock -c "sleep 30"

Enable automatic reboot

By default, TorizonCore is configured to automatically reboot the device after a successful update of the operating system. If you want to disable this feature, run the commands below:

# systemctl stop ostree-pending-reboot.path
# systemctl disable ostree-pending-reboot.path

In case you disabled the automatic reboot for system updates and want to re-enable it, run the commands below:

# systemctl enable ostree-pending-reboot.path
# systemctl start ostree-pending-reboot.path

Configuring the polling frequency

In TorizonCore, aktualizr is configured to poll the server for new updates every 5 minutes. To modify this behavior, we can change the polling_sec option. For example, create the configuration file below to change the polling frequency to 60 seconds:

# cat /etc/sota/conf.d/10-client.toml 
[uptane]
polling_sec = 60

Changing the default reboot command

By default, aktualizr will use /sbin/reboot to reboot the device after a successful update (if enabled). To modify the command used to reboot the device, we can change the reboot_command option. For example, create the configuration file below to change the command to reboot the device:

# cat /etc/sota/conf.d/20-bootloader.toml
[bootloader]
reboot_command = "/my-custom-reboot-command"

Note: For more information about aktualizr configuration options, please see the project's official documentation

Start aktualizr

Now you can start Aktualizr with the commands below:

# systemctl enable aktualizr
# systemctl start aktualizr

You can use journald to view the logs and monitor the operation of the update client:

# journalctl -f -u aktualizr

Troubleshooting

To see in more detail what aktualizr is doing, you can stop the systemd service and start aktualizr manually, e.g. with an increased loglevel for debugging:

# systemctl stop aktualizr
# aktualizr --loglevel 1

To provision the device again, make sure to stop aktualizr, remove the device and start aktualizr again:

# rm /var/sota/sql.db
# rm -rf /var/sota/storage/

Common issues

If you see the following message:

response http code: 400
response: "An error occurred: Missing entity: Ecu"
could not put manifest

Make sure to properly delete the storage of the secondary (see above).