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
292
state/bootc-state-quick-reference.md
Normal file
292
state/bootc-state-quick-reference.md
Normal file
|
|
@ -0,0 +1,292 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue