Search by Tags

How to Use Secure Offline Updates with TorizonCore


Article updated at 22 Jul 2022


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.


  • TorizonCore 5.7.0 or newer
  • Commercial account on our Torizon Platform Services website
  • An appropriate update medium (USB or SD Card drive)
  • An understanding of the basic concepts of Offline Updates
  • Basic understanding of our TorizonCore Builder Tool

Preparing Your Device

Two configuration tweaks are required to enable offline updates:

  • Provision device: add data specific to your account
  • Configure Aktualizr: add a configuration file with offline updates instructions

Provision Device for 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.

Configure Device for Offline Updates

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:

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.

Defining a Lockbox

The first step to an Offline Update is defining your Lockbox in the Platform Services web UI.

Define your Lockbox like so:

  • Login to your commercial-tier account on
  • Go to the Lockboxes tab in the left sidebar.
  • Click on DEFINE LOCKBOX:
    • In the first menu, select the component(s) you want to update.
    • In the second menu, select the specific package you want to include in your Lockbox. You need to select a package name and version for each component you selected in the first menu.
    • In the third menu, review your selection. When you’ve confirmed it’s correct hit CONTINUE.
    • In the fourth and final menu, give your lockbox a fitting name. Write down this name, you’ll need it in the next section!

Downloading Your Lockbox

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 ( file) to your PC.

With your Lockbox name, download it with the TorizonCore Builder tool:

torizoncore-builder platform lockbox --credentials 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.

Performing the Offline Update

At this point, you must have:

  • An update medium (SD Card or UB stick) with a lockbox.
  • A custom TorizonCore image with provisioning data and configured for offline updates.

To start an update, perform the following steps:

  • Install the custom TorizonCore image with Toradex Easy Installer.
  • Once the installation ends, power on (or reboot) the board.
  • Attach your update medium containing your Lockbox to the device. Pay attention to the following:
    • The update medium needs to be attached after the system has started (specifically after the update client has started). If the update medium is attached prior to this then it will not trigger the update.
    • Make sure the file path of your update medium is consistent with what you configured for the update client.

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*

Lockbox Update Order

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:

  • TorizonCore cannot be configured to perform Offline & Online updates at the same time. To switch the mode of operation, you must re-configure aktualizr-torizon and restart the client.
  • Offline Updates don't have a friendly logging/feedack mechanism. In comparison, Online OTA updates give feedback to the server about the status of an update. In order to see the status of an offline update, you will need to manually observe or parse the aktualizr-torizon logs as the update happens.
  • Device Monitoring will not work while in offline-update mode, even if the device has internet available.
  • If a device is online-provisioned but the client is still configured for offline-updates, then the device will not appear as “online” in our Torizon Platform Services web UI.

Known Issues

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: