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.

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