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
702
state/bootc-state-examples-troubleshooting.md
Normal file
702
state/bootc-state-examples-troubleshooting.md
Normal file
|
|
@ -0,0 +1,702 @@
|
|||
# bootc state - Examples and Troubleshooting
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides practical examples and troubleshooting guidance for the `bootc state` system, covering common use cases, error scenarios, and debugging techniques.
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. System Recovery
|
||||
|
||||
#### Complete System Reset
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Complete system reset script
|
||||
|
||||
echo "=== Bootc System Reset ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check current state
|
||||
echo "Current system state:"
|
||||
bootc status
|
||||
|
||||
# Confirm reset
|
||||
read -p "Are you sure you want to reset the system? (yes/no): " confirm
|
||||
if [ "$confirm" != "yes" ]; then
|
||||
echo "Reset cancelled"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Wipe all OSTree deployments
|
||||
echo "Wiping all OSTree deployments..."
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Verify wipe
|
||||
echo "Verifying wipe..."
|
||||
bootc status
|
||||
|
||||
# Check OSTree status
|
||||
echo "OSTree status:"
|
||||
ostree admin status
|
||||
|
||||
echo "System reset complete"
|
||||
```
|
||||
|
||||
#### Recovery from Corrupted State
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Recovery from corrupted state
|
||||
|
||||
echo "=== Bootc System Recovery ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check system state
|
||||
echo "Checking system state..."
|
||||
if ! bootc status > /dev/null 2>&1; then
|
||||
echo "System state is corrupted, attempting recovery..."
|
||||
|
||||
# Try to fix OSTree repository
|
||||
echo "Attempting to fix OSTree repository..."
|
||||
ostree fsck --repair
|
||||
|
||||
# If repair fails, wipe and reinstall
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Repair failed, wiping system..."
|
||||
bootc state wipe-ostree
|
||||
|
||||
echo "System wiped, ready for fresh installation"
|
||||
echo "Run: bootc install to-disk /dev/sda"
|
||||
else
|
||||
echo "Repository repaired successfully"
|
||||
fi
|
||||
else
|
||||
echo "System state is healthy"
|
||||
fi
|
||||
```
|
||||
|
||||
### 2. Development and Testing
|
||||
|
||||
#### Test Environment Reset
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Test environment reset script
|
||||
|
||||
echo "=== Test Environment Reset ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check if running in test environment
|
||||
if [ ! -f /etc/test-environment ]; then
|
||||
echo "ERROR: Not running in test environment"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Wipe test deployments
|
||||
echo "Wiping test deployments..."
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Clean up test data
|
||||
echo "Cleaning up test data..."
|
||||
rm -rf /var/lib/bootc/test-*
|
||||
rm -rf /tmp/bootc-test-*
|
||||
|
||||
# Reset test configuration
|
||||
echo "Resetting test configuration..."
|
||||
rm -f /etc/bootc/test-config.toml
|
||||
|
||||
echo "Test environment reset complete"
|
||||
```
|
||||
|
||||
#### Automated Testing
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Automated testing script
|
||||
|
||||
echo "=== Automated Testing ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Test 1: Normal wipe
|
||||
echo "Test 1: Normal wipe"
|
||||
bootc state wipe-ostree
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✓ Normal wipe test passed"
|
||||
else
|
||||
echo "✗ Normal wipe test failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Test 2: Wipe with no deployments
|
||||
echo "Test 2: Wipe with no deployments"
|
||||
bootc state wipe-ostree
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✓ Wipe with no deployments test passed"
|
||||
else
|
||||
echo "✗ Wipe with no deployments test failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
# Test 3: Verify system state
|
||||
echo "Test 3: Verify system state"
|
||||
bootc status
|
||||
if [ $? -eq 0 ]; then
|
||||
echo "✓ System state verification passed"
|
||||
else
|
||||
echo "✗ System state verification failed"
|
||||
exit 1
|
||||
fi
|
||||
|
||||
echo "All tests passed"
|
||||
```
|
||||
|
||||
### 3. System Maintenance
|
||||
|
||||
#### Scheduled Maintenance
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Scheduled maintenance script
|
||||
|
||||
echo "=== Scheduled Maintenance ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check system health
|
||||
echo "Checking system health..."
|
||||
if ! bootc status > /dev/null 2>&1; then
|
||||
echo "System health check failed, attempting recovery..."
|
||||
|
||||
# Try to fix system
|
||||
ostree fsck --repair
|
||||
|
||||
# If still failing, wipe and reinstall
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "System repair failed, wiping and reinstalling..."
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Reinstall system
|
||||
bootc install to-disk /dev/sda
|
||||
|
||||
echo "System reinstalled successfully"
|
||||
else
|
||||
echo "System repaired successfully"
|
||||
fi
|
||||
else
|
||||
echo "System health check passed"
|
||||
fi
|
||||
|
||||
# Log maintenance
|
||||
echo "Maintenance completed at $(date)" >> /var/log/bootc-maintenance.log
|
||||
```
|
||||
|
||||
#### Emergency Recovery
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Emergency recovery script
|
||||
|
||||
echo "=== Emergency Recovery ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check if system is bootable
|
||||
if ! systemctl is-system-running > /dev/null 2>&1; then
|
||||
echo "System is not running, attempting emergency recovery..."
|
||||
|
||||
# Mount root filesystem
|
||||
mount /dev/sda1 /mnt
|
||||
|
||||
# Change root and wipe deployments
|
||||
chroot /mnt bootc state wipe-ostree
|
||||
|
||||
# Unmount
|
||||
umount /mnt
|
||||
|
||||
echo "Emergency recovery completed"
|
||||
echo "System should be bootable now"
|
||||
else
|
||||
echo "System is running normally"
|
||||
fi
|
||||
```
|
||||
|
||||
### 4. System Migration
|
||||
|
||||
#### Migrate to New Configuration
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# System migration script
|
||||
|
||||
echo "=== System Migration ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Backup current configuration
|
||||
echo "Backing up current configuration..."
|
||||
cp -r /etc/bootc /etc/bootc.backup
|
||||
cp -r /var/lib/bootc /var/lib/bootc.backup
|
||||
|
||||
# Wipe current deployments
|
||||
echo "Wiping current deployments..."
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Install new configuration
|
||||
echo "Installing new configuration..."
|
||||
bootc install to-disk /dev/sda
|
||||
|
||||
# Verify new installation
|
||||
echo "Verifying new installation..."
|
||||
bootc status
|
||||
|
||||
echo "Migration completed successfully"
|
||||
```
|
||||
|
||||
#### Clean Installation
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Clean installation script
|
||||
|
||||
echo "=== Clean Installation ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Wipe existing deployments
|
||||
echo "Wiping existing deployments..."
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Clean up system
|
||||
echo "Cleaning up system..."
|
||||
rm -rf /var/lib/bootc/*
|
||||
rm -rf /etc/bootc/*
|
||||
|
||||
# Install fresh system
|
||||
echo "Installing fresh system..."
|
||||
bootc install to-disk /dev/sda
|
||||
|
||||
# Configure system
|
||||
echo "Configuring system..."
|
||||
bootc edit
|
||||
|
||||
echo "Clean installation completed"
|
||||
```
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### 1. Common Error Scenarios
|
||||
|
||||
#### Permission Denied Errors
|
||||
|
||||
**Error**: `Permission denied: This command must be executed as the root user`
|
||||
|
||||
**Cause**: Command executed without root privileges
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check current user
|
||||
whoami
|
||||
|
||||
# Switch to root
|
||||
sudo su -
|
||||
|
||||
# Or use sudo
|
||||
sudo bootc state wipe-ostree
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Check if running as root
|
||||
if [ "$EUID" -ne 0 ]; then
|
||||
echo "This script must be run as root"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
#### OSTree Not Available
|
||||
|
||||
**Error**: `OSTree not found`
|
||||
|
||||
**Cause**: OSTree package not installed
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Install OSTree
|
||||
apt update
|
||||
apt install ostree
|
||||
|
||||
# Verify installation
|
||||
ostree --version
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Check OSTree availability
|
||||
if ! command -v ostree &> /dev/null; then
|
||||
echo "OSTree is not installed"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
#### System Not OSTree-Based
|
||||
|
||||
**Error**: `No OSTree deployments found`
|
||||
|
||||
**Cause**: System is not OSTree-based
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Check if system is OSTree-based
|
||||
ostree admin status
|
||||
|
||||
# If not OSTree-based, install OSTree
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Check system type
|
||||
if ! ostree admin status > /dev/null 2>&1; then
|
||||
echo "System is not OSTree-based"
|
||||
exit 1
|
||||
fi
|
||||
```
|
||||
|
||||
#### OSTree Repository Corruption
|
||||
|
||||
**Error**: `OSTree repository corruption detected`
|
||||
|
||||
**Cause**: OSTree repository is corrupted
|
||||
|
||||
**Solution**:
|
||||
```bash
|
||||
# Try to repair repository
|
||||
ostree fsck --repair
|
||||
|
||||
# If repair fails, wipe and reinstall
|
||||
if [ $? -ne 0 ]; then
|
||||
bootc state wipe-ostree
|
||||
bootc install to-disk /dev/sda
|
||||
fi
|
||||
```
|
||||
|
||||
**Prevention**:
|
||||
```bash
|
||||
# Regular repository checks
|
||||
ostree fsck
|
||||
|
||||
# Backup important deployments
|
||||
ostree admin pin <deployment-id>
|
||||
```
|
||||
|
||||
### 2. Debugging Techniques
|
||||
|
||||
#### Enable Debug Logging
|
||||
|
||||
```bash
|
||||
# Set debug log level
|
||||
export RUST_LOG=debug
|
||||
|
||||
# Run command with debug output
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Check debug logs
|
||||
journalctl -u bootc-* --since "1 hour ago" | grep DEBUG
|
||||
```
|
||||
|
||||
#### Verbose Output
|
||||
|
||||
```bash
|
||||
# Enable verbose output
|
||||
bootc state wipe-ostree --verbose
|
||||
|
||||
# Check verbose logs
|
||||
journalctl -u bootc-* --since "1 hour ago" | grep -v INFO
|
||||
```
|
||||
|
||||
#### System Information
|
||||
|
||||
```bash
|
||||
# Gather system information
|
||||
uname -a
|
||||
lsb_release -a
|
||||
systemctl --version
|
||||
ostree --version
|
||||
bootc --version
|
||||
|
||||
# Check system configuration
|
||||
cat /etc/os-release
|
||||
cat /proc/version
|
||||
cat /proc/cpuinfo | head -20
|
||||
```
|
||||
|
||||
#### OSTree Diagnostics
|
||||
|
||||
```bash
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check repository integrity
|
||||
ostree fsck
|
||||
|
||||
# List all references
|
||||
ostree refs
|
||||
|
||||
# Show commit details
|
||||
ostree show <commit-hash>
|
||||
|
||||
# Check repository contents
|
||||
ostree ls <commit-hash>
|
||||
```
|
||||
|
||||
### 3. Recovery Procedures
|
||||
|
||||
#### System Recovery
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# System recovery script
|
||||
|
||||
echo "=== System Recovery ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check system status
|
||||
echo "Checking system status..."
|
||||
bootc status
|
||||
|
||||
# Check OSTree status
|
||||
echo "Checking OSTree status..."
|
||||
ostree admin status
|
||||
|
||||
# Check repository integrity
|
||||
echo "Checking repository integrity..."
|
||||
ostree fsck
|
||||
|
||||
# If errors found, attempt repair
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Repository errors detected, attempting repair..."
|
||||
ostree fsck --repair
|
||||
|
||||
# If repair fails, wipe and reinstall
|
||||
if [ $? -ne 0 ]; then
|
||||
echo "Repair failed, wiping and reinstalling..."
|
||||
bootc state wipe-ostree
|
||||
bootc install to-disk /dev/sda
|
||||
fi
|
||||
fi
|
||||
|
||||
# Verify system is working
|
||||
echo "Verifying system is working..."
|
||||
bootc status
|
||||
bootc status
|
||||
|
||||
echo "Recovery complete"
|
||||
```
|
||||
|
||||
#### Data Recovery
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Data recovery script
|
||||
|
||||
echo "=== Data Recovery ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check for available backups
|
||||
echo "Checking for available backups..."
|
||||
ls -la /var/lib/bootc/backups/
|
||||
|
||||
# List available deployments
|
||||
echo "Available deployments:"
|
||||
ostree admin status
|
||||
|
||||
# Check deployment history
|
||||
echo "Deployment history:"
|
||||
ostree log <deployment-id>
|
||||
|
||||
# Attempt to recover specific deployment
|
||||
echo "Attempting to recover deployment..."
|
||||
ostree admin deploy <deployment-id>
|
||||
|
||||
# Verify recovery
|
||||
echo "Verifying recovery..."
|
||||
bootc status
|
||||
```
|
||||
|
||||
### 4. Performance Analysis
|
||||
|
||||
#### System Performance
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# System performance analysis
|
||||
|
||||
echo "=== System Performance Analysis ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check system load
|
||||
echo "System load:"
|
||||
uptime
|
||||
|
||||
# Check memory usage
|
||||
echo "Memory usage:"
|
||||
free -h
|
||||
|
||||
# Check disk usage
|
||||
echo "Disk usage:"
|
||||
df -h
|
||||
|
||||
# Check I/O usage
|
||||
echo "I/O usage:"
|
||||
iotop -bn1
|
||||
|
||||
# Check process usage
|
||||
echo "Process usage:"
|
||||
top -bn1 | head -20
|
||||
```
|
||||
|
||||
#### Command Performance
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Command performance analysis
|
||||
|
||||
echo "=== Command Performance Analysis ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Time wipe operation
|
||||
echo "Timing wipe operation..."
|
||||
time bootc state wipe-ostree
|
||||
|
||||
# Check resource usage
|
||||
echo "Resource usage:"
|
||||
ps aux | grep bootc | awk '{sum+=$6} END {print sum/1024 " MB"}'
|
||||
|
||||
# Check system load
|
||||
echo "System load:"
|
||||
uptime
|
||||
```
|
||||
|
||||
### 5. Monitoring and Alerting
|
||||
|
||||
#### Health Check Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Health check script
|
||||
|
||||
HEALTH_STATUS=0
|
||||
|
||||
echo "=== Bootc State Health Check ==="
|
||||
echo "Date: $(date)"
|
||||
echo
|
||||
|
||||
# Check system status
|
||||
echo "Checking system status..."
|
||||
if ! bootc status > /dev/null 2>&1; then
|
||||
echo "ERROR: System status check failed"
|
||||
HEALTH_STATUS=1
|
||||
fi
|
||||
|
||||
# Check OSTree status
|
||||
echo "Checking OSTree status..."
|
||||
if ! ostree admin status > /dev/null 2>&1; then
|
||||
echo "ERROR: OSTree status check failed"
|
||||
HEALTH_STATUS=1
|
||||
fi
|
||||
|
||||
# Check repository integrity
|
||||
echo "Checking repository integrity..."
|
||||
if ! ostree fsck > /dev/null 2>&1; then
|
||||
echo "ERROR: Repository integrity check failed"
|
||||
HEALTH_STATUS=1
|
||||
fi
|
||||
|
||||
# Check storage usage
|
||||
echo "Checking storage usage..."
|
||||
STORAGE_USAGE=$(df /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//')
|
||||
if [ $STORAGE_USAGE -gt 90 ]; then
|
||||
echo "ERROR: Storage usage is critical: ${STORAGE_USAGE}%"
|
||||
HEALTH_STATUS=1
|
||||
elif [ $STORAGE_USAGE -gt 80 ]; then
|
||||
echo "WARNING: Storage usage is high: ${STORAGE_USAGE}%"
|
||||
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\": \"bootc-state\",
|
||||
\"severity\": \"$severity\",
|
||||
\"message\": \"$message\",
|
||||
\"timestamp\": \"$(date -Iseconds)\"
|
||||
}"
|
||||
}
|
||||
|
||||
# Check system health
|
||||
if ! /usr/local/bin/bootc-state-health-check.sh; then
|
||||
send_alert "critical" "Bootc state system health check failed"
|
||||
fi
|
||||
|
||||
# Check storage usage
|
||||
STORAGE_USAGE=$(df /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//')
|
||||
if [ $STORAGE_USAGE -gt 90 ]; then
|
||||
send_alert "critical" "Storage usage is critical: ${STORAGE_USAGE}%"
|
||||
elif [ $STORAGE_USAGE -gt 80 ]; then
|
||||
send_alert "warning" "Storage usage is high: ${STORAGE_USAGE}%"
|
||||
fi
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Usage Guidelines
|
||||
|
||||
- **Backup First**: Always backup important data before wiping
|
||||
- **Verify System**: Ensure system is OSTree-based before wiping
|
||||
- **Plan Recovery**: Have recovery plan ready
|
||||
- **Test First**: Test in non-production environment
|
||||
|
||||
### 2. Safety Measures
|
||||
|
||||
- **Confirmation**: Consider adding confirmation prompt
|
||||
- **Logging**: Log all wipe operations
|
||||
- **Monitoring**: Monitor system after wipe
|
||||
- **Documentation**: Document wipe procedures
|
||||
|
||||
### 3. Recovery Procedures
|
||||
|
||||
- **Fresh Install**: Plan for fresh installation
|
||||
- **Data Recovery**: Ensure data is backed up
|
||||
- **System Restore**: Have system restore plan
|
||||
- **Testing**: Test recovery procedures
|
||||
|
||||
This comprehensive examples and troubleshooting guide provides practical solutions for common issues and advanced debugging techniques for the bootc state system.
|
||||
949
state/bootc-state-external-commands.md
Normal file
949
state/bootc-state-external-commands.md
Normal file
|
|
@ -0,0 +1,949 @@
|
|||
# bootc state - External Commands Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive reference for all external commands used by `bootc state` operations. These commands are essential for understanding the dependencies and integration points of the bootc state system.
|
||||
|
||||
## Core Commands
|
||||
|
||||
### bootc
|
||||
|
||||
**Purpose**: Main bootc command for state operations
|
||||
**Usage**: `bootc state <subcommand> [options...]`
|
||||
**Dependencies**: None (core command)
|
||||
|
||||
#### State Subcommands
|
||||
- `bootc state wipe-ostree` - Remove all OSTree deployments
|
||||
- `bootc state help` - Show help information
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Wipe all OSTree deployments
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Show help
|
||||
bootc state --help
|
||||
bootc state wipe-ostree --help
|
||||
```
|
||||
|
||||
## OSTree Commands
|
||||
|
||||
### ostree
|
||||
|
||||
**Purpose**: OSTree repository operations
|
||||
**Usage**: `ostree <subcommand> [options...]`
|
||||
**Dependencies**: ostree package
|
||||
|
||||
#### Repository Commands
|
||||
- `ostree admin status` - Show admin status
|
||||
- `ostree log` - Show commit log
|
||||
- `ostree show` - Show commit details
|
||||
- `ostree refs` - List references
|
||||
- `ostree ls` - List repository contents
|
||||
- `ostree cat` - Show file contents
|
||||
- `ostree checkout` - Checkout files
|
||||
- `ostree admin pin` - Pin deployments
|
||||
- `ostree admin unpin` - Unpin deployments
|
||||
- `ostree admin deploy` - Deploy commits
|
||||
- `ostree admin rollback` - Rollback deployments
|
||||
- `ostree admin cleanup` - Clean up deployments
|
||||
- `ostree fsck` - Check repository integrity
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show current status
|
||||
ostree admin status
|
||||
|
||||
# List all references
|
||||
ostree refs
|
||||
|
||||
# Show commit details
|
||||
ostree show <commit-hash>
|
||||
|
||||
# List repository contents
|
||||
ostree ls <commit-hash>
|
||||
|
||||
# Show file contents
|
||||
ostree cat <commit-hash> /path/to/file
|
||||
|
||||
# Checkout files
|
||||
ostree checkout <commit-hash> /path/to/destination
|
||||
|
||||
# Deploy commit
|
||||
ostree admin deploy <commit-hash>
|
||||
|
||||
# Rollback deployment
|
||||
ostree admin rollback
|
||||
|
||||
# Clean up deployments
|
||||
ostree admin cleanup
|
||||
|
||||
# Check repository integrity
|
||||
ostree fsck
|
||||
```
|
||||
|
||||
### ostree-ext
|
||||
|
||||
**Purpose**: Extended OSTree operations
|
||||
**Usage**: `ostree-ext <subcommand> [options...]`
|
||||
**Dependencies**: ostree-ext package
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Container operations
|
||||
ostree-ext container pull quay.io/myorg/image:latest
|
||||
|
||||
# Repository operations
|
||||
ostree-ext repo create /path/to/repo
|
||||
|
||||
# Image operations
|
||||
ostree-ext image build /path/to/image
|
||||
```
|
||||
|
||||
## System Commands
|
||||
|
||||
### systemctl
|
||||
|
||||
**Purpose**: Systemd service management
|
||||
**Usage**: `systemctl <subcommand> [options...]`
|
||||
**Dependencies**: systemd
|
||||
|
||||
#### Service Commands
|
||||
- `systemctl status` - Show service status
|
||||
- `systemctl start` - Start service
|
||||
- `systemctl stop` - Stop service
|
||||
- `systemctl restart` - Restart service
|
||||
- `systemctl enable` - Enable service
|
||||
- `systemctl disable` - Disable service
|
||||
- `systemctl reload` - Reload service
|
||||
- `systemctl daemon-reload` - Reload systemd configuration
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Check service status
|
||||
systemctl status bootc-*
|
||||
|
||||
# Start service
|
||||
systemctl start bootc-*
|
||||
|
||||
# Enable service
|
||||
systemctl enable bootc-*
|
||||
|
||||
# Reload systemd configuration
|
||||
systemctl daemon-reload
|
||||
```
|
||||
|
||||
### journalctl
|
||||
|
||||
**Purpose**: Systemd journal viewing
|
||||
**Usage**: `journalctl [options...]`
|
||||
**Dependencies**: systemd
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show all logs
|
||||
journalctl
|
||||
|
||||
# Show logs for service
|
||||
journalctl -u bootc-*
|
||||
|
||||
# Show recent logs
|
||||
journalctl -n 100
|
||||
|
||||
# Follow logs
|
||||
journalctl -f
|
||||
|
||||
# Show logs since time
|
||||
journalctl --since "1 hour ago"
|
||||
|
||||
# Show logs with priority
|
||||
journalctl -p err
|
||||
```
|
||||
|
||||
## Filesystem Commands
|
||||
|
||||
### mount
|
||||
|
||||
**Purpose**: Filesystem mounting
|
||||
**Usage**: `mount [options...] <device> <directory>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Mount filesystem
|
||||
mount /dev/sda1 /mnt
|
||||
|
||||
# Unmount filesystem
|
||||
umount /mnt
|
||||
|
||||
# Check mount points
|
||||
findmnt
|
||||
|
||||
# Mount with options
|
||||
mount -o ro,noexec /dev/sda1 /mnt
|
||||
```
|
||||
|
||||
### umount
|
||||
|
||||
**Purpose**: Unmount filesystems
|
||||
**Usage**: `umount [options...] <directory>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Unmount filesystem
|
||||
umount /mnt
|
||||
|
||||
# Force unmount
|
||||
umount -f /mnt
|
||||
|
||||
# Lazy unmount
|
||||
umount -l /mnt
|
||||
```
|
||||
|
||||
### df
|
||||
|
||||
**Purpose**: Disk space usage
|
||||
**Usage**: `df [options...] [file...]`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show disk usage
|
||||
df -h
|
||||
|
||||
# Show specific filesystem
|
||||
df -h /var/lib/bootc
|
||||
|
||||
# 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 /var/lib/bootc
|
||||
|
||||
# Show total usage
|
||||
du -sh /var/lib/bootc
|
||||
|
||||
# Show usage by subdirectory
|
||||
du -h --max-depth=1 /var/lib/bootc
|
||||
|
||||
# Show usage of all files
|
||||
du -ah /var/lib/bootc
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
### 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 process_name
|
||||
```
|
||||
|
||||
### pkill
|
||||
|
||||
**Purpose**: Kill processes by name
|
||||
**Usage**: `pkill [options...] <pattern>`
|
||||
**Dependencies**: procps
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Kill by name
|
||||
pkill process_name
|
||||
|
||||
# Force kill by name
|
||||
pkill -9 process_name
|
||||
|
||||
# Kill by pattern
|
||||
pkill -f "pattern"
|
||||
```
|
||||
|
||||
## File Commands
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### find
|
||||
|
||||
**Purpose**: Find files
|
||||
**Usage**: `find [path...] [expression]`
|
||||
**Dependencies**: findutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Find files by name
|
||||
find /path -name "*.txt"
|
||||
|
||||
# Find files by type
|
||||
find /path -type f
|
||||
|
||||
# Find files by size
|
||||
find /path -size +100M
|
||||
|
||||
# Find files by modification time
|
||||
find /path -mtime -7
|
||||
|
||||
# Find files by permissions
|
||||
find /path -perm 644
|
||||
```
|
||||
|
||||
### stat
|
||||
|
||||
**Purpose**: File status
|
||||
**Usage**: `stat [options...] [file...]`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Show file status
|
||||
stat file.txt
|
||||
|
||||
# Show in custom format
|
||||
stat -c "%n %s %Y" file.txt
|
||||
|
||||
# Show filesystem status
|
||||
stat -f /path
|
||||
|
||||
# Show with format
|
||||
stat --format="%n: %s bytes" file.txt
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## Container Commands
|
||||
|
||||
### podman
|
||||
|
||||
**Purpose**: Container runtime
|
||||
**Usage**: `podman <subcommand> [options...]`
|
||||
**Dependencies**: podman
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# List containers
|
||||
podman ps
|
||||
|
||||
# List images
|
||||
podman images
|
||||
|
||||
# Pull image
|
||||
podman pull quay.io/myorg/image:latest
|
||||
|
||||
# Run container
|
||||
podman run -it image:latest
|
||||
|
||||
# Build image
|
||||
podman build -t myimage:latest .
|
||||
|
||||
# Inspect image
|
||||
podman inspect image:latest
|
||||
```
|
||||
|
||||
### docker
|
||||
|
||||
**Purpose**: Alternative container runtime
|
||||
**Usage**: `docker <subcommand> [options...]`
|
||||
**Dependencies**: docker
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# List containers
|
||||
docker ps
|
||||
|
||||
# List images
|
||||
docker images
|
||||
|
||||
# Pull image
|
||||
docker pull quay.io/myorg/image:latest
|
||||
|
||||
# Run container
|
||||
docker run -it image:latest
|
||||
|
||||
# Build image
|
||||
docker build -t myimage:latest .
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
### 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 "Bootc" -l /EFI/bootc/grubx64.efi
|
||||
|
||||
# Delete boot entry
|
||||
efibootmgr -b 0000 -B
|
||||
|
||||
# Set boot order
|
||||
efibootmgr -o 0000,0001,0002
|
||||
```
|
||||
|
||||
## Recovery Commands
|
||||
|
||||
### chroot
|
||||
|
||||
**Purpose**: Change root directory
|
||||
**Usage**: `chroot [options...] <directory> <command>`
|
||||
**Dependencies**: coreutils
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Change root
|
||||
chroot /mnt /bin/bash
|
||||
|
||||
# Change root with specific command
|
||||
chroot /mnt /bin/ls
|
||||
|
||||
# Change root with environment
|
||||
chroot /mnt env -i /bin/bash
|
||||
```
|
||||
|
||||
### mount
|
||||
|
||||
**Purpose**: Mount filesystems for recovery
|
||||
**Usage**: `mount [options...] <device> <directory>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Mount root filesystem
|
||||
mount /dev/sda1 /mnt
|
||||
|
||||
# Mount boot filesystem
|
||||
mount /dev/sda2 /mnt/boot
|
||||
|
||||
# Mount with specific options
|
||||
mount -o ro /dev/sda1 /mnt
|
||||
```
|
||||
|
||||
### umount
|
||||
|
||||
**Purpose**: Unmount filesystems after recovery
|
||||
**Usage**: `umount [options...] <directory>`
|
||||
**Dependencies**: util-linux
|
||||
|
||||
#### Examples
|
||||
```bash
|
||||
# Unmount filesystem
|
||||
umount /mnt
|
||||
|
||||
# Unmount all filesystems
|
||||
umount -a
|
||||
|
||||
# Force unmount
|
||||
umount -f /mnt
|
||||
```
|
||||
|
||||
This comprehensive reference covers all external commands used by the bootc state system, providing examples and usage patterns for each command.
|
||||
406
state/bootc-state-flowchart.md
Normal file
406
state/bootc-state-flowchart.md
Normal file
|
|
@ -0,0 +1,406 @@
|
|||
# bootc state - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc state` process flow, showing the decision points, operations, and system state changes involved in state modification operations.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Parse Command Arguments │
|
||||
│ │
|
||||
│ • Parse state subcommand │
|
||||
│ • Validate arguments │
|
||||
│ • Check permissions │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Route to Subcommand │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Subcommand Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ wipe-ostree │ │
|
||||
│ │ │ │
|
||||
│ │ • Remove all OSTree deployments │ │
|
||||
│ │ • Reset system state │ │
|
||||
│ │ • Prepare for fresh installation │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • State modification completed successfully │
|
||||
│ • System state updated │
|
||||
│ • Deployments removed │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## wipe-ostree Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ wipe-ostree Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Prerequisites │
|
||||
│ │
|
||||
│ • Verify root privileges │
|
||||
│ • Check OSTree availability │
|
||||
│ • Validate system state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initialize OSTree │
|
||||
│ │
|
||||
│ • Create OSTree sysroot instance │
|
||||
│ • Load sysroot configuration │
|
||||
│ • Prepare for operations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute Wipe Operation │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Wipe Operation │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Spawn Blocking Task │ │
|
||||
│ │ │ │
|
||||
│ │ • Move to blocking thread │ │
|
||||
│ │ • Execute OSTree operations │ │
|
||||
│ │ • Handle cancellable operations │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Write Empty Deployments │ │
|
||||
│ │ │ │
|
||||
│ │ • Call sysroot.write_deployments(&[]) │ │
|
||||
│ │ • Remove all deployment entries │ │
|
||||
│ │ • Update system state │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Operation │
|
||||
│ │
|
||||
│ • Check operation success │
|
||||
│ • Verify deployments removed │
|
||||
│ • Update system state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • All OSTree deployments removed │
|
||||
│ • System state reset │
|
||||
│ • Ready for fresh installation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## System State Transitions
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ System States │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initial State │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ System with OSTree Deployments │ │
|
||||
│ │ │ │
|
||||
│ │ • Active deployments present │ │
|
||||
│ │ • Boot entries configured │ │
|
||||
│ │ • System state managed │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Execute wipe-ostree │ │
|
||||
│ │ │ │
|
||||
│ │ • Remove all deployments │ │
|
||||
│ │ • Clear boot entries │ │
|
||||
│ │ • Reset system state │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Final State │ │
|
||||
│ │ │ │
|
||||
│ │ • No OSTree deployments │ │
|
||||
│ │ • No boot entries │ │
|
||||
│ │ • Clean system state │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Permission │ │ OSTree │ │ System │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Not Root │ │ • Not Available │ │ • Not OSTree │ │
|
||||
│ │ • Access Denied │ │ • Load Failed │ │ • Corrupted │ │
|
||||
│ │ • Invalid User │ │ • Write Failed │ │ • Unavailable │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Response │
|
||||
│ │
|
||||
│ • Display error message │
|
||||
│ • Provide context information │
|
||||
│ • Suggest remediation steps │
|
||||
│ • Return appropriate exit code │
|
||||
│ • Log error details │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## OSTree Operations Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ OSTree Operations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initialize Sysroot │
|
||||
│ │
|
||||
│ • Create OSTree::Sysroot::new_default() │
|
||||
│ • Load sysroot configuration │
|
||||
│ • Prepare for operations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute Operations │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Operation Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Write Deployments │ │
|
||||
│ │ │ │
|
||||
│ │ • Call write_deployments(&[]) │ │
|
||||
│ │ • Remove all deployment entries │ │
|
||||
│ │ • Update system metadata │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Results │
|
||||
│ │
|
||||
│ • Check operation success │
|
||||
│ • Verify deployments removed │
|
||||
│ • Update system state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • OSTree operations completed │
|
||||
│ • System state updated │
|
||||
│ • Deployments removed │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Asynchronous Execution Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Asynchronous Execution │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Spawn Blocking Task │
|
||||
│ │
|
||||
│ • Create tokio::task::spawn_blocking │
|
||||
│ • Move sysroot to blocking thread │
|
||||
│ • Prepare for OSTree operations │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute in Blocking Context │
|
||||
│ │
|
||||
│ • Run OSTree operations │
|
||||
│ │ • sysroot.write_deployments(&[]) │
|
||||
│ │ • Handle cancellable operations │
|
||||
│ │ • Update system state │
|
||||
│ • Return results to async context │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Await Results │
|
||||
│ │
|
||||
│ • Wait for blocking task completion │
|
||||
│ • Handle any errors │
|
||||
│ • Return results to caller │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Asynchronous operation completed │
|
||||
│ • Results returned to caller │
|
||||
│ • System state updated │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## System Impact Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ System Impact Analysis │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Before Wipe │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ System State │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Deployments │ │ Boot Entries │ │ System State │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Active │ │ • Grub entries │ │ • Managed │ │
|
||||
│ │ • Staged │ │ • Systemd │ │ • Configured │ │
|
||||
│ │ • Rollback │ │ • Bootloader │ │ • Tracked │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ During Wipe │
|
||||
│ │
|
||||
│ • Remove all deployments │
|
||||
│ • Clear boot entries │
|
||||
│ • Reset system state │
|
||||
│ • Update metadata │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ After Wipe │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ System State │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Deployments │ │ Boot Entries │ │ System State │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • None │ │ • None │ │ • Clean │ │
|
||||
│ │ • Removed │ │ • Cleared │ │ • Reset │ │
|
||||
│ │ • Wiped │ │ • Removed │ │ • Fresh │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Recovery Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Recovery Process │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Assess System State │
|
||||
│ │
|
||||
│ • Check if system is bootable │
|
||||
│ • Verify data integrity │
|
||||
│ • Determine recovery needs │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Recovery Options │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Recovery Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Fresh Install │ │ Restore │ │ Manual │ │
|
||||
│ │ │ │ Backup │ │ Recovery │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ Install ││ │ │ Restore ││ │ │ Fix ││ │
|
||||
│ │ │ New System ││ │ │ From Backup ││ │ │ Manually ││ │
|
||||
│ │ │ Configure ││ │ │ Restore ││ │ │ Rebuild ││ │
|
||||
│ │ │ Deploy ││ │ │ Data ││ │ │ System ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Recovery │
|
||||
│ │
|
||||
│ • Test system bootability │
|
||||
│ • Verify data integrity │
|
||||
│ • Check system functionality │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • System recovered successfully │
|
||||
│ • Data integrity verified │
|
||||
│ • System functionality restored │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc state process, showing all decision points, operations, and state transitions involved in state modification operations.
|
||||
292
state/bootc-state-quick-reference.md
Normal file
292
state/bootc-state-quick-reference.md
Normal file
|
|
@ -0,0 +1,292 @@
|
|||
# bootc state - Quick Reference
|
||||
|
||||
## Command Summary
|
||||
|
||||
| Command | Purpose | Usage |
|
||||
|---------|---------|-------|
|
||||
| `wipe-ostree` | Remove all OSTree deployments | `bootc state wipe-ostree` |
|
||||
| `help` | Show help information | `bootc state --help` |
|
||||
|
||||
## Quick Commands
|
||||
|
||||
### Basic Operations
|
||||
```bash
|
||||
# Wipe all OSTree deployments
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Show help
|
||||
bootc state --help
|
||||
bootc state wipe-ostree --help
|
||||
```
|
||||
|
||||
### System Status
|
||||
```bash
|
||||
# Check current state
|
||||
bootc status
|
||||
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check system health
|
||||
bootc status && echo "System healthy"
|
||||
```
|
||||
|
||||
### Recovery Operations
|
||||
```bash
|
||||
# Complete system reset
|
||||
bootc state wipe-ostree && bootc install to-disk /dev/sda
|
||||
|
||||
# Emergency recovery
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Verify recovery
|
||||
bootc status
|
||||
```
|
||||
|
||||
## Common Options
|
||||
|
||||
| Option | Purpose | Example |
|
||||
|--------|---------|---------|
|
||||
| `--help` | Show help | `bootc state --help` |
|
||||
| `--verbose` | Verbose output | `bootc state wipe-ostree --verbose` |
|
||||
| `--quiet` | Quiet output | `bootc state wipe-ostree --quiet` |
|
||||
|
||||
## Error Codes
|
||||
|
||||
| Code | Meaning | Solution |
|
||||
|------|---------|----------|
|
||||
| 1 | General error | Check logs for details |
|
||||
| 2 | Permission denied | Run as root |
|
||||
| 3 | OSTree not available | Install OSTree |
|
||||
| 4 | System not OSTree-based | Install OSTree system |
|
||||
| 5 | Repository corruption | Repair or wipe repository |
|
||||
|
||||
## Common Issues
|
||||
|
||||
### Permission Denied
|
||||
```bash
|
||||
# Check user
|
||||
whoami
|
||||
|
||||
# Run as root
|
||||
sudo bootc state wipe-ostree
|
||||
```
|
||||
|
||||
### OSTree Not Available
|
||||
```bash
|
||||
# Install OSTree
|
||||
apt install ostree
|
||||
|
||||
# Verify installation
|
||||
ostree --version
|
||||
```
|
||||
|
||||
### System Not OSTree-Based
|
||||
```bash
|
||||
# Check system type
|
||||
ostree admin status
|
||||
|
||||
# Install OSTree system
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
### Repository Corruption
|
||||
```bash
|
||||
# Check repository
|
||||
ostree fsck
|
||||
|
||||
# Repair repository
|
||||
ostree fsck --repair
|
||||
|
||||
# If repair fails, wipe and reinstall
|
||||
bootc state wipe-ostree
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
## 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` |
|
||||
| OSTree repo | Repository data | `/var/lib/bootc/ostree/` |
|
||||
| System state | System state | `/var/lib/bootc/state/` |
|
||||
|
||||
## Log Files
|
||||
|
||||
| File | Purpose | Location |
|
||||
|------|---------|----------|
|
||||
| System logs | System messages | `/var/log/messages` |
|
||||
| Journal logs | Systemd journal | `journalctl -u bootc-*` |
|
||||
| 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 /var/lib/bootc
|
||||
```
|
||||
|
||||
### Monitor System
|
||||
```bash
|
||||
# Check system status
|
||||
bootc status
|
||||
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check repository integrity
|
||||
ostree fsck
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### Root Privileges
|
||||
- All state commands require root privileges
|
||||
- Use `sudo` or switch to root user
|
||||
- Check current user with `whoami`
|
||||
|
||||
### Destructive Operations
|
||||
- This is a destructive operation that cannot be undone
|
||||
- Always backup important data before execution
|
||||
- Verify system can be reinstalled
|
||||
|
||||
### Safety Checks
|
||||
- Check system state before wiping
|
||||
- Ensure recovery plan is ready
|
||||
- Test in non-production environment
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Regular Maintenance
|
||||
- Check system health regularly
|
||||
- Monitor storage usage
|
||||
- Check repository integrity
|
||||
- Plan for recovery
|
||||
|
||||
### Development
|
||||
- Use test environments
|
||||
- Test commands before production
|
||||
- Document procedures
|
||||
- Monitor system health
|
||||
|
||||
### Production
|
||||
- Set up monitoring
|
||||
- Configure alerts
|
||||
- Regular backups
|
||||
- Document procedures
|
||||
|
||||
## Troubleshooting Steps
|
||||
|
||||
1. **Check system status**
|
||||
```bash
|
||||
bootc status
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
2. **Check logs**
|
||||
```bash
|
||||
journalctl -u bootc-* --since "1 hour ago"
|
||||
tail -f /var/log/bootc/main.log
|
||||
```
|
||||
|
||||
3. **Check resources**
|
||||
```bash
|
||||
df -h /var/lib/bootc
|
||||
free -h
|
||||
uptime
|
||||
```
|
||||
|
||||
4. **Run diagnostics**
|
||||
```bash
|
||||
ostree fsck
|
||||
bootc status
|
||||
```
|
||||
|
||||
5. **Check configuration**
|
||||
```bash
|
||||
cat /etc/bootc/config.toml
|
||||
systemctl daemon-reload
|
||||
```
|
||||
|
||||
## Quick Scripts
|
||||
|
||||
### Health Check
|
||||
```bash
|
||||
#!/bin/bash
|
||||
bootc status && ostree admin status && echo "System healthy"
|
||||
```
|
||||
|
||||
### System Reset
|
||||
```bash
|
||||
#!/bin/bash
|
||||
bootc state wipe-ostree && echo "System reset complete"
|
||||
```
|
||||
|
||||
### Recovery
|
||||
```bash
|
||||
#!/bin/bash
|
||||
bootc state wipe-ostree && bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
```bash
|
||||
#!/bin/bash
|
||||
df -h /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//'
|
||||
```
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Systemd Service
|
||||
```bash
|
||||
# Create service file
|
||||
cat > /etc/systemd/system/bootc-state.service << EOF
|
||||
[Unit]
|
||||
Description=Bootc State Service
|
||||
After=multi-user.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/local/bin/bootc-state-script.sh
|
||||
User=root
|
||||
Group=root
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
EOF
|
||||
|
||||
# Enable service
|
||||
systemctl daemon-reload
|
||||
systemctl enable bootc-state.service
|
||||
```
|
||||
|
||||
### Cron Job
|
||||
```bash
|
||||
# Add to crontab
|
||||
echo "0 2 * * * /usr/local/bin/bootc-state-maintenance.sh" | crontab -
|
||||
```
|
||||
|
||||
### Monitoring
|
||||
```bash
|
||||
# Check system health
|
||||
if ! bootc status > /dev/null 2>&1; then
|
||||
echo "WARNING: System status check failed"
|
||||
# Send alert
|
||||
fi
|
||||
```
|
||||
|
||||
This quick reference provides essential information for using the bootc state system effectively.
|
||||
504
state/bootc-state-technical-guide.md
Normal file
504
state/bootc-state-technical-guide.md
Normal file
|
|
@ -0,0 +1,504 @@
|
|||
# bootc state - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc state` is a hidden command that provides system state modification operations for bootc systems. Currently, it contains a single critical command: `wipe-ostree`, which removes all OSTree deployments from the system.
|
||||
|
||||
## Purpose
|
||||
|
||||
The state commands serve critical system management functions:
|
||||
|
||||
1. **System Reset**: Complete removal of all OSTree deployments
|
||||
2. **Clean Slate**: Prepare system for fresh installation
|
||||
3. **Recovery**: Reset system to a clean state when deployments are corrupted
|
||||
4. **Maintenance**: Remove all bootc-managed state
|
||||
|
||||
## Command Structure
|
||||
|
||||
```rust
|
||||
#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
|
||||
pub(crate) enum StateOpts {
|
||||
/// Remove all ostree deployments from this system
|
||||
WipeOstree,
|
||||
}
|
||||
```
|
||||
|
||||
## Core Command: wipe-ostree
|
||||
|
||||
### Purpose
|
||||
|
||||
The `wipe-ostree` command completely removes all OSTree deployments from the system, effectively resetting the bootc-managed state to a clean slate.
|
||||
|
||||
### Usage
|
||||
|
||||
```bash
|
||||
bootc state wipe-ostree
|
||||
```
|
||||
|
||||
### Functionality
|
||||
|
||||
- **Complete Removal**: Removes all OSTree deployments from the system
|
||||
- **System Reset**: Resets the system to a state where no bootc deployments exist
|
||||
- **Clean Slate**: Prepares the system for fresh installation
|
||||
- **Recovery**: Can be used to recover from corrupted deployment states
|
||||
|
||||
### Implementation
|
||||
|
||||
```rust
|
||||
pub(crate) async fn wipe_ostree(sysroot: Sysroot) -> Result<()> {
|
||||
tokio::task::spawn_blocking(move || {
|
||||
sysroot
|
||||
.write_deployments(&[], gio::Cancellable::NONE)
|
||||
.context("removing deployments")
|
||||
})
|
||||
.await??;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### Command Routing
|
||||
|
||||
The command is routed through the main CLI dispatcher:
|
||||
|
||||
```rust
|
||||
Opt::State(opts) => match opts {
|
||||
StateOpts::WipeOstree => {
|
||||
let sysroot = ostree::Sysroot::new_default();
|
||||
sysroot.load(gio::Cancellable::NONE)?;
|
||||
crate::deploy::wipe_ostree(sysroot).await?;
|
||||
Ok(())
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Technical Details
|
||||
|
||||
### 1. OSTree Integration
|
||||
|
||||
The `wipe-ostree` command directly interfaces with the OSTree library:
|
||||
|
||||
```rust
|
||||
// Create OSTree sysroot instance
|
||||
let sysroot = ostree::Sysroot::new_default();
|
||||
|
||||
// Load the sysroot
|
||||
sysroot.load(gio::Cancellable::NONE)?;
|
||||
|
||||
// Remove all deployments by writing empty array
|
||||
sysroot.write_deployments(&[], gio::Cancellable::NONE)
|
||||
.context("removing deployments")?;
|
||||
```
|
||||
|
||||
### 2. Asynchronous Execution
|
||||
|
||||
The operation is executed asynchronously to prevent blocking:
|
||||
|
||||
```rust
|
||||
tokio::task::spawn_blocking(move || {
|
||||
// OSTree operations in blocking context
|
||||
sysroot.write_deployments(&[], gio::Cancellable::NONE)
|
||||
.context("removing deployments")
|
||||
}).await??;
|
||||
```
|
||||
|
||||
### 3. Error Handling
|
||||
|
||||
Comprehensive error handling with context:
|
||||
|
||||
```rust
|
||||
#[context("removing deployments")]
|
||||
pub(crate) async fn wipe_ostree(sysroot: Sysroot) -> Result<()> {
|
||||
// Implementation with automatic error context
|
||||
}
|
||||
```
|
||||
|
||||
## System Impact
|
||||
|
||||
### 1. What Gets Removed
|
||||
|
||||
- **All OSTree Deployments**: Every deployment managed by OSTree
|
||||
- **Boot Entries**: All bootloader entries for bootc deployments
|
||||
- **System State**: Complete reset of bootc-managed system state
|
||||
- **Deployment History**: All deployment history and metadata
|
||||
|
||||
### 2. What Remains
|
||||
|
||||
- **Base System**: The underlying operating system remains intact
|
||||
- **User Data**: User data in `/home` and other non-OSTree locations
|
||||
- **System Configuration**: Non-OSTree system configuration
|
||||
- **Installed Packages**: System packages not managed by OSTree
|
||||
|
||||
### 3. System State After Wipe
|
||||
|
||||
After running `wipe-ostree`, the system will be in a state where:
|
||||
|
||||
- No bootc deployments exist
|
||||
- No OSTree-managed content is present
|
||||
- The system may not boot if it was entirely OSTree-based
|
||||
- Fresh installation is required to restore bootc functionality
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. System Recovery
|
||||
|
||||
When the system is in an unrecoverable state:
|
||||
|
||||
```bash
|
||||
# Check current state
|
||||
bootc status
|
||||
|
||||
# If system is corrupted, wipe and reinstall
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Reinstall from scratch
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
### 2. Clean Installation
|
||||
|
||||
When preparing for a fresh installation:
|
||||
|
||||
```bash
|
||||
# Wipe existing deployments
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Install new system
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
### 3. Development and Testing
|
||||
|
||||
When testing installation procedures:
|
||||
|
||||
```bash
|
||||
# Reset test environment
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Test installation process
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
### 4. System Migration
|
||||
|
||||
When migrating to a different bootc setup:
|
||||
|
||||
```bash
|
||||
# Remove old deployments
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Install new configuration
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Privilege Requirements
|
||||
|
||||
The command requires root privileges:
|
||||
|
||||
```rust
|
||||
pub(crate) fn require_root(is_container: bool) -> Result<()> {
|
||||
ensure!(
|
||||
rustix::process::getuid().is_root(),
|
||||
if is_container {
|
||||
"The user inside the container from which you are running this command must be root"
|
||||
} else {
|
||||
"This command must be executed as the root user"
|
||||
}
|
||||
);
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Destructive Operation
|
||||
|
||||
This is a destructive operation that cannot be undone:
|
||||
|
||||
- **No Undo**: Once executed, deployments cannot be restored
|
||||
- **System Impact**: May render system unbootable
|
||||
- **Data Loss**: All bootc-managed state is lost
|
||||
|
||||
### 3. Safety Checks
|
||||
|
||||
The command should be used with extreme caution:
|
||||
|
||||
- **Backup Required**: Always backup important data before execution
|
||||
- **System Verification**: Ensure system can be reinstalled
|
||||
- **Recovery Plan**: Have a recovery plan ready
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Common Error Scenarios
|
||||
|
||||
#### Permission Denied
|
||||
```bash
|
||||
# Error: Permission denied
|
||||
# Solution: Run as root
|
||||
sudo bootc state wipe-ostree
|
||||
```
|
||||
|
||||
#### OSTree Not Available
|
||||
```bash
|
||||
# Error: OSTree not found
|
||||
# Solution: Install OSTree
|
||||
apt install ostree
|
||||
```
|
||||
|
||||
#### System Not OSTree-Based
|
||||
```bash
|
||||
# Error: No OSTree deployments found
|
||||
# Solution: Verify system is OSTree-based
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
### 2. Error Recovery
|
||||
|
||||
If the command fails:
|
||||
|
||||
1. **Check Logs**: Review system logs for details
|
||||
2. **Verify System**: Ensure system is OSTree-based
|
||||
3. **Check Permissions**: Verify root privileges
|
||||
4. **Manual Cleanup**: May require manual OSTree cleanup
|
||||
|
||||
## Integration with Other Commands
|
||||
|
||||
### 1. Status Command
|
||||
|
||||
Check system state before and after:
|
||||
|
||||
```bash
|
||||
# Before wipe
|
||||
bootc status
|
||||
|
||||
# Wipe deployments
|
||||
bootc state wipe-ostree
|
||||
|
||||
# After wipe (should show no deployments)
|
||||
bootc status
|
||||
```
|
||||
|
||||
### 2. Install Command
|
||||
|
||||
Typically followed by fresh installation:
|
||||
|
||||
```bash
|
||||
# Wipe existing deployments
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Install fresh system
|
||||
bootc install to-disk /dev/sda
|
||||
```
|
||||
|
||||
### 3. OSTree Commands
|
||||
|
||||
Can be used with OSTree commands:
|
||||
|
||||
```bash
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Wipe deployments
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Verify wipe
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
## Performance Characteristics
|
||||
|
||||
### 1. Execution Time
|
||||
|
||||
- **Fast**: Operation completes quickly
|
||||
- **Atomic**: Single atomic operation
|
||||
- **Efficient**: Minimal resource usage
|
||||
|
||||
### 2. Resource Usage
|
||||
|
||||
- **Low CPU**: Minimal CPU usage
|
||||
- **Low Memory**: Minimal memory usage
|
||||
- **Disk I/O**: Only metadata operations
|
||||
|
||||
### 3. System Impact
|
||||
|
||||
- **Immediate**: Effect is immediate
|
||||
- **Permanent**: Cannot be undone
|
||||
- **Complete**: Removes all deployments
|
||||
|
||||
## Testing and Validation
|
||||
|
||||
### 1. Unit Tests
|
||||
|
||||
```rust
|
||||
#[cfg(test)]
|
||||
mod tests {
|
||||
use super::*;
|
||||
|
||||
#[tokio::test]
|
||||
async fn test_wipe_ostree() {
|
||||
let temp_dir = tempfile::tempdir().unwrap();
|
||||
let sysroot = create_test_sysroot(temp_dir.path()).unwrap();
|
||||
|
||||
// Add test deployments
|
||||
add_test_deployments(&sysroot).await.unwrap();
|
||||
|
||||
// Verify deployments exist
|
||||
let deployments = sysroot.deployments();
|
||||
assert!(!deployments.is_empty());
|
||||
|
||||
// Wipe deployments
|
||||
wipe_ostree(sysroot).await.unwrap();
|
||||
|
||||
// Verify deployments are gone
|
||||
let deployments = sysroot.deployments();
|
||||
assert!(deployments.is_empty());
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Integration Tests
|
||||
|
||||
```rust
|
||||
#[tokio::test]
|
||||
async fn test_wipe_ostree_integration() {
|
||||
// Setup test environment
|
||||
let test_env = TestEnvironment::new().await.unwrap();
|
||||
|
||||
// Install test system
|
||||
test_env.install_test_system().await.unwrap();
|
||||
|
||||
// Verify system is installed
|
||||
let status = test_env.run_command("bootc", &["status"]).await.unwrap();
|
||||
assert!(status.contains("booted"));
|
||||
|
||||
// Wipe deployments
|
||||
test_env.run_command("bootc", &["state", "wipe-ostree"]).await.unwrap();
|
||||
|
||||
// Verify deployments are gone
|
||||
let status = test_env.run_command("bootc", &["status"]).await.unwrap();
|
||||
assert!(status.contains("No deployments found"));
|
||||
}
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Usage Guidelines
|
||||
|
||||
- **Backup First**: Always backup important data
|
||||
- **Verify System**: Ensure system is OSTree-based
|
||||
- **Plan Recovery**: Have recovery plan ready
|
||||
- **Test First**: Test in non-production environment
|
||||
|
||||
### 2. Safety Measures
|
||||
|
||||
- **Confirmation**: Consider adding confirmation prompt
|
||||
- **Logging**: Log all wipe operations
|
||||
- **Monitoring**: Monitor system after wipe
|
||||
- **Documentation**: Document wipe procedures
|
||||
|
||||
### 3. Recovery Procedures
|
||||
|
||||
- **Fresh Install**: Plan for fresh installation
|
||||
- **Data Recovery**: Ensure data is backed up
|
||||
- **System Restore**: Have system restore plan
|
||||
- **Testing**: Test recovery procedures
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Additional State Commands
|
||||
|
||||
Potential future state commands:
|
||||
|
||||
```rust
|
||||
pub(crate) enum StateOpts {
|
||||
WipeOstree,
|
||||
ResetConfig, // Reset configuration
|
||||
ClearCache, // Clear system cache
|
||||
ResetSecrets, // Reset secrets
|
||||
WipeComposefs, // Wipe composefs data
|
||||
ResetBootloader, // Reset bootloader
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Safety Features
|
||||
|
||||
Enhanced safety features:
|
||||
|
||||
```rust
|
||||
pub(crate) struct WipeOptions {
|
||||
pub confirm: bool,
|
||||
pub backup: bool,
|
||||
pub dry_run: bool,
|
||||
pub force: bool,
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Recovery Tools
|
||||
|
||||
Recovery and restoration tools:
|
||||
|
||||
```rust
|
||||
pub(crate) enum RecoveryOpts {
|
||||
RestoreFromBackup { backup_path: PathBuf },
|
||||
RestoreFromImage { image: String },
|
||||
RestoreFromSnapshot { snapshot: String },
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### Command Not Found
|
||||
```bash
|
||||
# Error: bootc state: command not found
|
||||
# Solution: Ensure bootc is installed and in PATH
|
||||
which bootc
|
||||
```
|
||||
|
||||
#### Permission Denied
|
||||
```bash
|
||||
# Error: Permission denied
|
||||
# Solution: Run as root
|
||||
sudo bootc state wipe-ostree
|
||||
```
|
||||
|
||||
#### OSTree Error
|
||||
```bash
|
||||
# Error: OSTree operation failed
|
||||
# Solution: Check OSTree installation and system state
|
||||
ostree --version
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
### 2. Debug Information
|
||||
|
||||
Enable debug logging:
|
||||
|
||||
```bash
|
||||
# Set debug log level
|
||||
export RUST_LOG=debug
|
||||
|
||||
# Run command with debug output
|
||||
bootc state wipe-ostree
|
||||
|
||||
# Check debug logs
|
||||
journalctl -u bootc-* --since "1 hour ago" | grep DEBUG
|
||||
```
|
||||
|
||||
### 3. System Verification
|
||||
|
||||
Verify system state:
|
||||
|
||||
```bash
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check bootc status
|
||||
bootc status
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-* --since "1 hour ago"
|
||||
```
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc state system's functionality, implementation, and usage patterns.
|
||||
Loading…
Add table
Add a link
Reference in a new issue