Internals

This section documents bootc's internal architecture for developers working on the project. For user-facing documentation, see the rest of this book.

Code Architecture

CLI Structure

The bootc binary (crates/cli) is a thin wrapper that:

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

The CLI uses 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.

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.

Storage Backends

OSTree Backend (stable, default)

Uses 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

Composefs Backend (experimental)

Uses composefs-rs directly, enabling native UKI support and sealed images with fsverity integrity.

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:

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

Deploy Module

Handles deployment lifecycle:

• 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). These are ultimately the types that are serialized to bootc status --json and form a key part of the admin experience.

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 with proper lifecycle management and garbage collection tied to deployments.

Rustdoc API Documentation

The following rustdoc documentation is generated from the source code with --document-private-items to expose internal APIs.

Core crates

• bootc-lib - Core bootc implementation
• bootc - CLI frontend

Supporting crates

• ostree-ext - Extension APIs for OSTree
• bootc-mount - Internal mount utilities
• bootc-kernel-cmdline - Kernel command line parsing
• bootc-initramfs-setup - Initramfs setup code
• etc-merge - /etc merge handling

Utility crates

• bootc-internal-utils - Internal utilities
• bootc-internal-blockdev - Block device handling
• bootc-sysusers - systemd-sysusers implementation
• bootc-tmpfiles - systemd-tmpfiles implementation

External git crates

These crates are pulled from git and are not published to crates.io (so not on docs.rs).

• cfsctl - composefs-rs entrypoint crate (re-exports composefs, composefs-boot, composefs-oci)

The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.