bootc-docs/upgrade/quick-reference.md

bootc upgrade - Quick Reference

Command Syntax

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

# Check if updates are available
bootc upgrade --check

# Check quietly
bootc upgrade --check --quiet

Download Updates

# Download and stage updates
bootc upgrade

# Download quietly
bootc upgrade --quiet

Apply Updates

# 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

# 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

# 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

# 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

# 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

# Check and apply updates
bootc upgrade --check
bootc upgrade --apply

2. Automated Updates

# Automated update with soft reboot
bootc upgrade --apply --soft-reboot=auto --quiet

3. CI/CD Integration

# Check for updates
bootc upgrade --check

# Apply if available
if [ $? -eq 0 ]; then
    bootc upgrade --apply --soft-reboot=auto
fi

4. Monitoring

# 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

# 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

# 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

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

# Add to crontab
0 2 * * * /usr/local/bin/update-system.sh

Shell Script

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