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

rpm-ostree Architecture

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 architecture represents a significant achievement in bridging two fundamentally different package management paradigms while maintaining atomicity and reliability.

Core Architectural Principles

1. "From Scratch" Philosophy

Principle: Every change regenerates the target filesystem completely from scratch.

Benefits:

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

Implementation:

• OSTree commit-based filesystem management
• Atomic transaction processing
• Complete state regeneration for each operation
• Rollback capability through multiple deployments

2. Hybrid System Design

Principle: Combine the best of both package management and image-based deployments.

Components:

• RPM Package Management: Traditional package installation via libdnf
• OSTree Image Management: Atomic, immutable filesystem deployments
• Layered Architecture: Base image + user packages
• Atomic Operations: All changes are transactional

3. Daemon-Client Architecture

Principle: Centralized daemon with D-Bus communication for privileged operations.

Benefits:

• Privilege separation and security
• Concurrent operation support
• State persistence across operations
• Resource management and optimization

System Architecture

High-Level Architecture

┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   CLI Client    │    │   GUI Client    │    │   API Client    │
│  (rpmostree)    │    │  (GNOME/KDE)    │    │  (Python/Go)   │
└─────────┬───────┘    └─────────┬───────┘    └─────────┬───────┘
          │                      │                      │
          └──────────────────────┼──────────────────────┘
                                 │
                    ┌─────────────▼─────────────┐
                    │      D-Bus Interface      │
                    │  (org.projectatomic.rpmo  │
                    │      stree1)              │
                    └─────────────┬─────────────┘
                                  │
                    ┌─────────────▼─────────────┐
                    │    rpm-ostreed Daemon     │
                    │   (Privileged Service)    │
                    └─────────────┬─────────────┘
                                  │
          ┌───────────────────────┼───────────────────────┐
          │                       │                       │
    ┌─────▼─────┐         ┌───────▼──────┐         ┌─────▼─────┐
    │   libdnf  │         │   libostree  │         │  System   │
    │ (RPM/DNF) │         │ (Filesystem) │         │ Services  │
    └───────────┘         └──────────────┘         └───────────┘

Component Architecture

1. Client Layer

Purpose: User interface and command processing

Components:

• CLI Client (rpmostree): Command-line interface
• GUI Clients: GNOME Software, KDE Discover integration
• API Clients: Python, Go, and other language bindings

Responsibilities:

• Command-line argument parsing
• D-Bus communication with daemon
• Progress reporting and user feedback
• Error handling and user guidance

2. D-Bus Interface Layer

Purpose: Inter-process communication and service discovery

Interface: org.projectatomic.rpmostree1

Key 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

3. Daemon Layer

Purpose: Centralized system service for privileged operations

Components:

• Main Daemon (rpmostreed): Core daemon process
• Transaction Manager: Atomic operation management
• State Manager: System state tracking
• Resource Manager: Resource allocation and cleanup

Responsibilities:

• Privileged system operations
• Transaction management and atomicity
• State persistence and recovery
• Concurrent operation handling
• Resource management and optimization

4. Integration Layer

Purpose: Coordination between RPM and OSTree systems

Components:

• RPM Integration: Package management via libdnf
• OSTree Integration: Filesystem management via libostree
• System Integration: Bootloader and system service integration

Responsibilities:

• Package installation and removal
• Filesystem commit creation and management
• Deployment switching and rollback
• Boot configuration management
• System state synchronization

Detailed Component Analysis

1. Daemon Architecture (src/daemon/)

Core Daemon (rpmostreed-daemon.cxx)

Purpose: Main daemon object managing global state

Key Features:

• D-Bus service registration and activation
• Global state management
• Transaction lifecycle management
• Resource allocation and cleanup

Implementation:

class RpmOstreeDaemon {
    // Global state management
    std::unique_ptr<RpmOstreeSysroot> sysroot;
    std::unique_ptr<RpmOstreeOS> os;
    
    // Transaction management
    std::map<std::string, std::unique_ptr<RpmOstreeTransaction>> transactions;
    
    // D-Bus interface
    std::unique_ptr<GDBusObjectManagerServer> object_manager;
};

Transaction Management (rpmostreed-transaction.cxx)

Purpose: Atomic operation execution and management

Key Features:

• Transaction lifecycle management
• Atomic execution with rollback
• Progress reporting via D-Bus signals
• Cancellation support

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

Implementation:

class RpmOstreeTransaction {
    // Transaction state
    TransactionState state;
    std::string transaction_id;
    
    // Rollback information
    std::vector<RollbackPoint> rollback_points;
    
    // Progress reporting
    void emit_progress(const std::string& message, int percentage);
    
    // Atomic execution
    bool execute_atomic();
    void rollback_on_failure();
};

OS Interface (rpmostreed-os.cxx)

Purpose: D-Bus interface implementation for OS operations

Key Features:

• D-Bus method implementation
• Parameter validation
• Error handling and reporting
• Transaction creation and management

Implementation:

class RpmOstreeOS {
    // D-Bus method implementations
    void handle_upgrade(GDBusMethodInvocation* invocation);
    void handle_rollback(GDBusMethodInvocation* invocation);
    void handle_deploy(GDBusMethodInvocation* invocation);
    void handle_rebase(GDBusMethodInvocation* invocation);
    void handle_pkg_change(GDBusMethodInvocation* invocation);
    
    // Transaction creation
    std::string create_transaction(TransactionType type);
};

2. Client Architecture (src/app/)

Main CLI (libmain.cxx)

Purpose: Command-line interface entry point and dispatch

Key Features:

• Command-line argument parsing
• Command dispatch and execution
• D-Bus client communication
• Error handling and user feedback

Implementation:

class RpmOstreeClient {
    // D-Bus client
    std::unique_ptr<RpmOstreeClientLib> client_lib;
    
    // Command dispatch
    int dispatch_command(int argc, char* argv[]);
    
    // D-Bus communication
    bool connect_to_daemon();
    void handle_daemon_error(const std::string& error);
};

Client Library (rpmostree-clientlib.cxx)

Purpose: D-Bus client library for daemon communication

Key Features:

• D-Bus connection management
• Method call handling
• Signal reception and processing
• Error propagation

Implementation:

class RpmOstreeClientLib {
    // D-Bus connection
    GDBusConnection* connection;
    
    // Method calls
    bool call_method(const std::string& method, GVariant* parameters);
    
    // Signal handling
    void connect_signals();
    void handle_progress_signal(GVariant* parameters);
    void handle_completion_signal(GVariant* parameters);
};

Builtin Commands (rpmostree-builtin-*.cxx)

Purpose: Individual command implementations

Commands:

• rpmostree-builtin-upgrade.cxx: System upgrades
• rpmostree-builtin-rollback.cxx: Deployment rollbacks
• rpmostree-builtin-deploy.cxx: Deployment management
• rpmostree-builtin-rebase.cxx: Base image switching
• rpmostree-builtin-install.cxx: Package installation
• rpmostree-builtin-uninstall.cxx: Package removal
• rpmostree-builtin-override.cxx: Package overrides

Implementation Pattern:

class RpmOstreeBuiltinUpgrade {
    // Command execution
    int execute(int argc, char* argv[]);
    
    // Parameter validation
    bool validate_parameters();
    
    // D-Bus communication
    bool request_upgrade();
    void handle_progress(const std::string& message);
};

3. Core Engine (src/libpriv/)

Core Integration (rpmostree-core.cxx)

Purpose: Main integration between RPM and OSTree systems

Key Features:

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

Implementation:

class RpmOstreeCore {
    // RPM integration
    std::unique_ptr<DnfSack> sack;
    std::unique_ptr<DnfPackageSet> package_set;
    
    // OSTree integration
    OstreeRepo* repo;
    OstreeSysroot* sysroot;
    
    // Package operations
    bool install_packages(const std::vector<std::string>& packages);
    bool remove_packages(const std::vector<std::string>& packages);
    
    // OSTree operations
    bool create_commit(const std::string& ref);
    bool deploy_commit(const std::string& ref);
};

Post-processing (rpmostree-postprocess.cxx)

Purpose: Post-processing utilities for deployments

Key Features:

• SELinux policy regeneration
• Initramfs management
• Bootloader configuration
• System service integration

Implementation:

class RpmOstreePostprocess {
    // SELinux integration
    bool regenerate_selinux_policy();
    
    // Initramfs management
    bool update_initramfs();
    
    // Bootloader integration
    bool update_bootloader_config();
    
    // System services
    bool restart_affected_services();
};

Sysroot Management (rpmostree-sysroot-core.cxx)

Purpose: Sysroot management and deployment operations

Key Features:

• OSTree sysroot management
• Deployment switching
• Boot configuration
• State tracking

Implementation:

class RpmOstreeSysrootCore {
    // Sysroot management
    OstreeSysroot* sysroot;
    
    // Deployment operations
    bool switch_deployment(const std::string& ref);
    bool rollback_deployment();
    
    // Boot configuration
    bool update_boot_config();
    
    // State tracking
    void save_deployment_state();
    void load_deployment_state();
};

Rust Integration (rust/)

Modern Implementation

Purpose: Safety and performance improvements through Rust

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

Rust Architecture

// Core functionality
pub struct RpmOstreeCore {
    sack: DnfSack,
    repo: OstreeRepo,
    sysroot: OstreeSysroot,
}

impl RpmOstreeCore {
    pub fn install_packages(&mut self, packages: &[String]) -> Result<(), Error> {
        // Package installation logic
    }
    
    pub fn create_commit(&mut self, ref_name: &str) -> Result<(), Error> {
        // OSTree commit creation
    }
}

// Daemon implementation
pub struct RpmOstreeDaemon {
    core: RpmOstreeCore,
    transactions: HashMap<String, Transaction>,
}

impl RpmOstreeDaemon {
    pub fn handle_upgrade(&mut self, invocation: MethodInvocation) -> Result<(), Error> {
        // Upgrade handling
    }
}

Transaction System

Transaction Lifecycle

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

Transaction Types

DeployTransaction

• Purpose: Create new deployment
• Operations: Package installation, filesystem assembly, boot configuration
• Rollback: Remove deployment and restore previous state

RollbackTransaction

• Purpose: Revert to previous deployment
• Operations: Switch to previous deployment, update boot configuration
• Rollback: Switch back to current deployment

PkgChangeTransaction

• Purpose: Install or remove packages
• Operations: Package download, installation, dependency resolution
• Rollback: Remove installed packages or restore removed packages

RebaseTransaction

• Purpose: Switch to different base image
• Operations: Download new base, merge user packages, update boot config
• Rollback: Switch back to previous base image

UpgradeTransaction

• Purpose: Upgrade system to latest version
• Operations: Check for updates, download packages, install updates
• Rollback: Revert to previous system version

Atomic Operations

Principle: All operations are atomic - they either complete entirely or not at all.

Implementation:

• Transaction-based execution
• Rollback points at each stage
• State preservation during operations
• Cleanup on failure

Example Flow:

// Start transaction
auto transaction = start_transaction("upgrade");

// Create rollback points
create_rollback_point("pre-package-download");
create_rollback_point("pre-package-install");
create_rollback_point("pre-deployment-switch");

// Execute operations
if (!download_packages()) {
    rollback_to("pre-package-download");
    return false;
}

if (!install_packages()) {
    rollback_to("pre-package-install");
    return false;
}

if (!switch_deployment()) {
    rollback_to("pre-deployment-switch");
    return false;
}

// Commit transaction
commit_transaction(transaction);

Security Model

Privilege Separation

Principle: Separate privileged operations from unprivileged user operations.

Implementation:

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

Sandboxing

Principle: Execute package scripts in controlled, isolated environments.

Implementation:

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

SELinux Integration

Principle: Maintain SELinux policy consistency across deployments.

Implementation:

• SELinux policy regeneration after package changes
• Context preservation during layering
• Policy validation and enforcement

Performance Characteristics

Optimization Strategies

1. OSTree Deduplication: Leverage OSTree's content-addressable storage
2. Incremental Updates: Only download and apply changes
3. Parallel Processing: Concurrent package operations
4. Caching: Cache frequently accessed data

Resource Usage

• Memory: Scales with package count and complexity
• Disk: Optimized through OSTree deduplication
• Network: Minimized through delta updates
• CPU: Optimized through parallel processing

Performance Metrics

• Package Installation: ~100-500ms per package
• System Upgrade: ~30-60 seconds for typical updates
• Deployment Switch: ~5-15 seconds
• Rollback: ~5-15 seconds

Deployment Model

OSTree Integration

Principle: Use OSTree for atomic, immutable filesystem management.

Features:

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

Package Layering

Principle: Layer user packages on top of immutable base image.

Features:

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

Boot Configuration

Principle: Manage boot configuration for deployment switching.

Features:

• GRUB/systemd-boot integration
• Kernel argument management
• Initramfs management
• Boot-time deployment selection

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

Future Architecture

Container Integration

Planned Features:

• Direct container image support
• OCI image integration
• Container runtime integration
• Hybrid container/host management

Cloud Integration

Planned Features:

• Cloud deployment support
• Multi-cloud compatibility
• Cloud-native workflows
• Infrastructure as code integration

Enterprise Features

Planned Features:

• Role-based access control (RBAC)
• Audit logging and compliance
• Enterprise policy management
• Advanced security features