1cc175c110
- 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.
339 lines
No EOL
15 KiB
Markdown
339 lines
No EOL
15 KiB
Markdown
# apt-ostree Architecture
|
|
|
|
## Overview
|
|
|
|
apt-ostree follows the same daemon-client architecture as rpm-ostree, providing a robust, secure, and scalable system for atomic package management. The architecture ensures proper privilege separation, transaction management, and system reliability.
|
|
|
|
## Core Architecture
|
|
|
|
### Daemon-Client Model
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ apt-ostree (Client) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ CLI │ │ Parser │ │ Client │ │
|
|
│ │ Commands │ │ Options │ │ Library │ │
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
│ D-Bus Communication
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ apt-ostreed (Daemon) │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ D-Bus │ │ Transaction │ │ System │ │
|
|
│ │ Interface │ │ Manager │ │ Operations │ │
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
│
|
|
│ System Calls
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ System Layer │
|
|
├─────────────────────────────────────────────────────────────┤
|
|
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ OSTree │ │ APT │ │ Bubblewrap │ │
|
|
│ │ Operations │ │ Operations │ │ Sandboxing │ │
|
|
│ └─────────────┘ └─────────────┘ └─────────────┘ │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Component Details
|
|
|
|
### 1. Client (`apt-ostree`)
|
|
|
|
**Purpose**: User interface and command processing
|
|
|
|
**Key Responsibilities**:
|
|
- Parse command-line arguments
|
|
- Validate user input
|
|
- Communicate with daemon via D-Bus
|
|
- Format output for user consumption
|
|
- Handle fallback to client-only operations
|
|
|
|
**Key Components**:
|
|
- `main.rs`: Command-line interface and dispatch
|
|
- `daemon_client.rs`: D-Bus communication library
|
|
- `system.rs`: Client-only fallback operations
|
|
|
|
**Architecture Pattern**:
|
|
```rust
|
|
// Daemon-based command with fallback
|
|
let result = call_daemon_with_fallback(
|
|
|client| Box::pin(client.install_packages(packages.clone(), yes, dry_run)),
|
|
|| Box::pin(async {
|
|
// Fallback to client-only if daemon unavailable
|
|
let system = AptOstreeSystem::new("debian/stable/x86_64").await?;
|
|
system.install_packages(&packages, yes).await?;
|
|
Ok("Packages installed successfully".to_string())
|
|
})
|
|
).await?;
|
|
```
|
|
|
|
### 2. Daemon (`apt-ostreed`)
|
|
|
|
**Purpose**: Privileged operations and system management
|
|
|
|
**Key Responsibilities**:
|
|
- Handle all privileged operations
|
|
- Manage OSTree repository operations
|
|
- Execute APT package operations
|
|
- Provide transaction management
|
|
- Implement security policies
|
|
|
|
**Key Components**:
|
|
- `src/bin/apt-ostreed.rs`: Main daemon process
|
|
- D-Bus interface implementation
|
|
- Transaction management
|
|
- System integration
|
|
|
|
**Architecture Pattern**:
|
|
```rust
|
|
#[dbus_interface(name = "org.aptostree.dev.Daemon")]
|
|
impl AptOstreeDaemon {
|
|
async fn install_packages(&self, packages: Vec<String>, yes: bool, dry_run: bool) -> zbus::fdo::Result<String> {
|
|
// Privileged package installation logic
|
|
// Transaction management
|
|
// Error handling and rollback
|
|
}
|
|
}
|
|
```
|
|
|
|
### 3. D-Bus Communication
|
|
|
|
**Interface**: `org.aptostree.dev.Daemon`
|
|
**Object Path**: `/org/aptostree/dev/Daemon`
|
|
|
|
**Key Methods**:
|
|
- `ping()`: Health check
|
|
- `status()`: System status
|
|
- `install_packages()`: Package installation
|
|
- `remove_packages()`: Package removal
|
|
- `upgrade_system()`: System upgrade
|
|
- `rollback()`: System rollback
|
|
|
|
**Communication Pattern**:
|
|
```rust
|
|
// Client side
|
|
let client = DaemonClient::new().await?;
|
|
let result = client.install_packages(packages, yes, dry_run).await?;
|
|
|
|
// Daemon side
|
|
async fn install_packages(&self, packages: Vec<String>, yes: bool, dry_run: bool) -> zbus::fdo::Result<String> {
|
|
// Implementation
|
|
}
|
|
```
|
|
|
|
## Security Architecture
|
|
|
|
### Privilege Separation
|
|
|
|
```
|
|
┌─────────────────┐ Unprivileged ┌─────────────────┐
|
|
│ User Space │ ◄────────────────► │ Daemon Space │
|
|
│ (Client) │ │ (Privileged) │
|
|
│ │ │ │
|
|
│ • CLI Commands │ │ • OSTree Ops │
|
|
│ • Option Parsing│ │ • APT Ops │
|
|
│ • Output Format │ │ • File System │
|
|
│ • D-Bus Client │ │ • D-Bus Server │
|
|
└─────────────────┘ └─────────────────┘
|
|
```
|
|
|
|
### Security Features
|
|
|
|
1. **D-Bus Policy**: Restrictive access control
|
|
2. **Systemd Service**: Proper service isolation
|
|
3. **Bubblewrap Sandboxing**: Script execution isolation
|
|
4. **Capability Management**: Minimal privilege requirements
|
|
5. **Transaction Rollback**: Atomic operations
|
|
|
|
## Transaction Management
|
|
|
|
### Transaction Lifecycle
|
|
|
|
```
|
|
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
|
│ Start │───►│ Execute │───►│ Commit │
|
|
│ Transaction │ │ Operations │ │ or Rollback │
|
|
└─────────────┘ └─────────────┘ └─────────────┘
|
|
│ │ │
|
|
▼ ▼ ▼
|
|
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
|
|
│ Validate │ │ Monitor │ │ Update │
|
|
│ Input │ │ Progress │ │ System │
|
|
└─────────────┘ └─────────────┘ └─────────────┘
|
|
```
|
|
|
|
### Atomic Operations
|
|
|
|
1. **Pre-transaction**: Validate system state
|
|
2. **Transaction**: Execute operations atomically
|
|
3. **Post-transaction**: Update system state
|
|
4. **Rollback**: Restore previous state on failure
|
|
|
|
## Filesystem Architecture
|
|
|
|
### OSTree Integration
|
|
|
|
```
|
|
/ostree/
|
|
├── repo/ # OSTree repository
|
|
│ ├── objects/ # Content-addressed objects
|
|
│ ├── refs/ # Branch references
|
|
│ └── config # Repository configuration
|
|
├── deploy/ # Deployments
|
|
│ ├── debian/stable/x86_64/ # State root
|
|
│ │ ├── deploy/ # Deployment directories
|
|
│ │ └── var/ # Persistent state
|
|
└── boot/ # Boot configuration
|
|
├── loader/ # Bootloader configuration
|
|
└── ostree/ # OSTree boot data
|
|
```
|
|
|
|
### Package Layering
|
|
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ User Packages │
|
|
│ (Layered on top of base deployment) │
|
|
├─────────────────────────────────────────┤
|
|
│ Base Deployment │
|
|
│ (Immutable base system) │
|
|
├─────────────────────────────────────────┤
|
|
│ OSTree Repository │
|
|
│ (Content-addressed storage) │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
## Bubblewrap Integration
|
|
|
|
### Sandboxing Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ Bubblewrap Sandbox │
|
|
├─────────────────────────────────────────┤
|
|
│ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ Script │ │ Package │ │
|
|
│ │ Execution │ │ Extraction │ │
|
|
│ └─────────────┘ └─────────────┘ │
|
|
├─────────────────────────────────────────┤
|
|
│ Namespace Isolation │
|
|
│ • User namespace │
|
|
│ • PID namespace │
|
|
│ • Mount namespace │
|
|
│ • Network namespace │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
### Security Controls
|
|
|
|
1. **Namespace Isolation**: Complete process isolation
|
|
2. **Bind Mounts**: Read-only system directories
|
|
3. **Capability Dropping**: Minimal capabilities
|
|
4. **Environment Control**: Controlled execution environment
|
|
|
|
## Error Handling
|
|
|
|
### Error Hierarchy
|
|
|
|
```
|
|
AptOstreeError
|
|
├── PermissionDenied
|
|
├── DaemonError
|
|
│ ├── ConnectionFailed
|
|
│ ├── MethodCallFailed
|
|
│ └── TransactionFailed
|
|
├── PackageError
|
|
│ ├── DownloadFailed
|
|
│ ├── InstallationFailed
|
|
│ └── DependencyError
|
|
├── OSTreeError
|
|
│ ├── RepositoryError
|
|
│ ├── CommitError
|
|
│ └── DeploymentError
|
|
└── SystemError
|
|
├── FilesystemError
|
|
├── NetworkError
|
|
└── ConfigurationError
|
|
```
|
|
|
|
### Recovery Mechanisms
|
|
|
|
1. **Automatic Rollback**: Transaction rollback on failure
|
|
2. **Fallback Operations**: Client-only fallback when daemon unavailable
|
|
3. **Graceful Degradation**: Continue operation with reduced functionality
|
|
4. **Error Reporting**: Clear error messages and recovery suggestions
|
|
|
|
## Performance Considerations
|
|
|
|
### Optimization Strategies
|
|
|
|
1. **Parallel Operations**: Concurrent package downloads
|
|
2. **Caching**: Package metadata and content caching
|
|
3. **Hardlink Optimization**: OSTree hardlink deduplication
|
|
4. **Streaming**: Large file streaming operations
|
|
5. **Memory Management**: Efficient memory usage patterns
|
|
|
|
### Monitoring
|
|
|
|
1. **Transaction Monitoring**: Real-time progress reporting
|
|
2. **Resource Usage**: Memory and CPU monitoring
|
|
3. **Performance Metrics**: Operation timing and throughput
|
|
4. **Error Tracking**: Error rate and type monitoring
|
|
|
|
## Deployment Architecture
|
|
|
|
### System Integration
|
|
|
|
```
|
|
┌─────────────────────────────────────────┐
|
|
│ System Boot │
|
|
├─────────────────────────────────────────┤
|
|
│ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ GRUB │ │ systemd │ │
|
|
│ │ Bootloader │ │ Boot │ │
|
|
│ └─────────────┘ └─────────────┘ │
|
|
├─────────────────────────────────────────┤
|
|
│ OSTree Deployment │
|
|
├─────────────────────────────────────────┤
|
|
│ ┌─────────────┐ ┌─────────────┐ │
|
|
│ │ apt-ostree│ │ apt-ostreed │ │
|
|
│ │ Client │ │ Daemon │ │
|
|
│ └─────────────┘ └─────────────┘ │
|
|
└─────────────────────────────────────────┘
|
|
```
|
|
|
|
### Service Management
|
|
|
|
1. **systemd Integration**: Proper service lifecycle management
|
|
2. **D-Bus Activation**: Automatic daemon startup
|
|
3. **Service Dependencies**: Proper dependency management
|
|
4. **Health Monitoring**: Service health checks
|
|
|
|
## Future Architecture Considerations
|
|
|
|
### Scalability
|
|
|
|
1. **Multi-Client Support**: Multiple concurrent clients
|
|
2. **Distributed Operations**: Network-based operations
|
|
3. **Caching Layer**: Distributed caching
|
|
4. **Load Balancing**: Operation distribution
|
|
|
|
### Extensibility
|
|
|
|
1. **Plugin Architecture**: Extensible functionality
|
|
2. **API Evolution**: Backward-compatible API changes
|
|
3. **Feature Flags**: Optional feature enablement
|
|
4. **Configuration Management**: Flexible configuration
|
|
|
|
### Security Enhancements
|
|
|
|
1. **AppArmor Integration**: Mandatory access control
|
|
2. **SELinux Support**: Security context management
|
|
3. **Audit Integration**: Comprehensive audit logging
|
|
4. **Cryptographic Verification**: Package integrity verification |