meta-updater

This layer enables over-the-air updates (OTA) with OSTree and Aktualizr.

OSTree is a tool for atomic full file system upgrades with rollback capability. OSTree has several advantages over traditional dual-bank systems, but the most important one is that it minimizes network bandwidth and data storage footprint by sharing files with the same contents across file system deployments.

Aktualizr (and RVI SOTA client) add authentication and provisioning capabilities to OTA and are integrated with OSTree. You can connect with the open-source RVI SOTA server or sign up for a free account at ATS Garage to get started.

Table of Contents

• Build
  • Quickstart
  • Adding meta-updater capabilities to your build
  • Build in AGL
  • Build problems
• Supported boards
  • Adding support for your board
• SOTA-related variables in local.conf
• Usage
  • OSTree
  • garage-push
  • aktualizr configuration
• Development configuration
• QA with oe-selftest

Build

Quickstart

If you don’t already have a Yocto project that you want to add OTA to, you can use the ATS Garage Quickstart project to rapidly get up and running on a Raspberry Pi. It takes a standard poky distribution, and adds OTA and OSTree capabilities.

Adding meta-updater capabilities to your build

If you already have a Yocto-based project and you want to add atomic filesystem updates to it, you just need to do three things:

1. Clone the meta-updater layer and add it to your bblayers.conf.

2. Clone BSP integration layer (meta-updater-${PLATFORM}, e.g. meta-updater-raspberrypi) and add it to your conf/bblayers.conf. If your board isn’t supported yet, you could write a BSP integration for it yourself. See the Adding support for your board section for the details.

3. Set up your distro. If you are using "poky", the default distro in Yocto, you can change it in your conf/local.conf to "poky-sota". Alternatively, if you are using your own or third party distro configuration, you can add INHERIT += " sota" to it, thus combining capabilities of your distro with meta-updater features.

You can then build your image as usual, with bitbake. After building the root file system, bitbake will then create an OSTree-enabled version of it, commit it to your local OSTree repo and (optionally) push it to a remote server. Additionally, a live disk image will be created (normally named ${IMAGE_NAME}.-sdimg-ota e.g. core-image-raspberrypi3.rpi-sdimg-ota). You can control this behaviour through variables in your local.conf.

Build in AGL

With AGL you can just add agl-sota feature while configuring your build environment:

source meta-agl/scripts/aglsetup.sh -m porter agl-demo agl-appfw-smack agl-devel agl-sota

You can then run:

bitbake agl-demo-platform

and get as a result an ostree_repo folder in your images directory (tmp/deploy/images/${MACHINE}/ostree_repo). It will contain:

• your OSTree repository, with the rootfs committed as an OSTree deployment,

• an otaimg bootstrap image, which is an OSTree physical sysroot as a burnable filesystem image, and optionally

• some machine-dependent live images (e.g. .wic for Raspberry Pi or .porter-sdimg-ota Renesas Porter board).

Although aglsetup.sh hooks provide reasonable defaults for SOTA-related variables, you may want to tune some of them.

Build problems

Ubuntu users that encounter an error due to missing Python.h should install libpython2.7-dev on their host machine.

Supported boards

Currently supported platforms are

• Raspberry Pi3

• Minnowboard

• Native QEMU emulation

Adding support for your board

If your board isn’t supported yet, you can add board integration code yourself. The main purpose of this code is to provide a bootloader that will be able to use OSTree’s boot directory. In the meta-updater integration layers we have written so far, the basic steps are:

1. Make the board boot into U-Boot

2. Make U-boot import variables from /boot/loader/uEnv.txt and load the kernel with initramfs and kernel command line arguments according to what is set in this file.

You may take a look into Minnowboard or Raspberry Pi integration layers for examples.

Although we have used U-Boot so far, other boot loaders can be configured work with OSTree as well.

SOTA-related variables in local.conf

• OSTREE_REPO - path to your OSTree repository. Defaults to ${DEPLOY_DIR_IMAGE}/ostree_repo

• OSTREE_OSNAME - OS deployment name on your target device. For more information about deployments and osnames see the OSTree documentation. Defaults to "poky".

• OSTREE_INITRAMFS_IMAGE - initramfs/initrd image that is used as a proxy while booting into OSTree deployment. Do not change this setting unless you are sure that your initramfs can serve as such a proxy.

• SOTA_PACKED_CREDENTIALS - when set, your ostree commit will be pushed to a remote repo as a bitbake step. This should be the path to a zipped credentials file in the format accepted by garage-push.

• SOTA_CLIENT_PROV - which provisioning method to use. Valid options are aktualizr-auto-prov, aktualizr-implicit-prov, and aktualizr-hsm-prov. The default is aktualizr-auto-prov. This can also be set to an empty string to avoid using a provisioning recipe.

• SOTA_CLIENT_FEATURES - extensions to aktualizr. The only valid option is hsm (to build with HSM support)

• SOTA_SECONDARY_ECUS - a list of paths separated by spaces of JSON configuration files for virtual secondaries on the host. These will be installed into /var/sota/ecus on the device.

• SOTA_VIRTUAL_SECONDARIES - a list of paths separated by spaces of JSON configuration files for virtual secondaries installed on the device. If SOTA_SECONDARY_ECUS is used to install them, then you can expect them to be installed in /var/sota/ecus.

Usage

OSTree

OSTree used to include a simple HTTP server as part of the ostree binary, but this has been removed in more recent versions. However, OSTree repositories are self-contained directories, and can be trivially served over the network using any HTTP server. For example, you could use Python’s SimpleHTTPServer:

cd tmp/deploy/images/qemux86-64/ostree_repo
python -m SimpleHTTPServer <port> # port defaults to 8000

You can then run ostree from inside your device by adding your repo:

# This behaves like adding a Git remote; you can name it anything
ostree remote add --no-gpg-verify my-remote http://<your-ip>:<port>

# If OSTREE_BRANCHNAME is set in local.conf, that will be the name of the
# branch. If not set, it defaults to the value of MACHINE (e.g. qemux86-64).
ostree pull my-remote <branch>

# poky is the OS name as set in OSTREE_OSNAME
ostree admin deploy --os=poky my-remote:<branch>

After restarting, you will boot into the newly deployed OS image.

For example, on the raspberry pi you can try this sequence:

# add remote
ostree remote add --no-gpg-verify agl-snapshot https://download.automotivelinux.org/AGL/snapshots/master/latest/raspberrypi3/deploy/images/raspberrypi3/ostree_repo/ agl-ota

# pull
ostree pull agl-snapshot agl-ota

# deploy
ostree admin deploy --os=agl agl-snapshot:agl-ota

garage-push

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. In particular, this can be used with ATS Garage. garage-push is used as follows:

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

You can set SOTA_PACKED_CREDENTIALS in your local.conf to automatically synchronize your build results with a remote server. Credentials are stored in an archive as described in the aktualizr documentation.

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 SOTA-related variables in local.conf section for more information.

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

• aktualizr-example-interface.bb will configure aktualizr to connect to an example interface for a legacy flasher. This is intended to be used in conjunction with the aktualizr-examples package. See legacysecondary.adoc in the aktualizr repo for more information.

• aktualizr-disable-send-ip.bb disables the reporting of networking information to the server. This is enabled by default and supported by ATS Garage. 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.

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.

Development configuration

There are a few settings that can be controlled in local.conf to simplify the development process:

Option	Effect
require classes/sota_bleeding.inc	Build the latest head (by default, using the master branch) of Aktualizr
BRANCH_pn-aktualizr = "mybranch" BRANCH_pn-aktualizr-native = "mybranch"	Build mybranch of Aktualizr. Note that both of these need to be set. This is normally used in conjunction with require classes/sota_bleeding.inc
SRCREV_pn-aktualizr = "1004efa3f86cef90c012b34620992b5762b741e3" SRCREV_pn-aktualizr-native = "1004efa3f86cef90c012b34620992b5762b741e3"	Build the specified revision of Aktualizr. Note that both of these need to be set. This can be used in conjunction with BRANCH_pn-aktualizr and BRANCH_pn-aktualizr-native but will conflict with require classes/sota_bleeding.inc
TOOLCHAIN_HOST_TASK_append = " nativesdk-cmake "	Use with bitbake -c populate_sdk core-image-minimal to build an SDK. See the aktualizr repo for more information.

QA with oe-selftest

This layer relies on the test framework oe-selftest for quality assurance. Follow the steps below to run the tests:

1. Append the line below to conf/local.conf to disable the warning about supported operating systems:

   SANITY_TESTED_DISTROS = ""

2. If your image does not already include an ssh daemon such as dropbear or openssh, add this line to conf/local.conf as well:

   IMAGE_INSTALL_append = " dropbear "

3. Some tests require that SOTA_PACKED_CREDENTIALS is set in your conf/local.conf. See the SOTA-related variables in local.conf section.

4. To be able to build an image for the grub tests, you will need to install TianoCore’s ovmf package on your host system. On Debian-like systems, you can do so with this command:

   sudo apt install ovmf

5. Run oe-selftest:

   oe-selftest --run-tests updater

For more information about oe-selftest, including details about how to run individual test modules or classes, please refer to the Yocto Project wiki.