apt-ostree/.notes/rpm-ostree/how-commands-work/more.md

It's Thursday, July 17, 2025 at 7:56:25 PM PDT.

Let's break down the key operations in rpm-ostree: upgrade, compose, and overlay, and how they relate to the immutable filesystem model.

1. rpm-ostree upgrade (The Primary Client-Side Operation)

rpm-ostree upgrade is the command you run on a Fedora Atomic Desktop (like Silverblue or Kinoite) to update your operating system. It's the equivalent of dnf update on a traditional Fedora system, but it works very differently behind the scenes due to the immutable nature of the OS.

What it does:

• Fetches New Base Image: It first checks configured remote OSTree repositories (e.g., fedora-atomic) for a newer base OS image (an OSTree commit). This base image is a pre-built, complete filesystem tree assembled on the server side from RPMs.
• Resolves Layered Packages (if applicable): If you have used rpm-ostree install to "layer" any additional RPM packages on top of your base OS, upgrade then uses libdnf to:
  • Download those layered RPMs (and their dependencies) if new versions are available or required.
  • Calculate the complete set of changes needed to apply these layers onto the newly fetched base image.
• Composes a New Client-Side OSTree Commit: rpm-ostree then effectively "merges" the new base OS image with your layered packages. This isn't a literal file-by-file merge on your active filesystem. Instead, it creates a new, complete filesystem tree in a temporary area. This process involves:
  • Unpacking the layered RPMs onto the new base OS.
  • Running RPM scriptlets (like %post scripts) in a bubblewrap sandbox, capturing their intended effects, and applying them to the new tree.
  • Handling configuration file (/etc) merges, attempting to preserve your local changes while integrating upstream updates.
• Commits to Local OSTree Repository: Once this new filesystem tree is composed, rpm-ostree commits it to your local OSTree repository (/ostree/repo). This commit is content-addressed and deduplicated, so only the changed bits and new files are stored.
• Stages New Deployment: libostree then stages this new commit as a "deployment." This means it prepares a directory in /ostree/deploy/<checksum> that contains hardlinks to the objects in the local repository.
• Updates Bootloader: Finally, it updates your bootloader (e.g., GRUB) to point to this new deployment, making it the default to boot into on the next restart.
• Requires Reboot: The changes are not live until you reboot. This ensures the update is atomic: you're either running the old, stable version, or the new, stable version.

In essence: rpm-ostree upgrade builds a new, complete OS image incorporating updates and your custom layers, and stages it for an atomic boot.

2. compose (Server-Side Image Building / Local Creation of an OSTree Image)

The term "compose" in the context of rpm-ostree primarily refers to the process of building a complete, immutable operating system image (an OSTree commit) from a set of RPM packages. This happens in two main ways:

• Server-Side Composes (Predominant Model): This is how official Fedora Atomic Desktop images are created.
  • A dedicated build system (often using tools like osbuild or lorax in conjunction with rpm-ostree's capabilities) takes a defined set of RPMs.
  • It uses DNF/RPM to resolve all dependencies, install the packages into a chroot-like environment, run their scriptlets, and set up the base operating system.
  • The resulting filesystem tree is then "committed" into an OSTree repository. This produces a base OSTree commit that clients will later pull or upgrade to.
  • This ensures consistency: every user gets the exact same base OS image.
• Local Composes (Less Common for End-Users): While less common for typical desktop users, developers or system integrators can also perform local "composes."
  • This would involve using rpm-ostree commands (or similar tooling) to build an OSTree commit from a local RPM repository or specified RPMs.
  • For example, you might use rpm-ostree os-init or related commands in a build script to create a new OSTree repository and push a custom base image into it.
  • Tools like bootc (built on ostree) further streamline this, allowing you to "compose" an entire OS image into an OCI container image.

In essence: compose is the act of assembling a full, immutable filesystem tree (an OSTree commit) from RPMs, typically done once by a build system to create the base OS image, or locally for custom images.

3. overlay (Temporary, Writable Filesystem Layer)

The term "overlay" in the context of rpm-ostree (and OSTree generally) often refers to a mutable layer on top of an immutable base. While rpm-ostree primarily uses hardlinks for its persistent layering, it employs OverlayFS for specific, temporary situations:

• rpm-ostree usroverlay: This is the most direct use of OverlayFS by rpm-ostree.
  • Purpose: It's an escape hatch or debugging tool. It creates a temporary, writable overlayfs mount on top of your read-only /usr (or parts of your root filesystem).
  • Behavior: When you run this command, it provides a shell where any changes you make to files in /usr (or other typically immutable locations) are written to a temporary upper layer in RAM or on disk. The base OSTree layer remains untouched.
  • Transience: These changes are not persistent. They are lost on reboot. They are also not part of your rpm-ostree deployment history and cannot be rolled back atomically by rpm-ostree.
  • Use Case: Debugging, quick temporary fixes, or experimenting with software that needs to write to /usr without going through the layering process. It's explicitly designed for transient modifications.
• rpm-ostree install --apply-live (Experimental): As mentioned previously, this experimental flag also uses OverlayFS to apply layered RPM changes to the running system without a reboot. Again, it's a temporary effect that doesn't persist across boots and isn't the primary transactional update mechanism.

Confusion Point: It's important not to confuse OverlayFS (a kernel feature for combining filesystems) with rpm-ostree's general concept of "layering." rpm-ostree's persistent layering (via rpm-ostree install) creates a new OSTree commit that combines the base and the layered packages through hardlinks. OverlayFS is used specifically for the temporary, "live" modifications.

In essence: overlay (via OverlayFS) provides a transient, writable layer over the immutable base, primarily for debugging or live, non-persistent changes, distinct from rpm-ostree's atomic and persistent layering via new OSTree commits.