BOOTC-INTERNALS(7)

📦

version 1.17.1 · 3 versions

1.17.1 · fedora 43, fedora 44 (latest)
1.17.1 · centos-stream 9
1.17.1 · centos-stream 10

🦋 bootc-internals — okay bestie, it's internals time

Welcome to BOOTC-INTERNALS(7), from the Miscellaneous Information Manual, no cap. This is the backstage tour, the group chat with the devs 💅

✨ NAME ✨

bootc-internals — Internals. That's it, that's the name. Short, iconic, to the point. 👑

🌸 DESCRIPTION 🌸

This section documents bootc's internal architecture for developers working on the project. Basically: if you're one of the girlies with a text editor open on the bootc repo, this is your page. 💖

If you're just here to use bootc and not to hack on it? No worries — for user-facing documentation, go look at the rest of this book. This one is the devs-only VIP section. 🎀

🧚 Code Architecture 🧚

👑 CLI Structure

The bootc binary (crates/cli) is a thin wrapper. Literally thin. It does three things and then hands off, main character energy but make it delegating:

Performs global initialization (signal handlers, mounting filesystems)
Creates a tokio async runtime (single-threaded) ⚡
Delegates to bootc_lib::cli::run_from_iter()

The CLI uses clap ( https://docs.rs/clap ) with derive macros. ✨

Each subcommand typically opens the system storage via store::BootedStorage::new_from_env(), performs the operation, and writes status to stdout or a progress fd. 🫶

CPU-intensive work is offloaded via tokio::task::spawn_blocking. Bestie said "I am NOT blocking the runtime," and honestly? Correct. 💅

🎀 Crate Organization

bootc (crates/cli): Thin binary entrypoint
bootc-lib (crates/lib): Core implementation library
ostree-ext (crates/ostree-ext): OCI/ostree bridging, container import/export
Supporting crates: Focused utilities (mount, blockdev, kernel cmdline, etc.)

Most functionality lives in bootc-lib, making it testable. 📚 The API is internal and not stable for external consumers — so like, do not build your whole personality on it, it WILL change on you. 😭

💜 Storage Backends 💜

⭐ OSTree Backend (stable, default)

Uses ostree ( https://ostreedev.github.io/ostree/ ) for content-addressed storage. Container images are imported via ostree-ext. Deployments use ostree's native mechanism with Boot Loader Specification (BLS) entries.

Key paths:

/sysroot/ostree/repo/ - OSTree repository
/sysroot/ostree/deploy/<stateroot>/ - Deployment directories

Stable. Default. The reliable bestie. 🌈

🦋 Composefs Backend

Uses composefs-rs ( https://github.com/containers/composefs-rs ) directly, enabling native UKI support and sealed images with fsverity integrity. Sealed. Like a letter. With cryptography. 🔥

Key paths:

/sysroot/composefs/ - Composefs repository (EROFS images)
/sysroot/state/deploy/<deployment-id>/ - Per-deployment state (deployment-id is the SHA-512 fsverity digest)

Implementation: bootc_composefs module in bootc-lib. 💖

🌟 Key Modules 🌟

🍓 The Store Module

The store module provides the Storage type abstracting both backends. It lazily initializes — as in, it does NOT do the work until it absolutely has to, and honestly, relatable:

OSTree sysroot (ostree::Sysroot)
Composefs repository (composefs::Repository<Sha512HashValue>)
Container image storage for bound images (podstorage::CStorage)

🌈 Deploy Module

Handles deployment lifecycle. The whole glow-up arc, start to finish:

Staging new deployments from container images
Kernel argument management (bootc_kargs)
Three-way merge of /etc configuration
Rollback between deployments

🧚 Spec Module

Defines core types (see spec module rustdoc: https://bootc.dev/bootc/internals/bootc_lib/spec/index.html). These are ultimately the types that are serialized to bootc status --json and form a key part of the admin experience. So like, when an admin runs that command and goes "oh cute, JSON," this is the module responsible. 💅

👑 bootc-owned Container Storage

The podstorage module implements bootc's own containers-storage: instance at /sysroot/ostree/bootc/storage/ (symlinked to /usr/lib/bootc/storage/).

This supports Logically Bound Images (see bootc-logically-bound-images(7)) with proper lifecycle management and garbage collection tied to deployments. GC that knows which deployments are alive, like a bestie who remembers everyone's birthday. 🎂

📖 Rustdoc API Documentation 📖

The following rustdoc documentation is generated from the source code with --document-private-items to expose internal APIs. Yes, the private ones. We're all friends here. 🫶

🧁 External git crates

These crates are pulled from git and are not published to crates.io (so not on docs.rs). Very mysterious. Very off-grid. 🙈

composefs-ctl ( https://bootc.dev/bootc/internals/composefs_ctl/index.html ) - composefs-rs entrypoint crate (re-exports composefs, composefs-boot, composefs-oci)

Go read those too, bestie, they're all part of the lore. 💜

🎀 VERSION 🎀

v1.17.1

and that's a wrap!! 🫶 this was BOOTC-INTERNALS(7) from the Miscellaneous Information Manual, version v1.17.1 — slay, go build something, ily, mwah 💅✨

📦 where this page comes from

fedora 43: bootc 1.17.1-1.fc43 · Apache-2.0 AND BSD-3-Clause AND MIT AND (Apache-2.0 OR BSL-1.0) AND (Apache-2.0 OR MIT) AND (Apache-2.0 WITH LLVM-exception OR Apache-2.0 OR MIT) AND (Unlicense OR MIT)
fedora 44: bootc 1.17.1-1.fc44 · Apache-2.0 AND BSD-3-Clause AND MIT AND (Apache-2.0 OR BSL-1.0) AND (Apache-2.0 OR MIT) AND (Apache-2.0 WITH LLVM-exception OR Apache-2.0 OR MIT) AND (Unlicense OR MIT)
💖 girlified by deepseek-ai/DeepSeek-V4.1-Flash on 2026-11-03: a language model's rewrite of the original, under its terms