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!
357 lines
No EOL
12 KiB
Markdown
357 lines
No EOL
12 KiB
Markdown
# 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 |