apt-ostree/docs/DBUS_INFRASTRUCTURE.md

D-Bus Infrastructure Documentation

Created: August 21, 2024
Last Updated: August 21, 2024
Status: 🔄 In Progress - Client Infrastructure Complete

Overview

The apt-ostree project includes a D-Bus infrastructure for communication between the CLI client and the system daemon (apt-ostreed). This infrastructure enables system management, transaction handling, and privileged operations.

Architecture

Service Information

• Service Name: org.projectatomic.aptostree1
• Object Path: /org/projectatomic/aptostree1
• Interface: org.projectatomic.aptostree1
• Bus Type: System bus (privileged operations)

Component Structure

┌─────────────────┐    D-Bus    ┌─────────────────┐
│   CLI Client   │ ←────────→   │  apt-ostreed   │
│  (apt-ostree)  │              │    Daemon      │
└─────────────────┘              └─────────────────┘
        │                                │
        │                                │
        ▼                                ▼
┌─────────────────┐              ┌─────────────────┐
│  D-Bus Client  │              │  D-Bus Server   │
│   (zbus)       │              │   (zbus)        │
└─────────────────┘              └─────────────────┘

Client Implementation

AptOstreeClient Trait

The core client interface is defined by the AptOstreeClient trait:

#[async_trait::async_trait]
pub trait AptOstreeClient: Send + Sync {
    /// Start a new transaction
    async fn start_transaction(&mut self, transaction_type: &str) -> ClientResult<String>;
    
    /// Get transaction status
    async fn get_transaction_status(&self, transaction_id: &str) -> ClientResult<String>;
    
    /// Install packages
    async fn install_packages(&mut self, transaction_id: &str, packages: &[&str]) -> ClientResult<bool>;
    
    /// Remove packages
    async fn remove_packages(&mut self, transaction_id: &str, packages: &[&str]) -> ClientResult<bool>;
    
    /// Upgrade system
    async fn upgrade(&mut self, transaction_id: &str) -> ClientResult<bool>;
    
    /// Rollback system
    async fn rollback(&mut self, transaction_id: &str) -> ClientResult<bool>;
    
    /// Deploy new deployment
    async fn deploy(&mut self, transaction_id: &str, refspec: &str) -> ClientResult<bool>;
    
    /// Rebase system
    async fn rebase(&mut self, transaction_id: &str, refspec: &str) -> ClientResult<bool>;
    
    /// Get deployments
    async fn get_deployments(&self) -> ClientResult<Vec<DeploymentInfo>>;
    
    /// Reload daemon
    async fn reload(&mut self) -> ClientResult<bool>;
    
    /// Shutdown daemon
    async fn shutdown(&mut self) -> ClientResult<bool>;
}

ClientDBus Implementation

The ClientDBus struct provides the concrete implementation:

pub struct ClientDBus {
    config: ClientConfig,
    connection: Option<Connection>,
    proxy: Option<AptOstreeDaemonProxy<'static>>,
}

Key Features

• Connection management: Handles D-Bus connection lifecycle
• Error handling: Error types and conversion
• Async support: Async/await compatibility
• Type safety: Strong typing for operations

Data Structures

DeploymentInfo

#[derive(Debug, Clone, serde::Serialize, serde::Deserialize)]
pub struct DeploymentInfo {
    pub id: String,
    pub commit: String,
    pub booted: bool,
    pub timestamp: String,
    pub version: String,
}

ClientConfig

#[derive(Debug, Clone)]
pub struct ClientConfig {
    pub dbus_name: String,
    pub dbus_path: String,
    pub dbus_interface: String,
    pub timeout: std::time::Duration,
}

Error Handling

ClientError Types

#[derive(Debug, thiserror::Error)]
pub enum ClientError {
    #[error("DBus error: {0}")]
    DBus(#[from] zbus::Error),
    
    #[error("Connection error: {0}")]
    Connection(String),
    
    #[error("Timeout error: {0}")]
    Timeout(String),
    
    #[error("Authentication error: {0}")]
    Authentication(String),
}

Error Conversion

• Conversion from zbus errors
• Error messages for connection issues
• Timeout handling for operations
• Authentication error handling

Usage Examples

Basic Client Setup

use apt_ostree::client::{AptOstreeClient, ClientDBus, ClientConfig};

async fn setup_client() -> Result<Box<dyn AptOstreeClient>, Box<dyn std::error::Error>> {
    let config = ClientConfig::default();
    let mut client = ClientDBus::new(config);
    
    // Connect to the daemon
    client.connect().await?;
    
    Ok(Box::new(client))
}

Transaction Management

async fn perform_upgrade() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = setup_client().await?;
    
    // Start upgrade transaction
    let transaction_id = client.start_transaction("upgrade").await?;
    println!("Upgrade transaction started: {}", transaction_id);
    
    // Perform upgrade
    let success = client.upgrade(&transaction_id).await?;
    if success {
        println!("Upgrade completed successfully!");
    }
    
    Ok(())
}

Deployment Operations

async fn manage_deployments() -> Result<(), Box<dyn std::error::Error>> {
    let mut client = setup_client().await?;
    
    // Get current deployments
    let deployments = client.get_deployments().await?;
    for deployment in &deployments {
        println!("Deployment: {} (commit: {})", deployment.id, deployment.commit);
    }
    
    // Deploy new reference
    let transaction_id = client.start_transaction("deploy").await?;
    let success = client.deploy(&transaction_id, "debian/13/x86_64").await?;
    
    Ok(())
}

Daemon Integration

Service Configuration

The daemon runs as a systemd service with D-Bus activation:

[Unit]
Description=apt-ostree System Management Daemon
Type=dbus
BusName=org.projectatomic.aptostree1

[Service]
ExecStart=+apt-ostree start-daemon
User=apt-ostree
DynamicUser=yes

D-Bus Interface Implementation

The daemon implements the same interface that clients connect to:

#[interface(name = "org.projectatomic.aptostree1")]
impl DaemonDBus {
    fn start_transaction(&self, transaction_type: &str) -> zbus::fdo::Result<String>;
    fn upgrade(&self, transaction_id: &str) -> zbus::fdo::Result<bool>;
    // ... other methods
}

Security Model

Authentication

• Polkit integration: Privileged operations require authentication
• User isolation: Daemon runs as dedicated user
• Capability management: Limited system access

Authorization

• Transaction validation: All operations go through transaction system
• Resource limits: Prevents resource exhaustion
• Audit logging: Operation logging

Testing

Unit Tests

#[cfg(test)]
mod tests {
    use super::*;
    
    #[tokio::test]
    async fn test_client_connection() {
        let config = ClientConfig::default();
        let mut client = ClientDBus::new(config);
        
        // Test connection
        assert!(client.connect().await.is_ok());
    }
}

Integration Tests

# Test D-Bus communication
./scripts/simple-dbus-test.sh

# Python-based testing
./scripts/test-dbus-python.py

Configuration

Environment Variables

• DBUS_SESSION_BUS_ADDRESS: D-Bus session bus address
• DBUS_SYSTEM_BUS_ADDRESS: D-Bus system bus address
• RUST_LOG: Logging level for debugging

Configuration Files

# apt-ostreed.conf
[Daemon]
DbusName = "org.projectatomic.aptostree1"
DbusPath = "/org/projectatomic/aptostree1"
TransactionTimeout = 300
MaxConcurrentTransactions = 1

Performance Considerations

Connection Pooling

• Persistent connections: Reuse D-Bus connections
• Connection limits: Prevent connection exhaustion
• Timeout management: Handle slow operations gracefully

Transaction Optimization

• Batch operations: Group related operations
• Async processing: Non-blocking operation handling
• Resource cleanup: Cleanup of completed transactions

Troubleshooting

Common Issues

1. Connection Failures

# Check daemon status
systemctl status apt-ostreed

# Verify D-Bus service registration
busctl --system list | grep aptostree

2. Permission Errors

# Check Polkit policies
ls -la /usr/share/polkit-1/actions/org.projectatomic.aptostree1.policy

# Verify user permissions
id apt-ostree

3. Transaction Failures

# Check transaction logs
journalctl -u apt-ostreed -f

# Verify transaction state
apt-ostree transaction status

Debug Mode

Enable detailed logging:

RUST_LOG=debug apt-ostree start-daemon

Future Enhancements

Planned Features

• Real-time notifications: Signal-based status updates
• Transaction queuing: Multiple concurrent transactions
• Performance monitoring: Metrics and profiling
• Plugin system: Extensible daemon capabilities

Integration Goals

• Systemd integration: Native systemd support
• Container support: Kubernetes and Docker integration
• Monitoring: Prometheus metrics export
• Security: Enhanced authentication and authorization

Conclusion

The D-Bus infrastructure in apt-ostree provides a foundation for client-daemon communication. With error handling, async support, and strong typing, it enables system management operations while maintaining security and performance.

The infrastructure is designed to be extensible, allowing for future enhancements while maintaining backward compatibility and stability.