bootc-docs/state/bootc-state-quick-reference.md

# bootc state - Quick Reference

## Command Summary

| Command | Purpose | Usage |
|---------|---------|-------|
| `wipe-ostree` | Remove all OSTree deployments | `bootc state wipe-ostree` |
| `help` | Show help information | `bootc state --help` |

## Quick Commands

### Basic Operations
```bash
# Wipe all OSTree deployments
bootc state wipe-ostree

# Show help
bootc state --help
bootc state wipe-ostree --help
```

### System Status
```bash
# Check current state
bootc status

# Check OSTree status
ostree admin status

# Check system health
bootc status && echo "System healthy"
```

### Recovery Operations
```bash
# Complete system reset
bootc state wipe-ostree && bootc install to-disk /dev/sda

# Emergency recovery
bootc state wipe-ostree

# Verify recovery
bootc status
```

## Common Options

| Option | Purpose | Example |
|--------|---------|---------|
| `--help` | Show help | `bootc state --help` |
| `--verbose` | Verbose output | `bootc state wipe-ostree --verbose` |
| `--quiet` | Quiet output | `bootc state wipe-ostree --quiet` |

## Error Codes

| Code | Meaning | Solution |
|------|---------|----------|
| 1 | General error | Check logs for details |
| 2 | Permission denied | Run as root |
| 3 | OSTree not available | Install OSTree |
| 4 | System not OSTree-based | Install OSTree system |
| 5 | Repository corruption | Repair or wipe repository |

## Common Issues

### Permission Denied
```bash
# Check user
whoami

# Run as root
sudo bootc state wipe-ostree
```

### OSTree Not Available
```bash
# Install OSTree
apt install ostree

# Verify installation
ostree --version
```

### System Not OSTree-Based
```bash
# Check system type
ostree admin status

# Install OSTree system
bootc install to-disk /dev/sda
```

### Repository Corruption
```bash
# Check repository
ostree fsck

# Repair repository
ostree fsck --repair

# If repair fails, wipe and reinstall
bootc state wipe-ostree
bootc install to-disk /dev/sda
```

## Environment Variables

| Variable | Purpose | Default |
|----------|---------|---------|
| `RUST_LOG` | Log level | `info` |
| `BOOTC_DEBUG` | Debug mode | `false` |
| `BOOTC_CONFIG` | Config file | `/etc/bootc/config.toml` |

## Configuration Files

| File | Purpose | Location |
|------|---------|----------|
| Main config | Bootc configuration | `/etc/bootc/config.toml` |
| OSTree repo | Repository data | `/var/lib/bootc/ostree/` |
| System state | System state | `/var/lib/bootc/state/` |

## Log Files

| File | Purpose | Location |
|------|---------|----------|
| System logs | System messages | `/var/log/messages` |
| Journal logs | Systemd journal | `journalctl -u bootc-*` |
| Bootc logs | Bootc specific | `/var/log/bootc/` |

## Performance Tips

### Optimize Operations
```bash
# Check system load
uptime

# Check memory usage
free -h

# Check disk usage
df -h /var/lib/bootc
```

### Monitor System
```bash
# Check system status
bootc status

# Check OSTree status
ostree admin status

# Check repository integrity
ostree fsck
```

## Security Considerations

### Root Privileges
- All state commands require root privileges
- Use `sudo` or switch to root user
- Check current user with `whoami`

### Destructive Operations
- This is a destructive operation that cannot be undone
- Always backup important data before execution
- Verify system can be reinstalled

### Safety Checks
- Check system state before wiping
- Ensure recovery plan is ready
- Test in non-production environment

## Best Practices

### Regular Maintenance
- Check system health regularly
- Monitor storage usage
- Check repository integrity
- Plan for recovery

### Development
- Use test environments
- Test commands before production
- Document procedures
- Monitor system health

### Production
- Set up monitoring
- Configure alerts
- Regular backups
- Document procedures

## Troubleshooting Steps

1. **Check system status**
   ```bash
   bootc status
   ostree admin status
   ```

2. **Check logs**
   ```bash
   journalctl -u bootc-* --since "1 hour ago"
   tail -f /var/log/bootc/main.log
   ```

3. **Check resources**
   ```bash
   df -h /var/lib/bootc
   free -h
   uptime
   ```

4. **Run diagnostics**
   ```bash
   ostree fsck
   bootc status
   ```

5. **Check configuration**
   ```bash
   cat /etc/bootc/config.toml
   systemctl daemon-reload
   ```

## Quick Scripts

### Health Check
```bash
#!/bin/bash
bootc status && ostree admin status && echo "System healthy"
```

### System Reset
```bash
#!/bin/bash
bootc state wipe-ostree && echo "System reset complete"
```

### Recovery
```bash
#!/bin/bash
bootc state wipe-ostree && bootc install to-disk /dev/sda
```

### Monitoring
```bash
#!/bin/bash
df -h /var/lib/bootc | tail -1 | awk '{print $5}' | sed 's/%//'
```

## Integration Examples

### Systemd Service
```bash
# Create service file
cat > /etc/systemd/system/bootc-state.service << EOF
[Unit]
Description=Bootc State Service
After=multi-user.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/bootc-state-script.sh
User=root
Group=root

[Install]
WantedBy=multi-user.target
EOF

# Enable service
systemctl daemon-reload
systemctl enable bootc-state.service
```

### Cron Job
```bash
# Add to crontab
echo "0 2 * * * /usr/local/bin/bootc-state-maintenance.sh" | crontab -
```

### Monitoring
```bash
# Check system health
if ! bootc status > /dev/null 2>&1; then
    echo "WARNING: System status check failed"
    # Send alert
fi
```

This quick reference provides essential information for using the bootc state system effectively.