Event Logging goes systemd Journal Catalog

In RAUC v1.11, the new Event Logging framework was introduced, which allows configuring one or more RAUC-specific logfiles that record notable events from the device's boot and update life cycle (like (re)boots, installation start/stop/failure, slot selection actions and more).

When present, the logging abstraction already leverages systemd's journal as an additional log target for these events and assigns most log messages a dedicated MESSAGE_ID.

Based on MESSAGE_IDs, systemd allows enriching the journal with additional details, context, or potential help and debugging guidance for the respective messages. The template for this additional information is stored in so-called catalog files. To show available catalog information, use the -x switch when calling journalctl.

In this release the meson-based RAUC build system allows installing a catalog file for RAUC. To see the RAUC journal messages together with the catalog data, simply call

$ journalctl -u rauc -x

Example output for a successful installation:

Jul 19 09:51:22 qemux86-64 rauc[268]: [LNK] Installation ecd07c1c succeeded
-- Subject: RAUC Installation succeeded
-- Defined-By: rauc
-- Support: https://rauc.io
-- Documentation: https://rauc.readthedocs.io
--
-- The installation with transaction ID ecd07c1c-543b-4951-942b-089dbbd95a8e succeeded.
--
-- It installed the bundle version 2024.08-1
-- with hash 435b9fc8791bb6c10c70b52b03485027341c4b136af2c503a9a8f6c89e8f57c9 on your system.

Beside catalog support, some additional fixes for event logging made their way into v1.12, making the previously 'experimental' feature more reliable now.

Optional Minimal Bundle Version

When deploying updates in the field, it's not always possible (or reasonable) to remain compatible with internal data migrations or external infrastructure across all previous versions. Thus, potential (accidental) downgrades to incompatible older versions must be prevented in the field.

While the format and content of the version field in the bundle manifest can be freely chosen, a common approach is using the semantic versioning scheme.

Thanks to a feature brought in by RAUC contributor Johannes Schneider, it is now possible to define a semantic min-bundle-version in the RAUC system configuration file:

[system]
...
min-bundle-version=2024.12.0

As the name suggests, a system with a min-bundle-version set will reject the installation of bundles with a lower semantic version. For this feature, RAUC was extended to support semantic version parsing and precedence calculation.

Aborting Installations from CLI

Support for aborting an ongoing installation at any point would add significant complexity and hard-to-test code paths to RAUC, so it is not implemented. While this is quite obvious when triggering RAUC over D-Bus, a common pitfall is to start an installation via the command line interface (CLI) and then press Ctrl+C. While this will terminate the CLI, the installation keeps running in the background. To better reflect this behavior, the RAUC CLI now prints the following message when being interrupted by Ctrl+C (SIGINT):

Ctrl+C pressed. Exiting rauc installation client...
Note that this will not abort the installation running in the rauc service!

Bundle Input Directory Modification

So far, RAUC used the bundle input directory in-place and manipulated the input data, e.g. by rewriting the manifest or during image conversion.

To avoid this, RAUC v1.12 now uses a separate working directory with hard-linked copies of the bundle directory contents rather than the original directory.

For simplicity, it aborts on anything in the input directory which is not a regular file. If someone relies on the old (undocumented) behavior of including directories and symlinks in the bundle, please contact us via #rauc on IRC/Matrix or open a Discussion and explain your use case.

Migration to pytest for CLI tests

Until recently, RAUC used the sharness shell-based test library which paved the way for some simple tests of the RAUC command line interface.

But over the years the capabilities of the CLI grew and so the quantity and complexity of the test did as well and the monolithic rauc.t test file became quite large. We also realized that while sharness was good for simple tests, doing more sophisticated things (like parsing and comparing output) was cumbersome.

So, between v1.11 and v1.12 we decided to reorganize the tests and migrate to the Python pytest framework.

In the first round, this simplified using temporary directories and setting up test environments by using pytest fixtures. Some tests that only tested for exit codes before were already extended with stdout/stderr checks to have better checks for the expected behavior.

In the future, the pytest-based checks will make writing new and more complex tests, e.g. for the upcoming Artifact feature much easier.

test_expect_success ROOT,SERVICE "rauc install (verity)" "
  cp -L ${SHARNESS_TEST_DIRECTORY}/good-verity-bundle.raucb ${TEST_TMPDIR}/ &&
  test_when_finished rm -f ${TEST_TMPDIR}/good-verity-bundle.raucb &&
  start_rauc_dbus_service_with_system \
    --conf=${SHARNESS_TEST_DIRECTORY}/minimal-test.conf \
    --mount=${SHARNESS_TEST_DIRECTORY}/mnt \
    --override-boot-slot=system0 &&
  test_when_finished stop_rauc_dbus_service_with_system &&
  test ! -s ${SHARNESS_TEST_DIRECTORY}/images/rootfs-1 &&
  rauc \
    install ${TEST_TMPDIR}/good-verity-bundle.raucb &&
  test -s ${SHARNESS_TEST_DIRECTORY}/images/rootfs-1
"

def test_install_verity(rauc_service, rauc_dbus_service_with_system, tmp_path):
    assert os.path.exists("images/rootfs-1")
    assert not os.path.getsize("images/rootfs-1") > 0

    # copy to tmp path for safe ownership check
    shutil.copy("good-verity-bundle.raucb", tmp_path / "good-verity-bundle.raucb")

    out, err, exitcode = run(f"rauc install {tmp_path}/good-verity-bundle.raucb")

    assert exitcode == 0
    assert os.path.getsize("images/rootfs-1") > 0

The individual pytest files are encapsulated by meson unit test handling, thus you can simply run them with:

$ meson test
[..]
23/38 pytest_test_cmdline                   OK               0.86s
24/38 pytest_test_info                      OK               0.87s
25/38 pytest_test_bundle                    OK               3.09s
26/38 pytest_test_status                    OK               1.31s
27/38 pytest_test_mount                     OK               0.20s
28/38 pytest_test_service                   OK               0.36s
29/38 pytest_test_mark                      OK               0.76s
[..]

Other Notable Fixes

• With v1.10 and v1.11 the slot installation skipping mechanism (install-same) got broken when using a global slot status. Fixes and a new test case for this were added in #1392.
• The block-hash-index cache was fixed by not cleaning and properly re-using the slot's data directory during installation (in #1455 and #1474). This avoids redundant slot scans to find reusable blocks during installation and significantly increases the adaptive update performance in certain scenarios.
• Since streaming has much better performance with HTTP/2, a new warning was added when detecting the slower HTTP/1 (in #1473).
• An inconsistent default for the D-Bus policy installation directory was fixed in #1483. In cases where the policy directory was invalid for the distro, this caused service startup failures.

Thank You!

The changes described here are only excerpts from the full list of changes. A more comprehensive list can be found on the release page.

Thanks to all contributors for this release: David Hollister (@dhollister0), David Robertson (@djr-spectrummfg), Enrico Jörns (@ejoerns), Gaël PORTAY (@gportay), Heiko Thiery (@hthiery), Jan Lübbe (@jluebbe), Johannes Schneider (@js731ca), Michael B. Sumulong (@MSumulong), Peter Korsgaard (@jacmet), Tim van der Staaij (@tvdstaaij), Uwe Kleine-König (@ukleinek)