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**:
```cpp
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**:
```cpp
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**:
```cpp
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**:
```cpp
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**:
```cpp
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**:
```cpp
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**:
```cpp
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**:
```cpp
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**:
```cpp
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

```rust
// 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**:
```cpp
// 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