This article will cover how to use the Secure Offline Update (shortened to Offline Update) feature of our Torizon Platform Services. If you need conceptual context, please refer to our Torizon Updates Overview article on Secure Updates with Torizon.
Throughout the article, we will use terminology specific to Offline Updates. For this information and more on what Offline Updates are and the concepts surrounding them please refer to our First Steps article on the feature.
Otherwise, this article will be a purely how-to guide on the feature.
Two configuration tweaks are required to enable offline updates:
Before your device can perform any Offline Update it needs to be provisioned with some data.
If you want to provision a single device, you should use the command provided by the Torizon Platform Web Interface. If you need to provision multiple devices, please refer to our article on Production Programming & Provisioning.
By default, aktualizr-torizon offline updates are disabled in favor of traditional online/remote updates.
To enable offline updates, add a toml file in the Aktualizr configuration directory /etc/sota/conf.d/ with the following content:
/etc/sota/conf.d/100-offline-updates.toml[uptane] enable_offline_updates = true offline_updates_source = "<path to your lockbox>"
The first line is a boolean switch to enable offline updates.
The second is the path to the directory where your folder with the update (Lockbox) will be available when connected to the device (e.g. /media/usb/update).
Tip: The path might depend on the partition label set on your update medium, which is unrelated to offline updates. For a quick try, use the command df -h to find out the directory name for your lockbox. In the long term, consider adding to your lockbox creation checklist setting the partition name of the update medium.
Once the configuration file is created restart the client for it to take effect:
# sudo systemctl restart aktualizr
To confirm whether Offline Updates were successfully enabled or not you can check the logs of the update client, like so:
# journalctl -f -u aktualizr*
If successful you should see Offline Updates are enabled in the logs.
Once you have confirmed that everything is successfully configured you can capture changes with TorizonCore Builder, so these changes are persistently kept.
In versions of TorizonCore earlier than 5.7.0, the Offline Updates feature is not implemented. If your project requires Offline Updates then it is necessary to upgrade to at least TorizonCore 5.7.0.
Once your TorizonCore Builder project has both the provisioning data and the custom configuration, create a custom TorizonCore image ready for offline updates.
From a practical perspective, the lockbox is the USB stick or SD Card you will use for updates. Learn more in the First Steps with Secure Offline Updates - Terminology.
Before proceeding, make sure that your OS (TorizonCore) and/or application (container images) updates are already available in the UI. Learn how in the Torizon Platform Services Web Interface article.
Note: just because the update metadata is available in the Platform Services, it doesn't mean that your application is uploaded to our servers. In fact, container images cannot even be uploaded to our servers, they are kept in a container registry - in a public cloud (Docker Hub, Amazon AWS, Microsoft Azure) or a local registry, for example.
The first step to an Offline Update is defining your Lockbox in the Platform Services web UI.
Define your Lockbox like so:
Lockboxes tab in the left sidebar.DEFINE LOCKBOX:
CONTINUE.TorizonCore Builder can download any previously defined Lockbox by its name using the platform lockbox command. If you haven't done it yet, download your account credentials (credentials.zip file) to your PC.
With your Lockbox name, download it with the TorizonCore Builder tool:
torizoncore-builder platform lockbox --credentials credentials.zip LOCKBOX_NAME
Once done, your Lockbox will be available in a directory on your host machine - by default it is the update directory. For more details on the exact usage of this command please see our commands manual.
As a final step, move or copy it to your update medium of choice. Make sure that the directory matches the Aktualizr configuration present in the devices.
At this point, you must have:
To start an update, perform the following steps:
The update will start within seconds of your update medium being inserted. Once the update begins, the process will be similar to what happens in an online OTA update.
If you wish to follow the process you can view the logs of the update client:
# journalctl -f -u aktualizr*
You cannot update from a newer lockbox to an older lockbox, as of the time when they were downloaded with TorizonCore Builder. This is due to the security metadata included in each Lockbox: security metadata is versioned and does not allow updating to older Lockboxes.
For example imagine you have defined 2 Lockboxes in the Platform, A and B. You download Lockbox A, then a few days later download Lockbox B. If you update using A then B, that is fine since you are going in the order of oldest to newest. However, vice versa, B to A, will fail.
You can update the security metadata of a Lockbox by re-downloading it using TorizonCore Builder. Doing this will re-create your Lockbox with the latest security metadata available at that time. This is useful in scenarios such as if you identify a bug that has been introduced by a recent update and you want to revert to an older working version of your software.
Secure Offline Updates have a limited feature set as of their initial release. We are collecting customer feedback and plan to make improvements:
aktualizr-torizon and restart the client.aktualizr-torizon logs as the update happens.When operating the update client in offline update mode there are certain side effects to be aware of. They can either be ignored or worked around, please review them carefully and make sure to take them into account for your specific use case:
