particle-os/apt-ostree
1
0
Fork 0
Code Issues 1 Pull requests Projects Releases Packages Wiki Activity Actions
apt-ostree/.notes/rpm-ostree/overview.md
robojerk 97a9c40d7e docs: Add comprehensive documentation and update planning 
- Add docs/README.md with project overview and current status
- Add docs/architecture.md with detailed architecture documentation
- Add docs/development.md with development guide for contributors
- Update .notes/todo.md to reflect architecture fix completion
- Update .notes/plan.md with completed phases and next priorities

Architecture fixes (daemon and dbus), bubblewrap integration are now complete.
Ready for OCI integration phase.
2025-07-18 23:38:57 +00:00

260 lines
No EOL
11 KiB
Markdown
Raw Blame History

# rpm-ostree Source Code Analysis 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 Analysis
```
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
```
Files inside rpm-ostree-2025.8-2.fc42.rpm
```
etc/
rpm-ostreed.conf
usr/
bin/
rpm-ostree # client / cli executable
lib/
.build-id/
c0/
4a8f1297c0e4ffc011fd4b487f98388309d8d0
kernel/
install.d/
05-rpmostree.install
systemd/
system/
rpm-ostree-bootstatus.service
rpm-ostree-countme.service
rpm-ostree-countme.timer
rpm-ostree-fix-shadow-mode.service
rpm-ostreed-automatic.service
rpm-ostreed-automatic.timer
rpm-ostreed.service
lib64/
rpm-ostree/
rpm-ostree-0-integration-opt-usrlocal-compat.conf
rpm-ostree-0-integration-opt-usrlocal.conf
rpm-ostree-0-integration.conf
libexec/
rpm-ostreed # Daemon executable
share/
bash-completion/
completions/
rpm-ostree
dbus-1/
system-services/
org.projectatomic.rpmostree1.service
system.d/
org.projectatomic.rpmostree1.conf
doc/
rpm-ostree/
COPYING.GPL
COPYING.LGPL
LICENSE
README.md
man/
man1/
rpm-ostree.1.gz
man5/
rpm-ostreed.conf.5.gz
man8/
rpm-ostree-countme.service.8.gz
rpm-ostree-countme.timer.8.gz
rpm-ostreed-automatic.service.8.gz
rpm-ostreed-automatic.timer.8.gz
polkit-1/
actions/
org.projectatomic.rpmostree1.policy
```
## Key Components Analysis
### 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
### 5. Related Tools and Ecosystem
**bootc**: Focuses on booting directly from container images, offering an alternative to traditional rpm-ostree
- rpm-ostree and bootc can interact and operate on shared state for upgrades, rebases, and deployment tasks
- rpm-ostree is still necessary for certain functionalities, particularly when package layering is involved
**composefs and fsverity**:
- composefs provides enhanced filesystem integrity and deduplication by leveraging fs-verity
- This combination strengthens data integrity by validating the entire filesystem tree, making them effectively read-only and tamper-proof
**skopeo and podman**:
- These tools are primarily used for managing and interacting with container images
- While they can work alongside rpm-ostree systems, rpm-ostree's focus is on managing the host operating system
## D-Bus Interface Analysis
### 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. **CleanupTransaction**: System cleanup operations
4. **PackageDiffTransaction**: Package difference analysis
5. **FinalizeDeploymentTransaction**: Deployment finalization
### Atomicity Guarantees
- **Staging**: New deployments are staged before activation
- **Rollback Preservation**: Previous deployments are maintained
- **Transaction Isolation**: Operations succeed completely or fail completely
- **State Consistency**: System maintains consistent state across reboots
Reference in a new issue View git blame Copy permalink