apt-ostree/.notes/rpm-ostree/overview.md

rpm-ostree Source Code Analysis Overview

Executive Summary

rpm-ostree is a sophisticated hybrid image/package system that combines traditional RPM package management (via libdnf) with modern image-based deployments (via libostree). The project represents a significant architectural achievement in bridging two fundamentally different package management paradigms while maintaining atomicity and reliability.

Core Philosophy: Every Change is "From Scratch"

rpm-ostree follows a fundamental principle: every change regenerates the target filesystem "from scratch". This approach:

• Avoids hysteresis (state-dependent behavior)
• Ensures reproducible results
• Maintains system consistency
• Simplifies debugging and testing

Key Benefits

• Atomic Upgrades/Rollbacks: Provides a reliable and safe way to update and revert the operating system
• Immutable Base System: Enhances stability and predictability
• Reduced Update Size: Only downloads the changes, not the entire OS
• Client-side Customization: Allows layering of packages and overrides for specific needs
• Easily Create Derivatives: Simplifies the process of creating custom OS images

Project Architecture

Core Design Philosophy

• Hybrid System: Combines RPM package management with OSTree image-based deployments
• Atomic Operations: All system modifications are transactional and atomic
• Daemon-Client Architecture: Centralized daemon with D-Bus communication
• Rollback Capability: Maintains previous deployments for safe rollbacks

Directory Structure Analysis

rpm-ostree/
├── rust/                          # Modern Rust implementation
│   ├── libdnf-sys/               # Rust bindings for libdnf
│   ├── rpmostree-client/         # Rust client library
│   ├── src/                      # Main Rust source code
│   │   ├── builtins/             # Rust-implemented CLI commands
│   │   ├── cliwrap/              # Command-line wrapper utilities
│   │   ├── container.rs          # Container image support
│   │   ├── core.rs               # Core functionality (RPM + OSTree integration)
│   │   ├── daemon.rs             # Daemon-side Rust code
│   │   ├── lib.rs                # Main library entry point
│   │   └── ...                   # Various utility modules
│   └── Cargo.toml                # Rust dependency management
├── src/                          # C/C++ source code
│   ├── app/                      # Client-side application code
│   │   ├── libmain.cxx           # Main CLI entry point
│   │   ├── rpmostree-clientlib.cxx # D-Bus client library
│   │   ├── rpmostree-builtin-*.cxx # Individual CLI commands
│   │   └── rpmostree-compose-*.cxx # Image composition tools
│   ├── daemon/                   # Daemon implementation
│   │   ├── rpmostreed-daemon.cxx # Main daemon object
│   │   ├── rpmostreed-transaction.cxx # Transaction management
│   │   ├── rpmostreed-transaction-types.cxx # Transaction type implementations
│   │   ├── rpmostreed-os.cxx     # OS interface implementation
│   │   ├── org.projectatomic.rpmostree1.xml # D-Bus interface definition
│   │   └── rpm-ostreed.service   # Systemd service file
│   ├── lib/                      # Public library interface
│   └── libpriv/                  # Private library implementation
│       ├── rpmostree-core.cxx    # Core RPM + OSTree integration
│       ├── rpmostree-postprocess.cxx # Post-processing utilities
│       └── rpmostree-sysroot-core.cxx # Sysroot management
├── tests/                        # Test suite
├── docs/                         # Documentation
├── man/                          # Manual pages
├── packaging/                    # Distribution packaging files
├── Cargo.toml                    # Main Rust workspace configuration
├── configure.ac                  # Autotools configuration
└── Makefile.am                   # Build system configuration

Files inside rpm-ostree-2025.8-2.fc42.rpm

    etc/
        rpm-ostreed.conf
    usr/
        bin/
            rpm-ostree  # client / cli executable
        lib/
            .build-id/
                c0/
                    4a8f1297c0e4ffc011fd4b487f98388309d8d0
            kernel/
                install.d/
                    05-rpmostree.install
            systemd/
                system/
                    rpm-ostree-bootstatus.service
                    rpm-ostree-countme.service
                    rpm-ostree-countme.timer
                    rpm-ostree-fix-shadow-mode.service
                    rpm-ostreed-automatic.service
                    rpm-ostreed-automatic.timer
                    rpm-ostreed.service
        lib64/
            rpm-ostree/
                rpm-ostree-0-integration-opt-usrlocal-compat.conf
                rpm-ostree-0-integration-opt-usrlocal.conf
                rpm-ostree-0-integration.conf
        libexec/
            rpm-ostreed # Daemon executable
        share/
            bash-completion/
                completions/
                    rpm-ostree
            dbus-1/
                system-services/
                    org.projectatomic.rpmostree1.service
                system.d/
                    org.projectatomic.rpmostree1.conf
            doc/
                rpm-ostree/
                    COPYING.GPL
                    COPYING.LGPL
                    LICENSE
                    README.md
            man/
                man1/
                    rpm-ostree.1.gz
                man5/
                    rpm-ostreed.conf.5.gz
                man8/
                    rpm-ostree-countme.service.8.gz
                    rpm-ostree-countme.timer.8.gz
                    rpm-ostreed-automatic.service.8.gz
                    rpm-ostreed-automatic.timer.8.gz
            polkit-1/
                actions/
                    org.projectatomic.rpmostree1.policy

Key Components Analysis

1. Daemon Architecture (src/daemon/)

Purpose: Centralized system service that manages all rpm-ostree operations

Key Files:

• rpmostreed-daemon.cxx: Main daemon object managing global state
• rpmostreed-transaction.cxx: Transaction execution and management
• rpmostreed-transaction-types.cxx: Implementation of specific transaction types
• rpmostreed-os.cxx: D-Bus interface implementation for OS operations
• org.projectatomic.rpmostree1.xml: D-Bus interface definition

Features:

• D-Bus service exposing system management interface
• Transaction-based operations with atomicity guarantees
• Progress reporting and cancellation support
• PolicyKit integration for authentication
• Automatic update policies and scheduling

2. Client Architecture (src/app/)

Purpose: Command-line interface and client library for user interaction

Key Files:

• libmain.cxx: Main CLI entry point and command dispatch
• rpmostree-clientlib.cxx: D-Bus client library for daemon communication
• rpmostree-builtin-*.cxx: Individual command implementations
• rpmostree-compose-*.cxx: Image composition and build tools

Commands Implemented:

• upgrade: System upgrades
• rollback: Deployment rollbacks
• deploy: Specific deployment management
• rebase: Switch to different base images
• install/uninstall: Package layering
• override: Package override management
• compose: Image building tools

3. Core Engine (src/libpriv/)

Purpose: Core functionality shared between client and server components

Key Files:

• rpmostree-core.cxx: Main integration between RPM and OSTree systems
• rpmostree-postprocess.cxx: Post-processing utilities for deployments
• rpmostree-sysroot-core.cxx: Sysroot management and deployment operations

Features:

• RPM package installation and management via libdnf
• OSTree commit generation and deployment
• Package layering and override mechanisms
• SELinux policy integration
• Initramfs management

4. Rust Integration (rust/)

Purpose: Modern Rust implementation providing safety and performance improvements

Key Components:

• libdnf-sys/: Rust bindings for libdnf
• src/core.rs: Core functionality mirroring C++ implementation
• src/daemon.rs: Daemon-side Rust code
• src/container.rs: Container image support
• src/builtins/: Rust-implemented CLI commands

Benefits:

• Memory safety and thread safety
• Better error handling
• Performance improvements
• Modern async/await support
• Type safety for complex data structures

5. Related Tools and Ecosystem

bootc: Focuses on booting directly from container images, offering an alternative to traditional rpm-ostree

• rpm-ostree and bootc can interact and operate on shared state for upgrades, rebases, and deployment tasks
• rpm-ostree is still necessary for certain functionalities, particularly when package layering is involved

composefs and fsverity:

• composefs provides enhanced filesystem integrity and deduplication by leveraging fs-verity
• This combination strengthens data integrity by validating the entire filesystem tree, making them effectively read-only and tamper-proof

skopeo and podman:

• These tools are primarily used for managing and interacting with container images
• While they can work alongside rpm-ostree systems, rpm-ostree's focus is on managing the host operating system

D-Bus Interface Analysis

Service Interface (org.projectatomic.rpmostree1.xml)

Main Objects:

• /org/projectatomic/rpmostree1/Sysroot: System root management
• /org/projectatomic/rpmostree1/OS: Operating system operations

Key Methods:

• Upgrade: Perform system upgrades
• Rollback: Revert to previous deployment
• Deploy: Deploy specific version/commit
• Rebase: Switch to different base image
• PkgChange: Install/remove packages
• KernelArgs: Manage kernel arguments
• Cleanup: Clean up old deployments

Transaction System:

• All operations return transaction addresses
• Progress reporting via D-Bus signals
• Atomic execution with rollback capability
• Cancellation support

Transaction System

Transaction Types

1. DeployTransaction: New deployment creation
2. RollbackTransaction: Deployment rollback
3. CleanupTransaction: System cleanup operations
4. PackageDiffTransaction: Package difference analysis
5. FinalizeDeploymentTransaction: Deployment finalization

Atomicity Guarantees

• Staging: New deployments are staged before activation
• Rollback Preservation: Previous deployments are maintained
• Transaction Isolation: Operations succeed completely or fail completely
• State Consistency: System maintains consistent state across reboots