BOOTC-BO...ETECTION(7)

🌸 hey bestie, welcome to bootc-boot-failure-detection 🌸

okay so this is a page from the Miscellaneous Information Manual, section 7 💅 and it's literally all about how you catch a reboot that didn't do the thing it was supposed to do. no cap.

---

✨ NAME ✨

bootc-boot-failure-detection — Upgrade/rollback failure detection in bootc 🫶

---

💖 DESCRIPTION 💖

This doc walks you through how to detect when a reboot failed to enable the staged image in bootc. that's it, that's the whole vibe check.

🦋 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. like, genuinely crucial. main character crucial 💀

---

🌈 OSTree Backend Boot Failure Detection 🌈

For systems using the traditional OSTree backend, bootc relies on OSTree's own built-in boot failure detection mechanisms. it's giving "the classics never miss."

⭐ 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

so here's the tea ☕ 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. drama! it found the receipts!

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. so yeah, look backwards, not forwards 👀

---

🎀 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). not a cute look 😭

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 https://github.com/ostreedev/ostree/commit/08487091256b93493f8d692e37ab3d892c758da1 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. manifesting it ✨

---

👑 See Also 👑

• systemd Automatic Boot Assessment https://systemd.io/AUTOMATIC_BOOT_ASSESSMENT/
• OSTree Manual https://ostreedev.github.io/ostree/
• bootc-rollback(8) (see bootc-rollback(8))
• bootc-status(8) (see bootc-status(8))

---

🌟 SEE ALSO 🌟

bootc(8), bootc-docs(7), bootc-rollback(8), bootc-status(8)

---

🔥 VERSION 🔥

v1.17.1

---

and that's the whole page, bestie 🫶 this was all from BOOTC-BO...ETECTION(7), sourced from v1.17.1 — okay bye, go detect some failures, you ate 💅✨🌸