Offline Updates

This section guides you through the steps of updating a device offline.

Prerequisites

  1. Enable Offline Update support, i.e. add aklite-offline to PACKAGECONFIG of aktualizr. For example:

    cat meta-subscriber-overrides.git/recipes-sota/aktualizr/aktualizr_%.bbappend
PACKAGECONFIG:append = " aklite-offline"

  2. Enable App Preloading if you would like to update Compose Apps along with rootfs (aka ostree).

  3. Ensure that TUF keys are taken offline. If they are not, then do it.

  4. Build an LmP image and flash it onto a target device or update the device with the image via OTA.

Obtaining Offline Update Content

Once the prerequisites are met, download the offline update content from the FoundriesFactory to some medium, e.g., a USB drive, which can be attached to a target device. The offline update content consists of:

  1. TUF metadata;
  2. OSTree repo containing a device’s rootfs;
  3. Compose Apps.

Use the command fioctl targets offline-update <target-name> <dst> --tag <tag> [--prod] to download the update content.

  • <target-name> - denotes the Target to update a device to
  • <dst> - defines a path to download the update content to
  • <tag> - specifies the Target tag and the tag that the device is on
  • --prod - indicates that this is an update for a production device and <target-name> refers to Production Target (see the note below)

Note

Use fioctl waves init/complete commands to generate Production Targets.

Ensure that the target device is a Production device, see Manufacturing Process for Device Registration for more details.

Note

In order to download all artifacts, fioctl requires token with scopes: targets:read, ci:read.

Performing the Offline Update

Before doing the offline update, make the offline update content accessible on a device, e.g., attach and mount the USB drive.

Use the aklite-offline CLI utility to perform an offline update:If a device needs

  1. Run aklite-offline install [--config <config dir or file>] --src-dir <path to offline update content>.

  2. Run one of the post installation actions depending on the aklite-offline install result:

    1. trigger reboot to perform a rollback if the update failed;
    2. reboot device and invoke aklite-offline run [--config <config dir or file>] to finalize an ostree installation and start Apps if both ostree/rootfs and Apps are updated;
    3. restart the Docker Engine (e.g. systemctl restart docker) and invoke aklite-offline run [--config <config dir or file>] if just Apps are updated.

Usage Details

The CLI utility supports two commands:

  1. aklite-offline install [--config <config file/dir>] --src-dir <update-content-dir>
  2. aklite-offline run [--config <config file/dir>]
``--config`` -  Path to a directory that contains one of more ``*.toml`` configuration snippets or a path to a ``*.toml`` file. It may be omitted at all so the command collects config from the snippets found in the default directories/files, as ``aktualizr-lite`` does:

/usr/lib/sota/conf.d
/var/sota/sota.toml
/etc/sota/conf.d/

``--src-dir`` - Path to a directory that contains update content downloaded by ``fioctl targets offline-update`` command.

Post Install Actions

The command sets the following exit codes (echo $?) that instruct which of the post install actions you should perform:

  • 100 - Reboot is required to complete installation. After reboot aklite-offline run must be invoked.
  • 101 - Restart of dockerd service is required , e.g. systemctl restart docker. After the restart aklite-offline run must be invoked.
  • 0 - OSTree/rootfs installation and Apps start was successful, update completed. Only aklite-offline run can return this code.

If aklite-offline run returns 100 , then an update has not been successful and rollback has happened. In this case you should trigger reboot followed by another aklite-offline run to complete the rollback.

Configuration Details

The minimum required configuration is:

[provision]
primary_ecu_hardware_id = <>

The command can digest the default device config consisting of:

  1. *toml files added into LmP during bitbaking (usually just /usr/lib/sota/conf.d/40-hardware-id.toml);
  2. sota.toml generated by lmp-device-register.

If a device needs to support offline and online updating, then the configuration needs to be shared with aktualizr-lite.

Normally, each LmP image includes a configuration file /usr/lib/sota/conf.d/40-hardware-id.toml which defines a hardware ID. Therefore, by default, an LmP image includes the minimum required configuration, hence NO device registration is required for aklite-offline to work.

If you register a device and sota.toml is generated, then the offline update command can either work alone or alone with aktualizr-lite. In the later case, you must stop the aktualizr-lite systemd service before running the offline update command.