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

rpm-ostree 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

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

Key Components

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

D-Bus Interface

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. PkgChangeTransaction: Package installation/removal
4. RebaseTransaction: Base image switching
5. UpgradeTransaction: System upgrades

Transaction Flow

1. Initiation: Client requests operation via D-Bus
2. Validation: Daemon validates request and creates transaction
3. Execution: Transaction executes with progress reporting
4. Completion: Transaction completes with success/failure status
5. Cleanup: Resources are cleaned up and state is updated

CLI Commands

Core Commands

• status: Show system status and deployment information
• upgrade: Upgrade system to latest version
• rollback: Rollback to previous deployment
• deploy: Deploy specific version
• rebase: Switch to different base image
• install: Install packages
• uninstall: Remove packages
• override: Manage package overrides
• compose: Build custom images

Advanced Commands

• kargs: Manage kernel arguments
• initramfs: Manage initramfs
• usroverlay: Create transient overlayfs
• db: Query package database
• search: Search for packages
• cleanup: Clean up old deployments

Related Tools and Ecosystem

bootc

• Focuses on booting directly from container images
• Offers alternative to traditional rpm-ostree
• Can interact with rpm-ostree for shared state operations
• rpm-ostree still needed for package layering

composefs and fsverity

• composefs provides enhanced filesystem integrity and deduplication
• Leverages fs-verity for data integrity validation
• Makes filesystems effectively read-only and tamper-proof

skopeo and podman

• Tools for managing and interacting with container images
• Can work alongside rpm-ostree systems
• rpm-ostree focuses on host operating system management

Systemd Services

Core Services

• rpm-ostreed.service: Main daemon service
• rpm-ostree-bootstatus.service: Boot-time status logging
• rpm-ostreed-automatic.service: Automatic system updates
• rpm-ostree-countme.service: Usage reporting

Service Configuration

• D-Bus service activation
• PolicyKit integration
• Automatic update policies
• Boot-time status reporting

Security Model

Privilege Separation

• Daemon runs with elevated privileges
• Client operations are unprivileged
• D-Bus communication for privileged operations
• PolicyKit for authentication

Sandboxing

• Package script execution in sandboxed environment
• Namespace isolation for security
• Controlled filesystem access
• Privilege restrictions

Performance Characteristics

Optimization Strategies

• OSTree deduplication for storage efficiency
• Incremental updates for network efficiency
• Parallel package processing
• Caching mechanisms for repeated operations

Resource Usage

• Memory usage scales with package count
• Disk usage optimized through OSTree deduplication
• Network usage minimized through delta updates
• CPU usage optimized through parallel processing

Deployment Model

OSTree Integration

• Atomic commit-based deployments
• Rollback capability through multiple deployments
• Bootloader integration for deployment switching
• State tracking and management

Package Layering

• Base image remains immutable
• User packages layered on top
• Clear separation of base and user content
• Atomic layer application and removal