Initial commit: Comprehensive Debian bootc documentation
- Complete documentation for all bootc commands and subcommands - Debian-specific adaptations and workarounds - Manual installation methods to bypass bootc reliability issues - Technical guides with Rust source code analysis - Flowcharts and external command references - Hidden command documentation (bootc internals, state, etc.) - Composefs integration analysis - Base image creation guides (with and without bootc binary) - Management scripts and automation - Comprehensive troubleshooting and examples
This commit is contained in:
robojerk
commit
526f1c1afd
67 changed files with 34174 additions and 0 deletions
|
|
@ -0,0 +1,691 @@
|
|||
# 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.
|
||||
|
|
@ -0,0 +1,940 @@
|
|||
# bootc composefs-finalize-staged - External Commands Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive reference for all external commands used by `bootc composefs-finalize-staged` operations. These commands are essential for understanding the dependencies and integration points of the composefs-finalize-staged system.
|
||||
|
||||
## Core Commands
|
||||
|
||||
### bootc
|
||||
|
||||
**Purpose**: Main bootc command for composefs-finalize-staged operations
|
||||
**Usage**: `bootc composefs-finalize-staged`
|
||||
**Dependencies**: None (core command)
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Execute composefs-finalize-staged command
|
||||
bootc composefs-finalize-staged
|
||||
|
||||
# Check if command is available
|
||||
bootc --help | grep composefs-finalize-staged
|
||||
```
|
||||
|
||||
## Systemd Commands
|
||||
|
||||
### systemctl
|
||||
|
||||
**Purpose**: Systemd service management
|
||||
**Usage**: `systemctl <subcommand> [options...]`
|
||||
**Dependencies**: systemd
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Start composefs-finalize-staged service
|
||||
systemctl start composefs-finalize-staged.service
|
||||
|
||||
# Enable service for automatic start
|
||||
systemctl enable composefs-finalize-staged.service
|
||||
|
||||
# Check service status
|
||||
systemctl status composefs-finalize-staged.service
|
||||
|
||||
# Stop service
|
||||
systemctl stop composefs-finalize-staged.service
|
||||
|
||||
# Restart service
|
||||
systemctl restart composefs-finalize-staged.service
|
||||
|
||||
# Reload systemd configuration
|
||||
systemctl daemon-reload
|
||||
```
|
||||
|
||||
### journalctl
|
||||
|
||||
**Purpose**: Systemd journal viewing
|
||||
**Usage**: `journalctl [options...]`
|
||||
**Dependencies**: systemd
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show logs for composefs-finalize-staged service
|
||||
journalctl -u composefs-finalize-staged.service
|
||||
|
||||
# Show recent logs
|
||||
journalctl -u composefs-finalize-staged.service -n 100
|
||||
|
||||
# Follow logs in real-time
|
||||
journalctl -u composefs-finalize-staged.service -f
|
||||
|
||||
# Show logs since specific time
|
||||
journalctl -u composefs-finalize-staged.service --since "1 hour ago"
|
||||
|
||||
# Show logs with priority
|
||||
journalctl -u composefs-finalize-staged.service -p err
|
||||
|
||||
# Show logs with timestamps
|
||||
journalctl -u composefs-finalize-staged.service -o short-precise
|
||||
```
|
||||
|
||||
## Filesystem Commands
|
||||
|
||||
### mount
|
||||
|
||||
**Purpose**: Mount filesystems
|
||||
**Usage**: `mount [options...] <device> <directory>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Mount EROFS image
|
||||
mount -t erofs /dev/loop0 /mnt/erofs
|
||||
|
||||
# Mount ESP partition
|
||||
mount /dev/sda1 /mnt/esp
|
||||
|
||||
# Mount with specific options
|
||||
mount -o ro,noexec /dev/loop0 /mnt/erofs
|
||||
|
||||
# Mount bind
|
||||
mount --bind /source /target
|
||||
|
||||
# Show mounted filesystems
|
||||
mount | grep composefs
|
||||
```
|
||||
|
||||
### umount
|
||||
|
||||
**Purpose**: Unmount filesystems
|
||||
**Usage**: `umount [options...] <directory>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Unmount filesystem
|
||||
umount /mnt/erofs
|
||||
|
||||
# Force unmount
|
||||
umount -f /mnt/erofs
|
||||
|
||||
# Lazy unmount
|
||||
umount -l /mnt/erofs
|
||||
|
||||
# Unmount all
|
||||
umount -a
|
||||
```
|
||||
|
||||
### losetup
|
||||
|
||||
**Purpose**: Loop device management
|
||||
**Usage**: `losetup [options...]`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# List loop devices
|
||||
losetup -a
|
||||
|
||||
# Create loop device
|
||||
losetup /dev/loop0 /path/to/image.erofs
|
||||
|
||||
# Delete loop device
|
||||
losetup -d /dev/loop0
|
||||
|
||||
# Show loop device info
|
||||
losetup -l /dev/loop0
|
||||
```
|
||||
|
||||
### fsync
|
||||
|
||||
**Purpose**: Synchronize filesystem
|
||||
**Usage**: `fsync [options...] <file>`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Sync filesystem
|
||||
fsync /path/to/file
|
||||
|
||||
# Sync directory
|
||||
fsync /path/to/directory
|
||||
|
||||
# Force sync
|
||||
fsync -f /path/to/file
|
||||
```
|
||||
|
||||
## EROFS Commands
|
||||
|
||||
### mkfs.erofs
|
||||
|
||||
**Purpose**: Create EROFS filesystem
|
||||
**Usage**: `mkfs.erofs [options...] <image> <directory>`
|
||||
**Dependencies**: erofs-utils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Create EROFS image
|
||||
mkfs.erofs -z lz4 /path/to/image.erofs /source/directory
|
||||
|
||||
# Create with compression
|
||||
mkfs.erofs -z lz4hc /path/to/image.erofs /source/directory
|
||||
|
||||
# Create with specific block size
|
||||
mkfs.erofs -b 4096 /path/to/image.erofs /source/directory
|
||||
|
||||
# Create with file system label
|
||||
mkfs.erofs -L "composefs-image" /path/to/image.erofs /source/directory
|
||||
```
|
||||
|
||||
### erofs-fuse
|
||||
|
||||
**Purpose**: Mount EROFS image using FUSE
|
||||
**Usage**: `erofs-fuse [options...] <image> <mountpoint>`
|
||||
**Dependencies**: erofs-utils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Mount EROFS image with FUSE
|
||||
erofs-fuse /path/to/image.erofs /mnt/erofs
|
||||
|
||||
# Mount with specific options
|
||||
erofs-fuse -o allow_other /path/to/image.erofs /mnt/erofs
|
||||
|
||||
# Mount in background
|
||||
erofs-fuse -f /path/to/image.erofs /mnt/erofs
|
||||
```
|
||||
|
||||
## Bootloader Commands
|
||||
|
||||
### grub-mkconfig
|
||||
|
||||
**Purpose**: Generate GRUB configuration
|
||||
**Usage**: `grub-mkconfig [options...]`
|
||||
**Dependencies**: grub2
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Generate GRUB config
|
||||
grub-mkconfig -o /boot/grub/grub.cfg
|
||||
|
||||
# Generate with specific output
|
||||
grub-mkconfig -o /boot/grub2/grub.cfg
|
||||
|
||||
# Generate with verbose output
|
||||
grub-mkconfig -v -o /boot/grub/grub.cfg
|
||||
|
||||
# Generate for specific OS
|
||||
grub-mkconfig -o /boot/grub/grub.cfg --os-prober
|
||||
```
|
||||
|
||||
### grub-install
|
||||
|
||||
**Purpose**: Install GRUB bootloader
|
||||
**Usage**: `grub-install [options...] <device>`
|
||||
**Dependencies**: grub2
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Install GRUB
|
||||
grub-install /dev/sda
|
||||
|
||||
# Install with specific directory
|
||||
grub-install --boot-directory=/boot /dev/sda
|
||||
|
||||
# Install with verbose output
|
||||
grub-install -v /dev/sda
|
||||
|
||||
# Install with UEFI support
|
||||
grub-install --target=x86_64-efi --efi-directory=/boot/efi /dev/sda
|
||||
```
|
||||
|
||||
### efibootmgr
|
||||
|
||||
**Purpose**: EFI boot manager
|
||||
**Usage**: `efibootmgr [options...]`
|
||||
**Dependencies**: efibootmgr
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# List boot entries
|
||||
efibootmgr
|
||||
|
||||
# Create boot entry
|
||||
efibootmgr -c -d /dev/sda -p 1 -L "Composefs" -l /EFI/composefs/grubx64.efi
|
||||
|
||||
# Delete boot entry
|
||||
efibootmgr -b 0000 -B
|
||||
|
||||
# Set boot order
|
||||
efibootmgr -o 0000,0001,0002
|
||||
|
||||
# Set next boot
|
||||
efibootmgr -n 0000
|
||||
```
|
||||
|
||||
### bootctl
|
||||
|
||||
**Purpose**: systemd-boot manager
|
||||
**Usage**: `bootctl [options...]`
|
||||
**Dependencies**: systemd-boot
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# List boot entries
|
||||
bootctl list
|
||||
|
||||
# Install systemd-boot
|
||||
bootctl install
|
||||
|
||||
# Update boot entries
|
||||
bootctl update
|
||||
|
||||
# Set default boot entry
|
||||
bootctl set-default "composefs-1.0.0"
|
||||
|
||||
# Show boot status
|
||||
bootctl status
|
||||
```
|
||||
|
||||
## File Operations Commands
|
||||
|
||||
### cp
|
||||
|
||||
**Purpose**: Copy files and directories
|
||||
**Usage**: `cp [options...] <source> <destination>`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Copy file
|
||||
cp /source/file /destination/
|
||||
|
||||
# Copy directory recursively
|
||||
cp -r /source/directory /destination/
|
||||
|
||||
# Copy with preserve attributes
|
||||
cp -a /source/file /destination/
|
||||
|
||||
# Copy with verbose output
|
||||
cp -v /source/file /destination/
|
||||
```
|
||||
|
||||
### mv
|
||||
|
||||
**Purpose**: Move/rename files and directories
|
||||
**Usage**: `mv [options...] <source> <destination>`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Move file
|
||||
mv /source/file /destination/
|
||||
|
||||
# Rename file
|
||||
mv oldname newname
|
||||
|
||||
# Move directory
|
||||
mv /source/directory /destination/
|
||||
|
||||
# Move with verbose output
|
||||
mv -v /source/file /destination/
|
||||
```
|
||||
|
||||
### rm
|
||||
|
||||
**Purpose**: Remove files and directories
|
||||
**Usage**: `rm [options...] <file>`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Remove file
|
||||
rm /path/to/file
|
||||
|
||||
# Remove directory recursively
|
||||
rm -r /path/to/directory
|
||||
|
||||
# Force remove
|
||||
rm -f /path/to/file
|
||||
|
||||
# Remove with verbose output
|
||||
rm -v /path/to/file
|
||||
```
|
||||
|
||||
### ln
|
||||
|
||||
**Purpose**: Create links
|
||||
**Usage**: `ln [options...] <target> <link>`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Create symbolic link
|
||||
ln -s /target/file /link/file
|
||||
|
||||
# Create hard link
|
||||
ln /target/file /link/file
|
||||
|
||||
# Create link with verbose output
|
||||
ln -v /target/file /link/file
|
||||
```
|
||||
|
||||
## Directory Operations Commands
|
||||
|
||||
### mkdir
|
||||
|
||||
**Purpose**: Create directories
|
||||
**Usage**: `mkdir [options...] <directory>`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Create directory
|
||||
mkdir /path/to/directory
|
||||
|
||||
# Create directory with parents
|
||||
mkdir -p /path/to/directory
|
||||
|
||||
# Create directory with permissions
|
||||
mkdir -m 755 /path/to/directory
|
||||
|
||||
# Create multiple directories
|
||||
mkdir dir1 dir2 dir3
|
||||
```
|
||||
|
||||
### rmdir
|
||||
|
||||
**Purpose**: Remove empty directories
|
||||
**Usage**: `rmdir [options...] <directory>`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Remove empty directory
|
||||
rmdir /path/to/directory
|
||||
|
||||
# Remove directory with parents
|
||||
rmdir -p /path/to/directory
|
||||
|
||||
# Remove multiple directories
|
||||
rmdir dir1 dir2 dir3
|
||||
```
|
||||
|
||||
### ls
|
||||
|
||||
**Purpose**: List directory contents
|
||||
**Usage**: `ls [options...] [file...]`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# List files
|
||||
ls
|
||||
|
||||
# List with details
|
||||
ls -l
|
||||
|
||||
# List all files
|
||||
ls -a
|
||||
|
||||
# List with human readable sizes
|
||||
ls -lh
|
||||
|
||||
# List with recursive
|
||||
ls -R
|
||||
|
||||
# List with sort by time
|
||||
ls -lt
|
||||
```
|
||||
|
||||
## Process Commands
|
||||
|
||||
### ps
|
||||
|
||||
**Purpose**: Process status
|
||||
**Usage**: `ps [options...]`
|
||||
**Dependencies**: procps
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show all processes
|
||||
ps aux
|
||||
|
||||
# Show process tree
|
||||
ps -ef
|
||||
|
||||
# Show specific process
|
||||
ps -p 1234
|
||||
|
||||
# Show processes by user
|
||||
ps -u username
|
||||
|
||||
# Show processes by command
|
||||
ps -C bootc
|
||||
```
|
||||
|
||||
### kill
|
||||
|
||||
**Purpose**: Send signals to processes
|
||||
**Usage**: `kill [options...] <pid>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Kill process
|
||||
kill 1234
|
||||
|
||||
# Force kill process
|
||||
kill -9 1234
|
||||
|
||||
# Send signal
|
||||
kill -TERM 1234
|
||||
|
||||
# Kill by name
|
||||
pkill bootc
|
||||
```
|
||||
|
||||
## System Information Commands
|
||||
|
||||
### uname
|
||||
|
||||
**Purpose**: System information
|
||||
**Usage**: `uname [options...]`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show system name
|
||||
uname
|
||||
|
||||
# Show all information
|
||||
uname -a
|
||||
|
||||
# Show kernel name
|
||||
uname -s
|
||||
|
||||
# Show kernel version
|
||||
uname -r
|
||||
|
||||
# Show machine type
|
||||
uname -m
|
||||
```
|
||||
|
||||
### hostname
|
||||
|
||||
**Purpose**: Hostname operations
|
||||
**Usage**: `hostname [options...]`
|
||||
**Dependencies**: hostname
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show hostname
|
||||
hostname
|
||||
|
||||
# Show FQDN
|
||||
hostname -f
|
||||
|
||||
# Show short hostname
|
||||
hostname -s
|
||||
|
||||
# Show domain name
|
||||
hostname -d
|
||||
```
|
||||
|
||||
### lscpu
|
||||
|
||||
**Purpose**: CPU information
|
||||
**Usage**: `lscpu [options...]`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show CPU information
|
||||
lscpu
|
||||
|
||||
# Show in JSON format
|
||||
lscpu -J
|
||||
|
||||
# Show in extended format
|
||||
lscpu -e
|
||||
|
||||
# Show in parseable format
|
||||
lscpu -p
|
||||
```
|
||||
|
||||
### free
|
||||
|
||||
**Purpose**: Memory information
|
||||
**Usage**: `free [options...]`
|
||||
**Dependencies**: procps
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show memory usage
|
||||
free
|
||||
|
||||
# Show in human readable format
|
||||
free -h
|
||||
|
||||
# Show in bytes
|
||||
free -b
|
||||
|
||||
# Show with total
|
||||
free -t
|
||||
|
||||
# Show with wide format
|
||||
free -w
|
||||
```
|
||||
|
||||
## Storage Commands
|
||||
|
||||
### df
|
||||
|
||||
**Purpose**: Disk space usage
|
||||
**Usage**: `df [options...] [file...]`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show disk usage
|
||||
df -h
|
||||
|
||||
# Show specific filesystem
|
||||
df -h /sysroot
|
||||
|
||||
# Show inode usage
|
||||
df -i
|
||||
|
||||
# Show all filesystems
|
||||
df -a
|
||||
```
|
||||
|
||||
### du
|
||||
|
||||
**Purpose**: Directory space usage
|
||||
**Usage**: `du [options...] [file...]`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show directory usage
|
||||
du -h /sysroot
|
||||
|
||||
# Show total usage
|
||||
du -sh /sysroot
|
||||
|
||||
# Show usage by subdirectory
|
||||
du -h --max-depth=1 /sysroot
|
||||
|
||||
# Show usage of all files
|
||||
du -ah /sysroot
|
||||
```
|
||||
|
||||
### lsblk
|
||||
|
||||
**Purpose**: List block devices
|
||||
**Usage**: `lsblk [options...]`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# List block devices
|
||||
lsblk
|
||||
|
||||
# Show device tree
|
||||
lsblk -f
|
||||
|
||||
# Show device sizes
|
||||
lsblk -b
|
||||
|
||||
# Show device types
|
||||
lsblk -d
|
||||
```
|
||||
|
||||
## Network Commands
|
||||
|
||||
### curl
|
||||
|
||||
**Purpose**: HTTP client for registry operations
|
||||
**Usage**: `curl [options...] <url>`
|
||||
**Dependencies**: curl
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Download file
|
||||
curl -O https://example.com/file.tar
|
||||
|
||||
# Get HTTP headers
|
||||
curl -I https://example.com
|
||||
|
||||
# POST data
|
||||
curl -X POST -d "data" https://example.com
|
||||
|
||||
# With authentication
|
||||
curl -u username:password https://example.com
|
||||
|
||||
# With custom headers
|
||||
curl -H "Authorization: Bearer token" https://example.com
|
||||
```
|
||||
|
||||
### wget
|
||||
|
||||
**Purpose**: HTTP client for downloading files
|
||||
**Usage**: `wget [options...] <url>`
|
||||
**Dependencies**: wget
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Download file
|
||||
wget https://example.com/file.tar
|
||||
|
||||
# Download with progress
|
||||
wget --progress=bar https://example.com/file.tar
|
||||
|
||||
# Download recursively
|
||||
wget -r https://example.com/
|
||||
|
||||
# Download with authentication
|
||||
wget --user=username --password=password https://example.com
|
||||
```
|
||||
|
||||
## Archive Commands
|
||||
|
||||
### tar
|
||||
|
||||
**Purpose**: Archive operations
|
||||
**Usage**: `tar [options...] <archive> [file...]`
|
||||
**Dependencies**: tar
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Create archive
|
||||
tar -cf archive.tar file1 file2
|
||||
|
||||
# Extract archive
|
||||
tar -xf archive.tar
|
||||
|
||||
# List archive contents
|
||||
tar -tf archive.tar
|
||||
|
||||
# Create compressed archive
|
||||
tar -czf archive.tar.gz file1 file2
|
||||
|
||||
# Extract compressed archive
|
||||
tar -xzf archive.tar.gz
|
||||
```
|
||||
|
||||
### gzip
|
||||
|
||||
**Purpose**: Compression
|
||||
**Usage**: `gzip [options...] [file...]`
|
||||
**Dependencies**: gzip
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Compress file
|
||||
gzip file.txt
|
||||
|
||||
# Decompress file
|
||||
gzip -d file.txt.gz
|
||||
|
||||
# Compress with custom level
|
||||
gzip -9 file.txt
|
||||
|
||||
# Keep original file
|
||||
gzip -k file.txt
|
||||
```
|
||||
|
||||
## Monitoring Commands
|
||||
|
||||
### top
|
||||
|
||||
**Purpose**: Process monitoring
|
||||
**Usage**: `top [options...]`
|
||||
**Dependencies**: procps
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show processes
|
||||
top
|
||||
|
||||
# Show specific user
|
||||
top -u username
|
||||
|
||||
# Show specific process
|
||||
top -p 1234
|
||||
|
||||
# Show with custom delay
|
||||
top -d 5
|
||||
|
||||
# Show with custom sort
|
||||
top -o %CPU
|
||||
```
|
||||
|
||||
### htop
|
||||
|
||||
**Purpose**: Interactive process monitoring
|
||||
**Usage**: `htop [options...]`
|
||||
**Dependencies**: htop
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show processes
|
||||
htop
|
||||
|
||||
# Show specific user
|
||||
htop -u username
|
||||
|
||||
# Show specific process
|
||||
htop -p 1234
|
||||
|
||||
# Show with custom delay
|
||||
htop -d 5
|
||||
```
|
||||
|
||||
### iotop
|
||||
|
||||
**Purpose**: I/O monitoring
|
||||
**Usage**: `iotop [options...]`
|
||||
**Dependencies**: iotop
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show I/O usage
|
||||
iotop
|
||||
|
||||
# Show only processes doing I/O
|
||||
iotop -o
|
||||
|
||||
# Show with custom delay
|
||||
iotop -d 5
|
||||
|
||||
# Show with custom refresh
|
||||
iotop -n 10
|
||||
```
|
||||
|
||||
## Security Commands
|
||||
|
||||
### openssl
|
||||
|
||||
**Purpose**: SSL/TLS operations
|
||||
**Usage**: `openssl <command> [options...]`
|
||||
**Dependencies**: openssl
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Generate private key
|
||||
openssl genrsa -out key.pem 2048
|
||||
|
||||
# Generate certificate
|
||||
openssl req -new -x509 -key key.pem -out cert.pem
|
||||
|
||||
# Verify certificate
|
||||
openssl verify cert.pem
|
||||
|
||||
# Check certificate details
|
||||
openssl x509 -in cert.pem -text -noout
|
||||
|
||||
# Generate hash
|
||||
openssl dgst -sha256 file.txt
|
||||
```
|
||||
|
||||
### gpg
|
||||
|
||||
**Purpose**: GPG operations
|
||||
**Usage**: `gpg [options...]`
|
||||
**Dependencies**: gnupg
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Generate key pair
|
||||
gpg --gen-key
|
||||
|
||||
# List keys
|
||||
gpg --list-keys
|
||||
|
||||
# Sign file
|
||||
gpg --sign file.txt
|
||||
|
||||
# Verify signature
|
||||
gpg --verify file.txt.asc
|
||||
|
||||
# Encrypt file
|
||||
gpg --encrypt file.txt
|
||||
```
|
||||
|
||||
## Development Commands
|
||||
|
||||
### make
|
||||
|
||||
**Purpose**: Build automation
|
||||
**Usage**: `make [target...]`
|
||||
**Dependencies**: make
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Build project
|
||||
make
|
||||
|
||||
# Clean build
|
||||
make clean
|
||||
|
||||
# Install
|
||||
make install
|
||||
|
||||
# Run tests
|
||||
make test
|
||||
|
||||
# Update generated files
|
||||
make update-generated
|
||||
```
|
||||
|
||||
### cargo
|
||||
|
||||
**Purpose**: Rust package manager
|
||||
**Usage**: `cargo <subcommand> [options...]`
|
||||
**Dependencies**: rust
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Build project
|
||||
cargo build
|
||||
|
||||
# Run project
|
||||
cargo run
|
||||
|
||||
# Run tests
|
||||
cargo test
|
||||
|
||||
# Check code
|
||||
cargo check
|
||||
|
||||
# Update dependencies
|
||||
cargo update
|
||||
```
|
||||
|
||||
### git
|
||||
|
||||
**Purpose**: Version control
|
||||
**Usage**: `git <subcommand> [options...]`
|
||||
**Dependencies**: git
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Clone repository
|
||||
git clone https://github.com/containers/bootc.git
|
||||
|
||||
# Check status
|
||||
git status
|
||||
|
||||
# Add files
|
||||
git add .
|
||||
|
||||
# Commit changes
|
||||
git commit -m "message"
|
||||
|
||||
# Push changes
|
||||
git push
|
||||
```
|
||||
|
||||
This comprehensive reference covers all external commands used by the bootc composefs-finalize-staged system, providing examples and usage patterns for each command.
|
||||
|
|
@ -0,0 +1,417 @@
|
|||
# bootc composefs-finalize-staged - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc composefs-finalize-staged` process flow, showing the decision points, operations, and system state changes involved in finalizing staged composefs deployments.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc composefs-finalize-staged │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Get Deployment Status │
|
||||
│ │
|
||||
│ • Get composefs deployment status │
|
||||
│ • Validate booted composefs deployment │
|
||||
│ • Check for staged deployment │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Validate Staged Deployment │
|
||||
│ │
|
||||
│ • Check if staged deployment exists │
|
||||
│ • Validate staged deployment is composefs │
|
||||
│ • Get staged composefs configuration │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Mount EROFS Image │
|
||||
│ │
|
||||
│ • Open sysroot directory │
|
||||
│ • Mount booted EROFS image │
|
||||
│ • Create temporary mount point │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Perform /etc Merge │
|
||||
│ │
|
||||
│ • Access pristine /etc from EROFS │
|
||||
│ • Access current /etc from system │
|
||||
│ • Access new /etc from staged deployment │
|
||||
│ • Perform 3-way merge │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Unmount EROFS Image │
|
||||
│ │
|
||||
│ • Drop temporary mount │
|
||||
│ • Clean up EROFS mount │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Mount ESP Partition │
|
||||
│ │
|
||||
│ • Get sysroot parent device │
|
||||
│ • Get ESP partition │
|
||||
│ • Mount ESP partition │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Update Bootloader Entries │
|
||||
│ │
|
||||
│ • Determine bootloader type (GRUB vs systemd-boot) │
|
||||
│ • Determine boot type (BLS vs UKI) │
|
||||
│ • Update appropriate bootloader entries │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Complete Finalization │
|
||||
│ │
|
||||
│ • Sync filesystem changes │
|
||||
│ • Update deployment state │
|
||||
│ • Complete finalization process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Detailed Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Deployment Status Retrieval │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Get Composefs Status │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ composefs_deployment_status │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Check Kernel Cmdline │ │
|
||||
│ │ │ │
|
||||
│ │ • Parse composefs parameter │ │
|
||||
│ │ • Extract composefs digest │ │
|
||||
│ │ • Validate composefs state │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Staged Deployment Validation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Staged Deployment │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Staged Deployment Check │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ No Staged │ │ Staged Found │ │
|
||||
│ │ Deployment │ │ │ │
|
||||
│ │ │ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ ┌─────────────┐│ │ │ Check Composefs Type ││ │
|
||||
│ │ │ Return OK ││ │ │ ││ │
|
||||
│ │ │ (No Action) ││ │ │ • Validate composefs deployment ││ │
|
||||
│ │ └─────────────┘│ │ │ • Get composefs configuration ││ │
|
||||
│ └─────────────────┘ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ EROFS Image Operations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Mount EROFS Image │
|
||||
│ │
|
||||
│ • Open /sysroot directory │
|
||||
│ • Mount booted EROFS image using verity digest │
|
||||
│ • Create temporary mount point │
|
||||
│ • Access pristine /etc configuration │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ /etc Configuration Merge │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Three-Way Merge Process │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Pristine │ │ Current │ │ New │ │
|
||||
│ │ /etc │ │ /etc │ │ /etc │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ From EROFS ││ │ │ From System ││ │ │ From Staged ││ │
|
||||
│ │ │ Image ││ │ │ /etc ││ │ │ Deployment ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
│ │ │ │ │
|
||||
│ └─────────────────────┼─────────────────────┘ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Compute Differences │ │
|
||||
│ │ │ │
|
||||
│ │ • Compare pristine vs current │ │
|
||||
│ │ • Identify changes made by user │ │
|
||||
│ │ • Prepare for merge operation │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Perform Merge │ │
|
||||
│ │ │ │
|
||||
│ │ • Apply pristine configuration as base │ │
|
||||
│ │ • Apply user changes from current │ │
|
||||
│ │ • Apply new changes from staged deployment │ │
|
||||
│ │ • Resolve conflicts if any │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ EROFS Cleanup │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Unmount EROFS Image │
|
||||
│ │
|
||||
│ • Drop temporary mount │
|
||||
│ • Clean up EROFS mount │
|
||||
│ • Release file descriptors │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ ESP Partition Operations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Mount ESP Partition │
|
||||
│ │
|
||||
│ • Get sysroot parent device │
|
||||
│ • Get ESP partition information │
|
||||
│ • Mount ESP partition │
|
||||
│ • Access bootloader entries │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Bootloader Management │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Bootloader Type │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Bootloader Type Check │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ GRUB │ │ systemd-boot │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ BLS Entries ││ │ │ BLS Entries ││ │
|
||||
│ │ │ UKI Entries ││ │ │ UKI Entries ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Bootloader Operations Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Bootloader Operations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ GRUB Bootloader │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Boot Type │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ BLS Entries │ │ UKI Entries │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Update BLS ││ │ │ Update UKI Entries ││ │
|
||||
│ │ │ Entries ││ │ │ ││ │
|
||||
│ │ │ ││ │ │ • Rename staged UKI files ││ │
|
||||
│ │ │ • Exchange ││ │ │ • Update GRUB configuration ││ │
|
||||
│ │ │ entries ││ │ │ • Sync filesystem ││ │
|
||||
│ │ │ • Update ││ │ └─────────────────────────────────┘│ │
|
||||
│ │ │ order ││ │ │ │
|
||||
│ │ └─────────────┘│ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ systemd-boot Bootloader │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Boot Type │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ BLS Entries │ │ UKI Entries │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Update BLS ││ │ │ Update UKI Entries ││ │
|
||||
│ │ │ Entries ││ │ │ ││ │
|
||||
│ │ │ ││ │ │ • Rename staged UKI files ││ │
|
||||
│ │ │ • Exchange ││ │ │ • Sync filesystem ││ │
|
||||
│ │ │ entries ││ │ │ • Update boot order ││ │
|
||||
│ │ │ • Update ││ │ └─────────────────────────────────┘│ │
|
||||
│ │ │ order ││ │ │ │
|
||||
│ │ └─────────────┘│ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Deployment │ │ Filesystem │ │ Bootloader │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • No Staged │ │ • EROFS Mount │ │ • Entry Update │ │
|
||||
│ │ Deployment │ │ Failed │ │ Failed │ │
|
||||
│ │ • Non-Composefs │ │ • ESP Mount │ │ • Sync Failed │ │
|
||||
│ │ Deployment │ │ Failed │ │ • Permission │ │
|
||||
│ │ • Invalid State │ │ • Access Denied │ │ Denied │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Response │
|
||||
│ │
|
||||
│ • Log error details │
|
||||
│ • Provide context information │
|
||||
│ • Return appropriate error code │
|
||||
│ • Clean up resources │
|
||||
│ • Notify systemd service │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Systemd Service Integration Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Systemd Service Lifecycle │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Service Start │
|
||||
│ │
|
||||
│ • Service starts early in boot process │
|
||||
│ • After local-fs.target │
|
||||
│ • Before basic.target and final.target │
|
||||
│ • After systemd-journal-flush.service │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Command Execution │
|
||||
│ │
|
||||
│ • Execute bootc composefs-finalize-staged │
|
||||
│ • With 5-minute timeout │
|
||||
│ • With sandboxing enabled │
|
||||
│ • With /etc read-only protection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Service Completion │
|
||||
│ │
|
||||
│ • Command completes successfully or fails │
|
||||
│ • Service remains active (RemainAfterExit=yes) │
|
||||
│ • System continues boot process │
|
||||
│ • Logs are written to journal │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## State Transitions Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ System States │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initial State │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Staged Deployment Present │ │
|
||||
│ │ │ │
|
||||
│ │ • Staged composefs deployment exists │ │
|
||||
│ │ • Booted composefs deployment active │ │
|
||||
│ │ • System ready for finalization │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Finalization Process │ │
|
||||
│ │ │ │
|
||||
│ │ • Mount EROFS image │ │
|
||||
│ │ • Perform /etc merge │ │
|
||||
│ │ • Update bootloader entries │ │
|
||||
│ │ • Sync filesystem changes │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Final State │ │
|
||||
│ │ │ │
|
||||
│ │ • Staged deployment finalized │ │
|
||||
│ │ • Bootloader entries updated │ │
|
||||
│ │ • System ready for next boot │ │
|
||||
│ │ • Staged deployment becomes active │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc composefs-finalize-staged process, showing all decision points, operations, and state transitions involved in finalizing staged composefs deployments.
|
||||
|
|
@ -0,0 +1,336 @@
|
|||
# bootc composefs-finalize-staged - Quick Reference
|
||||
|
||||
## Command Summary
|
||||
|
||||
| Command | Purpose | Usage |
|
||||
|---------|---------|-------|
|
||||
| `composefs-finalize-staged` | Finalize staged composefs deployments | `bootc composefs-finalize-staged` |
|
||||
|
||||
## Quick Commands
|
||||
|
||||
### Basic Operations
|
||||
```bash
|
||||
# Execute composefs-finalize-staged command
|
||||
bootc composefs-finalize-staged
|
||||
|
||||
# Check if command is available
|
||||
bootc --help | grep composefs-finalize-staged
|
||||
```
|
||||
|
||||
### Systemd Service Operations
|
||||
```bash
|
||||
# Start service
|
||||
systemctl start composefs-finalize-staged.service
|
||||
|
||||
# Enable service
|
||||
systemctl enable composefs-finalize-staged.service
|
||||
|
||||
# Check service status
|
||||
systemctl status composefs-finalize-staged.service
|
||||
|
||||
# Stop service
|
||||
systemctl stop composefs-finalize-staged.service
|
||||
|
||||
# Restart service
|
||||
systemctl restart composefs-finalize-staged.service
|
||||
```
|
||||
|
||||
### Service Monitoring
|
||||
```bash
|
||||
# Check service logs
|
||||
journalctl -u composefs-finalize-staged.service
|
||||
|
||||
# Follow logs in real-time
|
||||
journalctl -u composefs-finalize-staged.service -f
|
||||
|
||||
# Show recent logs
|
||||
journalctl -u composefs-finalize-staged.service -n 100
|
||||
|
||||
# Show logs since specific time
|
||||
journalctl -u composefs-finalize-staged.service --since "1 hour ago"
|
||||
```
|
||||
|
||||
## Common Options
|
||||
|
||||
| Option | Purpose | Example |
|
||||
|--------|---------|---------|
|
||||
| `--help` | Show help | `bootc composefs-finalize-staged --help` |
|
||||
| `--verbose` | Verbose output | `bootc composefs-finalize-staged -v` |
|
||||
| `--quiet` | Quiet output | `bootc composefs-finalize-staged -q` |
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | Meaning | Solution |
|
||||
|------|---------|----------|
|
||||
| 0 | Success | Command completed successfully |
|
||||
| 1 | General error | Check logs for details |
|
||||
| 2 | No staged deployment | Create staged deployment |
|
||||
| 3 | Non-composefs deployment | Verify deployment type |
|
||||
| 4 | EROFS mount error | Check EROFS image and mount point |
|
||||
| 5 | ESP mount error | Check ESP partition and mount point |
|
||||
|
||||
## Common Issues
|
||||
|
||||
### No Staged Deployment
|
||||
```bash
|
||||
# Error: No staged deployment found
|
||||
# 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
|
||||
```
|
||||
|
||||
### Non-Composefs Deployment
|
||||
```bash
|
||||
# Error: 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
|
||||
```
|
||||
|
||||
### EROFS Mount Error
|
||||
```bash
|
||||
# Error: Failed to mount EROFS image
|
||||
# Solution: Check EROFS image
|
||||
file /path/to/image.erofs
|
||||
|
||||
# Check mount point
|
||||
ls -la /sysroot/
|
||||
|
||||
# Try manual mount
|
||||
mount -t erofs /path/to/image.erofs /mnt/test
|
||||
```
|
||||
|
||||
### ESP Mount Error
|
||||
```bash
|
||||
# Error: Failed to mount ESP partition
|
||||
# Solution: Check ESP partition
|
||||
lsblk | grep -i efi
|
||||
|
||||
# Check mount point
|
||||
ls -la /boot/efi/
|
||||
|
||||
# Try manual mount
|
||||
mount /dev/sda1 /mnt/esp
|
||||
```
|
||||
|
||||
## Environment Variables
|
||||
|
||||
| Variable | Purpose | Default |
|
||||
|----------|---------|---------|
|
||||
| `RUST_LOG` | Log level | `info` |
|
||||
| `BOOTC_DEBUG` | Debug mode | `false` |
|
||||
| `BOOTC_CONFIG` | Config file | `/etc/bootc/config.toml` |
|
||||
|
||||
## Configuration Files
|
||||
|
||||
| File | Purpose | Location |
|
||||
|------|---------|----------|
|
||||
| Main config | Bootc configuration | `/etc/bootc/config.toml` |
|
||||
| Service file | Systemd service | `/usr/lib/systemd/system/composefs-finalize-staged.service` |
|
||||
| Staged deployment | Staged deployment marker | `/var/lib/composefs-transient-state/staged-deployment` |
|
||||
| Composefs state | Composefs state directory | `/sysroot/composefs/` |
|
||||
|
||||
## Log Files
|
||||
|
||||
| File | Purpose | Location |
|
||||
|------|---------|----------|
|
||||
| System logs | System messages | `/var/log/messages` |
|
||||
| Journal logs | Systemd journal | `journalctl -u composefs-finalize-staged.service` |
|
||||
| Bootc logs | Bootc specific | `/var/log/bootc/` |
|
||||
|
||||
## Performance Tips
|
||||
|
||||
### Optimize Operations
|
||||
```bash
|
||||
# Check system load
|
||||
uptime
|
||||
|
||||
# Check memory usage
|
||||
free -h
|
||||
|
||||
# Check disk usage
|
||||
df -h /sysroot
|
||||
|
||||
# Check I/O usage
|
||||
iotop -bn1 | head -20
|
||||
```
|
||||
|
||||
### Monitor System
|
||||
```bash
|
||||
# Check service status
|
||||
systemctl is-active composefs-finalize-staged.service
|
||||
|
||||
# Check service logs
|
||||
journalctl -u composefs-finalize-staged.service --since "1 hour ago"
|
||||
|
||||
# Check system performance
|
||||
top -bn1 | head -20
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Root Privileges
|
||||
- All composefs-finalize-staged operations require root privileges
|
||||
- Use `sudo` or switch to root user
|
||||
- Check current user with `whoami`
|
||||
|
||||
### Sandboxing
|
||||
- Service runs with systemd sandboxing
|
||||
- `ProtectHome=yes` - restricts home directory access
|
||||
- `ReadOnlyPaths=/etc` - prevents /etc modification
|
||||
|
||||
### Access Control
|
||||
- Command accesses EROFS images for pristine configuration
|
||||
- Command accesses ESP partition for bootloader operations
|
||||
- Command manages system state for deployment management
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Regular Operations
|
||||
- Use systemd service for execution
|
||||
- Execute early in boot process
|
||||
- Monitor service status and logs
|
||||
- Implement proper error handling
|
||||
|
||||
### Development
|
||||
- Use in composefs-backend branch
|
||||
- Test with staged deployments
|
||||
- Document procedures
|
||||
- Monitor system health
|
||||
|
||||
### Production
|
||||
- Set up monitoring
|
||||
- Configure alerts
|
||||
- Regular testing
|
||||
- Document procedures
|
||||
|
||||
## Troubleshooting Steps
|
||||
|
||||
1. **Check service status**
|
||||
```bash
|
||||
systemctl status composefs-finalize-staged.service
|
||||
```
|
||||
|
||||
2. **Check service logs**
|
||||
```bash
|
||||
journalctl -u composefs-finalize-staged.service --since "1 hour ago"
|
||||
```
|
||||
|
||||
3. **Check staged deployment**
|
||||
```bash
|
||||
ls -la /var/lib/composefs-transient-state/
|
||||
cat /var/lib/composefs-transient-state/staged-deployment
|
||||
```
|
||||
|
||||
4. **Check composefs state**
|
||||
```bash
|
||||
ls -la /sysroot/composefs/
|
||||
```
|
||||
|
||||
5. **Check EROFS support**
|
||||
```bash
|
||||
modprobe erofs
|
||||
lsmod | grep erofs
|
||||
```
|
||||
|
||||
6. **Check ESP partition**
|
||||
```bash
|
||||
lsblk | grep -i efi
|
||||
ls -la /boot/efi/
|
||||
```
|
||||
|
||||
## Quick Scripts
|
||||
|
||||
### Health Check
|
||||
```bash
|
||||
#!/bin/bash
|
||||
systemctl is-active composefs-finalize-staged.service && echo "Service healthy"
|
||||
```
|
||||
|
||||
### Service Restart
|
||||
```bash
|
||||
#!/bin/bash
|
||||
systemctl restart composefs-finalize-staged.service && echo "Service restarted"
|
||||
```
|
||||
|
||||
### Log Check
|
||||
```bash
|
||||
#!/bin/bash
|
||||
journalctl -u composefs-finalize-staged.service -n 50
|
||||
```
|
||||
|
||||
### Staged Deployment Check
|
||||
```bash
|
||||
#!/bin/bash
|
||||
[ -f "/var/lib/composefs-transient-state/staged-deployment" ] && echo "Staged deployment found" || echo "No staged deployment"
|
||||
```
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Systemd Service
|
||||
```bash
|
||||
# Create service file
|
||||
cat > /etc/systemd/system/composefs-finalize-staged.service << EOF
|
||||
[Unit]
|
||||
Description=Composefs Finalize Staged Deployment
|
||||
Documentation=man:bootc(1)
|
||||
DefaultDependencies=no
|
||||
|
||||
RequiresMountsFor=/sysroot
|
||||
After=local-fs.target
|
||||
Before=basic.target final.target
|
||||
After=systemd-journal-flush.service
|
||||
Conflicts=final.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
RemainAfterExit=yes
|
||||
ExecStop=/usr/bin/bootc composefs-finalize-staged
|
||||
TimeoutStopSec=5m
|
||||
ProtectHome=yes
|
||||
ReadOnlyPaths=/etc
|
||||
EOF
|
||||
|
||||
# Enable service
|
||||
systemctl daemon-reload
|
||||
systemctl enable composefs-finalize-staged.service
|
||||
```
|
||||
|
||||
### Cron Job
|
||||
```bash
|
||||
# Add to crontab
|
||||
echo "0 2 * * * /usr/local/bin/composefs-finalize-staged-maintenance.sh" | crontab -
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
```bash
|
||||
# Check service health
|
||||
if ! systemctl is-active composefs-finalize-staged.service > /dev/null 2>&1; then
|
||||
echo "WARNING: Composefs finalize staged service not active"
|
||||
# Send alert
|
||||
fi
|
||||
```
|
||||
|
||||
## Service Configuration
|
||||
|
||||
### Service Dependencies
|
||||
- `RequiresMountsFor=/sysroot` - Requires /sysroot to be mounted
|
||||
- `After=local-fs.target` - Runs after local filesystems are mounted
|
||||
- `Before=basic.target final.target` - Runs before basic and final targets
|
||||
- `After=systemd-journal-flush.service` - Runs after journal is flushed
|
||||
|
||||
### Service Security
|
||||
- `ProtectHome=yes` - Protects home directory
|
||||
- `ReadOnlyPaths=/etc` - Makes /etc read-only
|
||||
- `TimeoutStopSec=5m` - 5-minute timeout for operations
|
||||
|
||||
### Service Execution
|
||||
- `Type=oneshot` - Runs once and exits
|
||||
- `RemainAfterExit=yes` - Service remains active after completion
|
||||
- `ExecStop=/usr/bin/bootc composefs-finalize-staged` - Command to execute
|
||||
|
||||
This quick reference provides essential information for using the bootc composefs-finalize-staged system effectively.
|
||||
|
|
@ -0,0 +1,559 @@
|
|||
# bootc composefs-finalize-staged - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc composefs-finalize-staged` is a hidden command specific to the `composefs-backend` branch that finalizes staged composefs deployments. This command is executed early in the boot process by a systemd service to complete the deployment of staged composefs images.
|
||||
|
||||
## Purpose
|
||||
|
||||
The composefs-finalize-staged command serves several critical functions:
|
||||
|
||||
1. **Staged Deployment Finalization**: Completes the deployment of staged composefs images
|
||||
2. **Boot Process Integration**: Executes early in the boot process via systemd service
|
||||
3. **Filesystem Operations**: Performs EROFS mounting and /etc merging operations
|
||||
4. **Bootloader Management**: Updates bootloader entries for staged deployments
|
||||
5. **System State Management**: Manages composefs deployment state transitions
|
||||
|
||||
## Command Structure
|
||||
|
||||
```rust
|
||||
#[cfg(feature = "composefs-backend")]
|
||||
ComposefsFinalizeStaged,
|
||||
```
|
||||
|
||||
The command is conditionally compiled only when the `composefs-backend` feature is enabled.
|
||||
|
||||
## Core Functionality
|
||||
|
||||
### Purpose
|
||||
|
||||
The command finalizes staged composefs deployments by:
|
||||
- Mounting the booted EROFS image to access pristine /etc configuration
|
||||
- Performing 3-way merge of /etc configurations (pristine, current, new)
|
||||
- Updating bootloader entries for staged deployments
|
||||
- Managing bootloader-specific operations (GRUB vs systemd-boot)
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
bootc composefs-finalize-staged
|
||||
```
|
||||
|
||||
### Implementation
|
||||
|
||||
```rust
|
||||
pub(crate) async fn composefs_native_finalize() -> Result<()> {
|
||||
let host = composefs_deployment_status().await?;
|
||||
|
||||
let booted_composefs = host.require_composefs_booted()?;
|
||||
|
||||
let Some(staged_depl) = host.status.staged.as_ref() else {
|
||||
tracing::debug!("No staged deployment found");
|
||||
return Ok(());
|
||||
};
|
||||
|
||||
let staged_composefs = staged_depl.composefs.as_ref().ok_or(anyhow::anyhow!(
|
||||
"Staged deployment is not a composefs deployment"
|
||||
))?;
|
||||
|
||||
// Mount the booted EROFS image to get pristine etc
|
||||
let sysroot = open_dir(CWD, "/sysroot")?;
|
||||
let composefs_fd = mount_composefs_image(&sysroot, &booted_composefs.verity, false)?;
|
||||
|
||||
let erofs_tmp_mnt = TempMount::mount_fd(&composefs_fd)?;
|
||||
|
||||
// Perform the /etc merge
|
||||
let pristine_etc =
|
||||
Dir::open_ambient_dir(erofs_tmp_mnt.dir.path().join("etc"), ambient_authority())?;
|
||||
let current_etc = Dir::open_ambient_dir("/etc", ambient_authority())?;
|
||||
|
||||
let new_etc_path = Path::new(STATE_DIR_ABS)
|
||||
.join(&staged_composefs.verity)
|
||||
.join("etc");
|
||||
|
||||
let new_etc = Dir::open_ambient_dir(new_etc_path, ambient_authority())?;
|
||||
|
||||
let (pristine_files, current_files, new_files) =
|
||||
traverse_etc(&pristine_etc, ¤t_etc, &new_etc)?;
|
||||
|
||||
let diff = compute_diff(&pristine_files, ¤t_files)?;
|
||||
merge(¤t_etc, ¤t_files, &new_etc, &new_files, diff)?;
|
||||
|
||||
// Unmount EROFS
|
||||
drop(erofs_tmp_mnt);
|
||||
|
||||
let sysroot_parent = get_sysroot_parent_dev()?;
|
||||
// NOTE: Assumption here that ESP will always be present
|
||||
let (esp_part, ..) = get_esp_partition(&sysroot_parent)?;
|
||||
|
||||
let esp_mount = TempMount::mount_dev(&esp_part)?;
|
||||
let boot_dir = Dir::open_ambient_dir("/sysroot/boot", ambient_authority())
|
||||
.context("Opening sysroot/boot")?;
|
||||
|
||||
// NOTE: Assuming here we won't have two bootloaders at the same time
|
||||
match booted_composefs.bootloader {
|
||||
Bootloader::Grub => match staged_composefs.boot_type {
|
||||
BootType::Bls => {
|
||||
let entries_dir = boot_dir.open_dir("loader")?;
|
||||
rename_exchange_bls_entries(&entries_dir)?;
|
||||
}
|
||||
BootType::Uki => finalize_staged_grub_uki(&esp_mount.fd, &boot_dir)?,
|
||||
},
|
||||
|
||||
Bootloader::Systemd => match staged_composefs.boot_type {
|
||||
BootType::Bls => {
|
||||
let entries_dir = esp_mount.fd.open_dir("loader")?;
|
||||
rename_exchange_bls_entries(&entries_dir)?;
|
||||
}
|
||||
BootType::Uki => rename_staged_uki_entries(&esp_mount.fd)?,
|
||||
},
|
||||
};
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
## Technical Details
|
||||
|
||||
### 1. Deployment Status Retrieval
|
||||
|
||||
The command first retrieves the current composefs deployment status:
|
||||
|
||||
```rust
|
||||
let host = composefs_deployment_status().await?;
|
||||
let booted_composefs = host.require_composefs_booted()?;
|
||||
```
|
||||
|
||||
### 2. Staged Deployment Validation
|
||||
|
||||
The command validates that a staged deployment exists and is a composefs deployment:
|
||||
|
||||
```rust
|
||||
let Some(staged_depl) = host.status.staged.as_ref() else {
|
||||
tracing::debug!("No staged deployment found");
|
||||
return Ok(());
|
||||
};
|
||||
|
||||
let staged_composefs = staged_depl.composefs.as_ref().ok_or(anyhow::anyhow!(
|
||||
"Staged deployment is not a composefs deployment"
|
||||
))?;
|
||||
```
|
||||
|
||||
### 3. EROFS Image Mounting
|
||||
|
||||
The command mounts the booted EROFS image to access pristine /etc configuration:
|
||||
|
||||
```rust
|
||||
let sysroot = open_dir(CWD, "/sysroot")?;
|
||||
let composefs_fd = mount_composefs_image(&sysroot, &booted_composefs.verity, false)?;
|
||||
let erofs_tmp_mnt = TempMount::mount_fd(&composefs_fd)?;
|
||||
```
|
||||
|
||||
### 4. /etc Configuration Merging
|
||||
|
||||
The command performs a 3-way merge of /etc configurations:
|
||||
|
||||
```rust
|
||||
let pristine_etc =
|
||||
Dir::open_ambient_dir(erofs_tmp_mnt.dir.path().join("etc"), ambient_authority())?;
|
||||
let current_etc = Dir::open_ambient_dir("/etc", ambient_authority())?;
|
||||
|
||||
let new_etc_path = Path::new(STATE_DIR_ABS)
|
||||
.join(&staged_composefs.verity)
|
||||
.join("etc");
|
||||
|
||||
let new_etc = Dir::open_ambient_dir(new_etc_path, ambient_authority())?;
|
||||
|
||||
let (pristine_files, current_files, new_files) =
|
||||
traverse_etc(&pristine_etc, ¤t_etc, &new_etc)?;
|
||||
|
||||
let diff = compute_diff(&pristine_files, ¤t_files)?;
|
||||
merge(¤t_etc, ¤t_files, &new_etc, &new_files, diff)?;
|
||||
```
|
||||
|
||||
### 5. Bootloader Management
|
||||
|
||||
The command updates bootloader entries based on the bootloader type and boot type:
|
||||
|
||||
```rust
|
||||
match booted_composefs.bootloader {
|
||||
Bootloader::Grub => match staged_composefs.boot_type {
|
||||
BootType::Bls => {
|
||||
let entries_dir = boot_dir.open_dir("loader")?;
|
||||
rename_exchange_bls_entries(&entries_dir)?;
|
||||
}
|
||||
BootType::Uki => finalize_staged_grub_uki(&esp_mount.fd, &boot_dir)?,
|
||||
},
|
||||
|
||||
Bootloader::Systemd => match staged_composefs.boot_type {
|
||||
BootType::Bls => {
|
||||
let entries_dir = esp_mount.fd.open_dir("loader")?;
|
||||
rename_exchange_bls_entries(&entries_dir)?;
|
||||
}
|
||||
BootType::Uki => rename_staged_uki_entries(&esp_mount.fd)?,
|
||||
},
|
||||
}
|
||||
```
|
||||
|
||||
## Command Routing
|
||||
|
||||
The command is routed through the main CLI dispatcher:
|
||||
|
||||
```rust
|
||||
#[cfg(feature = "composefs-backend")]
|
||||
Opt::ComposefsFinalizeStaged => composefs_native_finalize().await,
|
||||
```
|
||||
|
||||
## Systemd Integration
|
||||
|
||||
### Service Definition
|
||||
|
||||
The command is executed by a systemd service:
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Composefs Finalize Staged Deployment
|
||||
Documentation=man:bootc(1)
|
||||
DefaultDependencies=no
|
||||
|
||||
RequiresMountsFor=/sysroot
|
||||
After=local-fs.target
|
||||
Before=basic.target final.target
|
||||
After=systemd-journal-flush.service
|
||||
Conflicts=final.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
RemainAfterExit=yes
|
||||
ExecStop=/usr/bin/bootc composefs-finalize-staged
|
||||
TimeoutStopSec=5m
|
||||
ProtectHome=yes
|
||||
ReadOnlyPaths=/etc
|
||||
```
|
||||
|
||||
### Service Characteristics
|
||||
|
||||
- **Type**: oneshot - runs once and exits
|
||||
- **RemainAfterExit**: yes - service remains active after completion
|
||||
- **ExecStop**: executes the composefs-finalize-staged command
|
||||
- **TimeoutStopSec**: 5 minutes - long timeout for slow media
|
||||
- **ProtectHome**: yes - sandboxing for security
|
||||
- **ReadOnlyPaths**: /etc - prevents modification of current /etc
|
||||
|
||||
## Bootloader Operations
|
||||
|
||||
### GRUB Bootloader
|
||||
|
||||
#### BLS (Boot Loader Specification) Entries
|
||||
|
||||
```rust
|
||||
BootType::Bls => {
|
||||
let entries_dir = boot_dir.open_dir("loader")?;
|
||||
rename_exchange_bls_entries(&entries_dir)?;
|
||||
}
|
||||
```
|
||||
|
||||
#### UKI (Unified Kernel Image) Entries
|
||||
|
||||
```rust
|
||||
BootType::Uki => finalize_staged_grub_uki(&esp_mount.fd, &boot_dir)?,
|
||||
```
|
||||
|
||||
### systemd-boot Bootloader
|
||||
|
||||
#### BLS Entries
|
||||
|
||||
```rust
|
||||
BootType::Bls => {
|
||||
let entries_dir = esp_mount.fd.open_dir("loader")?;
|
||||
rename_exchange_bls_entries(&entries_dir)?;
|
||||
}
|
||||
```
|
||||
|
||||
#### UKI Entries
|
||||
|
||||
```rust
|
||||
BootType::Uki => rename_staged_uki_entries(&esp_mount.fd)?,
|
||||
```
|
||||
|
||||
## Filesystem Operations
|
||||
|
||||
### 1. EROFS Mounting
|
||||
|
||||
The command mounts EROFS images for access to pristine configuration:
|
||||
|
||||
```rust
|
||||
let composefs_fd = mount_composefs_image(&sysroot, &booted_composefs.verity, false)?;
|
||||
let erofs_tmp_mnt = TempMount::mount_fd(&composefs_fd)?;
|
||||
```
|
||||
|
||||
### 2. ESP Partition Mounting
|
||||
|
||||
The command mounts the ESP partition for bootloader operations:
|
||||
|
||||
```rust
|
||||
let sysroot_parent = get_sysroot_parent_dev()?;
|
||||
let (esp_part, ..) = get_esp_partition(&sysroot_parent)?;
|
||||
let esp_mount = TempMount::mount_dev(&esp_part)?;
|
||||
```
|
||||
|
||||
### 3. /etc Configuration Merging
|
||||
|
||||
The command performs 3-way merge of /etc configurations:
|
||||
|
||||
- **Pristine**: Original configuration from EROFS image
|
||||
- **Current**: Current system configuration
|
||||
- **New**: New configuration from staged deployment
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Common Error Scenarios
|
||||
|
||||
#### No Staged Deployment
|
||||
|
||||
```rust
|
||||
let Some(staged_depl) = host.status.staged.as_ref() else {
|
||||
tracing::debug!("No staged deployment found");
|
||||
return Ok(());
|
||||
};
|
||||
```
|
||||
|
||||
#### Non-Composefs Deployment
|
||||
|
||||
```rust
|
||||
let staged_composefs = staged_depl.composefs.as_ref().ok_or(anyhow::anyhow!(
|
||||
"Staged deployment is not a composefs deployment"
|
||||
))?;
|
||||
```
|
||||
|
||||
#### Filesystem Access Errors
|
||||
|
||||
```rust
|
||||
let sysroot = open_dir(CWD, "/sysroot")?;
|
||||
let composefs_fd = mount_composefs_image(&sysroot, &booted_composefs.verity, false)?;
|
||||
```
|
||||
|
||||
### 2. Error Recovery
|
||||
|
||||
The command provides comprehensive error context:
|
||||
|
||||
```rust
|
||||
#[context("Getting composefs deployment status")]
|
||||
pub(crate) async fn composefs_deployment_status() -> Result<Host> {
|
||||
// Implementation with automatic error context
|
||||
}
|
||||
```
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
### 1. Execution Time
|
||||
|
||||
- **Fast**: Optimized for early boot execution
|
||||
- **Efficient**: Minimal overhead for staging operations
|
||||
- **Atomic**: Single atomic operation
|
||||
|
||||
### 2. Resource Usage
|
||||
|
||||
- **Low CPU**: Minimal CPU usage
|
||||
- **Low Memory**: Minimal memory usage
|
||||
- **Disk I/O**: Efficient filesystem operations
|
||||
|
||||
### 3. System Impact
|
||||
|
||||
- **Early Boot**: Executes early in boot process
|
||||
- **Filesystem Access**: Accesses EROFS and ESP partitions
|
||||
- **Bootloader Updates**: Updates bootloader entries
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Privilege Requirements
|
||||
|
||||
The command requires appropriate privileges for:
|
||||
- Filesystem mounting operations
|
||||
- Bootloader entry modifications
|
||||
- System state management
|
||||
|
||||
### 2. Sandboxing
|
||||
|
||||
The systemd service provides sandboxing:
|
||||
- **ProtectHome**: yes - restricts home directory access
|
||||
- **ReadOnlyPaths**: /etc - prevents /etc modification
|
||||
|
||||
### 3. Access Control
|
||||
|
||||
The command accesses:
|
||||
- **EROFS images**: For pristine configuration
|
||||
- **ESP partition**: For bootloader operations
|
||||
- **System state**: For deployment management
|
||||
|
||||
## Integration Points
|
||||
|
||||
### 1. Composefs Backend
|
||||
|
||||
The command integrates with the composefs backend:
|
||||
|
||||
```rust
|
||||
#[cfg(feature = "composefs-backend")]
|
||||
use crate::bootc_composefs::{
|
||||
finalize::composefs_native_finalize, rollback::composefs_rollback, status::composefs_booted,
|
||||
switch::switch_composefs, update::upgrade_composefs,
|
||||
};
|
||||
```
|
||||
|
||||
### 2. Systemd Service
|
||||
|
||||
The command integrates with systemd for early boot execution:
|
||||
|
||||
```ini
|
||||
ExecStop=/usr/bin/bootc composefs-finalize-staged
|
||||
```
|
||||
|
||||
### 3. Bootloader Management
|
||||
|
||||
The command integrates with bootloader management:
|
||||
|
||||
```rust
|
||||
match booted_composefs.bootloader {
|
||||
Bootloader::Grub => { /* GRUB operations */ }
|
||||
Bootloader::Systemd => { /* systemd-boot operations */ }
|
||||
}
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. Staged Deployment Finalization
|
||||
|
||||
The primary use case is finalizing staged composefs deployments:
|
||||
|
||||
```bash
|
||||
# Executed by systemd service during boot
|
||||
systemctl start composefs-finalize-staged.service
|
||||
```
|
||||
|
||||
### 2. Boot Process Integration
|
||||
|
||||
The command integrates with the boot process:
|
||||
|
||||
```bash
|
||||
# Service runs early in boot process
|
||||
systemctl enable composefs-finalize-staged.service
|
||||
```
|
||||
|
||||
### 3. Configuration Management
|
||||
|
||||
The command manages /etc configuration merging:
|
||||
|
||||
```bash
|
||||
# Performs 3-way merge of /etc configurations
|
||||
# - Pristine: Original from EROFS
|
||||
# - Current: Current system
|
||||
# - New: Staged deployment
|
||||
```
|
||||
|
||||
### 4. Bootloader Updates
|
||||
|
||||
The command updates bootloader entries:
|
||||
|
||||
```bash
|
||||
# Updates GRUB or systemd-boot entries
|
||||
# - BLS entries for Boot Loader Specification
|
||||
# - UKI entries for Unified Kernel Image
|
||||
```
|
||||
|
||||
## Testing and Validation
|
||||
|
||||
### 1. Unit Tests
|
||||
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_composefs_native_finalize() {
|
||||
// Test finalization process
|
||||
let result = composefs_native_finalize().await;
|
||||
assert!(result.is_ok());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Integration Tests
|
||||
|
||||
```rust
|
||||
#[tokio::test]
|
||||
async fn test_composefs_finalize_integration() {
|
||||
// Test with staged deployment
|
||||
let test_env = TestEnvironment::new().await.unwrap();
|
||||
|
||||
// Create staged deployment
|
||||
test_env.create_staged_deployment().await.unwrap();
|
||||
|
||||
// Test finalization
|
||||
let result = composefs_native_finalize().await;
|
||||
assert!(result.is_ok());
|
||||
}
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Enhanced Error Handling
|
||||
|
||||
Enhanced error handling and recovery:
|
||||
|
||||
```rust
|
||||
pub(crate) struct FinalizeOptions {
|
||||
pub retry_attempts: u32,
|
||||
pub timeout_seconds: u64,
|
||||
pub rollback_on_failure: bool,
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Performance Monitoring
|
||||
|
||||
Performance monitoring and metrics:
|
||||
|
||||
```rust
|
||||
pub(crate) struct FinalizeMetrics {
|
||||
pub execution_time: Duration,
|
||||
pub files_processed: u64,
|
||||
pub merge_operations: u64,
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Configuration Options
|
||||
|
||||
Configuration options for finalization:
|
||||
|
||||
```rust
|
||||
pub(crate) struct FinalizeConfig {
|
||||
pub enable_etc_merge: bool,
|
||||
pub enable_bootloader_update: bool,
|
||||
pub backup_original: bool,
|
||||
}
|
||||
```
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc composefs-finalize-staged system's functionality, implementation, and usage patterns.
|
||||
Loading…
Add table
Add a link
Reference in a new issue