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