robojerk
d295f9bb4d
- ✅ Real package installation (replaced mock installation) - ✅ Real OSTree commit creation from installed packages - ✅ OCI image creation from both commits and rootfs - ✅ Full bootc compatibility with proper labels - ✅ Comprehensive test suite (test-bootc-apt-ostree.sh) - ✅ Container tool validation (skopeo, podman) - ✅ Updated compatibility reports for Ubuntu Questing - ✅ Fixed OCI schema version and field naming issues - ✅ Temporary directory lifecycle fixes - ✅ Serde rename attributes for OCI JSON compliance Ready for Aurora-style workflow deployment!
285 lines
No EOL
11 KiB
Markdown
285 lines
No EOL
11 KiB
Markdown
# 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 |