rpm-ostree Documentation

rpm-ostree is a hybrid image/package system that combines the libostree base image format with RPM package management. It allows for transactional, versioned, and checksummed upgrades using either bootable container images or an 'ostree native' HTTP model.

Key capabilities include:

• Transactional Upgrades: Background image-based upgrades.
• OS Rollback: Reverting the OS state without affecting user data in /etc or /var (it targets /usr).
• Package Layering: Adding individual packages or overrides on top of a base image on the client side.
• Custom Base Images: Creating custom images via rpm-ostree compose image (using containers) or rpm-ostree compose tree (using ostree repositories).

The rpm-ostree source code is organized into several key functional areas:

• src/app: The rpm-ostree CLI application.
• src/daemon: The rpm-ostree daemon, which provides the D-Bus API.
• src/lib: The public library containing APIs for exploring the rpmdb in OSTrees.
• src/libpriv: A private API shared specifically between the app and the daemon components.

.
└─ src
  ├── app                       rpm-ostree CLI application
  ├── daemon                    rpm-ostree daemon providing D-Bus API
  ├── lib                       Public library: contains APIs for exploring rpmdb in OSTrees
  └── libpriv                   Private API shared between app and daemon

Documentation for the project is distributed across several locations:

• docs/: General documentation for the repository.
• man/: Man pages for the rpm-ostree command.
• HACKING.md: Information specifically for developers looking to contribute or modify the codebase.

All Rust libraries utilized by rpm-ostree are located in the rust/ directory at the root of the repository.

.
└─ rust                         Contains rust libraries that rpm-ostree uses─

The DNF Count Me feature allows systems to anonymously report uptime to help improve package management. While classic DNF-based systems include a countme variable in RPM repository metadata requests, rpm-ostree systems do not fetch this metadata by default (unless a package overlay is present).

Instead, rpm-ostree implements this functionality via a standalone timer called rpm-ostree-countme.timer. This timer triggers automatically after 5 minutes following a boot, and then bi-weekly. In both instances, the timer executes with a random delay to preserve anonymity.

In rpm-ostree, a bootable deployment is defined as the pair of a (kernel, userspace).

• Single Kernel: Unlike dnf which may keep multiple kernels via installonly, rpm-ostree maintains exactly one kernel per userspace filesystem tree.
• Initramfs Generation: rpm-ostree manages initramfs regeneration (via dracut) as a controlled, transactional process. If a kernel is replaced or if client-side regeneration is enabled, rpm-ostree runs dracut inside a container to generate the CPIO archive, which is then placed in /usr/lib/modules/$kver.

The rpm-ostree daemon uses polkit to authorize system mutations. When a client calls a D-Bus method (like Upgrade()), the daemon converts that call into a polkit action via os_authorize_method and consults the polkit framework to decide if the user has permission.

• Policy Files: The project includes a base policy file (org.projectatomic.rpmostree1.policy) defining available actions.
• Distro Customization: Distributions may extend these rules (e.g., Fedora uses org.projectatomic.rpmostree1.rules) to allow authorization based on specific criteria like group membership.

When cliwrap is active, rpm-ostree intercepts certain commands to provide redirection or safer execution.

rpm

rpm-ostree wraps the rpm binary. If arguments are deemed "not known safe," rpm-ostree may drop privileges before executing. If you need to bypass the wrapper and use the real binary, it is located at /usr/libexec/rpm-ostree/wrapped/rpm.

dracut

Intercepts dracut calls and instructs users to use rpm-ostree initramfs for initramfs generation, as it is integrated with the OSTree transaction mechanism.

grubby

Intercepts grubby calls and instructs users to use rpm-ostree kargs instead.

yum/dnf

• dnf update is translated to rpm-ostree update.
• Other commands (like dnf install) are currently not implemented and will print a suggestion to use toolbox, podman, docker, or rpm-ostree install for layered packages.

To separate the OS from machine-local state, rpm-ostree automatically synthesizes systemd tmpfiles.d snippets from directories found in /var.

• Behavior: Directories in /var will be recreated on boot. This facilitates "factory reset" scenarios by allowing the wiping of /var without losing the OS structure.
• Limitation: Currently, any non-directory items (regular files or symbolic links) in /var are discarded during this process.

When a container image is converted to an OSTree commit, container-specific metadata (such as the version label) is not automatically mapped to OSTree commit metadata.

To include this metadata in your OSTree deployment, you should create a new derived commit that reuses the content from the base container commit but allows for custom metadata injection using the --tree flag.

# Create a new commit derived from the container base to inject metadata
ostree commit --tree=ref=$base