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

# Wipe all OSTree deployments
bootc state wipe-ostree

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

System Status

# Check current state
bootc status

# Check OSTree status
ostree admin status

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

Recovery Operations

# 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

# Check user
whoami

# Run as root
sudo bootc state wipe-ostree

OSTree Not Available

# Install OSTree
apt install ostree

# Verify installation
ostree --version

System Not OSTree-Based

# Check system type
ostree admin status

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

Repository Corruption

# 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

# Check system load
uptime

# Check memory usage
free -h

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

Monitor System

# 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

   bootc status
   ostree admin status
   

2. Check logs

   journalctl -u bootc-* --since "1 hour ago"
   tail -f /var/log/bootc/main.log
   

3. Check resources

   df -h /var/lib/bootc
   free -h
   uptime
   

4. Run diagnostics

   ostree fsck
   bootc status
   

5. Check configuration

   cat /etc/bootc/config.toml
   systemctl daemon-reload
   

Quick Scripts

Health Check

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

System Reset

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

Recovery

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

Monitoring

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

Integration Examples

Systemd Service

# 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

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

Monitoring

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