particle-os-tools/src/apt-ostree.py/SYSTEMD_USAGE.md

apt-ostree Systemd Service Usage

Overview

The apt-ostree daemon is managed through systemd using the apt-ostreed.service unit. The service is configured with proper locking mechanisms to prevent multiple instances and ensure clean startup/shutdown.

Service Configuration

Type=simple

The service uses Type=simple instead of Type=dbus because:

• The daemon manages its own D-Bus interface registration
• Provides better control over the daemon lifecycle
• Allows for proper PID file management
• Enables ExecStartPre/ExecStopPost hooks

Lock File Mechanism

• PID File: /var/run/apt-ostreed.pid - Contains the daemon's process ID
• Lock File: /run/apt-ostreed/daemon.lock - Prevents multiple instances
• Runtime Directory: /run/apt-ostreed/ - Managed by systemd

Instance Prevention

The service includes ExecStartPre commands to:

1. Remove stale PID files
2. Remove stale lock files
3. Create runtime directory
4. Create fresh lock file

Proper Service Management

⚠️ IMPORTANT: Use systemctl Only

DO NOT run the daemon directly with python3 apt_ostree.py --daemon. Always use systemctl commands:

# ✅ CORRECT - Use systemctl
sudo systemctl start apt-ostreed
sudo systemctl stop apt-ostreed
sudo systemctl restart apt-ostreed
sudo systemctl status apt-ostreed

# ❌ WRONG - Don't run directly
sudo python3 apt_ostree.py --daemon  # This bypasses systemd management

Why systemctl Only?

1. Lock File Management: systemd handles PID and lock files automatically
2. Process Supervision: systemd monitors the daemon and restarts on failure
3. Dependency Management: Ensures proper startup order (after dbus, etc.)
4. Security: Maintains security sandboxing and privilege restrictions
5. Logging: Integrates with journald for centralized logging
6. Resource Management: systemd can manage resource limits and cgroups

Service Commands

Basic Management

# Start the daemon
sudo systemctl start apt-ostreed

# Stop the daemon
sudo systemctl stop apt-ostreed

# Restart the daemon
sudo systemctl restart apt-ostreed

# Check status
sudo systemctl status apt-ostreed

# Enable auto-start on boot
sudo systemctl enable apt-ostreed

# Disable auto-start
sudo systemctl disable apt-ostreed

Monitoring and Debugging

# View real-time logs
sudo journalctl -u apt-ostreed -f

# View recent logs
sudo journalctl -u apt-ostreed -n 50

# View logs since boot
sudo journalctl -u apt-ostreed -b

# Check if service is active
sudo systemctl is-active apt-ostreed

# Check if service is enabled
sudo systemctl is-enabled apt-ostreed

Troubleshooting

# Check service configuration
sudo systemctl cat apt-ostreed

# Validate service file
sudo systemd-analyze verify apt-ostreed.service

# Check dependencies
sudo systemctl list-dependencies apt-ostreed

# Force reload configuration
sudo systemctl daemon-reload
sudo systemctl restart apt-ostreed

Service States

Normal Operation

• Active: Daemon is running and responding
• Inactive: Daemon is stopped
• Failed: Daemon failed to start or crashed

Transition States

• Activating: Daemon is starting up
• Deactivating: Daemon is shutting down
• Reloading: Daemon is reloading configuration

Lock File Troubleshooting

If the service fails to start due to lock files:

# Check for stale lock files
ls -la /var/run/apt-ostreed.pid
ls -la /run/apt-ostreed/daemon.lock

# Remove stale files (if service is not running)
sudo rm -f /var/run/apt-ostreed.pid
sudo rm -f /run/apt-ostreed/daemon.lock

# Restart service
sudo systemctl restart apt-ostreed

Integration with apt-ostree CLI

The apt-ostree CLI automatically communicates with the daemon via D-Bus:

# These commands work through the daemon
apt-ostree status
apt-ostree upgrade
apt-ostree install package-name
apt-ostree rollback

# The CLI will automatically start the daemon if needed
# (when using systemctl, not direct execution)

Security Considerations

• The daemon runs as root (required for system operations)
• Uses systemd security sandboxing (ProtectSystem, PrivateTmp, etc.)
• D-Bus communication is restricted by policy files
• Lock files prevent privilege escalation through multiple instances

Best Practices

1. Always use systemctl for service management
2. Never run the daemon directly with python3
3. Monitor logs with journalctl for troubleshooting
4. Use proper service states for automation scripts
5. Check lock files if startup fails
6. Enable the service for automatic startup on boot

Example Automation Script

#!/bin/bash
# Example script for managing apt-ostree daemon

SERVICE="apt-ostreed"

case "$1" in
    start)
        echo "Starting apt-ostree daemon..."
        sudo systemctl start $SERVICE
        ;;
    stop)
        echo "Stopping apt-ostree daemon..."
        sudo systemctl stop $SERVICE
        ;;
    restart)
        echo "Restarting apt-ostree daemon..."
        sudo systemctl restart $SERVICE
        ;;
    status)
        sudo systemctl status $SERVICE
        ;;
    logs)
        sudo journalctl -u $SERVICE -f
        ;;
    *)
        echo "Usage: $0 {start|stop|restart|status|logs}"
        exit 1
        ;;
esac