526f1c1afd
- 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
328 lines
6.7 KiB
Markdown
328 lines
6.7 KiB
Markdown
# 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.
|