DOCSEARCHbyAlgolia
Submit Docs

bootc Documentation

repository·main·Indexed 24 days ago

https://github.com/bootc-dev/bootc

bootc enables transactional, in-place operating system updates using OCI/Docker container images as the delivery mechanism for the bootable host system. The project includes the ostree-ext Rust crate for advanced OSTree features such as lossless tar export/import, OCI image encapsulation, and commit diffing, as well as the ostree-ext-cli for managing container images and deployments.

Tokens
75.3K
Snippets
165
Records
493
Agent score
80%

What's inside bootc

  1. Use ostree-ext for Rust-based OSTree tooling

    main

    The ostree-ext crate provides high-level extension APIs for ostree written in Rust. It is designed for developers building tooling that requires advanced OSTree features not present in the core C library, such as OCI/Docker image bridging, lossless tar export/import, and commit diffing.

    Note: While the OSTree core is stable, the APIs and data models in ostree-ext are considered "slushy" (subject to change), though efforts are made to maintain backwards compatibility for data formats like tar and container serialization.

  2. Understand the bootc architecture and crate organization

    main

    The bootc project is organized into several crates, with most core logic residing in bootc-lib. The bootc crate itself is a thin CLI wrapper.

    Core Crates:

    • bootc (crates/cli): The binary entrypoint.
    • bootc-lib (crates/lib): The core implementation library containing the majority of the logic.
    • ostree-ext (crates/ostree-ext): Handles OCI/ostree bridging and container import/export.

    Supporting Crates: Various utility crates handle specific tasks like mounting (bootc-mount), kernel command line parsing (bootc-kernel-cmdline), initramfs setup (bootc-initramfs-setup), and /etc merging (etc-merge).

  3. Use bootc to manage bootable container images

    main

    bootc is a tool used to deploy and perform transactional in-place updates using bootable container images. It uses ostree-containers as a backend.

    Once a system is installed (either via bootc install executed within a container or via an OS installer), you can manage the system lifecycle using subcommands like upgrade to pull new images and rollback to revert changes.

  4. What is bootc?

    main

    bootc is a tool for performing transactional, in-place operating system updates using standard OCI/Docker container images. It applies the container 'layer' model to host systems, using container images as the transport and delivery format for base operating system updates.

    Key characteristics:

    • OCI/Docker based: Uses standard container images to deliver the OS.
    • Kernel included: The container image contains the Linux kernel (e.g., in /usr/lib/modules).
    • Native execution: At runtime, the userspace is not running inside a container; processes like systemd run directly on the host as pid1.

  5. Overview of the composefs backend

    main

    The composefs backend is an experimental alternative to ostree for managing bootc system deployments. It uses composefs-rs for storage and management.

    It supports two integrity levels:

    • Sealed: The composefs digest is baked into the kernel command line of a Unified Kernel Image (UKI) and is required to match at boot. This provides end-to-end integrity protection.
    • Unsealed: fsverity enforcement is optional. While it still provides content-addressed, deduplicated storage and garbage collection, there is no guarantee that the root filesystem matches what was signed. This is achieved by building with the --allow-missing-verity flag.

  6. Understand the bootc design philosophy and relationship to systemd particles

    main

    bootc is an image-oriented operating system approach that aligns with parts of the systemd "particles" vision but differs in key areas. While "particles" emphasizes desktop use cases and sealed/secure-boot-only systems, bootc focuses on both server and desktop use cases, provides explicit support for "unlocked" systems (where root-level changes are first-class citizens), and aligns strongly with the cloud-native/container ecosystem (OCI/Docker/Kubernetes).

    Key differences include:

    • Installation: Unlike the "dd an image to disk" goal of some proposals, bootc install supports advanced provisioning like static IP addresses via kernel arguments.
    • Filesystem Layout: bootc allows arbitrary directory roots in the base image rather than strictly enforcing a hermetic /usr.
    • Image Format: bootc uses OCI/Docker images (via opencontainers/image-spec) instead of Discoverable Disk Images (DDI).

  7. Manage users and groups in bootc images

    main

    bootc is a generic OS update mechanism and does not directly manage user or group configuration. Users should avoid hardcoding passwords or private SSH keys in generic base images. Instead, use external injection methods or system-level tools to manage identities.

    Common patterns for injecting credentials include:

    • systemd credentials: Using SMBIOS (common in QEMU/local virtualization) to inject root passwords or SSH keys.
    • Cloud-init/Ignition: Using metadata servers (e.g., AWS, GCP) to process identities outside the bootable image.
    • Custom logic: Running a systemd unit or container that fetches credentials from a network source (e.g., FreeIPA) or a Kubernetes CRD.

  8. Understand the difference between container build and deployment filesystems

    main

    The filesystem behavior of bootc depends on its execution context:

    1. Container Build Time: When run as a container (e.g., during a build step), the filesystem is fully mutable to allow for image derivation.
    2. Deployment Time: When deployed to a physical or virtual machine and managed by bootc, the system operates as a 'deployment root'. The target deployment is determined by the ostree= kernel commandline argument. In this state, the filesystem is typically read-only (especially when composefs is enabled).

  9. The bootc Root Filesystem Model

    main

    Unlike the 'particles' model, the bootc root filesystem defaults to a single physical Linux filesystem (e.g., xfs, ext4, btrfs).

    Key characteristics:

    • Unified OS: The root filesystem contains the operating system itself; it is not a separate partition.
    • Space Management: This model avoids the space management constraints introduced by dm-verity (such as the need for unused empty space in a partition to allow for growth).
    • Mounting: While the root is a single filesystem, users are encouraged to mount other partitions/filesystems for specific needs, such as /var.
    • Locating Root: bootc does not mandate a specific method for locating the root. It may use the discoverable partitions specification or traditional root= kernel arguments.

  10. Understand the difference between container runtime and bootc runtime

    main

    A bootc image operates in two distinct modes depending on how it is invoked:

    1. Container Mode: When run via a container runtime like podman or docker (e.g., during a build process), the image behaves like a standard container. It uses the host's kernel, and the container runtime manages namespaces and cgroups. The kernel embedded in the image is ignored.

    2. Booted Host Mode: When installed on a physical or virtual machine, bootc takes control of the filesystem. In this mode, bootc is not a container runtime. It does not manage namespaces, cgroups, or PID isolation; those tasks are handled by the system (typically systemd). bootc's role is limited to:

      • Performing a "chroot" equivalent into the target filesystem root via the initramfs on boot.
      • Fetching new content during upgrades (without affecting the currently running root).

    bootc is not a persistent daemon and imposes no runtime overhead.

  11. How bootc manages the /usr directory and OS state

    main

    bootc strongly encourages placing operating system state (executable binaries and default configurations) under /usr, which should be read-only by default. However, unlike strictly hermetic models, bootc allows for arbitrary directory roots starting from / to be included in the base image to better align with container filesystem patterns.

    To maintain compatibility with legacy systems and the UsrMerge process, bootc continues to support:

    • Legacy compatibility symlinks in / (e.g., /bin → /usr/bin).
    • Operating systems that have not yet completed UsrMerge.

  12. Lossless tar export and import with ostree-ext

    main

    Standard OSTree tar exports are lossy because they lack commit metadata. ostree-ext provides a new export format that uses a custom repository mode combined with a hardlinked checkout. This allows for lossless imports back into a different repository.

    Filesystem Layout

    The exported format includes a specific structure to preserve extended attributes via .xattr files:

    .
├── etc                # content is at traditional /etc, not /usr/etc
│   └── passwd
├── sysroot       
│   └── ostree         # ostree object store with hardlinks to destinations
│       ├── repo
│       │   └── objects
│       │       ├── 00
│       │       └── 8b
│       │       │   └── <hash>.file.xattrs
│       │       │   └── <hash>.file
│       └── xattrs    # directory with extended attributes, hardlinked with .xattr files
│           └── <hash>
└── usr
    ├── bin
    │   └── bash
    └── lib64
        └── libc.so

    This layout uses special .xattr files to ensure that metadata like security.selinux is preserved and not overwritten by container runtimes during round trips.