# ⚙️ **apt-ostree Configuration Reference**

## 🎯 **Overview**

This document provides a complete reference for all apt-ostree configuration options, including configuration files, environment variables, command-line options, and best practices. The configuration system enables flexible deployment and customization of apt-ostree behavior.

## 📁 **Configuration File Locations**

### **System Configuration**
```bash
# Main configuration file
/etc/apt-ostree/config.toml

# Environment-specific configurations
/etc/apt-ostree/config.dev.toml      # Development environment
/etc/apt-ostree/config.prod.toml     # Production environment
/etc/apt-ostree/config.test.toml     # Testing environment

# User-specific configuration
~/.config/apt-ostree/config.toml

# Package-specific configuration
/usr/share/apt-ostree/config/default.toml
```

### **Configuration Priority Order**
1. **Command-line options** (highest priority)
2. **Environment variables**
3. **User configuration** (`~/.config/apt-ostree/config.toml`)
4. **Environment-specific configuration** (`/etc/apt-ostree/config.{env}.toml`)
5. **Main system configuration** (`/etc/apt-ostree/config.toml`)
6. **Package default configuration** (lowest priority)

## 🔧 **Main Configuration File**

### **Complete Configuration Example**
```toml
# /etc/apt-ostree/config.toml
# apt-ostree Configuration File
# Version: 1.0

[system]
# System-wide settings
ostree_path = "/ostree"
sysroot_path = "/"
default_os = "debian"
hostname = "apt-ostree-system"
timezone = "UTC"

# OSTree repository configuration
[ostree]
# Repository mode: bare-user, bare, archive
repo_mode = "bare-user"

# Compression algorithm: gzip, lz4, zstd, none
compression = "gzip"

# Compression level (1-9 for gzip, 1-22 for zstd)
compression_level = 6

# Maximum number of commits to keep
max_commits = 100

# Commit timeout in seconds
commit_timeout = 300

# Enable commit signing
sign_commits = false
gpg_key = ""

# Repository maintenance
auto_cleanup = true
cleanup_interval = 86400  # 24 hours
cleanup_older_than = 604800  # 7 days

# Daemon configuration
[daemon]
# Network binding
host = "127.0.0.1"
port = 8080
unix_socket = "/var/run/aptostreed.sock"

# Connection limits
max_connections = 100
max_concurrent_operations = 10
connection_timeout = 30
idle_timeout = 300

# Performance settings
worker_threads = 4
max_memory_usage = "2GB"
enable_caching = true
cache_size = "1GB"

# Logging configuration
log_level = "info"
log_file = "/var/log/apt-ostree/aptostreed.log"
log_format = "json"
log_max_size = "100MB"
log_max_files = 5
log_rotation = "daily"

# Console output
console_output = true
color_output = true
progress_bars = true
verbose_output = false

# Security settings
[security]
# Enable Polkit integration
polkit_enabled = true

# Require authorization for operations
require_authorization = true

# Allowed users and groups
allowed_users = ["root", "admin"]
allowed_groups = ["sudo", "wheel"]

# Session management
session_timeout = 3600
max_sessions_per_user = 5

# File permissions
umask = "022"
file_owner = "aptostree"
file_group = "aptostree"

# Package management settings
[packages]
# Automatic updates
auto_update = false
update_interval = 86400  # 24 hours
update_check_timeout = 300

# Package installation options
install_recommends = true
install_suggests = false
allow_downgrade = false
allow_remove_essential = false
allow_unauthenticated = false

# Package cache configuration
cache_dir = "/var/cache/apt-ostree"
max_cache_size = "10GB"
cache_cleanup_interval = 3600  # 1 hour
cache_ttl = 86400  # 24 hours

# Package sources
sources_list = "/etc/apt/sources.list"
sources_list_d = "/etc/apt/sources.list.d"
preferences_file = "/etc/apt/preferences"

# Package override settings
allow_package_overrides = true
max_override_size = "100MB"
override_validation = true

# User overlay settings
[usroverlay]
# Enable user overlays
enabled = true

# Overlay storage location
storage_dir = "/var/lib/apt-ostree/overlays"
max_overlay_size = "50MB"
max_overlays_per_user = 10

# Overlay options
allow_system_paths = false
allow_executable_files = true
allow_symlinks = true
read_only_by_default = false

# Live update settings
[live_update]
# Enable live updates
enabled = true

# Live update timeout
timeout = 300

# Maximum file size for live updates
max_file_size = "10MB"

# Allowed paths for live updates
allowed_paths = ["/usr/local", "/opt", "/var/local"]

# Boot management settings
[boot]
# Initramfs management
auto_regenerate_initramfs = false
initramfs_regeneration_interval = 0

# Kernel argument management
allow_kernel_arg_modification = true
protected_kernel_args = ["root", "ro", "rw"]

# Bootloader configuration
bootloader = "systemd-boot"
bootloader_config_dir = "/boot/loader"
bootloader_update_after_changes = true

# Transaction management
[transactions]
# Transaction timeout
default_timeout = 1800  # 30 minutes
max_timeout = 7200      # 2 hours

# Transaction persistence
persist_transactions = true
transaction_log_dir = "/var/log/apt-ostree/transactions"
max_transaction_logs = 100

# Rollback settings
enable_rollback = true
max_rollback_depth = 3
auto_rollback_on_failure = false

# Monitoring and metrics
[monitoring]
# Enable monitoring
enabled = true

# Metrics collection
metrics_enabled = true
metrics_port = 9090
metrics_path = "/metrics"

# Health checks
health_check_enabled = true
health_check_interval = 60
health_check_timeout = 30

# Performance monitoring
performance_monitoring = true
collect_system_metrics = true
collect_application_metrics = true

# Alerting
alerts_enabled = true
alert_webhook_url = ""
alert_email = ""

# Network configuration
[network]
# Proxy settings
http_proxy = ""
https_proxy = ""
no_proxy = "localhost,127.0.0.1"

# Network timeouts
connect_timeout = 30
read_timeout = 300
write_timeout = 300

# Retry settings
max_retries = 3
retry_delay = 5
backoff_multiplier = 2.0

# TLS/SSL settings
verify_ssl = true
ca_cert_file = "/etc/ssl/certs/ca-certificates.crt"
client_cert_file = ""
client_key_file = ""

# Database configuration
[database]
# Package database
package_db_path = "/var/lib/apt-ostree/db"
package_db_backup_enabled = true
package_db_backup_interval = 86400

# Transaction database
transaction_db_path = "/var/lib/apt-ostree/transactions"
transaction_db_backup_enabled = true

# Cache database
cache_db_path = "/var/cache/apt-ostree/db"
cache_db_cleanup_interval = 3600

# Backup and recovery
[backup]
# Enable automatic backups
enabled = true

# Backup schedule
schedule = "daily"
backup_time = "02:00"

# Backup retention
retention_days = 30
retention_weeks = 4
retention_months = 12

# Backup locations
local_backup_dir = "/var/backups/apt-ostree"
remote_backup_enabled = false
remote_backup_url = ""
remote_backup_credentials = ""

# Testing and development
[development]
# Development mode
dev_mode = false

# Debug settings
debug_enabled = false
debug_level = "info"
debug_file = "/tmp/apt-ostree-debug.log"

# Testing settings
test_mode = false
mock_services = false
test_data_dir = "/tmp/apt-ostree-test"

# Performance testing
performance_testing = false
benchmark_mode = false
```

## 🌍 **Environment Variables**

### **System Environment Variables**
```bash
# Configuration file location
export APT_OSTREE_CONFIG_FILE="/path/to/config.toml"

# Logging configuration
export APT_OSTREE_LOG_LEVEL="debug"
export APT_OSTREE_LOG_FILE="/path/to/log.log"
export APT_OSTREE_LOG_FORMAT="json"

# Network configuration
export APT_OSTREE_HOST="0.0.0.0"
export APT_OSTREE_PORT="8080"
export APT_OSTREE_HTTP_PROXY="http://proxy:8080"
export APT_OSTREE_HTTPS_PROXY="https://proxy:8080"

# Security configuration
export APT_OSTREE_POLKIT_ENABLED="true"
export APT_OSTREE_REQUIRE_AUTH="true"
export APT_OSTREE_ALLOWED_USERS="root,admin"

# Package management
export APT_OSTREE_AUTO_UPDATE="false"
export APT_OSTREE_CACHE_DIR="/path/to/cache"
export APT_OSTREE_MAX_CACHE_SIZE="5GB"

# OSTree configuration
export APT_OSTREE_OSTREE_PATH="/ostree"
export APT_OSTREE_REPO_MODE="bare-user"
export APT_OSTREE_COMPRESSION="gzip"

# Development and testing
export APT_OSTREE_DEV_MODE="true"
export APT_OSTREE_DEBUG_ENABLED="true"
export APT_OSTREE_TEST_MODE="true"
```

### **Runtime Environment Variables**
```bash
# User context
export APT_OSTREE_USER_ID="1000"
export APT_OSTREE_SESSION_ID="session-123"

# Operation context
export APT_OSTREE_OPERATION_TIMEOUT="1800"
export APT_OSTREE_DRY_RUN="false"
export APT_OSTREE_FORCE="false"

# Output formatting
export APT_OSTREE_OUTPUT_FORMAT="human"
export APT_OSTREE_COLOR_OUTPUT="true"
export APT_OSTREE_VERBOSE="false"
export APT_OSTREE_QUIET="false"
```

## 🚀 **Command-Line Options**

### **Global Options**
```bash
# Configuration options
--config, -c <FILE>           # Configuration file path
--config-dir <DIR>            # Configuration directory
--config-format <FORMAT>      # Configuration format (toml, json, yaml)

# Logging options
--log-level <LEVEL>           # Log level (error, warn, info, debug, trace)
--log-file <FILE>             # Log file path
--log-format <FORMAT>         # Log format (json, text, syslog)
--quiet, -q                   # Suppress output
--verbose, -v                 # Verbose output
--debug                       # Enable debug mode

# Network options
--host <HOST>                 # Bind host
--port <PORT>                 # Bind port
--unix-socket <SOCKET>        # Unix socket path
--timeout <SECONDS>           # Operation timeout

# Security options
--polkit-enabled              # Enable Polkit integration
--require-authorization       # Require authorization
--allowed-users <USERS>       # Comma-separated list of allowed users
--allowed-groups <GROUPS>     # Comma-separated list of allowed groups

# Package management options
--auto-update                 # Enable automatic updates
--install-recommends          # Install recommended packages
--install-suggests            # Install suggested packages
--allow-downgrade             # Allow package downgrades
--allow-remove-essential      # Allow removal of essential packages
--allow-unauthenticated       # Allow unauthenticated packages

# OSTree options
--ostree-path <PATH>          # OSTree repository path
--repo-mode <MODE>            # Repository mode
--compression <ALG>           # Compression algorithm
--max-commits <NUMBER>        # Maximum commits to keep

# Development options
--dev-mode                    # Enable development mode
--test-mode                   # Enable testing mode
--mock-services               # Use mock services
--performance-testing         # Enable performance testing
```

### **Command-Specific Options**
```bash
# Status command
apt-ostree status [OPTIONS]
  --os <OSNAME>               # Operating system name
  --json, -j                  # JSON output format
  --verbose, -v               # Verbose output

# Install command
apt-ostree install <PACKAGES> [OPTIONS]
  --version <VERSION>         # Package version
  --reboot, -r                # Reboot after installation
  --yes, -y                   # Answer yes to prompts
  --dry-run                   # Preview changes without applying

# Upgrade command
apt-ostree upgrade [OPTIONS]
  --reboot, -r                # Reboot after upgrade
  --preview                   # Preview changes without applying
  --yes, -y                   # Answer yes to prompts

# Override command
apt-ostree override <SUBCOMMAND> [OPTIONS]
  --reboot, -r                # Reboot after override
  --lock-finalization          # Lock finalization

# User overlay command
apt-ostree usroverlay <SUBCOMMAND> [OPTIONS]
  --read-only                 # Make overlay read-only
  --allow-other               # Allow other users to access
  --default-permissions       # Use default permissions
```

## 🔒 **Security Configuration**

### **Polkit Policy Configuration**
```xml
<!-- /usr/share/polkit-1/actions/org.projectatomic.aptostree.policy -->
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE policyconfig PUBLIC
 "-//freedesktop//DTD PolicyKit Policy Configuration 1.0//EN"
 "http://www.freedesktop.org/standards/PolicyKit/1/policyconfig.dtd">
<policyconfig>
  <vendor>Project Atomic</vendor>
  <vendor_url>https://github.com/projectatomic/apt-ostree</vendor_url>
  
  <!-- Read-only operations -->
  <action id="org.projectatomic.aptostree.status">
    <description>Get system status</description>
    <message>Authentication is required to get system status</message>
    <defaults>
      <allow_any>yes</allow_any>
      <allow_inactive>yes</allow_inactive>
      <allow_active>yes</allow_active>
    </defaults>
  </action>
  
  <action id="org.projectatomic.aptostree.deployments">
    <description>List deployments</description>
    <message>Authentication is required to list deployments</message>
    <defaults>
      <allow_any>yes</allow_any>
      <allow_inactive>yes</allow_inactive>
      <allow_active>yes</allow_active>
    </defaults>
  </action>
  
  <!-- Package management operations -->
  <action id="org.projectatomic.aptostree.install">
    <description>Install packages</description>
    <message>Authentication is required to install packages</message>
    <defaults>
      <allow_any>auth_admin</allow_any>
      <allow_inactive>auth_admin</allow_inactive>
      <allow_active>auth_admin</allow_active>
    </defaults>
  </action>
  
  <action id="org.projectatomic.aptostree.uninstall">
    <description>Remove packages</description>
    <message>Authentication is required to remove packages</message>
    <defaults>
      <allow_any>auth_admin</allow_any>
      <allow_inactive>auth_admin</allow_inactive>
      <allow_active>auth_admin</allow_active>
    </defaults>
  </action>
  
  <!-- System operations -->
  <action id="org.projectatomic.aptostree.upgrade">
    <description>Upgrade system</description>
    <message>Authentication is required to upgrade the system</message>
    <defaults>
      <allow_any>auth_admin</allow_any>
      <allow_inactive>auth_admin</allow_inactive>
      <allow_active>auth_admin</allow_active>
    </defaults>
  </action>
  
  <action id="org.projectatomic.aptostree.override">
    <description>Override packages</description>
    <message>Authentication is required to override packages</message>
    <defaults>
      <allow_any>auth_admin</allow_any>
      <allow_inactive>auth_admin</allow_inactive>
      <allow_active>auth_admin</allow_active>
    </defaults>
  </action>
  
  <!-- Advanced operations -->
  <action id="org.projectatomic.aptostree.usroverlay">
    <description>Manage user overlays</description>
    <message>Authentication is required to manage user overlays</message>
    <defaults>
      <allow_any>auth_admin</allow_any>
      <allow_inactive>auth_admin</allow_inactive>
      <allow_active>auth_admin</allow_active>
    </defaults>
  </action>
  
  <action id="org.projectatomic.aptostree.live-update">
    <description>Apply live updates</description>
    <message>Authentication is required to apply live updates</message>
    <defaults>
      <allow_any>auth_admin</allow_any>
      <allow_inactive>auth_admin</allow_inactive>
      <allow_active>auth_admin</allow_active>
    </defaults>
  </action>
  
  <action id="org.projectatomic.aptostree.boot-management">
    <description>Manage boot configuration</description>
    <message>Authentication is required to manage boot configuration</message>
    <defaults>
      <allow_any>auth_admin</allow_any>
      <allow_inactive>auth_admin</allow_inactive>
      <allow_active>auth_admin</allow_active>
    </defaults>
  </action>
</policyconfig>
```

### **Polkit Rules Configuration**
```javascript
// /etc/polkit-1/rules.d/50-apt-ostree.rules
polkit.addRule(function(action, subject) {
    // Allow read-only operations for all users
    if (action.id == "org.projectatomic.aptostree.status" ||
        action.id == "org.projectatomic.aptostree.deployments") {
        return polkit.Result.YES;
    }
    
    // Allow package operations for sudo/wheel group members
    if (action.id == "org.projectatomic.aptostree.install" ||
        action.id == "org.projectatomic.aptostree.uninstall" ||
        action.id == "org.projectatomic.aptostree.upgrade") {
        if (subject.isInGroup("sudo") || subject.isInGroup("wheel")) {
            return polkit.Result.YES;
        }
    }
    
    // Allow advanced operations for specific users
    if (action.id == "org.projectatomic.aptostree.override" ||
        action.id == "org.projectatomic.aptostree.usroverlay" ||
        action.id == "org.projectatomic.aptostree.live-update" ||
        action.id == "org.projectatomic.aptostree.boot-management") {
        if (subject.user == "root" || 
            subject.isInGroup("sudo") || 
            subject.isInGroup("wheel")) {
            return polkit.Result.YES;
        }
    }
    
    // Deny all other operations
    return polkit.Result.NO;
});
```

## 🔧 **Configuration Validation**

### **Configuration Schema**
```toml
# Configuration validation rules
[validation]
# Required fields
required_fields = [
    "system.ostree_path",
    "system.sysroot_path",
    "daemon.host",
    "daemon.port"
]

# Field validation rules
field_rules = [
    "daemon.port:range(1,65535)",
    "daemon.max_connections:range(1,1000)",
    "ostree.compression_level:range(1,9)",
    "packages.max_cache_size:size_format"
]

# Environment-specific validation
environment_validation = {
    "production" = [
        "security.polkit_enabled:true",
        "security.require_authorization:true",
        "daemon.host:127.0.0.1"
    ],
    "development" = [
        "development.dev_mode:true",
        "daemon.host:0.0.0.0"
    ]
}
```

### **Configuration Validation Script**
```bash
#!/bin/bash
# apt-ostree-config-validate.sh

CONFIG_FILE="${1:-/etc/apt-ostree/config.toml}"
VALIDATION_SCRIPT="/usr/bin/apt-ostree-config-validate"

echo "Validating configuration file: $CONFIG_FILE"

# Check if configuration file exists
if [ ! -f "$CONFIG_FILE" ]; then
    echo "❌ Configuration file not found: $CONFIG_FILE"
    exit 1
fi

# Validate TOML syntax
if command -v toml-validate >/dev/null 2>&1; then
    echo "🔍 Validating TOML syntax..."
    if toml-validate "$CONFIG_FILE"; then
        echo "✅ TOML syntax is valid"
    else
        echo "❌ TOML syntax validation failed"
        exit 1
    fi
fi

# Validate configuration with apt-ostree
if [ -x "$VALIDATION_SCRIPT" ]; then
    echo "🔍 Validating configuration..."
    if "$VALIDATION_SCRIPT" "$CONFIG_FILE"; then
        echo "✅ Configuration validation passed"
    else
        echo "❌ Configuration validation failed"
        exit 1
    fi
else
    echo "⚠️  Configuration validation script not found, skipping validation"
fi

# Check file permissions
echo "🔍 Checking file permissions..."
if [ "$(stat -c %a "$CONFIG_FILE")" != "600" ]; then
    echo "⚠️  Warning: Configuration file should have 600 permissions"
fi

if [ "$(stat -c %U "$CONFIG_FILE")" != "root" ]; then
    echo "⚠️  Warning: Configuration file should be owned by root"
fi

echo "✅ Configuration validation completed"
```

## 📊 **Configuration Monitoring**

### **Configuration Change Detection**
```rust
use notify::{Watcher, RecursiveMode, watcher};
use std::sync::mpsc::channel;
use std::time::Duration;

pub struct ConfigurationMonitor {
    config_path: PathBuf,
    watcher: notify::FsEventWatcher,
}

impl ConfigurationMonitor {
    pub fn new(config_path: PathBuf) -> Result<Self, Box<dyn std::error::Error>> {
        let (tx, rx) = channel();
        let mut watcher = watcher(tx, Duration::from_secs(1))?;
        
        watcher.watch(&config_path, RecursiveMode::NonRecursive)?;
        
        Ok(Self {
            config_path,
            watcher,
        })
    }
    
    pub async fn monitor_changes(&mut self) -> Result<(), Box<dyn std::error::Error>> {
        loop {
            match rx.recv_timeout(Duration::from_secs(1)) {
                Ok(event) => {
                    match event {
                        notify::DebouncedEvent::Write(path) |
                        notify::DebouncedEvent::Create(path) |
                        notify::DebouncedEvent::Remove(path) => {
                            if path == self.config_path {
                                println!("Configuration file changed: {:?}", path);
                                self.reload_configuration().await?;
                            }
                        }
                        _ => {}
                    }
                }
                Err(std::sync::mpsc::RecvTimeoutError::Timeout) => {
                    // Continue monitoring
                }
                Err(e) => {
                    return Err(format!("Configuration monitoring error: {}", e).into());
                }
            }
        }
    }
    
    async fn reload_configuration(&self) -> Result<(), Box<dyn std::error::Error>> {
        // Reload configuration logic
        println!("Reloading configuration...");
        Ok(())
    }
}
```

### **Configuration Health Check**
```rust
pub struct ConfigurationHealthChecker {
    config: Configuration,
}

impl ConfigurationHealthChecker {
    pub fn new(config: Configuration) -> Self {
        Self { config }
    }
    
    pub fn check_health(&self) -> ConfigurationHealth {
        let mut health = ConfigurationHealth::new();
        
        // Check required fields
        if self.config.system.ostree_path.is_empty() {
            health.add_issue("system.ostree_path is required");
        }
        
        if self.config.system.sysroot_path.is_empty() {
            health.add_issue("system.sysroot_path is required");
        }
        
        // Check port range
        if self.config.daemon.port < 1 || self.config.daemon.port > 65535 {
            health.add_issue("daemon.port must be between 1 and 65535");
        }
        
        // Check security settings
        if self.config.security.polkit_enabled && !self.config.security.require_authorization {
            health.add_warning("Polkit enabled but authorization not required");
        }
        
        // Check file permissions
        if let Err(e) = self.check_config_file_permissions() {
            health.add_issue(&format!("Configuration file permission issue: {}", e));
        }
        
        health
    }
    
    fn check_config_file_permissions(&self) -> Result<(), Box<dyn std::error::Error>> {
        let metadata = std::fs::metadata(&self.config.config_file_path)?;
        let permissions = metadata.permissions();
        
        if permissions.mode() & 0o777 != 0o600 {
            return Err("Configuration file should have 600 permissions".into());
        }
        
        Ok(())
    }
}

#[derive(Debug)]
pub struct ConfigurationHealth {
    pub is_healthy: bool,
    pub issues: Vec<String>,
    pub warnings: Vec<String>,
}

impl ConfigurationHealth {
    pub fn new() -> Self {
        Self {
            is_healthy: true,
            issues: Vec::new(),
            warnings: Vec::new(),
        }
    }
    
    pub fn add_issue(&mut self, issue: &str) {
        self.issues.push(issue.to_string());
        self.is_healthy = false;
    }
    
    pub fn add_warning(&mut self, warning: &str) {
        self.warnings.push(warning.to_string());
    }
    
    pub fn summary(&self) -> String {
        if self.is_healthy {
            format!("Configuration is healthy ({} warnings)", self.warnings.len())
        } else {
            format!("Configuration has {} issues and {} warnings", 
                self.issues.len(), self.warnings.len())
        }
    }
}
```

## 🎯 **Configuration Best Practices**

### **Security Best Practices**
```toml
# Security-focused configuration
[security]
# Always enable Polkit in production
polkit_enabled = true
require_authorization = true

# Restrict network access
[daemon]
host = "127.0.0.1"  # Only local access
port = 8080

# Use dedicated user
file_owner = "aptostree"
file_group = "aptostree"
umask = "022"

# Enable logging and monitoring
[logging]
log_level = "info"
log_file = "/var/log/apt-ostree/aptostreed.log"
log_format = "json"

[monitoring]
enabled = true
health_check_enabled = true
alerts_enabled = true
```

### **Performance Best Practices**
```toml
# Performance-optimized configuration
[daemon]
# Optimize worker threads
worker_threads = 4

# Enable connection pooling
max_connections = 100
max_concurrent_operations = 10

# Memory management
max_memory_usage = "2GB"
enable_caching = true
cache_size = "1GB"

[ostree]
# Use efficient compression
compression = "zstd"
compression_level = 3

# Optimize repository settings
repo_mode = "bare-user"
max_commits = 50

[packages]
# Cache optimization
cache_ttl = 86400
cache_cleanup_interval = 3600
```

### **Development Best Practices**
```toml
# Development environment configuration
[development]
dev_mode = true
debug_enabled = true
debug_level = "debug"

[daemon]
# Allow external connections for development
host = "0.0.0.0"
log_level = "debug"

[logging]
# Development logging
log_level = "debug"
console_output = true
color_output = true

[packages]
# Development package settings
auto_update = true
update_interval = 3600
install_recommends = true
```

## 🔄 **Configuration Migration**

### **Version Migration Script**
```bash
#!/bin/bash
# apt-ostree-config-migrate.sh

CURRENT_VERSION="1.0"
TARGET_VERSION="1.1"
CONFIG_FILE="/etc/apt-ostree/config.toml"
BACKUP_FILE="/etc/apt-ostree/config.toml.backup.$(date +%Y%m%d)"

echo "Migrating apt-ostree configuration from v$CURRENT_VERSION to v$TARGET_VERSION"

# Create backup
echo "📋 Creating backup: $BACKUP_FILE"
cp "$CONFIG_FILE" "$BACKUP_FILE"

# Perform migration
echo "🔄 Performing configuration migration..."

# Add new fields with defaults
if ! grep -q "\[monitoring\]" "$CONFIG_FILE"; then
    echo "Adding monitoring section..."
    cat >> "$CONFIG_FILE" << 'EOF'

# Monitoring configuration
[monitoring]
enabled = true
metrics_enabled = true
metrics_port = 9090
health_check_enabled = true
health_check_interval = 60
EOF
fi

# Update existing fields
echo "Updating existing configuration fields..."
sed -i 's/compression = "gzip"/compression = "zstd"/' "$CONFIG_FILE"
sed -i 's/compression_level = 6/compression_level = 3/' "$CONFIG_FILE"

# Validate migrated configuration
echo "🔍 Validating migrated configuration..."
if apt-ostree-config-validate "$CONFIG_FILE"; then
    echo "✅ Configuration migration completed successfully"
    echo "📋 Backup saved to: $BACKUP_FILE"
else
    echo "❌ Configuration migration failed, restoring backup..."
    cp "$BACKUP_FILE" "$CONFIG_FILE"
    exit 1
fi
```

## 🎯 **Next Steps**

### **Immediate Actions**
1. **Review current configuration** and identify gaps
2. **Implement configuration validation** and monitoring
3. **Set up security policies** and Polkit integration
4. **Create environment-specific** configurations

### **Short-term Goals**
1. **Complete configuration schema** and validation
2. **Implement configuration monitoring** and change detection
3. **Add configuration migration** tools
4. **Establish configuration** best practices

### **Long-term Vision**
1. **Automated configuration** management and deployment
2. **Configuration compliance** and auditing
3. **Multi-environment** configuration orchestration
4. **Integration with** configuration management tools

---

*This configuration reference provides comprehensive coverage of all apt-ostree configuration options and best practices. For detailed implementation information, refer to the architecture documents in the `docs/apt-ostree-daemon-plan/architecture/` directory.*