# apt-ostree Overview ## Executive Summary apt-ostree is a Debian/Ubuntu equivalent of rpm-ostree, providing a hybrid image/package system that combines the strengths of APT package management with OSTree's atomic, immutable deployment model. The project aims to bring the benefits of image-based deployments to the Debian/Ubuntu ecosystem. ### Core Philosophy: Every Change is "From Scratch" apt-ostree follows the same fundamental principle as rpm-ostree: **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 - **100% CLI Compatibility**: Identical user experience to rpm-ostree ## Project Architecture ### Core Design Philosophy - **Hybrid System**: Combines APT 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 - **Identical User Experience**: 100% CLI compatibility with rpm-ostree ## Directory Structure ``` apt-ostree/ ├── src/ # Source code │ ├── main.rs # CLI application │ ├── lib.rs # Library interface │ ├── apt.rs # APT package management │ ├── ostree.rs # OSTree operations │ ├── system.rs # System integration │ ├── package_manager.rs # High-level package operations │ ├── ostree_detection.rs # Environment detection │ ├── permissions.rs # Permission handling │ ├── error.rs # Error types │ ├── bin/ # Binary applications │ │ ├── apt-ostreed.rs # D-Bus daemon │ │ └── test_runner.rs # Test runner │ └── daemon/ # Daemon and service files ├── docs/ # Documentation │ ├── architecture/ # Architecture documentation │ ├── development/ # Development guides │ └── user-guide/ # User documentation ├── scripts/ # Scripts │ ├── testing/ # Test scripts │ └── daemon/ # Daemon management scripts ├── tests/ # Test files ├── .notes/ # Research and planning notes ├── Cargo.toml # Project configuration └── README.md # Project overview ``` ## Key Components ### 1. APT Manager (`src/apt.rs`) **Purpose**: APT package management using libapt-pkg **Key Features**: - Real DEB package download and extraction - APT database management in OSTree context - Package metadata extraction from control files - Dependency resolution using APT's native resolver - Package script execution with Bubblewrap sandboxing **Implementation**: - Direct libapt-pkg integration via FFI - OSTree-aware package installation - Atomic transaction management - Rollback support for failed operations ### 2. OSTree Manager (`src/ostree.rs`) **Purpose**: OSTree deployment management and filesystem operations **Key Features**: - OSTree commit creation and management - Deployment switching and rollback - Filesystem assembly from commits and layers - Boot configuration management - State tracking and synchronization **Implementation**: - Direct libostree integration - Atomic commit operations - Layer management and application - Deployment state tracking ### 3. System Integration (`src/system.rs`) **Purpose**: Coordination between APT and OSTree systems **Key Features**: - APT-OSTree state synchronization - Transaction management - Error handling and recovery - System state monitoring **Implementation**: - Coordinated package and deployment operations - Atomic transaction handling - Comprehensive error handling - State consistency management ### 4. Package Manager (`src/package_manager.rs`) **Purpose**: High-level package operations **Key Features**: - Package installation with atomic commits - Package removal with rollback support - System upgrades with automatic policies - Package search and information display **Implementation**: - Integrated APT-OSTree operations - Atomic transaction management - User-friendly error messages - Progress reporting ### 5. OSTree Detection (`src/ostree_detection.rs`) **Purpose**: Environment detection and validation **Key Features**: - Comprehensive OSTree environment detection - Multiple detection methods for reliability - Clear error messages for non-OSTree systems - Environment validation **Implementation**: - Filesystem detection (`/ostree` directory) - Boot detection (`/run/ostree-booted` file) - Kernel parameter detection (`ostree` in `/proc/cmdline`) - Library detection (OSTree sysroot loading) - Service detection (daemon availability) ### 6. Permissions (`src/permissions.rs`) **Purpose**: Root privilege checks and error handling **Key Features**: - Robust root privilege validation - User-friendly error messages - Security model enforcement - Privilege separation **Implementation**: - Root privilege checks for all operations - Clear error messages for permission issues - Security model validation - User guidance for privilege issues ## Daemon-Client Architecture ### Daemon (`src/bin/apt-ostreed.rs`) **Purpose**: Centralized system service for privileged operations **Key Features**: - D-Bus service exposing system management interface - Privileged package and deployment operations - Transaction management with atomicity guarantees - Progress reporting and cancellation support **Implementation**: - D-Bus service registration and activation - Method call handling and validation - Transaction execution and management - Error propagation and recovery ### Client (`src/main.rs`) **Purpose**: Command-line interface for user interaction **Key Features**: - 100% rpm-ostree CLI compatibility - D-Bus client communication with daemon - Fallback to direct system calls if daemon fails - User-friendly error messages and help **Implementation**: - Identical CLI interface to rpm-ostree - D-Bus client library for daemon communication - Fallback mechanisms for daemon failures - Comprehensive help and error messages ## CLI Commands (100% Complete) ### Core Commands (21/21 - 100% Complete) - **install**: Package installation with atomic commits - **deploy**: Deployment management and switching - **apply-live**: Live application of changes - **cancel**: Transaction cancellation - **cleanup**: Old deployment cleanup - **compose**: Tree composition - **status**: System status with rich formatting - **upgrade**: System upgrades with automatic policies - **rollback**: Deployment rollback - **db**: Package database queries (diff, list, version) - **search**: Enhanced package search - **override**: Package overrides (replace, remove, reset, list) - **refresh-md**: Repository metadata refresh - **reload**: Configuration reload - **reset**: State reset - **rebase**: Tree switching - **initramfs-etc**: Initramfs file management - **usroverlay**: Transient overlayfs to /usr - **kargs**: Kernel argument management - **uninstall**: Package removal (alias for remove) - **initramfs**: Initramfs management ### Command Architecture All commands follow the same architecture: 1. **CLI Parsing**: Parse command-line arguments 2. **Daemon Communication**: Request operation via D-Bus 3. **Fallback Handling**: Use direct system calls if daemon fails 4. **Progress Reporting**: Show operation progress 5. **Result Display**: Display operation results ## D-Bus Interface ### Service Interface (`org.aptostree.dev`) **Main Objects**: - `/org/aptostree/dev/Sysroot`: System root management - `/org/aptostree/dev/OS`: Operating system operations **Key Methods**: - `install_packages`: Install packages with atomic commits - `remove_packages`: Remove packages with rollback support - `upgrade_system`: Upgrade system with automatic policies - `rollback`: Rollback to previous deployment - `show_status`: Show system status and deployment information - `list_packages`: List installed packages - `search_packages`: Search for packages - `show_package_info`: Show package information **Transaction System**: - All operations return transaction addresses - Progress reporting via D-Bus signals - Atomic execution with rollback capability - Cancellation support ## Systemd Services ### Core Services - **apt-ostreed.service**: Main daemon service with OSTree detection - **apt-ostree-bootstatus.service**: Boot-time status logging - **apt-ostreed-automatic.service**: Automatic system updates (planned) - **apt-ostree-countme.service**: Usage reporting (planned) ### Service Configuration - D-Bus service activation - OSTree environment detection - 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 integration for authentication ### Bubblewrap Sandboxing - Package script execution in sandboxed environment - Namespace isolation for security - Controlled filesystem access - Privilege restrictions ## OSTree Environment Detection apt-ostree automatically detects if it's running in an OSTree environment using multiple methods: 1. **Filesystem Detection**: Check for `/ostree` directory 2. **Boot Detection**: Check for `/run/ostree-booted` file 3. **Kernel Parameter Detection**: Check for `ostree` in `/proc/cmdline` 4. **Library Detection**: Try to load OSTree sysroot 5. **Service Detection**: Check for daemon availability ### Error Handling When not running in an OSTree environment, apt-ostree provides clear error messages: ``` Error: apt-ostree requires an OSTree environment to operate. This system does not appear to be running on an OSTree deployment. To use apt-ostree: 1. Ensure you are running on an OSTree-based system 2. Verify that /ostree directory exists 3. Verify that /run/ostree-booted file exists 4. Ensure you have a valid booted deployment ``` ## 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 ## Future Development ### Planned Features - **OCI Integration**: Container image support - **Multi-architecture Support**: ARM, x86_64, etc. - **Advanced Security Features**: Enhanced sandboxing and security - **Cloud Integration**: Cloud deployment support - **Enterprise Features**: Advanced enterprise capabilities ### Community and Ecosystem - **Community Building**: User and developer community - **Ecosystem Integration**: Integration with Debian/Ubuntu ecosystem - **Adoption Strategies**: Strategies for widespread adoption - **Long-term Maintenance**: Sustainable maintenance model