Torizon Update Client - Aktualizr Commands & Settings
Introduction​
This article will help you understand, monitor, and configure the update client on Torizon OS, including controlling its behavior, adjusting configurations, and troubleshooting common issues. You will learn how to:
- Provision devices to Torizon Cloud, individually or at scale
- Start, stop, and monitor the Aktualizr service
- Control updates at runtime, including blocking or allowing them
- Modify configurations such as polling frequency, logging, hardware IDs, and reboot behavior
- Perform update checks, rollbacks, and manage offline/low-bandwidth scenarios
- Use Aktualizr on Torizon OS with or without the Torizon Remote Updates service
Torizon Remote Updates is the recommended method for Over-the-Air updates using Torizon, our easy-to-use embedded Linux platform. It also supports Secure Offline Updates.
Torizon OS is built with OSTree and Aktualizr. OSTree and Aktualizr are complementary and together they form the foundation for OTA (over-the-air) update capabilities on the device. To learn more about the technical aspects of Torizon Remote and Offline Updates, see the Torizon Updates Technical Overview article.
If you just want to use the Torizon Remote Updates with default settings, the pre-installed software on a Torizon OS image abstracts the settings of Aktualizr for you, therefore you can skip this article.
Prepare for Production​
After changing the setting in the SoM, we recommend that you use the TorizonCore Builder Tool to apply customization options to a Torizon OS image for production.
This article complies with the Typographic Conventions for Torizon Documentation.
Prerequisites​
- A Computer on Module with Torizon installed.
- Learn more about Aktualizr, by reading the Torizon Remote Updates Technical Overview article.
Provisioning the Device to Torizon Cloud​
Before Aktualizr (the Torizon OS update client) can run on a device, the device must be provisioned to an account in Torizon Cloud.
Provisioning a Single Device​
Provisioning a single device is a common practice during development and is typically done by running on the particular device a script provided through the Torizon Cloud UI. During provisioning, the device is assigned a unique Device ID and Device Name within the account. By default, the Device ID is derived from the SoM model and serial number, while the Device Name is generated from a random word list.
If you want to provide those values yourself, you can add them to the provisioning command by adding the -d option for Device ID and the -n option for Device Name. Your provisioning command will normally be of the form:
curl -fsSL <provisioning-script-URL> | sudo bash -s -- -t "<token-string>" <extra-script-parameters> && sudo systemctl restart aktualizr fluent-bit
To set the custom Device ID and Device Name, you would add the desired options to <extra-script-parameters>. For example, you could add -d "my-device-id" -n "My Product 0053" right before the double ampersand (&&) to set your custom Device ID and Name, respectively.
Provisioning at Scale​
In production, users would normally expect devices to be provisioned automatically. For that, users need to fetch some "provisioning data" from Torizon Cloud and install it into their Torizon OS image; that image would then be flashed into one or many devices. There are two types of provisioning data:
- Shared-data (used both with "offline" and "online" provisioning modes) allows the device to validate updates (by populating the initial Uptane root metadata).
- Online-data (added with the "online" mode provisioning) allows the device to register itself to the platform which is required for it to take updates from the platform.
To learn more about this topic, please read the documentation on Provisioning at Scale.
In terms of client configuration, users need to be aware that:
- By default, Aktualizr is configured with Online Updates enabled and Offline Updates disabled.
- A device imbued with only Shared-data is capable of accepting Offline Updates, exclusively; in this case Aktualizr must be configured to disable Online Updates and, normally, to enable Offline Updates, as described in section Enabling Offline Updates. More details on this topic are available on the Offline Updates article.
- A device imbued with both Shared-data and Online-data is capable of accepting both Online and Offline Updates; in this case, Online and Offline updates can be enabled/disabled independently, as desired.
- A device imbued with Online-data will try to register itself to Torizon Cloud. That work is done by the auto-provisioning service which can also be configured.
If an image is provisioned with Shared-data only, Aktualizr must be configured to disable Online Updates.
Basic Service-related Commands​
Aktualizr runs as a systemd service (named aktualizr-torizon but aliased as aktualizr) and can be managed using standard systemd service management commands. The commands that change the state of the service must be executed as root. It is recommended to use sudo for this purpose. Alternatively, users can log in as root, though this approach is discouraged.
In the sections below we provide the most common commands for managing the service and checking its status.
Stopping Aktualizr​
Before making changes to Aktualizr settings, stop its execution to avoid interference while creating configuration files:
# sudo systemctl stop aktualizr
Starting Aktualizr​
After applying the changes described in the following sections, you need to start Aktualizr with the command below:
# sudo systemctl start aktualizr
Viewing Aktualizr Logs​
It's often useful to follow up Aktualizr's operation through journalctl by running:
# journalctl -f -u "aktualizr*"
Disabling and Enabling Aktualizr​
If you don't want Aktualizr to start on every reboot, disable it:
# sudo systemctl disable aktualizr
If you want to revert that operation, enable it again:
# sudo systemctl enable aktualizr
Restarting Aktualizr​
If you need to restart Aktualizr, use the command:
# sudo systemctl restart aktualizr
Controlling Aktualizr at Runtime​
Once Aktualizr is running (i.e. its service is active), its behavior can be controlled by other programs, as described in the following sections.
Allowing and Blocking Updates​
You can lock Aktualizr to avoid receiving new updates on the client.
Every time before applying an update, Aktualizr attempts to acquire a lock on /run/lock/aktualizr-lock using flock.
To help control when updates are applied, you can have a custom code in your application(s) that acquires and releases this lock (see flock (2) man page for more details). This code will need to be custom to your application to be able to disable updates when the device is in operation, or in other states where updating should be disallowed.
If you are using 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"
Granular Control via D-Bus​
- Granular Control via D-Bus is an early access feature which means breaking changes can be introduced at any time.
- Users are encouraged to share feedback on how effectively the feature supports their use cases.
With Torizon OS 7.4.0 or newer, users have more granular control of Aktualizr through its D-Bus interface.
The interface includes methods/properties offering the following functionalities:
- Setting Aktualizr's configuration: Currently it's possible to configure the update client to automatically accept updates (default) or to wait for a consent before proceeding with the update.
- Providing consent for available updates: When Aktualizr is configured to wait for a consent, users can provide it (or not) through its Consent API. With that API, users of Torizon OS can offer their end-users the ability to accept or reject a given update, which may be required to fulfill the EU Cyber Resilience Act (CRA) requirements.
- Checking for Updates: Users can ask Aktualizr to check for remote updates immediately instead of waiting for the configured polling time.
- Canceling an Update: An ongoing update can be safely canceled putting Aktualizr back into its idle state.
- Triggering Offline Updates: It's possible to perform an Offline Update taking a specified directory as source.
Users can employ the Aktualizr Consent API to fulfill the CRA requirements for their products.
D-Bus API Documentation​
Detailed documentation of the D-Bus interface is available in the Aktualizr project:
D-Bus Usage Examples​
It's worth pointing out that users are expected to access the Aktualizr D-Bus API through the appropriate bindings for their programming language of choice. For testing purposes, one can leverage the busctl program available on Torizon OS.
For example, to cause Aktualizr to immediately check for updates one can run:
# busctl call org.uptane.Aktualizr /org/uptane/aktualizr org.uptane.Aktualizr CheckForUpdates
To see the effect, users can monitor the Aktualizr logs.
To communicate with Aktualizr from inside a container using D-Bus, users must ensure the system bus socket is accessible. For example, the previous command could be executed as follows:
# docker run -v /run/dbus/system_bus_socket:/run/dbus/system_bus_socket -it <container>
...And assuming busctl (part of the systemd package on Debian) is installed in the container:
## busctl call org.uptane.Aktualizr /org/uptane/aktualizr org.uptane.Aktualizr CheckForUpdates
Modifying the Aktualizr Configuration​
In this section, we will show how to make common adjustments to Aktualizr settings.
Aktualizr is configured via .toml configuration files. It searches the following directories for files with a .toml extension:
/usr/lib/sota/conf.d//etc/sota/conf.d/
It then processes all the .toml files it finds in alphabetical order. If a config option is specified in multiple files, the last entry overrules any previous entries. Torizon OS includes the following config files by default in /usr/lib/sota/conf.d/:
20-sota-device-cred.toml30-rollback.toml40-hardware-id.toml50-docker-compose.toml60-polling-interval.toml
If you want to override config options in those files, you should create a config file in /etc/sota/conf.d/ to add or modify config options.
Once you have changed the configuration options to the way that suits you, you can apply the changes to a custom Torizon OS image that you can use for production programming, following the instructions in Capture Changes in the Configuration of a Board on Torizon OS.
Enabling Offline Updates​
Aktualizr's standard configuration is to monitor update requests coming through the Remote Updates method, because of this an Offline Update request will not work out-of-the-box.
To reconfigure a device for using Secure Offline updates, you must create or modify a configuration file at /etc/sota/conf.d/. If the folder doesn't exist, you can create it with the following command:
# sudo mkdir -p /etc/sota/conf.d/
Use the following configuration in the file:
# cat /etc/sota/conf.d/99-offline-updates.toml
[uptane]
enable_offline_updates = true
enable_online_updates = false
offline_updates_source = /media/usb/update
This will enable offline updates but disable online updates. If you wish to enable both methods, see the next section.
In the sample configuration file, offline_updates_source indicates the folder that aktualizr will monitor for offline updates. In the example, /media/usb it's the path where the relevant USB drive is auto-mounted and update is the name of the actual folder inside that drive containing the update artifacts (i.e. the Lockbox).
As usual, remember to Restart Aktualizr after making changes to its configuration.
Enabling both Online and Offline Updates​
With Torizon 7, it is possible to enable online and offline Updates at the same time. This is achieved simply by setting both booleans enable_offline_updates and enable_online_updates to true in the configuration file shown in the previous section. In that case, users will be able perform updates via both methods and in whatever order they like. It is also worth mentioning that the offline method will have a higher priority than the other such that, when triggered, it may even interrupt an ongoing online update.
Configuring the Polling Frequency​
In Torizon OS, Aktualizr is configured to poll the server for new updates every 5 minutes. To modify this behavior, we can change the uptane.polling_sec option. For example, to change the polling frequency to 1 hour, you could create a configuration file in /etc/sota/conf.d/ called 61-custom-polling-interval.toml. If the folder doesn't exist, you can create it with the following command:
# sudo mkdir -p /etc/sota/conf.d/
Then create the file with:
# cat <<EOF | sudo tee /etc/sota/conf.d/61-custom-polling-interval.toml
[uptane]
polling_sec = 3600
EOF
After applying the changes, don't forget to Restart Aktualizr.
Configuring the Hardware ID​
When Toradex publishes our Torizon OS images to the OTA server, their metadata includes a list of which hardware IDs they are compatible with. This ensures that you don't accidentally send an image built for a colibri-imx7 to an apalis-imx8. This hardware compatibility is enforced by the update client: if your device reports that it is an apalis-imx8, it will refuse any update images that don't list apalis-imx8 as a compatible hardware ID.
Normally, it's best not to modify the hardware ID your device reports. If you give it a custom hardware ID, it will no longer accept stock Torizon OS images. But sometimes, that's exactly what you want: for example, if you have several different SKUs that need slightly different OS images, or if you have products with the same SoM but a different carrier board or peripherals. In those cases, you might want to make sure that each SKU or variant has its own hardware ID, and then publish a customized Torizon OS build for each one; that way you can make sure that nobody can accidentally create an OTA update that sends incompatible OS images.
To achieve that, you need to do two things:
- Modify the Aktualizr config on your device image to report a custom hardware ID
- Upload the customized image to Torizon Remote Updates along with metadata indicating it's compatible with your custom hardware ID
Configuring the Hardware ID on Torizon OS​
To configure the hardware ID in the Aktualizr config, you need to set the provision.primary_ecu_hardware_id config value. For example, if you wanted your device to be registered with the hardware ID apalis-imx8-sku001, you could create a configuration file in /etc/sota/conf.d/ called 41-custom-hardware-id.toml. If the folder doesn't exist, you can create it with the following command:
# sudo mkdir -p /etc/sota/conf.d/
Then create the file with:
# cat <<EOF | sudo tee /etc/sota/conf.d/41-custom-hardware-id.toml
[provision]
primary_ecu_hardware_id = apalis-imx8-sku001
EOF
Because this is a change to provisioning configuration, you will need to re-provision the device if you want to change it on a live device. It's highly recommended to apply the changes to a custom Torizon OS image that you can use for production programming, following the instructions in Capture Changes in the Configuration of a Board on Torizon OS. That way, your devices will use their custom hardware ID as soon as they are programmed.
Configuring Custom Hardware IDs for Torizon Remote Updates Images​
When sending a custom image to the OTA server, you can specify a list of hardware IDs it is compatible with. Using the push command of the TorizonCore Builder Tool, you can specify one or more --hardwareid arguments to override the image's compatible hardware IDs.
$ torizoncore-builder push my-branch --credentials credentials.zip --package-name my-custom-image --hardwareid apalis-imx8-sku0001
Each image can have several hardware IDs assigned to them. To add multiple hardware IDs to a custom image, use the --hardwareid argument once for each hardware ID.
$ torizoncore-builder push my-branch --credentials credentials.zip --package-name my-custom-image --hardwareid apalis-imx8-sku0001 --hardwareid apalis-imx8-sku0003 --hardwareid apalis-imx8-sku007-beta
Remember, Torizon Remote Updates will only permit you to install an image on a device if the hardware IDs match.
Configuring the Logging Level​
Aktualizr produces logs at different levels of detail depending on the loglevel setting:
- trace (0) logs everything, including the content of every HTTP request
- debug (1) has extra information useful for debug purposes, but is not as verbose as trace
- info (2) is the default, and logs basic information about normal and exceptional Aktualizr operations
- warning (3) only logs warnings and other exceptional information
- error (4) only logs errors
- fatal (5) only logs fatal errors
If you are troubleshooting an issue with the OTA client, it may be helpful to increase the loglevel. To do this, we can change the logger.loglevel option. For example, to enable trace logging, you could create a configuration file in /etc/sota/conf.d/ called 99-custom-loglevel.toml. If the folder doesn't exist, you can create it with the following command:
# sudo mkdir -p /etc/sota/conf.d/
Then create the file with:
# cat <<EOF | sudo tee /etc/sota/conf.d/99-custom-loglevel.toml
[logger]
loglevel = 0
EOF
More detailed loglevels, especially trace, can write a large volume of log data if left on for a long time. We recommend leaving the loglevel at the default except when specifically needed for troubleshooting.
After applying the changes, don't forget to Restart Aktualizr.
Enabling and Disabling Automatic Reboot​
By default, Torizon OS 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
After applying the changes, don't forget to Restart Aktualizr.
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 bootloader.reboot_command option. For example, you could create a configuration file in /etc/sota/conf.d/ called 21-custom-reboot.toml pointing to a custom reboot script. If the folder doesn't exist, you can create it with the following command:
# sudo mkdir -p /etc/sota/conf.d/
Then create the file with:
# cat <<EOF | sudo tee /etc/sota/conf.d/21-custom-reboot.toml
[bootloader]
reboot_command = "/my-custom-reboot-command"
EOF
Configuration for Low-Bandwidth Connections​
Torizon Remote Updates can present some limitations when dealing with very constrained, low-bandwidth connections. These limitations usually manifest as timeouts or various connection and download errors.
You can enhance the reliability of your infrastructure for delivering updates by optimizing how container images are distributed. One effective approach is to use a pull-through cache, which acts as a local proxy for container registries. For more information, see Store and Share Containers.
Additionally, there are a couple of options you can tweak to improve update stability in these situations. These options affect the download behavior of OS updates, specifically how OSTree performs downloads.
These options are only available in Torizon OS 6.5.0 or later.
To set these options, you must pass environment variables to Aktualizr. Therefore, you it is needed to modify the systemd service that launches Aktualizr.
When editing the systemd service, the environment variables that can be set to control these options are:
[Service]
...
Environment="OSTREE_CURL_TIMEOUT=<timeout_setting_in_s>"
Environment="OSTREE_CURLM_MAX_TOTAL_CONN=<max_number_of_connections>"
...
OSTREE_CURL_TIMEOUT: This sets the timeout, in seconds, for curl requests performed by OSTree. This timeout is per individual curl request and not for the entire update itself. By default this is about 13 minutes. Try increasing this if you find your connection is slow enough to trigger the default timeout.OSTREE_CURLM_MAX_TOTAL_CONN: This sets the max amount of parallel connections that can be used for downloads with OSTree. By default this will automatically optimize to use the max amount of parallel downloads possible. Decreasing the number here will increase the overall time it takes for your OS update to complete. However, less parallel downloads can improve download stability. Since more downloads occuring in parallel increase the chance of a connection error when working with a poor, or low-bandwidth connection.
After applying changes to the systemd service, don't forget to Restart Aktualizr.
Configuring Secondaries​
This section is aimed at developers extending Aktualizr, especially when adding components for it to manage their updates.
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. Torizon OS uses secondaries to update containers via docker-compose files. Secondaries are also used in Subsystem Updates and Bootloader Updates
If you want to override the default configuration - located at paths under /usr, which is ready-only - take them as starting point and create custom configuration files under /etc/sota/conf.d/.
Aktualizr first reads the configuration files from /usr/lib/sota/conf.d/ and loads it. If any custom configuration files are found in /etc/sota/conf.d/, the respective configurations are overridden.
The secondary configuration .toml file points to the secondary definition .json file.
To get the content from the default files, execute the commands below.
Secondary configuration .toml file (copy it from /usr/lib/sota/conf.d and edit under /etc/sota/conf.d/ to define the path for your secondary definition .json file). If the folder doesn't exist, you can create it with the following command:
# sudo mkdir -p /etc/sota/conf.d/
Then create the file with:
# cp /usr/lib/sota/conf.d/50-secondaries.toml /etc/sota/conf.d/50-secondaries.toml
# vi /etc/sota/conf.d/50-secondaries.toml
[uptane]
secondary_config_file = "/etc/sota/secondaries.json"
Secondary definition .json file (copy it from /usr/lib/sota and edit under /etc/sota/):
# cp /usr/lib/sota/secondaries.json /etc/sota/secondaries.json
# cat /etc/sota/secondaries.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"
}
],
"torizon-generic": [
{
"partial_verifying": false,
"ecu_hardware_id": "verdin-imx8mp-bootloader",
"full_client_dir": "/var/sota/storage/bootloader",
"ecu_private_key": "sec.private",
"ecu_public_key": "sec.public",
"firmware_path": "/var/sota/storage/bootloader/u-boot.img",
"target_name_path": "/var/sota/storage/bootloader/target_name",
"metadata_path": "/var/sota/storage/bootloader/metadata",
"action_handler_path": "/usr/bin/bl_actions.sh"
}
]
}
Edit to add your custom configuration. For example, add a new secondary for a subsystem update - maintaining the other definitions:
{
"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"
}
],
"torizon-generic": [
{
"partial_verifying": false,
"ecu_hardware_id": "verdin-imx8mp-bootloader",
"full_client_dir": "/var/sota/storage/bootloader",
"ecu_private_key": "sec.private",
"ecu_public_key": "sec.public",
"firmware_path": "/var/sota/storage/bootloader/u-boot.img",
"target_name_path": "/var/sota/storage/bootloader/target_name",
"metadata_path": "/var/sota/storage/bootloader/metadata",
"action_handler_path": "/usr/bin/bl_actions.sh"
},
{
"partial_verifying": false,
"ecu_hardware_id": "my-secondary",
"full_client_dir": "/var/sota/storage/my-secondary",
"ecu_private_key": "sec.private",
"ecu_public_key": "sec.public",
"firmware_path": "/var/sota/storage/my-secondary/my-payload.file",
"target_name_path": "/var/sota/storage/my-secondary/target_name",
"metadata_path": "/var/sota/storage/my-secondary/metadata",
"action_handler_path": "/usr/bin/my_secondary_actions.sh"
}
]
}
After making changes, don't forget to Restart Aktualizr.
Advanced Configuration​
Aktualizr has many more config options available. For more details, please consult the project's official documentation.
Update Checks and Rollbacks​
Greenboot (Generic Health Check Framework) is a Fedora project that helps manage systemd services health. Torizon OS uses Greenboot as a framework to make update checks and rollbacks more flexible and manageable by the user.
By default, Torizon OS will consider a successful boot if the boot-complete systemd target is successfully executed. This is because the main operating system services required for proper operation, including the Docker daemon, are inside boot-complete.target. And if boot-complete.target fails during an update, Torizon OS will automatically reboot, and after three tries, it will rollback to the previous operating system version.
In case you want to add additional checks to confirm a successful update, you can add shell scripts to /etc/greenboot/check/required.d/. As a convention, the script name should start with two numbers and finish with .sh (Example: 01_check_system.sh). Scripts in /etc/greenboot/check/required.d/ will be executed as part of the boot health checks.
If the scripts in /etc/greenboot/check/required.d/ are successfully executed, and the boot-complete.target is successfully started, the system will enter in the GREEN state. In this case, the greenboot-task-runner service will be triggered, and user-defined scripts inside /etc/greenboot/green.d/ will be executed. These scripts can be used to execute post-install operations during a successful update, but be aware that they will run every time the operating system boots.
Now, if one of the scripts in /etc/greenboot/check/required.d/ fail (exit code is not 0), the boot-complete.target will also fail, and the system will enter in the RED state. In this case, the redboot-task-runner service will be triggered, and user-defined scripts inside /etc/greenboot/red.d/ will be executed. These scripts can be used to execute post-install operations during a failed update, but be aware that they will run every time the operating system boots (when boot-complete.target fails). After redboot-task-runner service finishes execution, the redboot-auto-reboot service is triggered, and this service will run a script that will reboot the system (in case an update is in progress). After 3 reboots, the system will rollback to the previous operating system version.
To confirm if a boot was successful (GREEN status) or if it failed (RED status), you can check the status of the greenboot-status systemd service:
# systemctl status greenboot-status
* greenboot-status.service - greenboot MotD Generator
Loaded: loaded (/usr/lib/systemd/system/greenboot-status.service; enabled; vendor preset: enabled)
Active: active (exited) since Mon 2021-04-26 12:50:04 UTC; 16min ago
Process: 809 ExecStart=/usr/libexec/greenboot/greenboot-status (code=exited, status=0/SUCCESS)
Main PID: 809 (code=exited, status=0/SUCCESS)
Apr 26 12:50:04 apalis-imx6-05039068 systemd[1]: Starting greenboot MotD Generator...
Apr 26 12:50:04 apalis-imx6-05039068 greenboot-status[814]: Boot Status is GREEN - Health Check SUCCESS
Apr 26 12:50:04 apalis-imx6-05039068 systemd[1]: Started greenboot MotD Generator.
Alternatively, you can list the content of the /run/boot-status file:
# cat /run/boot-status
Boot Status is GREEN - Health Check SUCCESS
For more information about the Greenboot framework, please see the project's website.
Custom Rollback Rule Example: Rollback if the System Cannot Connect to the Internet​
Often, Torizon users want to set custom rules to define whether their specific products have successfully booted after an update. One of these use cases is to check if internet is available.
Create a script named /etc/greenboot/check/required.d/99_check-torizon-cloud-connectivity.sh so that it tries to connect to the Torizon Cloud every 10 seconds, for up-to 10 minutes:
#!/bin/bash
for i in $(seq 60); do
curl -sf --cert /var/sota/import/client.pem --key /var/sota/import/pkey.pem --cacert /var/sota/import/root.crt $(cat /var/sota/import/gateway.url)/director/root.json > /dev/null && exit 0
sleep 10
done
exit 1
Updates will fail and rollback if this check fails. Note that failing greenboot checks only trigger a rollback when there's an update in progress, so you don't have to worry about a check like this randomly causing your devices to rollback when they're outside a connectivity area. They do, however, prevent or delay the boot-complete systemd target from being reached, so if you have essential services ordered after that, be careful with what you put in those checks.
You can see what depends on the boot-complete target with the following commands:
# systemctl list-dependencies boot-complete.target --reverse
boot-complete.target
○ ├─aktualizr-torizon.service
● ├─greenboot-task-runner.service
● ├─remote-access.service
● └─greenboot.target
● └─multi-user.target
○ └─graphical.target
# systemctl list-dependencies boot-complete.target --before
boot-complete.target
○ ├─aktualizr-torizon.service
● ├─greenboot-task-runner.service
● ├─remote-access.service
● ├─greenboot.target
● │ ├─multi-user.target
○ │ │ ├─systemd-update-utmp-runlevel.service
○ │ │ ├─graphical.target
○ │ │ │ ├─systemd-update-utmp-runlevel.service
○ │ │ │ └─shutdown.target
○ │ │ │ └─final.target
○ │ │ └─shutdown.target
○ │ │ └─final.target
○ │ └─shutdown.target
○ │ └─final.target
○ └─shutdown.target
○ └─final.target
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-torizon --loglevel 1
# systemctl stop aktualizr
# aktualizr --loglevel 1
To provision the device again, make sure to stop Aktualizr, remove its databases and start it 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).