BOOTC-COMPATIBLE-IMAGES(7)

✨ NAME ✨

bootc-compatible-images — "bootc compatible" images 💖

So like, this is BOOTC-CO...LE-IMAGES(7) from the Miscellaneous Information Manual, if you were wondering where you wandered into. Welcome bestie, take a seat 🫶

---

🌸 DESCRIPTION 🌸

Okay so the whole toplevel goal of this project is to tightly integrate with the OCI ecosystem and make booting containers a totally normal, everyday activity. No big deal. Just booting containers. Casual. 💅

But — and this is the plot twist — there are a number of basic requirements and integration points, and some of them have distribution-specific variants. So let's go.

Generic requirements (composefs or ostree backends)

/sysroot

Your container image must have a /sysroot directory — that's where the "physical root" is gonna get mounted. The permissions (mode) should generally be the same as /usr, i.e. 0755 or similar. Match the vibe of /usr, basically. ✨

LABEL containers.bootc=1

The rationale for this required label is that a whole bunch of higher level tools out there expect to operate only on bootc-compatible OCI images, and they're gonna want to be able to present only the compatible ones. So yeah, the label is how they vibe-check you. 👑

Kernel (split)

The Linux kernel (and optionally initramfs) is embedded in the container image. The canonical location is /usr/lib/modules/$kver/vmlinuz, and the initramfs should be in initramfs.img in that directory.

You should not include any content in /boot in your container image. Bootc will take care of copying the kernel/initramfs as needed from the container image to /boot. It's giving "I got this, bestie." 🫶

Kernel (sealed UKI)

For the composefs backend, the UKI must be located at /boot/EFI/Linux/$kver.efi. See sealed images (see bootc-sealed-images(7)). 🔥

/ostree symlink and bootc container lint

bootc container lint requires a /ostree -> sysroot/ostree symlink — unless the image is composefs-native, which is signaled by the presence of /usr/lib/composefs/setup-root-conf.toml (it may be empty); see bootc-setup-root-conf.toml(5) (see bootc-setup-root-conf(5)). Such images also don't need ostree's prepare-root.conf to enable composefs. Iconic loophole honestly. 💅

composefs backend

There are no strict additional basic filesystem/layout requirements for images which plan to deploy with composefs. However, see also bootloaders (see bootc-bootloaders(7)). That's it. That's the whole section. Slay. 🌈

ostree backend

prepare-root.conf

The upstream ostree builds today do not default to composefs. You must enable this via a prepare-root.conf:

[composefs]
enabled = true

This is checked by bootc container lint. No skipping this one, fr fr. 😭

Historical usage of /ostree

Some images include a /ostree directory. A requirement for this was dropped in bootc 1.1.3 (https://github.com/bootc-dev/bootc/releases/tag/v1.1.3), and it is recommended that new images do not include it. Ancient history bestie, we're moving on. 🦋

Suggested image content

The bootc project provides a baseimage (https://github.com/bootc-dev/bootc/tree/main/baseimage) reference set of configuration files for base images. In particular, at the current time, the content defined by base must be used (or recreated). There's also suggested integration there with e.g. dracut to ensure the initramfs is set up, etc.

The bootc container lint command will check this. Consider this your vibe check. ⭐

SELinux

The default mechanism for labeling today is that bootc will load the file contexts from the image (e.g. /etc/selinux/policy) and apply labels dynamically. This is the only mechanism that will work today with a generic bootc-unaware build tooling. That's the whole tea. 🍓

It is not supported to add security.selinux extended attributes into the OCI tar layers, though support for this may be added if requested. So like, don't. 🙈

More details

Container runtimes such as podman and docker commonly apply a "coarse" SELinux policy to running containers. See container-selinux (https://github.com/containers/container-selinux/blob/main/container_selinux.8).

It is very important to understand that non-bootc base images do not (usually) have any embedded security.selinux metadata at all; all labels on the toplevel container image are dynamically generated per container invocation, and there are no individually distinct e.g. etc_t and usr_t types. Big difference, do not sleep on it. 💀

/ostree

Only with the ostree backend, there is support for including the ostree commit metadata in the OCI image, which includes all xattrs. File content in derived layers will be labeled using the default file contexts (from /etc/selinux). For example, you can do this (as of bootc 1.1.0):

RUN semanage fcontext -a -t httpd_sys_content_t "/web(/.*)?"

(This command will write to /etc/selinux/$policy/policy/.)

It will currently not work to do e.g.:

RUN chcon -t foo_t /usr/bin/foo

Because the container runtime state will deny the attempt to "physically" set the security.selinux extended attribute. Rip. It's giving denied. 😭

---

👑 SEE ALSO 👑

bootc(8), bootc-bootloaders(7), bootc-docs(7), bootc-sealed-images(7), bootc-setup-root-conf(5)

---

🌟 VERSION 🌟

v1.17.1

---

okay that's the whole page bestie, you ate it, no crumbs left 💖 this was BOOTC-CO...LE-IMAGES(7) from the Miscellaneous Information Manual, version v1.17.1 — go forth and build your images, mwah 🎀🦋✨