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
467
upgrade/bootc-upgrade-guide.md
Normal file
467
upgrade/bootc-upgrade-guide.md
Normal file
|
|
@ -0,0 +1,467 @@
|
|||
# bootc upgrade - Comprehensive Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc upgrade` is the primary command for downloading and applying system updates in bootc-managed systems. It implements an A/B upgrade system where updates are staged and applied at the next boot, ensuring system stability and providing rollback capabilities.
|
||||
|
||||
## Purpose
|
||||
|
||||
The upgrade system serves several critical functions:
|
||||
|
||||
1. **Transactional Updates**: Downloads and stages updates without affecting the running system
|
||||
2. **A/B Deployment**: Maintains two system versions for safe rollback
|
||||
3. **Registry Integration**: Pulls updates from container registries
|
||||
4. **Automatic Application**: Can automatically apply updates and reboot
|
||||
5. **Soft Reboot Support**: Faster restarts when possible
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc upgrade [OPTIONS...]
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Check for available updates
|
||||
bootc upgrade --check
|
||||
|
||||
# Download and stage updates
|
||||
bootc upgrade
|
||||
|
||||
# Download, stage, and apply updates (with reboot)
|
||||
bootc upgrade --apply
|
||||
|
||||
# Upgrade with soft reboot if available
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
|
||||
# Quiet mode (no progress output)
|
||||
bootc upgrade --quiet
|
||||
```
|
||||
|
||||
## Command Options
|
||||
|
||||
### Core Options
|
||||
|
||||
| Option | Description | Default | Conflicts With |
|
||||
|--------|-------------|---------|----------------|
|
||||
| `--check` | Check for updates without downloading | `false` | `--apply` |
|
||||
| `--apply` | Apply updates and reboot | `false` | `--check` |
|
||||
| `--quiet` | Suppress progress output | `false` | None |
|
||||
| `--soft-reboot` | Configure soft reboot behavior | `None` | `--check` |
|
||||
|
||||
### Soft Reboot Modes
|
||||
|
||||
| Mode | Description | Behavior |
|
||||
|------|-------------|----------|
|
||||
| `required` | Fail if soft reboot unavailable | Error if not supported |
|
||||
| `auto` | Use soft reboot if available | Fallback to regular reboot |
|
||||
|
||||
## Upgrade Process
|
||||
|
||||
### 1. Check Phase (`--check`)
|
||||
|
||||
The check phase only downloads metadata to determine if updates are available:
|
||||
|
||||
```bash
|
||||
bootc upgrade --check
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
- Downloads container manifest and configuration
|
||||
- Compares with currently booted image
|
||||
- Shows available updates without downloading layers
|
||||
- Displays version information and digest
|
||||
|
||||
**Output example**:
|
||||
```
|
||||
Update available for: quay.io/myorg/debian-bootc:latest
|
||||
Version: 1.2.3
|
||||
Digest: sha256:abc123...
|
||||
```
|
||||
|
||||
### 2. Download Phase (default)
|
||||
|
||||
Downloads and stages the updated container image:
|
||||
|
||||
```bash
|
||||
bootc upgrade
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
- Downloads full container image layers
|
||||
- Stages the update for next boot
|
||||
- Preserves current running system
|
||||
- Updates system status
|
||||
|
||||
**Process**:
|
||||
1. **Registry Query**: Check for updated image
|
||||
2. **Layer Download**: Pull container layers
|
||||
3. **OSTree Import**: Convert to OSTree format
|
||||
4. **Staging**: Prepare for next boot
|
||||
5. **Status Update**: Mark as staged
|
||||
|
||||
### 3. Apply Phase (`--apply`)
|
||||
|
||||
Immediately applies staged updates and reboots:
|
||||
|
||||
```bash
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
- Applies staged updates
|
||||
- Reboots into new system
|
||||
- Preserves `/etc` and `/var` state
|
||||
- Updates bootloader configuration
|
||||
|
||||
## Upgrade Modes
|
||||
|
||||
### 1. Check-Only Mode
|
||||
|
||||
```bash
|
||||
bootc upgrade --check
|
||||
```
|
||||
|
||||
**Use cases**:
|
||||
- Monitoring for updates
|
||||
- CI/CD pipeline checks
|
||||
- Update availability verification
|
||||
- Automated update detection
|
||||
|
||||
**Benefits**:
|
||||
- Fast execution (metadata only)
|
||||
- No bandwidth usage for full download
|
||||
- Safe to run frequently
|
||||
|
||||
### 2. Stage-Only Mode
|
||||
|
||||
```bash
|
||||
bootc upgrade
|
||||
```
|
||||
|
||||
**Use cases**:
|
||||
- Download updates for later application
|
||||
- Batch update preparation
|
||||
- Offline update preparation
|
||||
- Manual control over application timing
|
||||
|
||||
**Benefits**:
|
||||
- Updates ready for next boot
|
||||
- No immediate system changes
|
||||
- Allows review before application
|
||||
|
||||
### 3. Immediate Apply Mode
|
||||
|
||||
```bash
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
**Use cases**:
|
||||
- Automated update application
|
||||
- CI/CD deployment
|
||||
- Immediate update application
|
||||
- Single-command updates
|
||||
|
||||
**Benefits**:
|
||||
- Complete update cycle
|
||||
- Automatic reboot
|
||||
- No manual intervention required
|
||||
|
||||
## Soft Reboot Support
|
||||
|
||||
### What is Soft Reboot?
|
||||
|
||||
Soft reboot is a faster restart mechanism that avoids full hardware reboot when possible, typically used in virtualized environments.
|
||||
|
||||
### Soft Reboot Modes
|
||||
|
||||
#### Required Mode
|
||||
```bash
|
||||
bootc upgrade --apply --soft-reboot=required
|
||||
```
|
||||
|
||||
**Behavior**:
|
||||
- Fails if soft reboot is not available
|
||||
- Ensures fastest possible restart
|
||||
- Use when soft reboot is critical
|
||||
|
||||
#### Auto Mode
|
||||
```bash
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
```
|
||||
|
||||
**Behavior**:
|
||||
- Uses soft reboot if available
|
||||
- Falls back to regular reboot if not supported
|
||||
- Recommended for most use cases
|
||||
|
||||
### Soft Reboot Requirements
|
||||
|
||||
- Virtualized environment (VMware, QEMU, etc.)
|
||||
- Kernel support for kexec
|
||||
- Sufficient memory for kexec
|
||||
- Compatible hardware
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### 1. Manual Updates
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
|
||||
# If updates available, apply them
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
### 2. Automated Updates
|
||||
|
||||
```bash
|
||||
# Automated update with soft reboot
|
||||
bootc upgrade --apply --soft-reboot=auto --quiet
|
||||
```
|
||||
|
||||
### 3. CI/CD Integration
|
||||
|
||||
```yaml
|
||||
# GitHub Actions example
|
||||
- name: Update system
|
||||
run: |
|
||||
bootc upgrade --check
|
||||
if [ $? -eq 0 ]; then
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
fi
|
||||
```
|
||||
|
||||
### 4. Monitoring Integration
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Update monitoring script
|
||||
if bootc upgrade --check; then
|
||||
echo "Updates available"
|
||||
# Send notification
|
||||
notify-send "System updates available"
|
||||
else
|
||||
echo "System up to date"
|
||||
fi
|
||||
```
|
||||
|
||||
## Status and Monitoring
|
||||
|
||||
### Check Update Status
|
||||
|
||||
```bash
|
||||
# View current status
|
||||
bootc status
|
||||
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
```
|
||||
|
||||
### Status Indicators
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `booted` | Currently running system |
|
||||
| `staged` | Update ready for next boot |
|
||||
| `incompatible` | System has local modifications |
|
||||
|
||||
### Update Verification
|
||||
|
||||
```bash
|
||||
# Check what's staged
|
||||
bootc status
|
||||
|
||||
# Verify update details
|
||||
bootc upgrade --check
|
||||
```
|
||||
|
||||
## Rollback and Recovery
|
||||
|
||||
### Rollback Process
|
||||
|
||||
```bash
|
||||
# Rollback to previous version
|
||||
bootc rollback
|
||||
|
||||
# Check rollback status
|
||||
bootc status
|
||||
```
|
||||
|
||||
### Recovery Scenarios
|
||||
|
||||
1. **Failed Update**: Use `bootc rollback`
|
||||
2. **Corrupted System**: Boot from previous deployment
|
||||
3. **Incompatible Update**: Check system compatibility
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Update Strategy
|
||||
|
||||
- **Test First**: Test updates in staging environment
|
||||
- **Gradual Rollout**: Use `bootc switch` for controlled deployments
|
||||
- **Monitor Status**: Check `bootc status` regularly
|
||||
- **Backup State**: Ensure `/etc` and `/var` are backed up
|
||||
|
||||
### 2. Automation
|
||||
|
||||
- **Use `--check`**: For monitoring and CI/CD
|
||||
- **Use `--apply`**: For automated deployments
|
||||
- **Use `--soft-reboot`**: For faster restarts when possible
|
||||
- **Use `--quiet`**: For automated scripts
|
||||
|
||||
### 3. Error Handling
|
||||
|
||||
- **Check Return Codes**: Handle update failures gracefully
|
||||
- **Verify Status**: Confirm updates are staged correctly
|
||||
- **Test Rollback**: Ensure rollback works before applying
|
||||
- **Monitor Logs**: Check system logs for issues
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
#### No Updates Available
|
||||
|
||||
```bash
|
||||
# Check current status
|
||||
bootc status
|
||||
|
||||
# Verify image source
|
||||
bootc edit
|
||||
|
||||
# Check registry connectivity
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
```
|
||||
|
||||
#### Update Fails to Apply
|
||||
|
||||
```bash
|
||||
# Check staged status
|
||||
bootc status
|
||||
|
||||
# Verify system compatibility
|
||||
bootc upgrade --check
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
#### Soft Reboot Fails
|
||||
|
||||
```bash
|
||||
# Check soft reboot support
|
||||
bootc upgrade --apply --soft-reboot=required
|
||||
|
||||
# Fall back to regular reboot
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
### Debug Commands
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc upgrade --check
|
||||
|
||||
# Check system status
|
||||
bootc status --json
|
||||
|
||||
# Verify image integrity
|
||||
bootc upgrade --check --quiet
|
||||
```
|
||||
|
||||
## Advanced Usage
|
||||
|
||||
### 1. Custom Image Sources
|
||||
|
||||
```bash
|
||||
# Switch to different image
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Upgrade from new source
|
||||
bootc upgrade
|
||||
```
|
||||
|
||||
### 2. Offline Updates
|
||||
|
||||
```bash
|
||||
# Download updates offline
|
||||
bootc upgrade
|
||||
|
||||
# Apply when ready
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
### 3. Batch Updates
|
||||
|
||||
```bash
|
||||
# Download multiple updates
|
||||
bootc upgrade
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.1
|
||||
bootc upgrade
|
||||
|
||||
# Apply all at once
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Image Verification
|
||||
|
||||
- **Signature Verification**: Ensure images are signed
|
||||
- **Registry Security**: Use trusted registries
|
||||
- **Digest Verification**: Verify image digests
|
||||
|
||||
### 2. Update Security
|
||||
|
||||
- **Network Security**: Use secure connections
|
||||
- **Authentication**: Authenticate with registries
|
||||
- **Authorization**: Control update permissions
|
||||
|
||||
### 3. Rollback Security
|
||||
|
||||
- **State Preservation**: Ensure `/etc` and `/var` are secure
|
||||
- **Access Control**: Limit rollback permissions
|
||||
- **Audit Logging**: Log all update activities
|
||||
|
||||
## Performance Optimization
|
||||
|
||||
### 1. Update Speed
|
||||
|
||||
- **Use `--check`**: For quick availability checks
|
||||
- **Use `--soft-reboot`**: For faster restarts
|
||||
- **Use `--quiet`**: For automated scripts
|
||||
|
||||
### 2. Bandwidth Usage
|
||||
|
||||
- **Check First**: Use `--check` before downloading
|
||||
- **Incremental Updates**: Only download changed layers
|
||||
- **Local Caching**: Use local registry mirrors
|
||||
|
||||
### 3. System Impact
|
||||
|
||||
- **Staged Updates**: No impact on running system
|
||||
- **Atomic Application**: All-or-nothing updates
|
||||
- **Rollback Capability**: Quick recovery from issues
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
|
||||
- **Userspace Restart**: For kernel-unchanged updates
|
||||
- **Delta Updates**: More efficient layer downloads
|
||||
- **Rollback Automation**: Automatic rollback on failure
|
||||
- **Update Scheduling**: Time-based update application
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
- **API Support**: REST API for update management
|
||||
- **Webhook Integration**: Event notifications
|
||||
- **Metrics Collection**: Update performance metrics
|
||||
- **Dashboard Integration**: Web-based management
|
||||
|
||||
---
|
||||
|
||||
This comprehensive guide provides everything needed to understand and use `bootc upgrade` effectively for system updates and maintenance.
|
||||
662
upgrade/examples-and-troubleshooting.md
Normal file
662
upgrade/examples-and-troubleshooting.md
Normal file
|
|
@ -0,0 +1,662 @@
|
|||
# bootc upgrade - Examples and Troubleshooting
|
||||
|
||||
## Practical Examples
|
||||
|
||||
### 1. Basic Update Operations
|
||||
|
||||
#### Check for Updates
|
||||
|
||||
```bash
|
||||
# Check if updates are available
|
||||
bootc upgrade --check
|
||||
|
||||
# Expected output:
|
||||
# Update available for: quay.io/myorg/debian-bootc:latest
|
||||
# Version: 1.2.3
|
||||
# Digest: sha256:abc123...
|
||||
```
|
||||
|
||||
#### Download Updates
|
||||
|
||||
```bash
|
||||
# Download and stage updates
|
||||
bootc upgrade
|
||||
|
||||
# Expected output:
|
||||
# Update available for: quay.io/myorg/debian-bootc:latest
|
||||
# Version: 1.2.3
|
||||
# Digest: sha256:abc123...
|
||||
# Staging update...
|
||||
# Update staged successfully
|
||||
```
|
||||
|
||||
#### Apply Updates
|
||||
|
||||
```bash
|
||||
# Apply updates and reboot
|
||||
bootc upgrade --apply
|
||||
|
||||
# Expected output:
|
||||
# Update available for: quay.io/myorg/debian-bootc:latest
|
||||
# Version: 1.2.3
|
||||
# Digest: sha256:abc123...
|
||||
# Staging update...
|
||||
# Update staged successfully
|
||||
# Rebooting system...
|
||||
```
|
||||
|
||||
### 2. Automated Update Scripts
|
||||
|
||||
#### Simple Update Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# update-system.sh
|
||||
|
||||
set -e
|
||||
|
||||
echo "Checking for updates..."
|
||||
if bootc upgrade --check; then
|
||||
echo "Updates available, applying..."
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
else
|
||||
echo "System is up to date"
|
||||
fi
|
||||
```
|
||||
|
||||
#### Advanced Update Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# advanced-update.sh
|
||||
|
||||
set -e
|
||||
|
||||
# Configuration
|
||||
IMAGE_SOURCE="quay.io/myorg/debian-bootc:latest"
|
||||
LOG_FILE="/var/log/bootc-updates.log"
|
||||
MAX_RETRIES=3
|
||||
|
||||
# Logging function
|
||||
log() {
|
||||
echo "$(date): $1" | tee -a "$LOG_FILE"
|
||||
}
|
||||
|
||||
# Update function
|
||||
update_system() {
|
||||
local retry_count=0
|
||||
|
||||
while [ $retry_count -lt $MAX_RETRIES ]; do
|
||||
log "Attempting update (attempt $((retry_count + 1)))"
|
||||
|
||||
if bootc upgrade --check; then
|
||||
log "Updates available, applying..."
|
||||
if bootc upgrade --apply --soft-reboot=auto; then
|
||||
log "Update applied successfully"
|
||||
return 0
|
||||
else
|
||||
log "Update failed, retrying..."
|
||||
retry_count=$((retry_count + 1))
|
||||
sleep 30
|
||||
fi
|
||||
else
|
||||
log "No updates available"
|
||||
return 0
|
||||
fi
|
||||
done
|
||||
|
||||
log "Update failed after $MAX_RETRIES attempts"
|
||||
return 1
|
||||
}
|
||||
|
||||
# Main execution
|
||||
log "Starting update process"
|
||||
update_system
|
||||
log "Update process completed"
|
||||
```
|
||||
|
||||
### 3. CI/CD Integration
|
||||
|
||||
#### GitHub Actions
|
||||
|
||||
```yaml
|
||||
name: Update System
|
||||
|
||||
on:
|
||||
schedule:
|
||||
- cron: '0 2 * * *' # Daily at 2 AM
|
||||
workflow_dispatch:
|
||||
|
||||
jobs:
|
||||
update:
|
||||
runs-on: ubuntu-latest
|
||||
steps:
|
||||
- name: Checkout
|
||||
uses: actions/checkout@v4
|
||||
|
||||
- name: Setup SSH
|
||||
uses: webfactory/ssh-agent@v0.7.0
|
||||
with:
|
||||
ssh-private-key: ${{ secrets.SSH_PRIVATE_KEY }}
|
||||
|
||||
- name: Update System
|
||||
run: |
|
||||
ssh -o StrictHostKeyChecking=no user@${{ secrets.HOST_IP }} '
|
||||
bootc upgrade --check
|
||||
if [ $? -eq 0 ]; then
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
fi
|
||||
'
|
||||
```
|
||||
|
||||
#### GitLab CI
|
||||
|
||||
```yaml
|
||||
stages:
|
||||
- update
|
||||
|
||||
update_system:
|
||||
stage: update
|
||||
script:
|
||||
- ssh user@$HOST_IP 'bootc upgrade --check'
|
||||
- ssh user@$HOST_IP 'bootc upgrade --apply --soft-reboot=auto'
|
||||
only:
|
||||
- schedules
|
||||
- web
|
||||
```
|
||||
|
||||
#### Jenkins Pipeline
|
||||
|
||||
```groovy
|
||||
pipeline {
|
||||
agent any
|
||||
|
||||
stages {
|
||||
stage('Update System') {
|
||||
steps {
|
||||
script {
|
||||
sh '''
|
||||
ssh user@${HOST_IP} 'bootc upgrade --check'
|
||||
if [ $? -eq 0 ]; then
|
||||
ssh user@${HOST_IP} 'bootc upgrade --apply --soft-reboot=auto'
|
||||
fi
|
||||
'''
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
|
||||
triggers {
|
||||
cron('0 2 * * *') // Daily at 2 AM
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Monitoring and Alerting
|
||||
|
||||
#### Update Monitoring Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# monitor-updates.sh
|
||||
|
||||
# Configuration
|
||||
WEBHOOK_URL="https://hooks.slack.com/services/YOUR/WEBHOOK/URL"
|
||||
HOSTNAME=$(hostname)
|
||||
|
||||
# Check for updates
|
||||
check_updates() {
|
||||
if bootc upgrade --check > /dev/null 2>&1; then
|
||||
return 0 # Updates available
|
||||
else
|
||||
return 1 # No updates
|
||||
fi
|
||||
}
|
||||
|
||||
# Send notification
|
||||
send_notification() {
|
||||
local message="$1"
|
||||
curl -X POST -H 'Content-type: application/json' \
|
||||
--data "{\"text\":\"$HOSTNAME: $message\"}" \
|
||||
"$WEBHOOK_URL"
|
||||
}
|
||||
|
||||
# Main monitoring loop
|
||||
while true; do
|
||||
if check_updates; then
|
||||
send_notification "Updates available for $HOSTNAME"
|
||||
# Wait longer after finding updates
|
||||
sleep 3600 # 1 hour
|
||||
else
|
||||
# Check more frequently when no updates
|
||||
sleep 300 # 5 minutes
|
||||
fi
|
||||
done
|
||||
```
|
||||
|
||||
#### Prometheus Metrics
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# prometheus-metrics.sh
|
||||
|
||||
# Create metrics file
|
||||
METRICS_FILE="/var/lib/prometheus/node-exporter/bootc-updates.prom"
|
||||
|
||||
# Check update status
|
||||
if bootc upgrade --check > /dev/null 2>&1; then
|
||||
UPDATES_AVAILABLE=1
|
||||
else
|
||||
UPDATES_AVAILABLE=0
|
||||
fi
|
||||
|
||||
# Write metrics
|
||||
cat > "$METRICS_FILE" << EOF
|
||||
# HELP bootc_updates_available Whether updates are available
|
||||
# TYPE bootc_updates_available gauge
|
||||
bootc_updates_available $UPDATES_AVAILABLE
|
||||
EOF
|
||||
```
|
||||
|
||||
### 5. Systemd Integration
|
||||
|
||||
#### Update Service
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/bootc-update.service
|
||||
[Unit]
|
||||
Description=Update bootc system
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/local/bin/update-system.sh
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
#### Update Timer
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/bootc-update.timer
|
||||
[Unit]
|
||||
Description=Update bootc system daily
|
||||
Requires=bootc-update.service
|
||||
|
||||
[Timer]
|
||||
OnCalendar=daily
|
||||
Persistent=true
|
||||
|
||||
[Install]
|
||||
WantedBy=timers.target
|
||||
```
|
||||
|
||||
#### Enable and Start
|
||||
|
||||
```bash
|
||||
# Enable and start timer
|
||||
sudo systemctl enable bootc-update.timer
|
||||
sudo systemctl start bootc-update.timer
|
||||
|
||||
# Check status
|
||||
sudo systemctl status bootc-update.timer
|
||||
sudo systemctl list-timers bootc-update.timer
|
||||
```
|
||||
|
||||
## Troubleshooting Guide
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### No Updates Available
|
||||
|
||||
**Problem**: `bootc upgrade --check` shows no updates
|
||||
**Possible Causes**:
|
||||
- System is already up to date
|
||||
- Registry connectivity issues
|
||||
- Image source not configured
|
||||
- Authentication problems
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check current status
|
||||
bootc status
|
||||
|
||||
# Verify image source
|
||||
bootc edit
|
||||
|
||||
# Test registry connectivity
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
|
||||
# Check authentication
|
||||
podman login quay.io
|
||||
```
|
||||
|
||||
#### Update Fails to Download
|
||||
|
||||
**Problem**: `bootc upgrade` fails during download
|
||||
**Possible Causes**:
|
||||
- Network connectivity issues
|
||||
- Registry authentication problems
|
||||
- Insufficient disk space
|
||||
- Registry rate limiting
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check network connectivity
|
||||
ping quay.io
|
||||
|
||||
# Check disk space
|
||||
df -h
|
||||
|
||||
# Check authentication
|
||||
podman login quay.io
|
||||
|
||||
# Retry with verbose output
|
||||
RUST_LOG=debug bootc upgrade
|
||||
```
|
||||
|
||||
#### Update Fails to Apply
|
||||
|
||||
**Problem**: `bootc upgrade --apply` fails
|
||||
**Possible Causes**:
|
||||
- Staged update corrupted
|
||||
- Insufficient disk space
|
||||
- Bootloader configuration issues
|
||||
- System compatibility problems
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check staged status
|
||||
bootc status
|
||||
|
||||
# Verify system compatibility
|
||||
bootc upgrade --check
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
|
||||
# Try rollback
|
||||
bootc rollback
|
||||
```
|
||||
|
||||
#### Soft Reboot Fails
|
||||
|
||||
**Problem**: `--soft-reboot=required` fails
|
||||
**Possible Causes**:
|
||||
- Soft reboot not supported
|
||||
- Insufficient memory
|
||||
- Kernel compatibility issues
|
||||
- Hardware limitations
|
||||
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check soft reboot support
|
||||
bootc upgrade --apply --soft-reboot=required
|
||||
|
||||
# Use auto mode (fallback to regular reboot)
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
|
||||
# Use regular reboot
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
### 2. Debug Commands
|
||||
|
||||
#### Enable Debug Logging
|
||||
|
||||
```bash
|
||||
# Enable debug output
|
||||
RUST_LOG=debug bootc upgrade --check
|
||||
|
||||
# Enable trace output
|
||||
RUST_LOG=trace bootc upgrade --check
|
||||
|
||||
# Save debug output to file
|
||||
RUST_LOG=debug bootc upgrade --check 2>&1 | tee debug.log
|
||||
```
|
||||
|
||||
#### Check System Status
|
||||
|
||||
```bash
|
||||
# Check current status
|
||||
bootc status
|
||||
|
||||
# Check status in JSON format
|
||||
bootc status --json
|
||||
|
||||
# Check system configuration
|
||||
bootc edit
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
#### Verify Image Integrity
|
||||
|
||||
```bash
|
||||
# Check image source
|
||||
bootc edit
|
||||
|
||||
# Verify image exists
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
|
||||
# Check image labels
|
||||
podman inspect quay.io/myorg/debian-bootc:latest | jq '.[0].Config.Labels'
|
||||
```
|
||||
|
||||
### 3. Recovery Procedures
|
||||
|
||||
#### Rollback from Failed Update
|
||||
|
||||
```bash
|
||||
# Check current status
|
||||
bootc status
|
||||
|
||||
# Rollback to previous version
|
||||
bootc rollback
|
||||
|
||||
# Verify rollback
|
||||
bootc status
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
#### Reset System State
|
||||
|
||||
```bash
|
||||
# Check for local modifications
|
||||
bootc status
|
||||
|
||||
# Reset local modifications (if any)
|
||||
rpm-ostree reset
|
||||
|
||||
# Check status again
|
||||
bootc status
|
||||
|
||||
# Try update again
|
||||
bootc upgrade --check
|
||||
```
|
||||
|
||||
#### Manual Image Switch
|
||||
|
||||
```bash
|
||||
# Switch to different image
|
||||
bootc switch quay.io/myorg/debian-bootc:v1.0
|
||||
|
||||
# Check status
|
||||
bootc status
|
||||
|
||||
# Apply update
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
### 4. Performance Issues
|
||||
|
||||
#### Slow Update Downloads
|
||||
|
||||
**Problem**: Updates take too long to download
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check network speed
|
||||
speedtest-cli
|
||||
|
||||
# Use local registry mirror
|
||||
bootc switch registry.local/myorg/debian-bootc:latest
|
||||
|
||||
# Check disk I/O
|
||||
iostat -x 1
|
||||
|
||||
# Use quiet mode
|
||||
bootc upgrade --quiet
|
||||
```
|
||||
|
||||
#### High Memory Usage
|
||||
|
||||
**Problem**: Update process uses too much memory
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check memory usage
|
||||
free -h
|
||||
|
||||
# Check swap usage
|
||||
swapon -s
|
||||
|
||||
# Monitor during update
|
||||
htop
|
||||
|
||||
# Use check mode first
|
||||
bootc upgrade --check
|
||||
```
|
||||
|
||||
#### Disk Space Issues
|
||||
|
||||
**Problem**: Insufficient disk space for updates
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Check disk usage
|
||||
df -h
|
||||
|
||||
# Clean up old deployments
|
||||
ostree admin cleanup
|
||||
|
||||
# Check OSTree usage
|
||||
ostree admin status
|
||||
|
||||
# Free up space
|
||||
sudo apt autoremove
|
||||
sudo apt autoclean
|
||||
```
|
||||
|
||||
### 5. Network Issues
|
||||
|
||||
#### Registry Connectivity
|
||||
|
||||
**Problem**: Cannot connect to registry
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Test connectivity
|
||||
ping quay.io
|
||||
|
||||
# Check DNS resolution
|
||||
nslookup quay.io
|
||||
|
||||
# Test with curl
|
||||
curl -I https://quay.io
|
||||
|
||||
# Check firewall
|
||||
sudo ufw status
|
||||
```
|
||||
|
||||
#### Authentication Issues
|
||||
|
||||
**Problem**: Registry authentication fails
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Login to registry
|
||||
podman login quay.io
|
||||
|
||||
# Check credentials
|
||||
cat ~/.docker/config.json
|
||||
|
||||
# Test authentication
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
|
||||
# Check token expiration
|
||||
podman logout quay.io
|
||||
podman login quay.io
|
||||
```
|
||||
|
||||
#### Proxy Configuration
|
||||
|
||||
**Problem**: Updates fail behind proxy
|
||||
**Solutions**:
|
||||
```bash
|
||||
# Configure proxy for podman
|
||||
mkdir -p ~/.config/containers
|
||||
cat > ~/.config/containers/containers.conf << EOF
|
||||
[containers]
|
||||
http_proxy = "http://proxy.example.com:8080"
|
||||
https_proxy = "http://proxy.example.com:8080"
|
||||
no_proxy = "localhost,127.0.0.1"
|
||||
EOF
|
||||
|
||||
# Test proxy
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
```
|
||||
|
||||
### 6. Advanced Troubleshooting
|
||||
|
||||
#### System Logs Analysis
|
||||
|
||||
```bash
|
||||
# Check bootc logs
|
||||
journalctl -u bootc-fetch-apply-updates.service -f
|
||||
|
||||
# Check system logs
|
||||
journalctl -f
|
||||
|
||||
# Check kernel logs
|
||||
dmesg | tail -50
|
||||
|
||||
# Check boot logs
|
||||
journalctl -b
|
||||
```
|
||||
|
||||
#### Network Diagnostics
|
||||
|
||||
```bash
|
||||
# Check network interfaces
|
||||
ip addr show
|
||||
|
||||
# Check routing table
|
||||
ip route show
|
||||
|
||||
# Check DNS configuration
|
||||
cat /etc/resolv.conf
|
||||
|
||||
# Test DNS resolution
|
||||
dig quay.io
|
||||
```
|
||||
|
||||
#### System Health Check
|
||||
|
||||
```bash
|
||||
# Check system resources
|
||||
htop
|
||||
|
||||
# Check disk health
|
||||
sudo smartctl -a /dev/sda
|
||||
|
||||
# Check memory
|
||||
free -h
|
||||
|
||||
# Check CPU
|
||||
lscpu
|
||||
```
|
||||
|
||||
This comprehensive examples and troubleshooting guide provides practical solutions for common bootc upgrade issues and integration patterns.
|
||||
857
upgrade/external-commands-reference.md
Normal file
857
upgrade/external-commands-reference.md
Normal file
|
|
@ -0,0 +1,857 @@
|
|||
# bootc upgrade - External Commands Reference
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a comprehensive reference for all external commands, system services, and tools that interact with or are used by the `bootc upgrade` system. Understanding these external dependencies is crucial for troubleshooting, monitoring, and integrating bootc upgrades into larger systems.
|
||||
|
||||
## Core System Commands
|
||||
|
||||
### 1. bootc Commands
|
||||
|
||||
#### bootc upgrade
|
||||
**Purpose**: Primary upgrade command
|
||||
**Usage**: `bootc upgrade [OPTIONS...]`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment management
|
||||
- `podman` - For container registry access
|
||||
- `systemd` - For service management and reboot
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
|
||||
# Download and stage updates
|
||||
bootc upgrade
|
||||
|
||||
# Apply updates and reboot
|
||||
bootc upgrade --apply
|
||||
|
||||
# Apply with soft reboot
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
```
|
||||
|
||||
#### bootc status
|
||||
**Purpose**: Check system status and deployment state
|
||||
**Usage**: `bootc status [OPTIONS...]`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment information
|
||||
- `systemd` - For service status
|
||||
|
||||
```bash
|
||||
# Check current status
|
||||
bootc status
|
||||
|
||||
# Check status in JSON format
|
||||
bootc status --json
|
||||
|
||||
# Check specific deployment
|
||||
bootc status --deployment=deployment-id
|
||||
```
|
||||
|
||||
#### bootc rollback
|
||||
**Purpose**: Rollback to previous deployment
|
||||
**Usage**: `bootc rollback [OPTIONS...]`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment switching
|
||||
- `systemd` - For service management
|
||||
|
||||
```bash
|
||||
# Rollback to previous version
|
||||
bootc rollback
|
||||
|
||||
# Rollback to specific deployment
|
||||
bootc rollback --deployment=deployment-id
|
||||
```
|
||||
|
||||
#### bootc switch
|
||||
**Purpose**: Switch to different container image
|
||||
**Usage**: `bootc switch [OPTIONS...]`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment management
|
||||
- `podman` - For container registry access
|
||||
|
||||
```bash
|
||||
# Switch to different image
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Switch and apply immediately
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0 --apply
|
||||
```
|
||||
|
||||
### 2. OSTree Commands
|
||||
|
||||
#### ostree admin status
|
||||
**Purpose**: Check OSTree deployment status
|
||||
**Usage**: `ostree admin status`
|
||||
**Integration**: Used by `bootc status` for deployment information
|
||||
|
||||
```bash
|
||||
# Check deployment status
|
||||
ostree admin status
|
||||
|
||||
# Check specific deployment
|
||||
ostree admin status --deployment=deployment-id
|
||||
```
|
||||
|
||||
#### ostree admin cleanup
|
||||
**Purpose**: Clean up old deployments and free space
|
||||
**Usage**: `ostree admin cleanup [OPTIONS...]`
|
||||
**Integration**: Used for disk space management
|
||||
|
||||
```bash
|
||||
# Clean up old deployments
|
||||
ostree admin cleanup
|
||||
|
||||
# Clean up with specific options
|
||||
ostree admin cleanup --keep=2
|
||||
```
|
||||
|
||||
#### ostree admin deploy
|
||||
**Purpose**: Deploy new OSTree deployment
|
||||
**Usage**: `ostree admin deploy [OPTIONS...]`
|
||||
**Integration**: Used internally by bootc for staging updates
|
||||
|
||||
```bash
|
||||
# Deploy new deployment
|
||||
ostree admin deploy --os=debian-bootc deployment-id
|
||||
|
||||
# Deploy with specific options
|
||||
ostree admin deploy --os=debian-bootc --karg=console=ttyS0 deployment-id
|
||||
```
|
||||
|
||||
#### ostree admin rollback
|
||||
**Purpose**: Rollback to previous deployment
|
||||
**Usage**: `ostree admin rollback [OPTIONS...]`
|
||||
**Integration**: Used by `bootc rollback` for deployment switching
|
||||
|
||||
```bash
|
||||
# Rollback to previous deployment
|
||||
ostree admin rollback
|
||||
|
||||
# Rollback with specific options
|
||||
ostree admin rollback --deployment=deployment-id
|
||||
```
|
||||
|
||||
### 3. Container Registry Commands
|
||||
|
||||
#### podman pull
|
||||
**Purpose**: Pull container images from registry
|
||||
**Usage**: `podman pull [OPTIONS...] IMAGE`
|
||||
**Integration**: Used by bootc for downloading updates
|
||||
|
||||
```bash
|
||||
# Pull image from registry
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
|
||||
# Pull with authentication
|
||||
podman pull --creds=username:password quay.io/myorg/debian-bootc:latest
|
||||
|
||||
# Pull specific tag
|
||||
podman pull quay.io/myorg/debian-bootc:v1.2.3
|
||||
```
|
||||
|
||||
#### podman login
|
||||
**Purpose**: Authenticate with container registry
|
||||
**Usage**: `podman login [OPTIONS...] REGISTRY`
|
||||
**Integration**: Required for private registry access
|
||||
|
||||
```bash
|
||||
# Login to registry
|
||||
podman login quay.io
|
||||
|
||||
# Login with specific credentials
|
||||
podman login --username=myuser --password=mypass quay.io
|
||||
|
||||
# Login with token
|
||||
podman login --authfile=/path/to/auth.json quay.io
|
||||
```
|
||||
|
||||
#### podman inspect
|
||||
**Purpose**: Inspect container image metadata
|
||||
**Usage**: `podman inspect [OPTIONS...] IMAGE`
|
||||
**Integration**: Used for image validation and metadata extraction
|
||||
|
||||
```bash
|
||||
# Inspect image
|
||||
podman inspect quay.io/myorg/debian-bootc:latest
|
||||
|
||||
# Inspect specific configuration
|
||||
podman inspect --format='{{.Config.Labels}}' quay.io/myorg/debian-bootc:latest
|
||||
|
||||
# Inspect manifest
|
||||
podman inspect --format='{{.Manifest}}' quay.io/myorg/debian-bootc:latest
|
||||
```
|
||||
|
||||
### 4. System Management Commands
|
||||
|
||||
#### systemctl
|
||||
**Purpose**: Control systemd services and units
|
||||
**Usage**: `systemctl [COMMAND] [UNIT...]`
|
||||
**Integration**: Used for service management and reboot coordination
|
||||
|
||||
```bash
|
||||
# Check service status
|
||||
systemctl status bootc-fetch-apply-updates.service
|
||||
|
||||
# Start service
|
||||
systemctl start bootc-fetch-apply-updates.service
|
||||
|
||||
# Enable service
|
||||
systemctl enable bootc-fetch-apply-updates.service
|
||||
|
||||
# Restart service
|
||||
systemctl restart bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
#### reboot
|
||||
**Purpose**: Reboot the system
|
||||
**Usage**: `reboot [OPTIONS...]`
|
||||
**Integration**: Used by `bootc upgrade --apply` for system restart
|
||||
|
||||
```bash
|
||||
# Reboot system
|
||||
reboot
|
||||
|
||||
# Reboot with specific delay
|
||||
reboot +5
|
||||
|
||||
# Reboot with message
|
||||
reboot "Applying bootc update"
|
||||
```
|
||||
|
||||
#### shutdown
|
||||
**Purpose**: Shutdown the system
|
||||
**Usage**: `shutdown [OPTIONS...]`
|
||||
**Integration**: Used for controlled shutdown before reboot
|
||||
|
||||
```bash
|
||||
# Shutdown system
|
||||
shutdown -h now
|
||||
|
||||
# Shutdown with delay
|
||||
shutdown -h +5
|
||||
|
||||
# Shutdown with message
|
||||
shutdown -h now "Applying bootc update"
|
||||
```
|
||||
|
||||
## System Services
|
||||
|
||||
### 1. bootc-fetch-apply-updates.service
|
||||
|
||||
**Purpose**: Automated update fetching and application
|
||||
**File**: `/usr/lib/systemd/system/bootc-fetch-apply-updates.service`
|
||||
**Dependencies**:
|
||||
- `network-online.target`
|
||||
- `bootc` command
|
||||
- `ostree` system
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Download and apply bootc updates
|
||||
After=network-online.target
|
||||
Wants=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/bin/bootc upgrade --apply
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
**Management Commands**:
|
||||
```bash
|
||||
# Check service status
|
||||
systemctl status bootc-fetch-apply-updates.service
|
||||
|
||||
# Start service manually
|
||||
systemctl start bootc-fetch-apply-updates.service
|
||||
|
||||
# Enable service
|
||||
systemctl enable bootc-fetch-apply-updates.service
|
||||
|
||||
# Check service logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
### 2. bootc-fetch-apply-updates.timer
|
||||
|
||||
**Purpose**: Schedule automated updates
|
||||
**File**: `/usr/lib/systemd/system/bootc-fetch-apply-updates.timer`
|
||||
**Dependencies**:
|
||||
- `bootc-fetch-apply-updates.service`
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Download and apply bootc updates daily
|
||||
Requires=bootc-fetch-apply-updates.service
|
||||
|
||||
[Timer]
|
||||
OnCalendar=daily
|
||||
Persistent=true
|
||||
|
||||
[Install]
|
||||
WantedBy=timers.target
|
||||
```
|
||||
|
||||
**Management Commands**:
|
||||
```bash
|
||||
# Check timer status
|
||||
systemctl status bootc-fetch-apply-updates.timer
|
||||
|
||||
# List timers
|
||||
systemctl list-timers bootc-fetch-apply-updates.timer
|
||||
|
||||
# Start timer
|
||||
systemctl start bootc-fetch-apply-updates.timer
|
||||
|
||||
# Enable timer
|
||||
systemctl enable bootc-fetch-apply-updates.timer
|
||||
```
|
||||
|
||||
### 3. ostree-finalize-staged.service
|
||||
|
||||
**Purpose**: Finalize staged OSTree deployments
|
||||
**File**: `/usr/lib/systemd/system/ostree-finalize-staged.service`
|
||||
**Dependencies**:
|
||||
- `ostree` system
|
||||
- `systemd` reboot coordination
|
||||
|
||||
```ini
|
||||
[Unit]
|
||||
Description=Finalize staged OSTree deployment
|
||||
After=ostree-remount.service
|
||||
Before=systemd-reboot.service
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/bin/ostree admin finalize-staged
|
||||
StandardOutput=journal
|
||||
StandardError=journal
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
**Management Commands**:
|
||||
```bash
|
||||
# Check service status
|
||||
systemctl status ostree-finalize-staged.service
|
||||
|
||||
# Check service logs
|
||||
journalctl -u ostree-finalize-staged.service
|
||||
|
||||
# Manually run service
|
||||
systemctl start ostree-finalize-staged.service
|
||||
```
|
||||
|
||||
## Network and Registry Commands
|
||||
|
||||
### 1. curl
|
||||
**Purpose**: HTTP client for registry communication
|
||||
**Usage**: `curl [OPTIONS...] URL`
|
||||
**Integration**: Used for registry API calls and authentication
|
||||
|
||||
```bash
|
||||
# Test registry connectivity
|
||||
curl -I https://quay.io/v2/
|
||||
|
||||
# Check registry API
|
||||
curl -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
|
||||
https://quay.io/v2/myorg/debian-bootc/manifests/latest
|
||||
|
||||
# Authenticate with registry
|
||||
curl -u username:password https://quay.io/v2/token
|
||||
```
|
||||
|
||||
### 2. wget
|
||||
**Purpose**: Download files from web servers
|
||||
**Usage**: `wget [OPTIONS...] URL`
|
||||
**Integration**: Alternative to curl for registry communication
|
||||
|
||||
```bash
|
||||
# Download registry manifest
|
||||
wget -O manifest.json https://quay.io/v2/myorg/debian-bootc/manifests/latest
|
||||
|
||||
# Download with authentication
|
||||
wget --user=username --password=password https://quay.io/v2/token
|
||||
```
|
||||
|
||||
### 3. dig
|
||||
**Purpose**: DNS lookup tool
|
||||
**Usage**: `dig [OPTIONS...] DOMAIN`
|
||||
**Integration**: Used for DNS resolution troubleshooting
|
||||
|
||||
```bash
|
||||
# Resolve registry domain
|
||||
dig quay.io
|
||||
|
||||
# Check specific DNS record
|
||||
dig quay.io A
|
||||
|
||||
# Check DNS server
|
||||
dig @8.8.8.8 quay.io
|
||||
```
|
||||
|
||||
### 4. nslookup
|
||||
**Purpose**: DNS lookup tool
|
||||
**Usage**: `nslookup [OPTIONS...] DOMAIN`
|
||||
**Integration**: Alternative to dig for DNS troubleshooting
|
||||
|
||||
```bash
|
||||
# Resolve registry domain
|
||||
nslookup quay.io
|
||||
|
||||
# Check specific DNS record
|
||||
nslookup -type=A quay.io
|
||||
```
|
||||
|
||||
## Storage and Filesystem Commands
|
||||
|
||||
### 1. df
|
||||
**Purpose**: Display filesystem disk space usage
|
||||
**Usage**: `df [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for disk space monitoring
|
||||
|
||||
```bash
|
||||
# Check disk usage
|
||||
df -h
|
||||
|
||||
# Check specific filesystem
|
||||
df -h /sysroot
|
||||
|
||||
# Check inode usage
|
||||
df -i
|
||||
```
|
||||
|
||||
### 2. du
|
||||
**Purpose**: Display directory space usage
|
||||
**Usage**: `du [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for directory space analysis
|
||||
|
||||
```bash
|
||||
# Check directory usage
|
||||
du -sh /sysroot
|
||||
|
||||
# Check OSTree usage
|
||||
du -sh /sysroot/ostree
|
||||
|
||||
# Check specific deployment
|
||||
du -sh /sysroot/ostree/deploy/debian-bootc
|
||||
```
|
||||
|
||||
### 3. lsblk
|
||||
**Purpose**: List block devices
|
||||
**Usage**: `lsblk [OPTIONS...]`
|
||||
**Integration**: Used for storage device identification
|
||||
|
||||
```bash
|
||||
# List all block devices
|
||||
lsblk
|
||||
|
||||
# List with filesystem information
|
||||
lsblk -f
|
||||
|
||||
# List specific device
|
||||
lsblk /dev/sda
|
||||
```
|
||||
|
||||
### 4. mount
|
||||
**Purpose**: Mount filesystems
|
||||
**Usage**: `mount [OPTIONS...] DEVICE DIR`
|
||||
**Integration**: Used for filesystem mounting
|
||||
|
||||
```bash
|
||||
# List mounted filesystems
|
||||
mount
|
||||
|
||||
# Mount specific device
|
||||
mount /dev/sda1 /mnt
|
||||
|
||||
# Mount with options
|
||||
mount -o ro /dev/sda1 /mnt
|
||||
```
|
||||
|
||||
## Monitoring and Logging Commands
|
||||
|
||||
### 1. journalctl
|
||||
**Purpose**: Query systemd journal
|
||||
**Usage**: `journalctl [OPTIONS...]`
|
||||
**Integration**: Used for service and system log analysis
|
||||
|
||||
```bash
|
||||
# Check bootc service logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
|
||||
# Check recent logs
|
||||
journalctl -n 100
|
||||
|
||||
# Check logs since boot
|
||||
journalctl -b
|
||||
|
||||
# Follow logs in real-time
|
||||
journalctl -f
|
||||
```
|
||||
|
||||
### 2. dmesg
|
||||
**Purpose**: Display kernel ring buffer
|
||||
**Usage**: `dmesg [OPTIONS...]`
|
||||
**Integration**: Used for kernel-level troubleshooting
|
||||
|
||||
```bash
|
||||
# Display kernel messages
|
||||
dmesg
|
||||
|
||||
# Display recent messages
|
||||
dmesg -T
|
||||
|
||||
# Display with timestamps
|
||||
dmesg -T | tail -50
|
||||
```
|
||||
|
||||
### 3. htop
|
||||
**Purpose**: Interactive process viewer
|
||||
**Usage**: `htop [OPTIONS...]`
|
||||
**Integration**: Used for system resource monitoring
|
||||
|
||||
```bash
|
||||
# Start htop
|
||||
htop
|
||||
|
||||
# Monitor specific process
|
||||
htop -p $(pgrep bootc)
|
||||
```
|
||||
|
||||
### 4. iostat
|
||||
**Purpose**: I/O statistics
|
||||
**Usage**: `iostat [OPTIONS...]`
|
||||
**Integration**: Used for disk I/O monitoring
|
||||
|
||||
```bash
|
||||
# Display I/O statistics
|
||||
iostat
|
||||
|
||||
# Display with interval
|
||||
iostat 1
|
||||
|
||||
# Display specific device
|
||||
iostat /dev/sda
|
||||
```
|
||||
|
||||
## Security and Authentication Commands
|
||||
|
||||
### 1. openssl
|
||||
**Purpose**: OpenSSL command line tool
|
||||
**Usage**: `openssl [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Used for certificate and key management
|
||||
|
||||
```bash
|
||||
# Check certificate
|
||||
openssl x509 -in certificate.crt -text -noout
|
||||
|
||||
# Verify certificate chain
|
||||
openssl verify -CAfile ca.crt certificate.crt
|
||||
|
||||
# Generate key pair
|
||||
openssl genrsa -out private.key 2048
|
||||
```
|
||||
|
||||
### 2. gpg
|
||||
**Purpose**: GNU Privacy Guard
|
||||
**Usage**: `gpg [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Used for signature verification
|
||||
|
||||
```bash
|
||||
# Verify signature
|
||||
gpg --verify signature.asc file.txt
|
||||
|
||||
# Import public key
|
||||
gpg --import public.key
|
||||
|
||||
# List keys
|
||||
gpg --list-keys
|
||||
```
|
||||
|
||||
### 3. ssh
|
||||
**Purpose**: Secure shell client
|
||||
**Usage**: `ssh [OPTIONS...] [USER@]HOST [COMMAND]`
|
||||
**Integration**: Used for remote system management
|
||||
|
||||
```bash
|
||||
# Connect to remote system
|
||||
ssh user@hostname
|
||||
|
||||
# Execute remote command
|
||||
ssh user@hostname 'bootc upgrade --check'
|
||||
|
||||
# Copy files
|
||||
scp file.txt user@hostname:/path/to/destination
|
||||
```
|
||||
|
||||
## Network Troubleshooting Commands
|
||||
|
||||
### 1. ping
|
||||
**Purpose**: Test network connectivity
|
||||
**Usage**: `ping [OPTIONS...] HOST`
|
||||
**Integration**: Used for network connectivity testing
|
||||
|
||||
```bash
|
||||
# Test connectivity
|
||||
ping quay.io
|
||||
|
||||
# Test with specific count
|
||||
ping -c 4 quay.io
|
||||
|
||||
# Test with specific interface
|
||||
ping -I eth0 quay.io
|
||||
```
|
||||
|
||||
### 2. traceroute
|
||||
**Purpose**: Trace network path
|
||||
**Usage**: `traceroute [OPTIONS...] HOST`
|
||||
**Integration**: Used for network path analysis
|
||||
|
||||
```bash
|
||||
# Trace path to registry
|
||||
traceroute quay.io
|
||||
|
||||
# Trace with specific options
|
||||
traceroute -n quay.io
|
||||
```
|
||||
|
||||
### 3. netstat
|
||||
**Purpose**: Display network connections
|
||||
**Usage**: `netstat [OPTIONS...]`
|
||||
**Integration**: Used for network connection analysis
|
||||
|
||||
```bash
|
||||
# Display all connections
|
||||
netstat -an
|
||||
|
||||
# Display listening ports
|
||||
netstat -ln
|
||||
|
||||
# Display with process information
|
||||
netstat -tulpn
|
||||
```
|
||||
|
||||
### 4. ss
|
||||
**Purpose**: Socket statistics
|
||||
**Usage**: `ss [OPTIONS...]`
|
||||
**Integration**: Modern alternative to netstat
|
||||
|
||||
```bash
|
||||
# Display all sockets
|
||||
ss -an
|
||||
|
||||
# Display listening sockets
|
||||
ss -ln
|
||||
|
||||
# Display with process information
|
||||
ss -tulpn
|
||||
```
|
||||
|
||||
## Container Runtime Commands
|
||||
|
||||
### 1. podman
|
||||
**Purpose**: Container runtime
|
||||
**Usage**: `podman [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Primary container runtime for bootc
|
||||
|
||||
```bash
|
||||
# List containers
|
||||
podman ps -a
|
||||
|
||||
# List images
|
||||
podman images
|
||||
|
||||
# Run container
|
||||
podman run -it quay.io/myorg/debian-bootc:latest
|
||||
|
||||
# Remove containers
|
||||
podman rm -f container-id
|
||||
```
|
||||
|
||||
### 2. docker
|
||||
**Purpose**: Alternative container runtime
|
||||
**Usage**: `docker [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Alternative to podman
|
||||
|
||||
```bash
|
||||
# List containers
|
||||
docker ps -a
|
||||
|
||||
# List images
|
||||
docker images
|
||||
|
||||
# Run container
|
||||
docker run -it quay.io/myorg/debian-bootc:latest
|
||||
```
|
||||
|
||||
## System Information Commands
|
||||
|
||||
### 1. uname
|
||||
**Purpose**: Display system information
|
||||
**Usage**: `uname [OPTIONS...]`
|
||||
**Integration**: Used for system identification
|
||||
|
||||
```bash
|
||||
# Display system information
|
||||
uname -a
|
||||
|
||||
# Display kernel version
|
||||
uname -r
|
||||
|
||||
# Display architecture
|
||||
uname -m
|
||||
```
|
||||
|
||||
### 2. lscpu
|
||||
**Purpose**: Display CPU information
|
||||
**Usage**: `lscpu [OPTIONS...]`
|
||||
**Integration**: Used for system resource analysis
|
||||
|
||||
```bash
|
||||
# Display CPU information
|
||||
lscpu
|
||||
|
||||
# Display in specific format
|
||||
lscpu --extended
|
||||
```
|
||||
|
||||
### 3. free
|
||||
**Purpose**: Display memory usage
|
||||
**Usage**: `free [OPTIONS...]`
|
||||
**Integration**: Used for memory monitoring
|
||||
|
||||
```bash
|
||||
# Display memory usage
|
||||
free -h
|
||||
|
||||
# Display in specific format
|
||||
free -m
|
||||
```
|
||||
|
||||
### 4. uptime
|
||||
**Purpose**: Display system uptime
|
||||
**Usage**: `uptime [OPTIONS...]`
|
||||
**Integration**: Used for system status monitoring
|
||||
|
||||
```bash
|
||||
# Display uptime
|
||||
uptime
|
||||
|
||||
# Display with load average
|
||||
uptime -p
|
||||
```
|
||||
|
||||
## Configuration Management Commands
|
||||
|
||||
### 1. bootc edit
|
||||
**Purpose**: Edit bootc configuration
|
||||
**Usage**: `bootc edit [OPTIONS...]`
|
||||
**Integration**: Used for configuration management
|
||||
|
||||
```bash
|
||||
# Edit configuration
|
||||
bootc edit
|
||||
|
||||
# Edit specific deployment
|
||||
bootc edit --deployment=deployment-id
|
||||
```
|
||||
|
||||
### 2. bootc config
|
||||
**Purpose**: Display bootc configuration
|
||||
**Usage**: `bootc config [OPTIONS...]`
|
||||
**Integration**: Used for configuration inspection
|
||||
|
||||
```bash
|
||||
# Display configuration
|
||||
bootc config
|
||||
|
||||
# Display in specific format
|
||||
bootc config --json
|
||||
```
|
||||
|
||||
## Backup and Recovery Commands
|
||||
|
||||
### 1. tar
|
||||
**Purpose**: Archive files
|
||||
**Usage**: `tar [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for backup creation
|
||||
|
||||
```bash
|
||||
# Create backup
|
||||
tar -czf backup.tar.gz /sysroot
|
||||
|
||||
# Extract backup
|
||||
tar -xzf backup.tar.gz
|
||||
|
||||
# List archive contents
|
||||
tar -tzf backup.tar.gz
|
||||
```
|
||||
|
||||
### 2. rsync
|
||||
**Purpose**: Synchronize files
|
||||
**Usage**: `rsync [OPTIONS...] SRC DEST`
|
||||
**Integration**: Used for backup synchronization
|
||||
|
||||
```bash
|
||||
# Synchronize files
|
||||
rsync -av /sysroot/ /backup/sysroot/
|
||||
|
||||
# Synchronize with remote
|
||||
rsync -av /sysroot/ user@host:/backup/sysroot/
|
||||
```
|
||||
|
||||
## Performance Monitoring Commands
|
||||
|
||||
### 1. top
|
||||
**Purpose**: Display running processes
|
||||
**Usage**: `top [OPTIONS...]`
|
||||
**Integration**: Used for process monitoring
|
||||
|
||||
```bash
|
||||
# Display processes
|
||||
top
|
||||
|
||||
# Display specific process
|
||||
top -p $(pgrep bootc)
|
||||
```
|
||||
|
||||
### 2. ps
|
||||
**Purpose**: Display process information
|
||||
**Usage**: `ps [OPTIONS...]`
|
||||
**Integration**: Used for process analysis
|
||||
|
||||
```bash
|
||||
# Display all processes
|
||||
ps aux
|
||||
|
||||
# Display specific process
|
||||
ps aux | grep bootc
|
||||
|
||||
# Display process tree
|
||||
ps auxf
|
||||
```
|
||||
|
||||
### 3. vmstat
|
||||
**Purpose**: Display virtual memory statistics
|
||||
**Usage**: `vmstat [OPTIONS...]`
|
||||
**Integration**: Used for system performance monitoring
|
||||
|
||||
```bash
|
||||
# Display statistics
|
||||
vmstat
|
||||
|
||||
# Display with interval
|
||||
vmstat 1
|
||||
|
||||
# Display specific count
|
||||
vmstat 5 10
|
||||
```
|
||||
|
||||
This comprehensive external commands reference provides all the tools and commands needed to effectively manage, troubleshoot, and integrate with the bootc upgrade system.
|
||||
328
upgrade/quick-reference.md
Normal file
328
upgrade/quick-reference.md
Normal file
|
|
@ -0,0 +1,328 @@
|
|||
# bootc upgrade - Quick Reference
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc upgrade [OPTIONS...]
|
||||
```
|
||||
|
||||
## Common Options
|
||||
|
||||
| Option | Description | Example |
|
||||
|--------|-------------|---------|
|
||||
| `--check` | Check for updates without downloading | `bootc upgrade --check` |
|
||||
| `--apply` | Apply updates and reboot | `bootc upgrade --apply` |
|
||||
| `--quiet` | Suppress progress output | `bootc upgrade --quiet` |
|
||||
| `--soft-reboot` | Configure soft reboot behavior | `bootc upgrade --apply --soft-reboot=auto` |
|
||||
|
||||
## Soft Reboot Modes
|
||||
|
||||
| Mode | Description | Use Case |
|
||||
|------|-------------|----------|
|
||||
| `required` | Fail if soft reboot unavailable | Virtualized environments |
|
||||
| `auto` | Use soft reboot if available | General use (recommended) |
|
||||
|
||||
## Common Commands
|
||||
|
||||
### Check for Updates
|
||||
|
||||
```bash
|
||||
# Check if updates are available
|
||||
bootc upgrade --check
|
||||
|
||||
# Check quietly
|
||||
bootc upgrade --check --quiet
|
||||
```
|
||||
|
||||
### Download Updates
|
||||
|
||||
```bash
|
||||
# Download and stage updates
|
||||
bootc upgrade
|
||||
|
||||
# Download quietly
|
||||
bootc upgrade --quiet
|
||||
```
|
||||
|
||||
### Apply Updates
|
||||
|
||||
```bash
|
||||
# Apply updates and reboot
|
||||
bootc upgrade --apply
|
||||
|
||||
# Apply with soft reboot
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
|
||||
# Apply with required soft reboot
|
||||
bootc upgrade --apply --soft-reboot=required
|
||||
```
|
||||
|
||||
## Update Workflow
|
||||
|
||||
### 1. Check Phase
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
|
||||
# Expected output:
|
||||
# Update available for: quay.io/myorg/debian-bootc:latest
|
||||
# Version: 1.2.3
|
||||
# Digest: sha256:abc123...
|
||||
```
|
||||
|
||||
### 2. Download Phase
|
||||
|
||||
```bash
|
||||
# Download updates
|
||||
bootc upgrade
|
||||
|
||||
# Expected output:
|
||||
# Update available for: quay.io/myorg/debian-bootc:latest
|
||||
# Version: 1.2.3
|
||||
# Digest: sha256:abc123...
|
||||
# Staging update...
|
||||
# Update staged successfully
|
||||
```
|
||||
|
||||
### 3. Apply Phase
|
||||
|
||||
```bash
|
||||
# Apply updates
|
||||
bootc upgrade --apply
|
||||
|
||||
# Expected output:
|
||||
# Update available for: quay.io/myorg/debian-bootc:latest
|
||||
# Version: 1.2.3
|
||||
# Digest: sha256:abc123...
|
||||
# Staging update...
|
||||
# Update staged successfully
|
||||
# Rebooting system...
|
||||
```
|
||||
|
||||
## Status Commands
|
||||
|
||||
### Check System Status
|
||||
|
||||
```bash
|
||||
# View current status
|
||||
bootc status
|
||||
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
|
||||
# View status in JSON
|
||||
bootc status --json
|
||||
```
|
||||
|
||||
### Status Indicators
|
||||
|
||||
| Status | Description |
|
||||
|--------|-------------|
|
||||
| `booted` | Currently running system |
|
||||
| `staged` | Update ready for next boot |
|
||||
| `incompatible` | System has local modifications |
|
||||
|
||||
## Common Use Cases
|
||||
|
||||
### 1. Manual Updates
|
||||
|
||||
```bash
|
||||
# Check and apply updates
|
||||
bootc upgrade --check
|
||||
bootc upgrade --apply
|
||||
```
|
||||
|
||||
### 2. Automated Updates
|
||||
|
||||
```bash
|
||||
# Automated update with soft reboot
|
||||
bootc upgrade --apply --soft-reboot=auto --quiet
|
||||
```
|
||||
|
||||
### 3. CI/CD Integration
|
||||
|
||||
```bash
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
|
||||
# Apply if available
|
||||
if [ $? -eq 0 ]; then
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
fi
|
||||
```
|
||||
|
||||
### 4. Monitoring
|
||||
|
||||
```bash
|
||||
# Check update availability
|
||||
bootc upgrade --check
|
||||
|
||||
# Check system status
|
||||
bootc status
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Common Issues
|
||||
|
||||
| Problem | Solution |
|
||||
|---------|----------|
|
||||
| No updates available | Check image source with `bootc edit` |
|
||||
| Update fails to download | Check network and authentication |
|
||||
| Update fails to apply | Check system compatibility and logs |
|
||||
| Soft reboot fails | Use `--soft-reboot=auto` or regular reboot |
|
||||
|
||||
### Debug Commands
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc upgrade --check
|
||||
|
||||
# Check system status
|
||||
bootc status
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
|
||||
# Check image source
|
||||
bootc edit
|
||||
```
|
||||
|
||||
### Recovery Commands
|
||||
|
||||
```bash
|
||||
# Rollback to previous version
|
||||
bootc rollback
|
||||
|
||||
# Check rollback status
|
||||
bootc status
|
||||
|
||||
# Reset local modifications
|
||||
rpm-ostree reset
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Update Strategy
|
||||
|
||||
- **Test First**: Test updates in staging environment
|
||||
- **Check Before Apply**: Use `--check` before `--apply`
|
||||
- **Use Soft Reboot**: Use `--soft-reboot=auto` when possible
|
||||
- **Monitor Status**: Check `bootc status` regularly
|
||||
|
||||
### 2. Automation
|
||||
|
||||
- **Use `--check`**: For monitoring and CI/CD
|
||||
- **Use `--apply`**: For automated deployments
|
||||
- **Use `--quiet`**: For automated scripts
|
||||
- **Handle Errors**: Check return codes and handle failures
|
||||
|
||||
### 3. Security
|
||||
|
||||
- **Verify Images**: Ensure images are signed and trusted
|
||||
- **Use HTTPS**: Use secure registry connections
|
||||
- **Monitor Logs**: Check system logs for issues
|
||||
- **Test Rollback**: Ensure rollback works before applying
|
||||
|
||||
## Integration Examples
|
||||
|
||||
### Systemd Service
|
||||
|
||||
```ini
|
||||
# /etc/systemd/system/bootc-update.service
|
||||
[Unit]
|
||||
Description=Update bootc system
|
||||
After=network-online.target
|
||||
|
||||
[Service]
|
||||
Type=oneshot
|
||||
ExecStart=/usr/local/bin/update-system.sh
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
```
|
||||
|
||||
### Cron Job
|
||||
|
||||
```bash
|
||||
# Add to crontab
|
||||
0 2 * * * /usr/local/bin/update-system.sh
|
||||
```
|
||||
|
||||
### Shell Script
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# update-system.sh
|
||||
|
||||
if bootc upgrade --check; then
|
||||
bootc upgrade --apply --soft-reboot=auto
|
||||
fi
|
||||
```
|
||||
|
||||
## Performance Tips
|
||||
|
||||
### 1. Speed Optimization
|
||||
|
||||
- **Use `--check`**: For quick availability checks
|
||||
- **Use `--soft-reboot`**: For faster restarts
|
||||
- **Use `--quiet`**: For automated scripts
|
||||
- **Check First**: Use `--check` before downloading
|
||||
|
||||
### 2. Bandwidth Optimization
|
||||
|
||||
- **Check First**: Use `--check` before downloading
|
||||
- **Use Local Mirrors**: Use local registry mirrors
|
||||
- **Incremental Updates**: Only download changed layers
|
||||
- **Offline Updates**: Download updates offline
|
||||
|
||||
### 3. System Impact
|
||||
|
||||
- **Staged Updates**: No impact on running system
|
||||
- **Atomic Application**: All-or-nothing updates
|
||||
- **Rollback Capability**: Quick recovery from issues
|
||||
- **State Preservation**: Preserves `/etc` and `/var`
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Image Security
|
||||
|
||||
- **Signature Verification**: Ensure images are signed
|
||||
- **Registry Security**: Use trusted registries
|
||||
- **Digest Verification**: Verify image digests
|
||||
- **Access Control**: Control update permissions
|
||||
|
||||
### 2. Update Security
|
||||
|
||||
- **Network Security**: Use secure connections
|
||||
- **Authentication**: Authenticate with registries
|
||||
- **Authorization**: Control update permissions
|
||||
- **Audit Logging**: Log all update activities
|
||||
|
||||
### 3. Rollback Security
|
||||
|
||||
- **State Preservation**: Ensure `/etc` and `/var` are secure
|
||||
- **Access Control**: Limit rollback permissions
|
||||
- **Audit Logging**: Log all rollback activities
|
||||
- **Testing**: Test rollback procedures regularly
|
||||
|
||||
## Future Features
|
||||
|
||||
### 1. Planned Enhancements
|
||||
|
||||
- **Userspace Restart**: For kernel-unchanged updates
|
||||
- **Delta Updates**: More efficient layer downloads
|
||||
- **Rollback Automation**: Automatic rollback on failure
|
||||
- **Update Scheduling**: Time-based update application
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
- **API Support**: REST API for update management
|
||||
- **Webhook Integration**: Event notifications
|
||||
- **Metrics Collection**: Update performance metrics
|
||||
- **Dashboard Integration**: Web-based management
|
||||
|
||||
---
|
||||
|
||||
This quick reference provides essential commands and patterns for using `bootc upgrade` effectively.
|
||||
422
upgrade/technical-reference.md
Normal file
422
upgrade/technical-reference.md
Normal file
|
|
@ -0,0 +1,422 @@
|
|||
# bootc upgrade - Technical Reference
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
The bootc upgrade system is built on OSTree's A/B deployment model, providing transactional updates with rollback capabilities. The system integrates with container registries to pull updates and stages them for application at the next boot.
|
||||
|
||||
## Core Components
|
||||
|
||||
### 1. Upgrade Command Structure
|
||||
|
||||
```rust
|
||||
// From cli.rs:64-89
|
||||
pub(crate) struct UpgradeOpts {
|
||||
pub(crate) quiet: bool, // Suppress progress output
|
||||
pub(crate) check: bool, // Check-only mode
|
||||
pub(crate) apply: bool, // Apply and reboot
|
||||
pub(crate) soft_reboot: Option<SoftRebootMode>, // Soft reboot behavior
|
||||
pub(crate) progress: ProgressOptions, // Progress reporting
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Command-line interface configuration
|
||||
**Features**: Mutually exclusive options, progress control, soft reboot support
|
||||
|
||||
### 2. Upgrade Implementation
|
||||
|
||||
```rust
|
||||
// From cli.rs:860-969
|
||||
async fn upgrade(opts: UpgradeOpts) -> Result<()> {
|
||||
let sysroot = &get_storage().await?;
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let repo = &ostree.repo();
|
||||
let (booted_deployment, _deployments, host) = crate::status::get_status_require_booted(ostree)?;
|
||||
let imgref = host.spec.image.as_ref();
|
||||
let prog: ProgressWriter = opts.progress.try_into()?;
|
||||
// ... upgrade logic
|
||||
}
|
||||
```
|
||||
|
||||
**Process Flow**:
|
||||
1. **System Validation**: Check system status and compatibility
|
||||
2. **Image Resolution**: Determine source image reference
|
||||
3. **Update Check**: Verify if updates are available
|
||||
4. **Download/Stage**: Pull and stage updates
|
||||
5. **Application**: Apply updates if requested
|
||||
|
||||
## Upgrade Modes
|
||||
|
||||
### 1. Check Mode (`--check`)
|
||||
|
||||
```rust
|
||||
// From cli.rs:894-915
|
||||
if opts.check {
|
||||
let imgref = imgref.clone().into();
|
||||
let mut imp = crate::deploy::new_importer(repo, &imgref).await?;
|
||||
match imp.prepare().await? {
|
||||
PrepareResult::AlreadyPresent(_) => {
|
||||
println!("No changes in: {imgref:#}");
|
||||
}
|
||||
PrepareResult::Ready(r) => {
|
||||
crate::deploy::check_bootc_label(&r.config);
|
||||
println!("Update available for: {imgref:#}");
|
||||
if let Some(version) = r.version() {
|
||||
println!(" Version: {version}");
|
||||
}
|
||||
println!(" Digest: {}", r.manifest_digest);
|
||||
changed = true;
|
||||
// ... diff printing
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Check for updates without downloading
|
||||
**Benefits**: Fast execution, minimal bandwidth usage
|
||||
**Output**: Update availability, version info, digest comparison
|
||||
|
||||
### 2. Download Mode (default)
|
||||
|
||||
```rust
|
||||
// From cli.rs:916-949
|
||||
let fetched = crate::deploy::pull(repo, imgref, None, opts.quiet, prog.clone()).await?;
|
||||
let staged_digest = staged_image.map(|s| s.digest().expect("valid digest in status"));
|
||||
let fetched_digest = &fetched.manifest_digest;
|
||||
|
||||
let staged_unchanged = staged_digest
|
||||
.as_ref()
|
||||
.map(|d| d == fetched_digest)
|
||||
.unwrap_or_default();
|
||||
let booted_unchanged = booted_image
|
||||
.as_ref()
|
||||
.map(|img| &img.manifest_digest == fetched_digest)
|
||||
.unwrap_or_default();
|
||||
|
||||
if staged_unchanged {
|
||||
println!("Staged update present, not changed.");
|
||||
handle_staged_soft_reboot(ostree, opts.soft_reboot, &host)?;
|
||||
if opts.apply {
|
||||
crate::reboot::reboot()?;
|
||||
}
|
||||
} else if booted_unchanged {
|
||||
println!("No update available.")
|
||||
} else {
|
||||
let osname = booted_deployment.osname();
|
||||
crate::deploy::stage(sysroot, &osname, &fetched, &spec, prog.clone()).await?;
|
||||
changed = true;
|
||||
// ... diff printing
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Download and stage updates
|
||||
**Process**: Registry pull → OSTree import → Staging → Status update
|
||||
**Features**: Duplicate detection, progress reporting, diff display
|
||||
|
||||
### 3. Apply Mode (`--apply`)
|
||||
|
||||
```rust
|
||||
// From cli.rs:951-968
|
||||
if changed {
|
||||
sysroot.update_mtime()?;
|
||||
|
||||
if opts.soft_reboot.is_some() {
|
||||
let updated_host = crate::status::get_status(ostree, Some(&booted_deployment))?.1;
|
||||
handle_staged_soft_reboot(ostree, opts.soft_reboot, &updated_host)?;
|
||||
}
|
||||
|
||||
if opts.apply {
|
||||
crate::reboot::reboot()?;
|
||||
}
|
||||
} else {
|
||||
tracing::debug!("No changes");
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Apply staged updates and reboot
|
||||
**Process**: Update system status → Handle soft reboot → Reboot system
|
||||
**Features**: Soft reboot support, automatic reboot, status updates
|
||||
|
||||
## Soft Reboot System
|
||||
|
||||
### 1. Soft Reboot Modes
|
||||
|
||||
```rust
|
||||
// From cli.rs:81-85
|
||||
#[clap(long = "soft-reboot", conflicts_with = "check")]
|
||||
pub(crate) soft_reboot: Option<SoftRebootMode>,
|
||||
```
|
||||
|
||||
**Modes**:
|
||||
- `required`: Fail if soft reboot unavailable
|
||||
- `auto`: Use soft reboot if available, fallback to regular reboot
|
||||
|
||||
### 2. Soft Reboot Handling
|
||||
|
||||
```rust
|
||||
// From cli.rs:954-959
|
||||
if opts.soft_reboot.is_some() {
|
||||
let updated_host = crate::status::get_status(ostree, Some(&booted_deployment))?.1;
|
||||
handle_staged_soft_reboot(ostree, opts.soft_reboot, &updated_host)?;
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Configure soft reboot behavior
|
||||
**Process**: Check availability → Configure if supported → Fallback if needed
|
||||
|
||||
## Registry Integration
|
||||
|
||||
### 1. Image Reference Resolution
|
||||
|
||||
```rust
|
||||
// From cli.rs:865-889
|
||||
let imgref = host.spec.image.as_ref();
|
||||
let booted_image = host
|
||||
.status
|
||||
.booted
|
||||
.as_ref()
|
||||
.map(|b| b.query_image(repo))
|
||||
.transpose()?
|
||||
.flatten();
|
||||
let imgref = imgref.ok_or_else(|| anyhow::anyhow!("No image source specified"))?;
|
||||
```
|
||||
|
||||
**Purpose**: Determine source image for updates
|
||||
**Process**: Get from host spec → Validate availability → Use for upgrade
|
||||
|
||||
### 2. Container Registry Pull
|
||||
|
||||
```rust
|
||||
// From cli.rs:917
|
||||
let fetched = crate::deploy::pull(repo, imgref, None, opts.quiet, prog.clone()).await?;
|
||||
```
|
||||
|
||||
**Purpose**: Download container image from registry
|
||||
**Process**: Registry authentication → Layer download → OSTree conversion
|
||||
**Features**: Progress reporting, error handling, signature verification
|
||||
|
||||
## OSTree Integration
|
||||
|
||||
### 1. Deployment Management
|
||||
|
||||
```rust
|
||||
// From cli.rs:864
|
||||
let (booted_deployment, _deployments, host) = crate::status::get_status_require_booted(ostree)?;
|
||||
```
|
||||
|
||||
**Purpose**: Get current system state
|
||||
**Process**: Query OSTree → Get booted deployment → Get host configuration
|
||||
|
||||
### 2. Staging Process
|
||||
|
||||
```rust
|
||||
// From cli.rs:940
|
||||
crate::deploy::stage(sysroot, &osname, &fetched, &spec, prog.clone()).await?;
|
||||
```
|
||||
|
||||
**Purpose**: Stage updates for next boot
|
||||
**Process**: Create new deployment → Configure bootloader → Update status
|
||||
**Features**: Atomic staging, rollback capability, state preservation
|
||||
|
||||
## Status Management
|
||||
|
||||
### 1. System Status Query
|
||||
|
||||
```rust
|
||||
// From cli.rs:864
|
||||
let (booted_deployment, _deployments, host) = crate::status::get_status_require_booted(ostree)?;
|
||||
```
|
||||
|
||||
**Purpose**: Get current system state
|
||||
**Returns**: Booted deployment, all deployments, host configuration
|
||||
|
||||
### 2. Status Updates
|
||||
|
||||
```rust
|
||||
// From cli.rs:952
|
||||
sysroot.update_mtime()?;
|
||||
```
|
||||
|
||||
**Purpose**: Update system modification time
|
||||
**Process**: Update filesystem timestamp → Trigger status refresh
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Compatibility Checks
|
||||
|
||||
```rust
|
||||
// From cli.rs:869-879
|
||||
if imgref.is_none() {
|
||||
let booted_incompatible = host.status.booted.as_ref().is_some_and(|b| b.incompatible);
|
||||
let staged_incompatible = host.status.staged.as_ref().is_some_and(|b| b.incompatible);
|
||||
|
||||
if booted_incompatible || staged_incompatible {
|
||||
return Err(anyhow::anyhow!(
|
||||
"Deployment contains local rpm-ostree modifications; cannot upgrade via bootc. You can run `rpm-ostree reset` to undo the modifications."
|
||||
));
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Check system compatibility
|
||||
**Checks**: Local modifications, incompatible deployments
|
||||
**Error**: Prevents upgrade on incompatible systems
|
||||
|
||||
### 2. Update Validation
|
||||
|
||||
```rust
|
||||
// From cli.rs:902
|
||||
crate::deploy::check_bootc_label(&r.config);
|
||||
```
|
||||
|
||||
**Purpose**: Validate container image compatibility
|
||||
**Checks**: bootc labels, image configuration
|
||||
**Error**: Prevents upgrade of incompatible images
|
||||
|
||||
## Progress Reporting
|
||||
|
||||
### 1. Progress Writer
|
||||
|
||||
```rust
|
||||
// From cli.rs:866
|
||||
let prog: ProgressWriter = opts.progress.try_into()?;
|
||||
```
|
||||
|
||||
**Purpose**: Handle progress output
|
||||
**Features**: Quiet mode support, progress bars, status updates
|
||||
|
||||
### 2. Progress Options
|
||||
|
||||
```rust
|
||||
// From cli.rs:87-88
|
||||
#[clap(flatten)]
|
||||
pub(crate) progress: ProgressOptions,
|
||||
```
|
||||
|
||||
**Purpose**: Configure progress display
|
||||
**Options**: Quiet mode, progress bars, status updates
|
||||
|
||||
## Diff and Comparison
|
||||
|
||||
### 1. Manifest Comparison
|
||||
|
||||
```rust
|
||||
// From cli.rs:910-913
|
||||
if let Some(previous_image) = booted_image.as_ref() {
|
||||
let diff = ostree_container::ManifestDiff::new(&previous_image.manifest, &r.manifest);
|
||||
diff.print();
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Show differences between images
|
||||
**Process**: Compare manifests → Generate diff → Display changes
|
||||
**Features**: Layer changes, configuration differences, size changes
|
||||
|
||||
### 2. Update Information
|
||||
|
||||
```rust
|
||||
// From cli.rs:903-908
|
||||
println!("Update available for: {imgref:#}");
|
||||
if let Some(version) = r.version() {
|
||||
println!(" Version: {version}");
|
||||
}
|
||||
println!(" Digest: {}", r.manifest_digest);
|
||||
```
|
||||
|
||||
**Purpose**: Display update information
|
||||
**Information**: Image reference, version, digest, changes
|
||||
|
||||
## System Integration
|
||||
|
||||
### 1. Storage Management
|
||||
|
||||
```rust
|
||||
// From cli.rs:861
|
||||
let sysroot = &get_storage().await?;
|
||||
```
|
||||
|
||||
**Purpose**: Get system storage interface
|
||||
**Features**: OSTree integration, filesystem management
|
||||
|
||||
### 2. Reboot Integration
|
||||
|
||||
```rust
|
||||
// From cli.rs:962
|
||||
crate::reboot::reboot()?;
|
||||
```
|
||||
|
||||
**Purpose**: Reboot system after update
|
||||
**Process**: Trigger system reboot → Apply staged updates
|
||||
**Features**: Soft reboot support, reboot coordination
|
||||
|
||||
## Performance Optimizations
|
||||
|
||||
### 1. Duplicate Detection
|
||||
|
||||
```rust
|
||||
// From cli.rs:922-929
|
||||
let staged_unchanged = staged_digest
|
||||
.as_ref()
|
||||
.map(|d| d == fetched_digest)
|
||||
.unwrap_or_default();
|
||||
let booted_unchanged = booted_image
|
||||
.as_ref()
|
||||
.map(|img| &img.manifest_digest == fetched_digest)
|
||||
.unwrap_or_default();
|
||||
```
|
||||
|
||||
**Purpose**: Avoid unnecessary downloads
|
||||
**Process**: Compare digests → Skip if unchanged
|
||||
**Benefits**: Reduced bandwidth, faster execution
|
||||
|
||||
### 2. Incremental Updates
|
||||
|
||||
```rust
|
||||
// From cli.rs:917
|
||||
let fetched = crate::deploy::pull(repo, imgref, None, opts.quiet, prog.clone()).await?;
|
||||
```
|
||||
|
||||
**Purpose**: Download only changed layers
|
||||
**Process**: Registry comparison → Layer download → OSTree import
|
||||
**Benefits**: Reduced bandwidth, faster updates
|
||||
|
||||
## Security Features
|
||||
|
||||
### 1. Signature Verification
|
||||
|
||||
```rust
|
||||
// From cli.rs:917
|
||||
let fetched = crate::deploy::pull(repo, imgref, None, opts.quiet, prog.clone()).await?;
|
||||
```
|
||||
|
||||
**Purpose**: Verify image signatures
|
||||
**Process**: Registry authentication → Signature verification → Image validation
|
||||
**Features**: Cryptographic verification, trust validation
|
||||
|
||||
### 2. Image Validation
|
||||
|
||||
```rust
|
||||
// From cli.rs:902
|
||||
crate::deploy::check_bootc_label(&r.config);
|
||||
```
|
||||
|
||||
**Purpose**: Validate image compatibility
|
||||
**Process**: Check bootc labels → Verify configuration → Validate compatibility
|
||||
**Features**: Label verification, configuration validation
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
|
||||
- **Userspace Restart**: For kernel-unchanged updates
|
||||
- **Delta Updates**: More efficient layer downloads
|
||||
- **Rollback Automation**: Automatic rollback on failure
|
||||
- **Update Scheduling**: Time-based update application
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
- **API Support**: REST API for update management
|
||||
- **Webhook Integration**: Event notifications
|
||||
- **Metrics Collection**: Update performance metrics
|
||||
- **Dashboard Integration**: Web-based management
|
||||
|
||||
This technical reference provides comprehensive understanding of the bootc upgrade system's architecture, implementation, and integration patterns.
|
||||
Loading…
Add table
Add a link
Reference in a new issue