BOOTC-UPGRADES(7)

✨ NAME ✨

bootc-upgrades — managing upgrades, bestie edition 💅

---

💖 DESCRIPTION 💖

okay so rn, bootc is a pretty simple tool, and that's on purpose — it does a few things and it does them well. One of those things? Transactionally pulling brand-new OS updates from a registry and booting into them, with rollback support in its back pocket. No cap. 🫶

🌈 The bootc upgrade verb

This will query the container image source and queue an updated container image for the next boot. literally queuing up your glow-up. ✨

With the default OSTree backend, this implements an A/B style upgrade system. Changes to the base image get staged, and the running system is not changed by default. iconic behaviour honestly.

Use bootc upgrade --apply to auto-apply if there are queued changes.

🎀 Staged updates with --download-only

The --download-only flag is giving "prepare now, commit later" — it lets you prepare updates without automatically applying them on the next reboot:

bootc upgrade --download-only

This will pull the new container image from the container image source and create a staged deployment in download-only mode. The deployment will not be applied on shutdown or reboot until you explicitly apply it. it's just chilling there, waiting for your permission. 🙈

🦋 Checking download-only status

To see whether a staged deployment is in download-only mode, use:

bootc status --verbose

In the output, you'll see Download-only: yes for deployments in download-only mode, or Download-only: no for deployments that will apply automatically. This status is only shown in verbose mode — so don't come crying to me when you don't see it without --verbose. 😭

👑 Applying download-only updates

There are three ways to apply a staged update that is in download-only mode:

Option 1: Apply the staged update without checking for newer updates

bootc upgrade --from-downloaded

This unlocks the staged deployment for automatic application on the next shutdown or reboot, without fetching updates from the container image source. This is useful when you want to apply the already-downloaded update at a scheduled time. lowkey the most controlled-girlboss option.

Option 2: Apply the staged update and reboot immediately

bootc upgrade --from-downloaded --apply

This unlocks the staged deployment and immediately reboots into it, without checking for newer updates.

Option 3: Check for newer updates and apply

bootc upgrade

Running bootc upgrade without flags will pull from the container image source to check for updates. If the staged deployment matches the latest available update, it will be unlocked. If a newer update is available, the staged deployment will be replaced with the newer version. slay, it self-updates. 🔥

🧚 Checking for updates without side effects

To check if updates are available without modifying the download-only state:

bootc upgrade --check

This only downloads updated metadata without changing the download-only state. no side quests, just ✨vibes✨.

🍓 Example workflow

A typical workflow for controlled updates:

# 1. Download the update in download-only mode
bootc upgrade --download-only

# 2. Verify the staged deployment
bootc status --verbose
# Output shows: Download-only: yes

# 3. Test or wait for maintenance window...

# 4. Apply the update (choose one):
# Option A: Apply staged update without fetching from image source
bootc upgrade --from-downloaded

# Option B: Apply staged update and reboot immediately (without fetching from image source)
bootc upgrade --from-downloaded --apply

# Option C: Check for newer updates first, then apply
bootc upgrade

Important notes:

• Image source check difference: bootc upgrade --from-downloaded does NOT fetch from the container image source to check for newer updates, while bootc upgrade always does. Use --from-downloaded when you want to apply the specific version you already downloaded, regardless of whether newer updates are available. fr fr this is the whole point.
• If you reboot before applying a download-only update, the system will boot into the current deployment and the staged deployment will be discarded. However, the downloaded image data remains cached, so re-running bootc upgrade --download-only will be fast and won't re-download the container image. thank god, no re-downloading. 😌
• If you switch to a different image (using bootc switch or bootc upgrade to a different image), the new staged deployment will replace the previous download-only deployment, and the previously cached image will become eligible for garbage collection. rip to that image, it had a good run. 💀

There is also an opinionated bootc-fetch-apply-updates.timer and corresponding service available in upstream for operating systems and distributions to enable.

Man page: bootc-upgrade (see bootc-upgrade(8)).

💜 Changing the container image source

Another useful pattern to implement can be to use a management agent to invoke bootc switch (or declaratively via bootc edit) to implement e.g. blue/green deployments, where some hosts are rolled onto a new image independently of others.

bootc switch quay.io/examplecorp/os-prod-blue:latest

bootc switch has the same effect as bootc upgrade; there is no semantic difference between the two other than changing the container image being tracked.

This will preserve existing state in /etc and /var — for example, host SSH keys and home directories. your stuff stays safe bestie 🫶

Man page: bootc-switch (see bootc-switch(8)).

🌸 Soft reboots

Soft reboot restarts userspace without restarting the kernel, avoiding a full hardware reboot. so much less dramatic honestly. On the OSTree backend, bootc upgrade and bootc switch support these --soft-reboot modes:

• required: Fails if the target deployment is not soft-reboot capable.
• auto: Prepares a soft reboot if the target deployment is capable; otherwise, leaves it configured for a regular reboot.

Use --apply to request an immediate restart after preparing the deployment. Without --apply, --soft-reboot prepares the deployment but does not restart the system immediately. Without --soft-reboot, --apply requests a regular reboot.

The composefs backend (see bootc-composefs(7)) currently differs: both modes fail if systemd lacks soft-reboot support. If the target deployment is not soft-reboot capable, auto leaves it staged without restarting, even with --apply; it does not automatically fall back to a regular reboot in this case. heads up, it's giving "no fallback, sorry". 🙈

⭐ Rollback

There is a bootc rollback verb, and associated declarative interface accessible to tools via bootc edit. This will swap the bootloader ordering to the previous boot entry. take me back to before I made that decision energy. 💫

Man page: bootc-rollback (see bootc-rollback(8)).

---

🌈 SEE ALSO 🌈

bootc(8), bootc-composefs(7), bootc-docs(7), bootc-rollback(8), bootc-switch(8), bootc-upgrade(8)

---

🌟 VERSION 🌟

v1.17.1

---

and that's the whole page bestie 💖 this came from the Miscellaneous Information Manual, section 7 (yes, the cool section), and this version v1.17.1 is the one you're reading right now — go forth and upgrade responsibly, mwah 🎀✨