apt-ostree/.notes/overview-apt-ostree.md

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