bootc-docs/building/management-services.md

# Management services

Management services in bootc systems handle operational tasks like updates, monitoring, and system maintenance. This document covers how to implement and manage these services in Debian bootc images.

## Overview

Management services are systemd services that handle:

- **System updates**: Managing bootc updates and rollbacks
- **Monitoring**: Health checks and system monitoring
- **Maintenance**: Log rotation, cleanup, and maintenance tasks
- **Configuration**: Dynamic configuration updates

## Update Management

### bootc Update Service

Create a service to handle bootc updates:

```dockerfile
# Create update management service
COPY bootc-update.service /usr/lib/systemd/system/
COPY bootc-update.timer /usr/lib/systemd/system/
COPY update-bootc.sh /usr/local/bin/
```

Service file (`/usr/lib/systemd/system/bootc-update.service`):
```ini
[Unit]
Description=Update bootc system
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/update-bootc.sh
StandardOutput=journal
StandardError=journal
```

Timer file (`/usr/lib/systemd/system/bootc-update.timer`):
```ini
[Unit]
Description=Run bootc update daily
Requires=bootc-update.service

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target
```

### Update Script Example

```bash
#!/bin/bash
# /usr/local/bin/update-bootc.sh

set -euo pipefail

# Check for updates
if bootc update --check; then
    echo "Updates available, applying..."
    bootc update
    echo "Update completed successfully"
else
    echo "No updates available"
fi
```

## Monitoring Services

### Health Check Service

Create a health check service:

```dockerfile
# Create health check service
COPY health-check.service /usr/lib/systemd/system/
COPY health-check.timer /usr/lib/systemd/system/
COPY health-check.sh /usr/local/bin/
```

Health check script example:
```bash
#!/bin/bash
# /usr/local/bin/health-check.sh

set -euo pipefail

# Check system health
check_system_health() {
    # Check disk space
    df -h | awk 'NR>1 {if ($5+0 > 80) exit 1}'
    
    # Check memory usage
    free | awk 'NR==2{if ($3/$2 > 0.9) exit 1}'
    
    # Check critical services
    systemctl is-active --quiet sshd || exit 1
    systemctl is-active --quiet systemd-resolved || exit 1
    
    echo "System health check passed"
}

check_system_health
```

### Log Management

Set up log rotation and management:

```dockerfile
# Configure logrotate
COPY logrotate.conf /etc/logrotate.d/bootc

# Create log cleanup service
COPY log-cleanup.service /usr/lib/systemd/system/
COPY log-cleanup.timer /usr/lib/systemd/system/
COPY cleanup-logs.sh /usr/local/bin/
```

## Configuration Management

### Dynamic Configuration Updates

Create a service for configuration updates:

```dockerfile
# Create config management service
COPY config-manager.service /usr/lib/systemd/system/
COPY config-manager.sh /usr/local/bin/
COPY config-templates/ /etc/config-templates/
```

### Configuration Template Example

```bash
#!/bin/bash
# /usr/local/bin/config-manager.sh

set -euo pipefail

# Update configuration from templates
update_config() {
    local template="$1"
    local target="$2"
    
    # Process template with environment variables
    envsubst < "$template" > "$target"
    
    # Reload service if needed
    if systemctl is-active --quiet "$3"; then
        systemctl reload "$3"
    fi
}

# Update configurations
update_config /etc/config-templates/nginx.conf /etc/nginx/nginx.conf nginx
update_config /etc/config-templates/sshd.conf /etc/ssh/sshd_config sshd
```

## Debian-Specific Considerations

### Debian Service Management

Debian uses systemd for service management:

- **Service files**: `/usr/lib/systemd/system/`
- **User services**: `~/.config/systemd/user/`
- **Service enablement**: `systemctl enable`
- **Service status**: `systemctl status`

### Example Debian Management Services

```dockerfile
FROM debian:bookworm-slim

# Install management tools
RUN apt update && \
    apt install -y curl jq logrotate cron && \
    apt clean && \
    rm -rf /var/lib/apt/lists/*

# Create management services
COPY management-services/ /usr/lib/systemd/system/
COPY management-scripts/ /usr/local/bin/

# Set up permissions
RUN chmod +x /usr/local/bin/*.sh

# Enable services
RUN systemctl enable bootc-update.timer health-check.timer log-cleanup.timer
```

### Debian Package Integration

Integrate with Debian package management:

```bash
#!/bin/bash
# Update Debian packages alongside bootc

# Update package lists
apt update

# Check for security updates
apt list --upgradable | grep -i security

# Install security updates
apt upgrade -y

# Clean up
apt autoremove -y
apt autoclean
```

### Debian Monitoring Tools

Use Debian's monitoring tools:

- **htop**: Process monitoring
- **iotop**: I/O monitoring
- **nethogs**: Network monitoring
- **sysstat**: System statistics

## Best Practices

### Service Design

1. **Idempotent operations**: Services should be safe to run multiple times
2. **Error handling**: Proper error handling and logging
3. **Resource limits**: Set appropriate resource limits
4. **Dependencies**: Define proper service dependencies

### Security Considerations

1. **Least privilege**: Run services with minimal required privileges
2. **Secure communication**: Use TLS for network communication
3. **Access control**: Restrict access to management interfaces
4. **Audit logging**: Log all management operations

### Operational Guidelines

1. **Monitoring**: Monitor service health and performance
2. **Alerting**: Set up alerts for critical failures
3. **Documentation**: Document all management services
4. **Testing**: Test management services in non-production environments

---

The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage.