Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Upgrade/rollback failure detection in bootc

This document describes how to detect when a reboot failed to enable the staged image in bootc.

Overview

bootc uses different mechanisms to detect boot failures depending on the backend (OSTree vs. composefs+UKI) and the specific point of failure. Understanding these mechanisms is crucial for system administrators and automated tooling that needs to detect failed updates.

OSTree Backend Boot Failure Detection

For systems using the traditional OSTree backend, bootc relies on OSTree's built-in boot failure detection mechanisms.

Key Services

  1. ostree-finalize-staged.service - Runs during shutdown to finalize staged deployments
  2. ostree-boot-complete.service - Runs early in boot to detect finalization failures

When ostree-finalize-staged.service fails during shutdown/reboot, this will create a stamp file in /boot, and then on a subsequent reboot the ostree-boot-complete.service service will detect it, and then itself exit with a failure mode.

You can monitor the success of both services, though for ostree-finalize-staged.service note that the failure occurred during the previous boot's shutdown.

Composefs Backend Boot Failure Detection

Key Services

There is a bootc-finalize-staged.service which is similar to ostree-finalize-staged.service, but there is not currently a similar -boot-complete.service. There is also a bootc-root-setup.service that runs during initramfs to mount the composefs image and set up /etc and /var - but if this service fails, the system will not boot at all (emergency mode or hang).

At the current time then, it is recommended to check the journal for failures from the previous boot:

# Check for finalization failures from previous boot
journalctl -u bootc-finalize-staged.service -b -1

Systemd Boot Assessment Integration

As of a recent OSTree with this commit it is possible to configure the boot loader entry counting.

At the current time, the composefs backend does not configure boot entry counting, this is likely to be added in the future.

See Also

The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.