# 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