Installation History - New Event Logging

One of the most notable additions in v1.11 is probably the new installation history and event logging which has paved its way into mainline since the last release by introducing several smaller new features. The changes introduced mainly focused on clarifying relations and states in the update life-cycle and fix inconsistencies in that context.

With this release, the slot status file was extended: It can now also serve as storage location for global information that is not slot-specific. This first user of this is the new boot detection which works by persisting the system's boot_id and compare it with the current one. Another addition in slot status file handling is that the status field was extended to consistently show the actual slot update status and now has pending and failed state.

The primary purpose of the new framework is to provide configurable log file writing of relevant update- and redundancy boot-related events over the life time of a device. This information is meant to better answer common OTA update-related questions like:

• Was the update X ever installed on this particular device?
• After installing update Y a month ago, did the device boot successfully into that?
• Has there ever been an update failure?

While some of this information could be obtained from the normal RAUC service log already, the messages so far lacked well structuring and consistency, and, with a device lifetime of years in mind, they were hard to filter and archive.

The new dedicated "event" messages make use of Glib's structured logging capabilities, have distinct identifiers, and are used both for the service log as well as for the configurable log files. They consist of a readable text message combined with fields for additional context information.

Soon, the journal messages will be enriched with journald message catalog information, allowing users to obtain more details and possible guidance from the systemd journal output.

[log.install-log]
filename=install.log
events=install;boot
output-format=short
max-size=1M
max-files=5

Refer to the RAUC documentation for more details on the framework and its configuration options.

An example log of the (default) human-readable verbose logger (without event type filtering) looks as follows:

2023-12-20T11:32:15Z: Booted into rootfs.0 (A)
                      boot ID: 55304525-445b-45b2-95e3-71d6646ca437
                      bundle hash: unknown
2023-12-20T11:32:16Z: Marked slot rootfs.0 good
2023-12-20T11:32:33Z: Service restarted
2023-12-20T11:33:56Z: Installation 871dbf94 started
                      transaction ID: 871dbf94-75cf-4a6a-b3de-6b81d2013d9e
2023-12-20T11:33:56Z: Marked slot rootfs.1 bad
2023-12-20T11:33:56Z: Updating slot efi.0
2023-12-20T11:34:17Z: Updating slot rootfs.1
2023-12-20T11:35:05Z: Marked slot rootfs.1 active
                      bundle hash: ee3f0b6649cd1425efe69c3947f7c5e862ce0e3f91cb4d36904a1e99c2bff110
                      bootname: B
2023-12-20T11:35:06Z: Installation 871dbf94 succeeded
                      bundle hash: ee3f0b6649cd1425efe69c3947f7c5e862ce0e3f91cb4d36904a1e99c2bff110
                      bundle version: 1.0
                      transaction ID: 871dbf94-75cf-4a6a-b3de-6b81d2013d9e
2023-12-20T11:35:50Z: Booted into rootfs.1 (B)
                      boot ID: 3850cffb-2eca-4960-b682-ec95bd5a222c
                      bundle hash: ee3f0b6649cd1425efe69c3947f7c5e862ce0e3f91cb4d36904a1e99c2bff110
2023-12-20T11:35:51Z: Marked slot rootfs.1 good

HTTP Header Information

RAUC becomes more and more relevant in the context of (semi-)automatic network-based OTA roll-outs where devices fetch their updates from a server. With its built-in HTTP(S) streaming capabilities, RAUC already made a leap forward towards securely supporting network downloads without the need for intermediate services.

This is sufficient for simple externally triggered bundle downloads from a fixed location, but use cases like automated downloads, update roll-out scheduling, device/fleet monitoring, etc. often require more information about the system and more logic within the client.

When using dedicated deployment servers with control APIs, these tasks clearly belong to an external service (like rauc-hawkbit-updater for hawkBit). However, for many cases, a simple HTTP server with a minimum of backend handling would be sufficient.

As the first step towards supporting the simple update server use-case in RAUC, we identified the ability to send additional information about the device to the server. For this, RAUC v1.11 now comes with configurable and extendable HTTP header information support.

[streaming]
...
send-headers=boot-id;transaction-id,uptime

[handlers]
system-info=example-script.sh

#!/bin/sh

echo "RAUC_HTTP_MAC=$(cat /sys/class/net/eth0/address)"

An example GET request would then look as follows:

GET /test/good-verity-bundle.raucb HTTP/1.1
Host: localhost:8081
Range: bytes=0-3
User-Agent: rauc/v1.11
Accept: */*
RAUC-Boot-ID: 70b30259-817a-4f11-89bb-ae99d22b4b11
RAUC-Transaction-ID: 9c18267e-36ff-4672-ac0d-19f639ca1910
RAUC-Uptime: 19.83
RAUC-MAC: 00:b0:d0:63:c2:26

It is then up to the update server to either just log this information for later or to use them for custom purposes.

Links for Active Slot Devices

For some use cases it can be required to know or access the currently active slots from RAUC's perspective. While this information so far could only be retrieved by parsing the output of rauc status or its D-Bus call pendant, both meant additional effort.

RAUC v1.11 introduces a simple solution for this: the automatic creation of symbolic links to the active slot devices under /run/rauc/slots/active. The symlinks are named after the corresponding slot class.

Ignore Images During (casync) Conversion

People that wanted to use RAUC's casync support instead of the new built-in streaming, sometimes ran into a problem: rauc convert unconditionally converted all images from the conventional bundle to casync index files. However, some slot/storage types simply (like raw NAND) cannot be written with casync.

With this release we have introduced the new --ignore-image option to exclude certain slots from the conversion. For example, to exclude the bootloader slot class, use

rauc convert --ignore-image=bootloader input-bundle.raucb mixed-casync-bundle.raucb

Further Notable Changes

RAUC now has a simple mechanism for detecting changes to its config file during service runtime. Just like e.g. systemd, it now warns (in the journal/service log) if the config file was changed but you forgot to restart the RAUC service which turned out to be a common pitfall over the years.

For the rauc resign and rauc replace-signature commands, support for encrypted bundles was implemented.

This release also comes with a fuzzing support. Initially contributed by René Fischer, it was extended and adapted to the needs of the OSS-Fuzz project where RAUC is monitored since then.

Parts of the documentation received a little makeover. Both the generated HTML documentation as well as the man pages can now be installed by meson and thus can be made available in distros as offline documentation.

For a comprehensive list of changes in v1.11, see the official changelog.

Outlook

For those wanting to update applications, data files, containers, etc. that are separate from the root file system, the pull-request #1301 gives a preview of the ongoing work to implement the RAUC Concept Issue #969 for Artifact Updates. Stay tuned for one of the most significant extensions RAUC has received recently.

Thank You!

Contributions to this release came from Angelo Compagnucci, Roland Hieber, Zygmunt Krynicki, David Runge, Emil Velikov, Hans Christian Lonstad, René Fischer, Stephan Wurm, Thomas Kilian, Ulrich Ölmann, and Uwe Kleine-König.

Thanks to you and to all RAUC contributors for effort you put in discussing ideas, reporting and reproducing bugs, and especially for contributing fixes and features over the last year. We wish you Happy Holidays and a successful version bump to 2024!