OTA Connect Developer Guide

Advanced usage of meta-updater

This page describes advanced features of meta-updater.


The aktualizr repo contains a tool, garage-push, which lets you push the changes in OSTree repository generated by bitbake process. It communicates with an http server capable of querying files with HEAD requests and uploading them with POST requests.

This tool is used automatically as part of every normal Yocto build in our quick start tutorials, but can be used manually or used to communicate with another server if desired.

If you set SOTA_PACKED_CREDENTIALS in your local.conf, bitbake will automatically synchronize your build results with the remote server specified in your credentials file. (See the provisioning method and credentials.zip page for more information.) garage-push can also be used on the command line as follows:

garage-push --repo=/path/to/ostree-repo --ref=mybranch --credentials=/path/to/credentials.zip


meta-updater also uses a tool, garage-sign, for signing Uptane metadata and communicating with a remote server. It can be configured with variables described in the build configuration section. Of particular importance is controlling the expiration of the Targets metadata, which is described in detail in the metadata expiry page. garage-sign can also be used to rotate your signing keys.

aktualizr configuration

Aktualizr supports a variety of configuration options via a configuration file and the command line. There are two primary ways to control aktualizr’s configuration from meta-updater.

First, you can set SOTA_CLIENT_PROV to control which provisioning recipe is used. Each recipe installs an appropriate sota.toml file from aktualizr according to the provisioning needs. See the build configuration section for more information.

Second, you can write recipes to install additional config files with customized options. A few recipes already exist as examples and to address common needs:

  • aktualizr-auto-reboot.bb configures aktualizr to automatically reboot after new updates are installed in order to apply the updates immediately. This is only relevant for package managers (such as OSTree) that require a reboot to complete the installation process. If this is not enabled, you will need to reboot the system through other means.

  • aktualizr-disable-send-ip.bb disables the reporting of networking information to the server. This is enabled by default and supported by HERE OTA Connect. However, if you are using a different server that does not support this feature, you may want to disable it in aktualizr.

  • aktualizr-log-debug.bb sets the log level of aktualizr to 0 (trace). The default is 2 (info). This recipe is intended for development and debugging purposes.

  • aktualizr-polling-interval.bb sets the polling interval of aktualizr to the value of SOTA_POLLING_SEC. See the build configuration and recommended configuration sections for more information.

  • aktualizr-virtualsec.bb creates a virtual Secondary on the Primary. This can be used for testing purposes or to update a file on the Primary outside of OSTree.

To use these recipes, you will need to add them to your image with a line such as IMAGE_INSTALL_append = " aktualizr-log-debug " in your local.conf.

aktualizr service resource control

With systemd-based images, it is possible to set resource policies for the aktualizr service. The main use case is to provide a safeguard against resource exhaustion during an unforeseen failure scenario.

To enable it, install aktualizr-resource-control on the target image and optionally override the default resource limits set in aktualizr_git.bb, from your local.conf.

For example:

IMAGE_INSTALL_append += " aktualizr-resource-control "
RESOURCE_CPU_WEIGHT_pn-aktualizr = "50"