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

```rust
#[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

```bash
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

```rust
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:

```rust
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:

```rust
// 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:

```rust
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:

```rust
#[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:

```bash
# 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:

```bash
# Wipe existing deployments
bootc state wipe-ostree

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

### 3. Development and Testing

When testing installation procedures:

```bash
# 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:

```bash
# 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:

```rust
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
```bash
# Error: Permission denied
# Solution: Run as root
sudo bootc state wipe-ostree
```

#### OSTree Not Available
```bash
# Error: OSTree not found
# Solution: Install OSTree
apt install ostree
```

#### System Not OSTree-Based
```bash
# 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:

```bash
# 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:

```bash
# 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:

```bash
# 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

```rust
#[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

```rust
#[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:

```rust
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:

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

### 3. Recovery Tools

Recovery and restoration tools:

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

## Troubleshooting

### 1. Common Issues

#### Command Not Found
```bash
# Error: bootc state: command not found
# Solution: Ensure bootc is installed and in PATH
which bootc
```

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

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

### 2. Debug Information

Enable debug logging:

```bash
# 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:

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