# 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:

```bash
# ✅ 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
```bash
# 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
```bash
# 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
```bash
# 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:

```bash
# 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:

```bash
# 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

```bash
#!/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
```