s0sta
EN NL عربي
Filters
How to search
  • Plain words find names, texts and examples.
  • "two words" finds the exact phrase.
  • --name or -x finds an option.
  • #word looks only inside commands.
  • @grep finds lessons and labs that use grep.
  • Filters: cat:network · in:labs · in:notes · level:rhcsa · ch:8 · root:yes. Put ! before a word to leave it out. OR between words means one of them.
  • ↑ ↓ to move · Enter to open · Esc to close · / to search

bootc

Manage an image-mode system: show the booted image, update to a new image, switch to another one, or roll back — all as one transaction.

Level
Extra
Group
Software packages
Needs root
Yes
Package
bootc
Also called
bootc-image-builder

What it does

In image mode for RHEL, the operating system is a bootable container image (built FROM registry.redhat.io/rhel10/rhel-bootc). bootc runs on the installed system. bootc upgrade downloads a newer build of the image the system follows and stages it for the next boot; bootc switch makes the system follow another image; bootc rollback boots the previous image again.

/usr comes from the image and is read-only. /etc is kept and merged with the image's /etc at every update. /var is local data and is never changed by an update. To change the system, change the Containerfile and build a new image — not dnf install on the server. Disk images are made with bootc-image-builder (a container image).

How to write it

bootc COMMAND [OPTION]...
bootc upgrade [--check | --apply]
bootc switch [OPTION]... IMAGE

Main parts

Commands

status
Show the booted, staged and rollback images.
upgrade
Download and stage a newer build of the current image.
switch IMAGE
Follow another image (another tag or repository).
rollback
Boot the previous image at the next reboot.
edit
Change the host settings (image, transport) in an editor or from a file.
usr-overlay
Make /usr writable with a temporary layer, until the next reboot.
install to-disk DEVICE
Install the running container image to a disk (run inside the image with podman).
install to-filesystem DIR
Install into a mounted file system.
install to-existing-root
Replace the OS of an existing system with the image.
container lint
Check a container image for problems (run in the build).
image list
List images in the bootc storage.
image copy-to-storage
Copy the booted image to the Podman storage.

Options 21

Most used

status

--format=FORMAT
Output as humanreadable, yaml or json.
--booted
Only the booted image.
--json
Same as --format json.

upgrade

--check
Only check if there is an update; download the metadata only.
--apply
Stage the update and reboot at once.
--quiet
Less output.
--soft-reboot=MODE
Use a soft reboot when possible (required or auto).

switch

--transport=TRANSPORT
registry (default), oci, oci-archive, containers-storage.
--apply
Reboot at once into the new image.
--retain
Keep the current image as rollback target.
--enforce-container-sigpolicy
Check signatures with the container policy.
--quiet
Less output.

rollback

--apply
Reboot at once.

install (to-disk, to-filesystem)

--wipe
Wipe the disk first (to-disk).
--filesystem=TYPE
Root file system type (xfs, ext4, btrfs).
--root-size=SIZE
Size of the root partition.
--karg=ARG
Add a kernel argument.
--root-ssh-authorized-keys=FILE
Install SSH keys for root.
--target-imgref=IMAGE
The image the installed system follows for updates.
--generic-image
Make an image that fits any hardware (for disk images).
--via-loopback
Install into a disk image file.

Examples 11

$ run as a normal user# run as root (or with sudo)

  1. 1Show what the system runs

    sudo bootc status
sudo bootc status --format json | jq '.status.booted.image.image.image'
"quay.io/s0sta/web-bootc:prod"

  2. 2Check for an update without changing anything

    sudo bootc upgrade --check

  3. 3Download an update, use it at the next reboot

    sudo bootc upgrade
sudo systemctl reboot

  4. 4Update and reboot in one step

    sudo bootc upgrade --apply

  5. 5Follow another image (for example a new major tag)

    sudo bootc switch quay.io/s0sta/web-bootc:2.0
sudo bootc switch --apply quay.io/s0sta/web-bootc:prod

  6. 6Go back after a bad update

    sudo bootc rollback
sudo systemctl reboot

    The previous image boots again; /etc and /var keep their state.

  7. 7Turn automatic updates on or off

    systemctl status bootc-fetch-apply-updates.timer
sudo systemctl disable --now bootc-fetch-apply-updates.timer

  8. 8Install a debug tool for a short test

    sudo bootc usr-overlay
sudo dnf install -y strace

    The overlay is gone after the next reboot.

  9. 9Check the image in the build pipeline (DevSecOps)

    cat Containerfile
FROM registry.redhat.io/rhel10/rhel-bootc:10.0
RUN dnf -y install httpd && dnf clean all && systemctl enable httpd
RUN bootc container lint
podman build -t quay.io/s0sta/web-bootc:1.0 .

  10. 10Make a qcow2 disk with bootc-image-builder

    podman run --rm -it --privileged --pull=newer --security-opt label=type:unconfined_t -v ./config.toml:/config.toml:ro -v ./output:/output -v /var/lib/containers/storage:/var/lib/containers/storage registry.redhat.io/rhel10/bootc-image-builder:latest --type qcow2 quay.io/s0sta/web-bootc:1.0
ls output/qcow2/
disk.qcow2

  11. 11Install the image to a second disk from a running RHEL host

    podman run --rm --privileged --pid=host -v /dev:/dev -v /var/lib/containers:/var/lib/containers --security-opt label=type:unconfined_t quay.io/s0sta/web-bootc:1.0 bootc install to-disk --wipe /dev/vdb

Watch out

  • Files put in /var by the Containerfile are copied only at the first install; updates never change /var.
  • dnf install on the running system fails (/usr is read-only). Add packages to the Containerfile.
  • A rollback target exists only after the first upgrade or switch.

Files

/usr
Read-only, from the image.
/etc
Local changes kept and merged with the image at updates.
/var
Local data, kept across updates and rollbacks.
/usr/lib/bootc/kargs.d/
Kernel arguments that come with the image.

Tips to remember

  • Follow a moving tag (:prod) on servers; build fixed tags (:1.0, :1.1) in CI and move :prod when tests pass.
  • Sign images in CI and turn on --enforce-container-sigpolicy so servers only boot signed images.

Exit codes

0Success.
1Error.

Full manual

This page explains the command in simple words. The original manual has every detail.

In your terminal: man 8 bootc

Open the man page (linux.die.net)docs.redhat.com