apt-ostree/DAEMON-ARCHITECTURE.md

# apt-ostree Daemon 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 daemon (`apt-ostreed`) handles all privileged operations while the client (`apt-ostree`) provides the user interface.

## Architecture Components

### 1. Daemon (`apt-ostreed`)

**Location**: `/usr/libexec/apt-ostreed`

**Purpose**: 
- Handles all privileged operations requiring root access
- Manages OSTree repository operations
- Executes APT package operations
- Provides transaction management and rollback support
- Implements security policies and access control

**Key Features**:
- D-Bus interface for client communication
- Transaction-based operations with atomic rollback
- Sandboxed package script execution
- Automatic update management
- System state monitoring

### 2. Client (`apt-ostree`)

**Location**: `/usr/bin/apt-ostree`

**Purpose**:
- Provides user-friendly command-line interface
- Communicates with daemon via D-Bus
- Handles command parsing and validation
- Formats output for user consumption
- Implements fallback to direct operations when daemon unavailable

### 3. D-Bus Integration

**Interface**: `org.aptostree.dev.Daemon`
**Object Path**: `/org/aptostree/dev`

**Configuration Files**:
- `/etc/dbus-1/system.d/org.aptostree.dev.conf` - D-Bus policy
- `/usr/share/dbus-1/system-services/org.aptostree.dev.service` - Service activation

**Key Methods**:
- `Ping()` - Health check
- `GetStatus()` - System status
- `InstallPackages()` - Package installation
- `RemovePackages()` - Package removal
- `UpgradeSystem()` - System upgrade
- `Rollback()` - System rollback
- `DeployCommit()` - Commit deployment
- `ModifyKernelArgs()` - Kernel argument management
- `SetInitramfsState()` - Initramfs management

### 4. Systemd Services

#### Core Services

**apt-ostreed.service**
- Main daemon service
- Runs as root
- Provides D-Bus interface
- Handles privileged operations

**apt-ostree-bootstatus.service**
- Boot-time status logging
- Records deployment information to journal
- Runs once at boot

#### Automatic Update Services

**apt-ostreed-automatic.service**
- Handles automatic system updates
- Configurable for security-only or full updates
- Non-blocking operation with timeout

**apt-ostreed-automatic.timer**
- Triggers automatic updates daily
- Randomized delays to prevent thundering herd
- Persistent across reboots

#### Usage Reporting Services

**apt-ostree-countme.service**
- Privacy-compliant usage reporting
- Collects anonymous usage statistics
- Secure data collection with proper permissions

**apt-ostree-countme.timer**
- Weekly usage reporting
- Randomized delays for privacy
- Optional opt-out capability

### 5. Security Integration

#### Polkit Policies

**Location**: `/usr/share/polkit-1/actions/org.aptostree.dev.policy`

**Actions**:
- `org.aptostree.dev.install-packages` - Package installation
- `org.aptostree.dev.remove-packages` - Package removal
- `org.aptostree.dev.upgrade-system` - System upgrade
- `org.aptostree.dev.rollback` - System rollback
- `org.aptostree.dev.modify-kernel-args` - Kernel arguments
- `org.aptostree.dev.initramfs` - Initramfs management
- `org.aptostree.dev.rebase` - System rebase
- `org.aptostree.dev.reset` - System reset

#### Authentication Requirements

All privileged operations require authentication:
- `auth_admin` for all privileged actions
- Proper user session validation
- Secure credential handling

### 6. Configuration

**Main Config**: `/etc/apt-ostree/apt-ostreed.conf`

**Key Settings**:
- OSTree repository path
- APT cache and state directories
- Transaction timeout and concurrency
- Automatic update policies
- Logging configuration
- D-Bus settings
- Security policies

### 7. Directory Structure

```
/usr/
├── bin/
│   └── apt-ostree                    # Client binary
├── libexec/
│   └── apt-ostreed                   # Daemon binary
└── share/
    ├── dbus-1/system-services/
    │   └── org.aptostree.dev.service # D-Bus activation
    └── polkit-1/actions/
        └── org.aptostree.dev.policy  # Authorization policies

/etc/
├── apt-ostree/
│   └── apt-ostreed.conf              # Daemon configuration
├── dbus-1/system.d/
│   └── org.aptostree.dev.conf        # D-Bus policy
└── systemd/system/
    ├── apt-ostreed.service           # Main daemon service
    ├── apt-ostree-bootstatus.service # Boot status service
    ├── apt-ostree-countme.service    # Usage reporting service
    ├── apt-ostree-countme.timer      # Weekly timer
    ├── apt-ostreed-automatic.service # Automatic updates
    └── apt-ostreed-automatic.timer   # Daily timer

/var/
├── lib/apt-ostree/                   # OSTree repository and state
├── cache/apt-ostree/                 # APT cache
└── log/apt-ostree/                   # Log files
```

## Benefits of Daemon Architecture

### 1. Security
- Privileged operations isolated in daemon
- Proper authentication and authorization
- Sandboxed execution environment
- Secure credential handling

### 2. Reliability
- Transaction-based operations
- Atomic rollback support
- Automatic recovery mechanisms
- Robust error handling

### 3. Scalability
- Asynchronous operations
- Concurrent transaction support
- Resource management
- Performance optimization

### 4. Maintainability
- Clear separation of concerns
- Modular design
- Comprehensive logging
- Debugging support

### 5. Integration
- Systemd service integration
- D-Bus communication
- Polkit authorization
- Standard Linux security model

## Installation

Use the provided installation script:

```bash
sudo ./scripts/install-daemon.sh
```

This script:
1. Creates necessary directories
2. Installs daemon binary
3. Copies configuration files
4. Sets up D-Bus integration
5. Installs systemd services
6. Configures Polkit policies
7. Initializes OSTree repository
8. Starts and enables services

## Usage

### Basic Commands

```bash
# Check daemon status
systemctl status apt-ostreed.service

# Test D-Bus connection
gdbus introspect --system --dest org.aptostree.dev --object-path /org/aptostree/dev

# Use apt-ostree with daemon support
apt-ostree status
apt-ostree install package-name
apt-ostree upgrade
apt-ostree rollback
```

### Service Management

```bash
# Enable automatic updates
systemctl enable apt-ostreed-automatic.timer

# Check automatic update status
systemctl status apt-ostreed-automatic.timer

# View usage reporting
systemctl status apt-ostree-countme.timer

# View logs
journalctl -u apt-ostreed.service
```

## Troubleshooting

### Common Issues

1. **Daemon not starting**
   - Check systemd status: `systemctl status apt-ostreed.service`
   - View logs: `journalctl -u apt-ostreed.service`
   - Verify D-Bus configuration

2. **Permission denied**
   - Check Polkit policies
   - Verify user authentication
   - Check D-Bus policy configuration

3. **D-Bus connection failed**
   - Restart D-Bus: `systemctl restart dbus`
   - Reload daemon: `systemctl reload apt-ostreed.service`
   - Check service activation file

### Debug Mode

Enable debug logging in `/etc/apt-ostree/apt-ostreed.conf`:

```ini
[Daemon]
LogLevel=debug
```

## Comparison with rpm-ostree

apt-ostree maintains 100% architectural compatibility with rpm-ostree:

- **Same daemon-client model**
- **Same D-Bus interface patterns**
- **Same systemd service structure**
- **Same security integration**
- **Same transaction management**
- **Same automatic update mechanisms**

The only differences are:
- APT package management instead of DNF
- Debian/Ubuntu-specific configurations
- Package format handling (.deb vs .rpm)

This ensures that users familiar with rpm-ostree will have an identical experience with apt-ostree.