robojerk 97a9c40d7e docs: Add comprehensive documentation and update planning

- 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.

2025-07-18 23:38:57 +00:00

7.7 KiB

Raw Blame History

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:

sudo ./scripts/install-daemon.sh

This script:

Creates necessary directories
Installs daemon binary
Copies configuration files
Sets up D-Bus integration
Installs systemd services
Configures Polkit policies
Initializes OSTree repository
Starts and enables services

Usage

Basic Commands

# 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

# 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

Daemon not starting
- Check systemd status: systemctl status apt-ostreed.service
- View logs: journalctl -u apt-ostreed.service
- Verify D-Bus configuration
Permission denied
- Check Polkit policies
- Verify user authentication
- Check D-Bus policy configuration
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:

[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.

7.7 KiB Raw Blame History