RAUC v1.9 Released

Download

Download v1.9 release of RAUC

GitHub release page

"Getting things off the ground" could be the motto for the v1.9 release of RAUC. The support for custom metadata in the manifest got a step further, a new, more flexible, D-Bus API for bundle inspection paved the way for obtaining more detailed information, and a new manifest hash marks the first of several planned changes for configurable event logging. However, one of the most invasive changes happened under the hood: We have started the transition from autotools to meson as a build system.

For more details on what happened in the 121 (non-merge) commits since v1.8, read below.

Custom Meta-Data in Manifest

Beside the mandatory compatible, a RAUC bundle manifest provides a few pre-defined fields that are not interpreted by RAUC and that you can fill with your own information, such as version, description, or build.

While these fields are sufficient for many common use cases, there are also cases where more (structured) meta-data should be included in the bundle. This meta-data could be used on the target for filtering installations, displaying additional release information to the user, etc.

As announced in the previous release blog post, RAUC has now gained basic support for defining custom [meta.<section>] sections in the manifest. For now, these are just parsed and stored by RAUC. The plan for the next release is to expose them via rauc info and the new InspectBundle D-Bus method described below.

A bundle can have multiple [meta.<section>] sections for different purposes. The <section> name can be chosen freely and each meta section can contain a number of key-values, e.g.:

[update]
compatible=My Product
description=Some verbose text
version=2023.03.1
...

[meta.pengutronix]
location=Hildesheim
release-notes=https://example.com/release-nodes-2023.03.1
release-channel=beta

[meta.vendor]
key=value

New InspectBundle D-Bus API

A D-BUS API method in RAUC which has always been quite limited in functionality is the Info method. It was aimed to provide the functionality a rauc info call has, but just took the bundle path as argument and returned the compatible and the version. This was neither suitable for inspecting remote bundles on HTTP servers with authentication nor did it allow to return any more information about the bundle.

Initiated by Stefan Ursella, a new InspectBundle D-Bus method is introduced in this release. Similar to the InstallBundle method, this allows passing additional input arguments as a dictionary (a{sv} in D-Bus type syntax). It then returns bundle information as a (nested) dictionary.

While for now the returned values are only the compatible, the version, the description and the build, this is already more information than the old method provided.

In following releases, it will be extended to return the same information as a rauc info call, including the custom meta-data described above.

If you want to give the method a try, you can use busctl for a test query:

$ busctl call de.pengutronix.rauc / de.pengutronix.rauc.Installer InspectBundle sa{sv} "<bundle-path>/<bundle-url>" 0
a{sv} 1 "update" v a{sv} 4 "version" s "1.0" "compatible" s "qemu86-64 demo platform" "build" s "20230306231217" "description" s "qemu-demo-bundle version 1.0-r0"

Manifest Hash

Surprisingly, answering the question if a specific bundle is actually the one installed on a system was not straight-forward so far. The slot status information saved on the target contained the checksums of the images installed as well as some manifest information such as version or build ID. None of these fully described the bundle's manifest and content, though.

This gap was closed by introducing the manifest hash. The manifest hash is defined as the (SHA-256) hash calculated over the manifest. This hash securely identifies all the manifest fields and, since (for 'verity' bundles) the verity hash is also part of the manifest, it also identifies the entire bundle contents.

To actually allow using the manifest hash for identifying bundles, it is printed when using rauc info, saved in RAUC'S slot status file, and is exposed via rauc status --detailed and the GetSlotStatus D-Bus method.

The manifest hash is the first simple enhancement in a number of planned features aimed to allow better tracing of RAUC installations on the target. Some more details are described in issue #1040.

Configurable Boot Attempts (for Barebox)

With boot-attempts, RAUC allows configuring the reset attempts value written to the bootloader's attempts variable in case of a 'mark good'. So far, this was supported for the U-Boot backend only. This release now adds support to configure reset attempts for barebox, too:

[system]
...
bootloader=barebox
boot-attempts=5
boot-attempts-primary=10

A patient user, who had their boot-attempts configured to a value >= 10, might have run into the issue that some U-Boot environment variables were still erroneously handled as decimal numbers. Thanks to Christian Meusel, this if fixed now.

Target vs Host Tool Usage Enhancements

The RAUC binary can be used as both a host tool (for bundle generation) and a target tool (for installation). This has its advantages, but is not always clearly separated and may cause some confusion.

A long-standing message that caused confused, e.g. when calling rauc bundle from within a container, was:

rauc-Message: 04:13:16.008: Failed to resolve realpath for '/dev/mapper/vg01-root'

This was printed as the RAUC startup routines attempted to find out where we the system was booted from. While this step is necessary on the target, it's useless on the development host. Finally, with #1059, a clearer separation of host- and target-related setup handling made this message disappear and also paved the way for other enhancements.

With v1.9, the separation of host and target tool usage is now also reflected in the output of rauc --help that now has a distinct section for target-related subcommands as service or install.

The ongoing process of removing the subcommand-specific options from the global argument list continued as well: The --intermediate option is now enabled for signing subcommands only. Some previous changes in this area were reflected in the man page, as well.

Meson Build System Support

Over the years we have encountered several pitfalls, inconveniences and over- complicated handling with the autotools build system, especially when generating release artifacts. The plan to switch to a state-of-the art build system has now finally been realized with the switch to the meson build system.

To simplify the transition for users, we have decided to keep autotools support for this release and to drop it in 1.10, unless there are good reasons to keep it for longer.

For those building RAUC from source manually, this requires a bit of muscle-memory reconfiguration:

$ meson setup build
$ cd build
$ meson compile

(For all others, this change will probably not visible).

One of the benefits of using meson is that the available build configuration options are now clearly visible and documented in meson_options.txt.

Note

As the tar archive generated by meson does not contain a configure script, you may need to run autogen.sh to generate it. To simplify the migration, we also provide a -autotools archive variant which is generated using autotool's make dist (and does not contain the meson build support).

Documentation and Ecosystem

  • Since the question about bundle compatibility comes up from time to time, we have added a FAQ entry describing our understanding and approach.
  • RAUC is used by several Open Source community projects that can serve as an example or starting point. To point new users into the right direction, we have added some of them (such as meta-rauc-community for OpenEmbeeded/Yocto or br2rauc for Buildroot) to the example integrations section in the documentation. If we have overlook anything here, please feel free to add it.
  • Those who submitted an issue since v1.8 might have already noticed: We added GitHub issue templates to better guide users to open an issue or to use discussions depending on the case. Also, for pull request we have added a template with some hints on which information the PR description should contain.

Thanks

Thanks go out to all those who raised questions, inspired new features, gave others insight into their use-cases, opened issues or PRs, or contributed to the project in any other form.

A special shout-out to all that directly contributed patches to this release: Christian Meusel, Enrico Jörns, Jan Lübbe, Jung-Te Hsieh, Stefan Ursella, Ulrich Ölmann, and Uwe Kleine-König


Further Readings

RAUC v1.12 Released

With 93 pull requests that brought in 248 new commits, a lot happened since the last release on master (v1.11.1). The new v1.12 version of RAUC focusses on making it even more robust while adding some features and improvements.


RAUC v1.11 Released

Ho Ho ho! As the year's progress bar approaches 99%, another update is already completed: RAUC v1.11 is here!


RAUC v1.10 Released

Just in time for the EOSS 2023 in Prague, we have released v1.10 of RAUC. Just-in-time means the release was actually finalized by Jan Lübbe in the train to Prague (like I finally wrote the majority of this blog post on the train back).