bootc-docs/composefs-finalize-staged/bootc-composefs-finalize-staged-examples-troubleshooting.md

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

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

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

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

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

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

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

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

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

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

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

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

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

# Check deployment type
cat /sysroot/composefs/*/deployment-id.origin

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

Prevention:

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

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

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

# Check ESP partition
lsblk | grep -i efi

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

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

Prevention:

# 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

# 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

# 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

# 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

# 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

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

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

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

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

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

#!/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.