244 lines
No EOL
8.6 KiB
Markdown
244 lines
No EOL
8.6 KiB
Markdown
# apt-ostree Architecture Overview
|
|
|
|
## Project Organization
|
|
|
|
### Directory Structure
|
|
The apt-ostree project follows a well-organized structure designed for maintainability and clarity:
|
|
|
|
```
|
|
apt-ostree/
|
|
├── src/ # Source code
|
|
│ ├── main.rs # CLI application entry point
|
|
│ ├── 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 Design Decisions
|
|
- **Modular Architecture**: Each component is self-contained with clear interfaces
|
|
- **Separation of Concerns**: CLI, daemon, and library code are clearly separated
|
|
- **Documentation-First**: Comprehensive documentation for all components
|
|
- **Testing Infrastructure**: Dedicated testing framework and utilities
|
|
- **Research Integration**: Planning and research notes preserved for reference
|
|
|
|
## Introduction
|
|
|
|
apt-ostree is a Debian/Ubuntu equivalent of rpm-ostree, providing a hybrid image/package system that combines APT package management with OSTree's atomic, immutable deployment model.
|
|
|
|
## Core Design Principles
|
|
|
|
### 1. "From Scratch" Philosophy
|
|
Every change regenerates the target filesystem completely, avoiding hysteresis and ensuring reproducible results.
|
|
|
|
### 2. Atomic Operations
|
|
All changes are atomic with proper rollback support, ensuring no partial states.
|
|
|
|
### 3. Immutable Base + Layered Packages
|
|
- Base image remains unchanged
|
|
- User packages layered on top
|
|
- Clear separation of concerns
|
|
|
|
## Architecture Components
|
|
|
|
### Core Modules
|
|
|
|
#### APT Manager (`src/apt.rs`)
|
|
- Package management using libapt-pkg
|
|
- Repository management and metadata handling
|
|
- Package downloading and dependency resolution
|
|
|
|
#### OSTree Manager (`src/ostree.rs`)
|
|
- Deployment management and filesystem operations
|
|
- Repository operations and commit management
|
|
- Boot configuration management
|
|
|
|
#### System Integration (`src/system.rs`)
|
|
- Coordination between APT and OSTree
|
|
- High-level system operations
|
|
- Transaction management and rollback
|
|
|
|
#### Package Manager (`src/package_manager.rs`)
|
|
- High-level package operations
|
|
- Atomic transaction handling
|
|
- State synchronization
|
|
|
|
#### OSTree Detection (`src/ostree_detection.rs`)
|
|
- Environment detection and validation
|
|
- Multiple detection methods
|
|
- Error handling for non-OSTree environments
|
|
|
|
### Integration Modules
|
|
|
|
#### APT-OSTree Integration (`src/apt_ostree_integration.rs`)
|
|
- Bridge between APT and OSTree systems
|
|
- Package conversion and metadata handling
|
|
- Filesystem layout management
|
|
|
|
#### Filesystem Assembly (`src/filesystem_assembly.rs`)
|
|
- "From scratch" filesystem regeneration
|
|
- Hardlink optimization for content deduplication
|
|
- Proper layering order for packages
|
|
|
|
#### Dependency Resolver (`src/dependency_resolver.rs`)
|
|
- Package dependency resolution
|
|
- Topological sorting for layering
|
|
- Conflict detection and resolution
|
|
|
|
#### Script Execution (`src/script_execution.rs`)
|
|
- Sandboxed execution using bubblewrap
|
|
- Namespace isolation and security controls
|
|
- Rollback support for failed script execution
|
|
|
|
#### Bubblewrap Sandbox (`src/bubblewrap_sandbox.rs`)
|
|
- Security sandboxing for script execution
|
|
- Namespace isolation and capability management
|
|
- Environment variable handling
|
|
|
|
#### APT Database (`src/apt_database.rs`)
|
|
- APT database management in OSTree context
|
|
- State persistence and synchronization
|
|
- Package tracking and metadata management
|
|
|
|
#### OSTree Commit Manager (`src/ostree_commit_manager.rs`)
|
|
- OSTree commit management
|
|
- Atomic commit creation and deployment
|
|
- Layer tracking and metadata management
|
|
|
|
### Support Modules
|
|
|
|
#### Error Handling (`src/error.rs`)
|
|
- Unified error types
|
|
- Error conversion and propagation
|
|
- User-friendly error messages
|
|
|
|
#### Permissions (`src/permissions.rs`)
|
|
- Root privilege checks
|
|
- Permission validation
|
|
- User-friendly error messages
|
|
|
|
## Daemon Architecture
|
|
|
|
### D-Bus Service (`src/bin/apt-ostreed.rs`)
|
|
- System service providing D-Bus interface
|
|
- Privileged operations and transaction management
|
|
- Progress reporting and cancellation support
|
|
|
|
### Client Library
|
|
- D-Bus communication with daemon
|
|
- Fallback to direct system calls
|
|
- Error handling and retry logic
|
|
|
|
## Data Flow
|
|
|
|
### Package Installation Flow
|
|
1. **Command Parsing**: CLI options and package list
|
|
2. **Permission Check**: Root privilege validation
|
|
3. **Environment Detection**: OSTree environment validation
|
|
4. **Package Resolution**: APT dependency resolution
|
|
5. **Download**: Package downloading and verification
|
|
6. **Extraction**: DEB package extraction
|
|
7. **Filesystem Assembly**: "From scratch" filesystem creation
|
|
8. **Script Execution**: Sandboxed script execution
|
|
9. **Commit Creation**: Atomic OSTree commit
|
|
10. **Deployment**: Boot configuration update
|
|
|
|
### Rollback Flow
|
|
1. **State Validation**: Verify rollback target
|
|
2. **Transaction Start**: Begin rollback transaction
|
|
3. **State Restoration**: Restore previous state
|
|
4. **Boot Configuration**: Update boot configuration
|
|
5. **Transaction Commit**: Complete rollback
|
|
|
|
## Security Model
|
|
|
|
### Script Sandboxing
|
|
- All DEB scripts run in bubblewrap sandbox
|
|
- Namespace isolation and capability management
|
|
- Seccomp profiles for system call filtering
|
|
|
|
### Permission Controls
|
|
- Proper file and directory permissions
|
|
- Root privilege validation
|
|
- Environment validation
|
|
|
|
### Atomic Operations
|
|
- No partial states that could be exploited
|
|
- Instant rollback capability
|
|
- Transactional updates
|
|
|
|
## Performance Characteristics
|
|
|
|
### Optimization Features
|
|
- **Hardlink Optimization**: Content deduplication for identical files
|
|
- **Caching Strategies**: Efficient package and metadata caching
|
|
- **Parallel Processing**: Async operations for better performance
|
|
- **Content Addressing**: SHA256-based deduplication
|
|
|
|
### Expected Performance
|
|
- **Package Resolution**: Comparable to native APT
|
|
- **Memory Usage**: Reduced due to Rust's ownership system
|
|
- **Deployment Speed**: Optimized with OSTree's content addressing
|
|
- **Error Recovery**: Faster due to compile-time guarantees
|
|
|
|
## Integration Points
|
|
|
|
### System Integration
|
|
- **systemd**: Service management and boot integration
|
|
- **D-Bus**: Inter-process communication
|
|
- **OSTree**: Deployment and filesystem management
|
|
- **APT**: Package management and dependency resolution
|
|
|
|
### External Dependencies
|
|
- **bubblewrap**: Script sandboxing
|
|
- **libapt-pkg**: APT package management
|
|
- **libostree**: OSTree deployment management
|
|
- **zbus**: D-Bus communication
|
|
|
|
## Error Handling
|
|
|
|
### Error Types
|
|
- **AptOstreeError**: Unified error type for all operations
|
|
- **Permission Errors**: Root privilege and access control
|
|
- **Environment Errors**: OSTree environment validation
|
|
- **Package Errors**: APT package management errors
|
|
- **OSTree Errors**: OSTree operation errors
|
|
|
|
### Error Recovery
|
|
- **Automatic Rollback**: Failed operations automatically rollback
|
|
- **Graceful Degradation**: Fallback mechanisms for failures
|
|
- **User Feedback**: Clear error messages and recovery suggestions
|
|
|
|
## Testing Strategy
|
|
|
|
### Test Categories
|
|
- **Unit Tests**: Individual component testing
|
|
- **Integration Tests**: End-to-end workflow testing
|
|
- **OSTree Integration Tests**: Real OSTree repository testing
|
|
- **Sandbox Testing**: Bubblewrap integration validation
|
|
- **Rollback Testing**: Rollback functionality validation
|
|
|
|
### Test Infrastructure
|
|
- **Test Runner**: Comprehensive test execution framework
|
|
- **Test Utilities**: Common test helpers and utilities
|
|
- **Mock Objects**: Mock implementations for testing
|
|
- **Test Data**: Test packages and repositories |