bootc-docs/state/bootc-state-technical-guide.md

bootc state - Technical Guide

Overview

bootc state is a hidden command that provides system state modification operations for bootc systems. Currently, it contains a single critical command: wipe-ostree, which removes all OSTree deployments from the system.

Purpose

The state commands serve critical system management functions:

1. System Reset: Complete removal of all OSTree deployments
2. Clean Slate: Prepare system for fresh installation
3. Recovery: Reset system to a clean state when deployments are corrupted
4. Maintenance: Remove all bootc-managed state

Command Structure

#[derive(Debug, clap::Subcommand, PartialEq, Eq)]
pub(crate) enum StateOpts {
    /// Remove all ostree deployments from this system
    WipeOstree,
}

Core Command: wipe-ostree

Purpose

The wipe-ostree command completely removes all OSTree deployments from the system, effectively resetting the bootc-managed state to a clean slate.

Usage

bootc state wipe-ostree

Functionality

• Complete Removal: Removes all OSTree deployments from the system
• System Reset: Resets the system to a state where no bootc deployments exist
• Clean Slate: Prepares the system for fresh installation
• Recovery: Can be used to recover from corrupted deployment states

Implementation

pub(crate) async fn wipe_ostree(sysroot: Sysroot) -> Result<()> {
    tokio::task::spawn_blocking(move || {
        sysroot
            .write_deployments(&[], gio::Cancellable::NONE)
            .context("removing deployments")
    })
    .await??;

    Ok(())
}

Command Routing

The command is routed through the main CLI dispatcher:

Opt::State(opts) => match opts {
    StateOpts::WipeOstree => {
        let sysroot = ostree::Sysroot::new_default();
        sysroot.load(gio::Cancellable::NONE)?;
        crate::deploy::wipe_ostree(sysroot).await?;
        Ok(())
    }
}

Technical Details

1. OSTree Integration

The wipe-ostree command directly interfaces with the OSTree library:

// Create OSTree sysroot instance
let sysroot = ostree::Sysroot::new_default();

// Load the sysroot
sysroot.load(gio::Cancellable::NONE)?;

// Remove all deployments by writing empty array
sysroot.write_deployments(&[], gio::Cancellable::NONE)
    .context("removing deployments")?;

2. Asynchronous Execution

The operation is executed asynchronously to prevent blocking:

tokio::task::spawn_blocking(move || {
    // OSTree operations in blocking context
    sysroot.write_deployments(&[], gio::Cancellable::NONE)
        .context("removing deployments")
}).await??;

3. Error Handling

Comprehensive error handling with context:

#[context("removing deployments")]
pub(crate) async fn wipe_ostree(sysroot: Sysroot) -> Result<()> {
    // Implementation with automatic error context
}

System Impact

1. What Gets Removed

• All OSTree Deployments: Every deployment managed by OSTree
• Boot Entries: All bootloader entries for bootc deployments
• System State: Complete reset of bootc-managed system state
• Deployment History: All deployment history and metadata

2. What Remains

• Base System: The underlying operating system remains intact
• User Data: User data in /home and other non-OSTree locations
• System Configuration: Non-OSTree system configuration
• Installed Packages: System packages not managed by OSTree

3. System State After Wipe

After running wipe-ostree, the system will be in a state where:

• No bootc deployments exist
• No OSTree-managed content is present
• The system may not boot if it was entirely OSTree-based
• Fresh installation is required to restore bootc functionality

Use Cases

1. System Recovery

When the system is in an unrecoverable state:

# Check current state
bootc status

# If system is corrupted, wipe and reinstall
bootc state wipe-ostree

# Reinstall from scratch
bootc install to-disk /dev/sda

2. Clean Installation

When preparing for a fresh installation:

# Wipe existing deployments
bootc state wipe-ostree

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

3. Development and Testing

When testing installation procedures:

# Reset test environment
bootc state wipe-ostree

# Test installation process
bootc install to-disk /dev/sda

4. System Migration

When migrating to a different bootc setup:

# Remove old deployments
bootc state wipe-ostree

# Install new configuration
bootc install to-disk /dev/sda

Security Considerations

1. Privilege Requirements

The command requires root privileges:

pub(crate) fn require_root(is_container: bool) -> Result<()> {
    ensure!(
        rustix::process::getuid().is_root(),
        if is_container {
            "The user inside the container from which you are running this command must be root"
        } else {
            "This command must be executed as the root user"
        }
    );
    Ok(())
}

2. Destructive Operation

This is a destructive operation that cannot be undone:

• No Undo: Once executed, deployments cannot be restored
• System Impact: May render system unbootable
• Data Loss: All bootc-managed state is lost

3. Safety Checks

The command should be used with extreme caution:

• Backup Required: Always backup important data before execution
• System Verification: Ensure system can be reinstalled
• Recovery Plan: Have a recovery plan ready

Error Handling

1. Common Error Scenarios

Permission Denied

# Error: Permission denied
# Solution: Run as root
sudo bootc state wipe-ostree

OSTree Not Available

# Error: OSTree not found
# Solution: Install OSTree
apt install ostree

System Not OSTree-Based

# Error: No OSTree deployments found
# Solution: Verify system is OSTree-based
ostree admin status

2. Error Recovery

If the command fails:

1. Check Logs: Review system logs for details
2. Verify System: Ensure system is OSTree-based
3. Check Permissions: Verify root privileges
4. Manual Cleanup: May require manual OSTree cleanup

Integration with Other Commands

1. Status Command

Check system state before and after:

# Before wipe
bootc status

# Wipe deployments
bootc state wipe-ostree

# After wipe (should show no deployments)
bootc status

2. Install Command

Typically followed by fresh installation:

# Wipe existing deployments
bootc state wipe-ostree

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

3. OSTree Commands

Can be used with OSTree commands:

# Check OSTree status
ostree admin status

# Wipe deployments
bootc state wipe-ostree

# Verify wipe
ostree admin status

Performance Characteristics

1. Execution Time

• Fast: Operation completes quickly
• Atomic: Single atomic operation
• Efficient: Minimal resource usage

2. Resource Usage

• Low CPU: Minimal CPU usage
• Low Memory: Minimal memory usage
• Disk I/O: Only metadata operations

3. System Impact

• Immediate: Effect is immediate
• Permanent: Cannot be undone
• Complete: Removes all deployments

Testing and Validation

1. Unit Tests

#[cfg(test)]
mod tests {
    use super::*;

    #[tokio::test]
    async fn test_wipe_ostree() {
        let temp_dir = tempfile::tempdir().unwrap();
        let sysroot = create_test_sysroot(temp_dir.path()).unwrap();
        
        // Add test deployments
        add_test_deployments(&sysroot).await.unwrap();
        
        // Verify deployments exist
        let deployments = sysroot.deployments();
        assert!(!deployments.is_empty());
        
        // Wipe deployments
        wipe_ostree(sysroot).await.unwrap();
        
        // Verify deployments are gone
        let deployments = sysroot.deployments();
        assert!(deployments.is_empty());
    }
}

2. Integration Tests

#[tokio::test]
async fn test_wipe_ostree_integration() {
    // Setup test environment
    let test_env = TestEnvironment::new().await.unwrap();
    
    // Install test system
    test_env.install_test_system().await.unwrap();
    
    // Verify system is installed
    let status = test_env.run_command("bootc", &["status"]).await.unwrap();
    assert!(status.contains("booted"));
    
    // Wipe deployments
    test_env.run_command("bootc", &["state", "wipe-ostree"]).await.unwrap();
    
    // Verify deployments are gone
    let status = test_env.run_command("bootc", &["status"]).await.unwrap();
    assert!(status.contains("No deployments found"));
}

Best Practices

1. Usage Guidelines

• Backup First: Always backup important data
• Verify System: Ensure system is OSTree-based
• Plan Recovery: Have recovery plan ready
• Test First: Test in non-production environment

2. Safety Measures

• Confirmation: Consider adding confirmation prompt
• Logging: Log all wipe operations
• Monitoring: Monitor system after wipe
• Documentation: Document wipe procedures

3. Recovery Procedures

• Fresh Install: Plan for fresh installation
• Data Recovery: Ensure data is backed up
• System Restore: Have system restore plan
• Testing: Test recovery procedures

Future Enhancements

1. Additional State Commands

Potential future state commands:

pub(crate) enum StateOpts {
    WipeOstree,
    ResetConfig,        // Reset configuration
    ClearCache,         // Clear system cache
    ResetSecrets,       // Reset secrets
    WipeComposefs,      // Wipe composefs data
    ResetBootloader,    // Reset bootloader
}

2. Safety Features

Enhanced safety features:

pub(crate) struct WipeOptions {
    pub confirm: bool,
    pub backup: bool,
    pub dry_run: bool,
    pub force: bool,
}

3. Recovery Tools

Recovery and restoration tools:

pub(crate) enum RecoveryOpts {
    RestoreFromBackup { backup_path: PathBuf },
    RestoreFromImage { image: String },
    RestoreFromSnapshot { snapshot: String },
}

Troubleshooting

1. Common Issues

Command Not Found

# Error: bootc state: command not found
# Solution: Ensure bootc is installed and in PATH
which bootc

Permission Denied

# Error: Permission denied
# Solution: Run as root
sudo bootc state wipe-ostree

OSTree Error

# Error: OSTree operation failed
# Solution: Check OSTree installation and system state
ostree --version
ostree admin status

2. Debug Information

Enable debug logging:

# Set debug log level
export RUST_LOG=debug

# Run command with debug output
bootc state wipe-ostree

# Check debug logs
journalctl -u bootc-* --since "1 hour ago" | grep DEBUG

3. System Verification

Verify system state:

# Check OSTree status
ostree admin status

# Check bootc status
bootc status

# Check system logs
journalctl -u bootc-* --since "1 hour ago"

This technical guide provides comprehensive understanding of the bootc state system's functionality, implementation, and usage patterns.