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.
We recommend that you use the TorizonCore Builder Tool to apply customization options to TorizonCore, once you are satisfied with tweaking the device configuration.
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.
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
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.
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
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"
}
]
}
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"
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
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
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
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
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/
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).