# bootc composefs-finalize-staged - Examples and Troubleshooting

## Overview

This document provides practical examples and troubleshooting guidance for the `bootc composefs-finalize-staged` system, covering common use cases, error scenarios, and debugging techniques.

## Common Use Cases

### 1. Systemd Service Management

#### Enable and Start Service

```bash
#!/bin/bash
# Enable and start composefs-finalize-staged service

echo "=== Composefs Finalize Staged Service Management ==="
echo "Date: $(date)"
echo

# Enable service for automatic start
echo "Enabling service..."
systemctl enable composefs-finalize-staged.service

# Start service
echo "Starting service..."
systemctl start composefs-finalize-staged.service

# Check service status
echo "Service status:"
systemctl status composefs-finalize-staged.service
```

#### Service Monitoring

```bash
#!/bin/bash
# Monitor composefs-finalize-staged service

echo "=== Service Monitoring ==="
echo "Date: $(date)"
echo

# Check service status
echo "Service status:"
systemctl is-active composefs-finalize-staged.service

# Check service logs
echo "Recent logs:"
journalctl -u composefs-finalize-staged.service -n 50

# Check service configuration
echo "Service configuration:"
systemctl show composefs-finalize-staged.service
```

### 2. Staged Deployment Management

#### Check Staged Deployment

```bash
#!/bin/bash
# Check for staged composefs deployment

echo "=== Staged Deployment Check ==="
echo "Date: $(date)"
echo

# Check if staged deployment exists
if [ -f "/var/lib/composefs-transient-state/staged-deployment" ]; then
    echo "Staged deployment found:"
    cat /var/lib/composefs-transient-state/staged-deployment
else
    echo "No staged deployment found"
fi

# Check composefs state directory
echo "Composefs state directory:"
ls -la /sysroot/composefs/

# Check staged deployment files
echo "Staged deployment files:"
find /sysroot/composefs/ -name "*.staged" -type f
```

#### Create Staged Deployment

```bash
#!/bin/bash
# Create staged composefs deployment

echo "=== Create Staged Deployment ==="
echo "Date: $(date)"
echo

# Create composefs state directory
mkdir -p /sysroot/composefs

# Create staged deployment marker
echo "staged-deployment-id" > /var/lib/composefs-transient-state/staged-deployment

# Create staged deployment directory
mkdir -p /sysroot/composefs/staged-deployment-id

# Create origin file
cat > /sysroot/composefs/staged-deployment-id/staged-deployment-id.origin << EOF
[origin]
container=ostree-unverified-image:quay.io/myorg/composefs:latest

[boot]
type=uki
digest=sha256:abcd1234...
EOF

echo "Staged deployment created"
```

### 3. EROFS Image Operations

#### Mount EROFS Image

```bash
#!/bin/bash
# Mount EROFS image for testing

echo "=== EROFS Image Operations ==="
echo "Date: $(date)"
echo

# Create mount point
mkdir -p /mnt/erofs

# Mount EROFS image
echo "Mounting EROFS image..."
mount -t erofs /path/to/image.erofs /mnt/erofs

# Check mount
echo "Mount status:"
mount | grep erofs

# List contents
echo "EROFS contents:"
ls -la /mnt/erofs/

# Unmount
echo "Unmounting EROFS image..."
umount /mnt/erofs
```

#### Create EROFS Image

```bash
#!/bin/bash
# Create EROFS image for testing

echo "=== Create EROFS Image ==="
echo "Date: $(date)"
echo

# Create source directory
mkdir -p /tmp/erofs-source/etc
mkdir -p /tmp/erofs-source/usr
mkdir -p /tmp/erofs-source/var

# Add some test files
echo "test config" > /tmp/erofs-source/etc/test.conf
echo "test binary" > /tmp/erofs-source/usr/bin/test

# Create EROFS image
echo "Creating EROFS image..."
mkfs.erofs -z lz4 /tmp/test-image.erofs /tmp/erofs-source

# Verify image
echo "Verifying EROFS image..."
file /tmp/test-image.erofs

# Clean up
rm -rf /tmp/erofs-source
```

### 4. Bootloader Operations

#### GRUB Configuration

```bash
#!/bin/bash
# GRUB configuration for composefs

echo "=== GRUB Configuration ==="
echo "Date: $(date)"
echo

# Check GRUB configuration
echo "Current GRUB configuration:"
cat /boot/grub/grub.cfg | grep -i composefs

# Update GRUB configuration
echo "Updating GRUB configuration..."
grub-mkconfig -o /boot/grub/grub.cfg

# Check GRUB entries
echo "GRUB entries:"
ls -la /boot/grub/loader/entries/

# Check for staged entries
echo "Staged GRUB entries:"
find /boot/grub/ -name "*.staged" -type f
```

#### systemd-boot Configuration

```bash
#!/bin/bash
# systemd-boot configuration for composefs

echo "=== systemd-boot Configuration ==="
echo "Date: $(date)"
echo

# Check systemd-boot entries
echo "systemd-boot entries:"
bootctl list

# Check ESP partition
echo "ESP partition:"
ls -la /boot/efi/EFI/

# Check for staged entries
echo "Staged systemd-boot entries:"
find /boot/efi/ -name "*.staged" -type f

# Update boot entries
echo "Updating boot entries..."
bootctl update
```

### 5. /etc Configuration Management

#### Check /etc Configuration

```bash
#!/bin/bash
# Check /etc configuration state

echo "=== /etc Configuration Check ==="
echo "Date: $(date)"
echo

# Check current /etc
echo "Current /etc contents:"
ls -la /etc/

# Check composefs state
echo "Composefs state:"
ls -la /sysroot/composefs/

# Check staged /etc
echo "Staged /etc contents:"
find /sysroot/composefs/ -name "etc" -type d -exec ls -la {} \;

# Check for merge conflicts
echo "Checking for merge conflicts..."
find /etc/ -name "*.orig" -o -name "*.bak" -o -name "*.conflict"
```

#### Manual /etc Merge

```bash
#!/bin/bash
# Manual /etc merge for testing

echo "=== Manual /etc Merge ==="
echo "Date: $(date)"
echo

# Create test directories
mkdir -p /tmp/pristine-etc
mkdir -p /tmp/current-etc
mkdir -p /tmp/new-etc

# Create test files
echo "pristine config" > /tmp/pristine-etc/test.conf
echo "current config" > /tmp/current-etc/test.conf
echo "new config" > /tmp/new-etc/test.conf

# Perform manual merge
echo "Performing manual merge..."
cp /tmp/pristine-etc/test.conf /tmp/merged-etc/test.conf

# Apply current changes
echo "Applying current changes..."
# This would be done by the etc-merge library in practice

# Apply new changes
echo "Applying new changes..."
# This would be done by the etc-merge library in practice

# Clean up
rm -rf /tmp/pristine-etc /tmp/current-etc /tmp/new-etc /tmp/merged-etc
```

## Troubleshooting Guide

### 1. Common Error Scenarios

#### No Staged Deployment Error

**Error**: `No staged deployment found`

**Cause**: No staged deployment exists to finalize

**Solution**:
```bash
# Check for staged deployment
ls -la /var/lib/composefs-transient-state/

# Create staged deployment if needed
echo "deployment-id" > /var/lib/composefs-transient-state/staged-deployment

# Check composefs state
ls -la /sysroot/composefs/
```

**Prevention**:
```bash
# Ensure staged deployment exists before finalization
if [ ! -f "/var/lib/composefs-transient-state/staged-deployment" ]; then
    echo "Error: No staged deployment found"
    exit 1
fi
```

#### Non-Composefs Deployment Error

**Error**: `Staged deployment is not a composefs deployment`

**Cause**: Staged deployment is not a composefs deployment

**Solution**:
```bash
# Check deployment type
cat /sysroot/composefs/*/deployment-id.origin

# Verify composefs configuration
grep -i composefs /sysroot/composefs/*/deployment-id.origin
```

**Prevention**:
```bash
# Verify composefs deployment before staging
if ! grep -q "composefs" /path/to/deployment.origin; then
    echo "Error: Not a composefs deployment"
    exit 1
fi
```

#### EROFS Mount Error

**Error**: `Failed to mount EROFS image`

**Cause**: EROFS image cannot be mounted

**Solution**:
```bash
# Check EROFS image
file /path/to/image.erofs

# Check mount point
ls -la /sysroot/

# Check permissions
ls -la /sysroot/composefs/

# Try manual mount
mount -t erofs /path/to/image.erofs /mnt/test
```

**Prevention**:
```bash
# Verify EROFS image before use
if ! file /path/to/image.erofs | grep -q "EROFS"; then
    echo "Error: Invalid EROFS image"
    exit 1
fi
```

#### ESP Mount Error

**Error**: `Failed to mount ESP partition`

**Cause**: ESP partition cannot be mounted

**Solution**:
```bash
# Check ESP partition
lsblk | grep -i efi

# Check mount point
ls -la /boot/efi/

# Try manual mount
mount /dev/sda1 /mnt/esp
```

**Prevention**:
```bash
# Verify ESP partition before use
if ! lsblk | grep -q "EFI"; then
    echo "Error: No ESP partition found"
    exit 1
fi
```

### 2. Debugging Techniques

#### Enable Debug Logging

```bash
# Set debug log level
export RUST_LOG=debug

# Run command with debug output
bootc composefs-finalize-staged

# Check debug logs
journalctl -u composefs-finalize-staged.service --since "1 hour ago" | grep DEBUG
```

#### Verbose Output

```bash
# Enable verbose output
bootc composefs-finalize-staged -v

# Check verbose logs
journalctl -u composefs-finalize-staged.service --since "1 hour ago" | grep -v INFO
```

#### System Information

```bash
# Gather system information
uname -a
lsb_release -a
systemctl --version
bootc --version

# Check system configuration
cat /etc/os-release
cat /proc/version
cat /proc/cpuinfo | head -20
```

#### Composefs Diagnostics

```bash
# Check composefs state
ls -la /sysroot/composefs/
cat /var/lib/composefs-transient-state/staged-deployment

# Check kernel cmdline
cat /proc/cmdline | grep -i composefs

# Check mounted filesystems
mount | grep -i composefs
```

### 3. Recovery Procedures

#### Service Recovery

```bash
#!/bin/bash
# Service recovery script

echo "=== Service Recovery ==="
echo "Date: $(date)"
echo

# Stop service
echo "Stopping service..."
systemctl stop composefs-finalize-staged.service

# Reset service state
echo "Resetting service state..."
systemctl reset-failed composefs-finalize-staged.service

# Reload systemd
echo "Reloading systemd..."
systemctl daemon-reload

# Start service
echo "Starting service..."
systemctl start composefs-finalize-staged.service

# Check status
echo "Service status:"
systemctl status composefs-finalize-staged.service
```

#### Deployment Recovery

```bash
#!/bin/bash
# Deployment recovery script

echo "=== Deployment Recovery ==="
echo "Date: $(date)"
echo

# Check staged deployment
echo "Checking staged deployment..."
if [ -f "/var/lib/composefs-transient-state/staged-deployment" ]; then
    echo "Staged deployment found"
    cat /var/lib/composefs-transient-state/staged-deployment
else
    echo "No staged deployment found"
fi

# Check composefs state
echo "Checking composefs state..."
ls -la /sysroot/composefs/

# Clean up if needed
echo "Cleaning up if needed..."
rm -f /var/lib/composefs-transient-state/staged-deployment

echo "Deployment recovery complete"
```

### 4. Performance Analysis

#### Execution Performance

```bash
#!/bin/bash
# Execution performance analysis

echo "=== Execution Performance Analysis ==="
echo "Date: $(date)"
echo

# Time service execution
echo "Timing service execution..."
time systemctl start composefs-finalize-staged.service

# Check resource usage
echo "Resource usage:"
ps aux | grep composefs-finalize-staged | awk '{sum+=$6} END {print sum/1024 " MB"}'

# Check system load
echo "System load:"
uptime
```

#### Filesystem Performance

```bash
#!/bin/bash
# Filesystem performance analysis

echo "=== Filesystem Performance Analysis ==="
echo "Date: $(date)"
echo

# Check disk usage
echo "Disk usage:"
df -h /sysroot

# Check I/O usage
echo "I/O usage:"
iotop -bn1 | head -20

# Check mount performance
echo "Mount performance:"
time mount -t erofs /path/to/image.erofs /mnt/test
time umount /mnt/test
```

### 5. Monitoring and Alerting

#### Health Check Script

```bash
#!/bin/bash
# Health check script

HEALTH_STATUS=0

echo "=== Composefs Finalize Staged Health Check ==="
echo "Date: $(date)"
echo

# Check service status
echo "Checking service status..."
if ! systemctl is-active composefs-finalize-staged.service > /dev/null 2>&1; then
    echo "ERROR: Service not active"
    HEALTH_STATUS=1
fi

# Check staged deployment
echo "Checking staged deployment..."
if [ ! -f "/var/lib/composefs-transient-state/staged-deployment" ]; then
    echo "WARNING: No staged deployment found"
fi

# Check composefs state
echo "Checking composefs state..."
if [ ! -d "/sysroot/composefs" ]; then
    echo "ERROR: Composefs state directory not found"
    HEALTH_STATUS=1
fi

# Check EROFS support
echo "Checking EROFS support..."
if ! modprobe erofs > /dev/null 2>&1; then
    echo "ERROR: EROFS module not available"
    HEALTH_STATUS=1
fi

# Report health status
if [ $HEALTH_STATUS -eq 0 ]; then
    echo "Health check passed"
else
    echo "Health check failed"
fi

exit $HEALTH_STATUS
```

#### Alerting Script

```bash
#!/bin/bash
# Alerting script

# Send alert to monitoring system
send_alert() {
    local severity=$1
    local message=$2
    
    curl -X POST "https://monitoring.example.com/alerts" \
        -H "Content-Type: application/json" \
        -d "{
            \"service\": \"composefs-finalize-staged\",
            \"severity\": \"$severity\",
            \"message\": \"$message\",
            \"timestamp\": \"$(date -Iseconds)\"
        }"
}

# Check service health
if ! /usr/local/bin/composefs-finalize-staged-health-check.sh; then
    send_alert "critical" "Composefs finalize staged service health check failed"
fi

# Check service status
if ! systemctl is-active composefs-finalize-staged.service > /dev/null 2>&1; then
    send_alert "critical" "Composefs finalize staged service not active"
fi

# Check staged deployment
if [ ! -f "/var/lib/composefs-transient-state/staged-deployment" ]; then
    send_alert "warning" "No staged deployment found"
fi
```

## Best Practices

### 1. Usage Guidelines

- **Systemd Integration**: Use systemd service for execution
- **Early Boot**: Execute early in boot process
- **Error Handling**: Implement proper error handling
- **Logging**: Use appropriate logging levels

### 2. Security Considerations

- **Privilege Requirements**: Ensure appropriate privileges
- **Sandboxing**: Use systemd sandboxing features
- **Access Control**: Limit filesystem access
- **Error Recovery**: Implement proper error recovery

### 3. Performance Optimization

- **Efficient Operations**: Use efficient filesystem operations
- **Resource Management**: Manage resources appropriately
- **Timeout Handling**: Handle timeouts gracefully
- **Error Recovery**: Implement proper error recovery

This comprehensive examples and troubleshooting guide provides practical solutions for common issues and advanced debugging techniques for the bootc composefs-finalize-staged system.