# bootc composefs-finalize-staged - Quick Reference

## Command Summary

| Command | Purpose | Usage |
|---------|---------|-------|
| `composefs-finalize-staged` | Finalize staged composefs deployments | `bootc composefs-finalize-staged` |

## Quick Commands

### Basic Operations
```bash
# Execute composefs-finalize-staged command
bootc composefs-finalize-staged

# Check if command is available
bootc --help | grep composefs-finalize-staged
```

### Systemd Service Operations
```bash
# Start service
systemctl start composefs-finalize-staged.service

# Enable service
systemctl enable composefs-finalize-staged.service

# Check service status
systemctl status composefs-finalize-staged.service

# Stop service
systemctl stop composefs-finalize-staged.service

# Restart service
systemctl restart composefs-finalize-staged.service
```

### Service Monitoring
```bash
# Check service logs
journalctl -u composefs-finalize-staged.service

# Follow logs in real-time
journalctl -u composefs-finalize-staged.service -f

# Show recent logs
journalctl -u composefs-finalize-staged.service -n 100

# Show logs since specific time
journalctl -u composefs-finalize-staged.service --since "1 hour ago"
```

## Common Options

| Option | Purpose | Example |
|--------|---------|---------|
| `--help` | Show help | `bootc composefs-finalize-staged --help` |
| `--verbose` | Verbose output | `bootc composefs-finalize-staged -v` |
| `--quiet` | Quiet output | `bootc composefs-finalize-staged -q` |

## Error Codes

| Code | Meaning | Solution |
|------|---------|----------|
| 0 | Success | Command completed successfully |
| 1 | General error | Check logs for details |
| 2 | No staged deployment | Create staged deployment |
| 3 | Non-composefs deployment | Verify deployment type |
| 4 | EROFS mount error | Check EROFS image and mount point |
| 5 | ESP mount error | Check ESP partition and mount point |

## Common Issues

### No Staged Deployment
```bash
# Error: No staged deployment found
# Solution: Check for staged deployment
ls -la /var/lib/composefs-transient-state/

# Create staged deployment if needed
echo "deployment-id" > /var/lib/composefs-transient-state/staged-deployment
```

### Non-Composefs Deployment
```bash
# Error: Staged deployment is not a composefs deployment
# Solution: Check deployment type
cat /sysroot/composefs/*/deployment-id.origin

# Verify composefs configuration
grep -i composefs /sysroot/composefs/*/deployment-id.origin
```

### EROFS Mount Error
```bash
# Error: Failed to mount EROFS image
# Solution: Check EROFS image
file /path/to/image.erofs

# Check mount point
ls -la /sysroot/

# Try manual mount
mount -t erofs /path/to/image.erofs /mnt/test
```

### ESP Mount Error
```bash
# Error: Failed to mount ESP partition
# Solution: Check ESP partition
lsblk | grep -i efi

# Check mount point
ls -la /boot/efi/

# Try manual mount
mount /dev/sda1 /mnt/esp
```

## 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` |
| Service file | Systemd service | `/usr/lib/systemd/system/composefs-finalize-staged.service` |
| Staged deployment | Staged deployment marker | `/var/lib/composefs-transient-state/staged-deployment` |
| Composefs state | Composefs state directory | `/sysroot/composefs/` |

## Log Files

| File | Purpose | Location |
|------|---------|----------|
| System logs | System messages | `/var/log/messages` |
| Journal logs | Systemd journal | `journalctl -u composefs-finalize-staged.service` |
| 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 /sysroot

# Check I/O usage
iotop -bn1 | head -20
```

### Monitor System
```bash
# Check service status
systemctl is-active composefs-finalize-staged.service

# Check service logs
journalctl -u composefs-finalize-staged.service --since "1 hour ago"

# Check system performance
top -bn1 | head -20
```

## Security Considerations

### Root Privileges
- All composefs-finalize-staged operations require root privileges
- Use `sudo` or switch to root user
- Check current user with `whoami`

### Sandboxing
- Service runs with systemd sandboxing
- `ProtectHome=yes` - restricts home directory access
- `ReadOnlyPaths=/etc` - prevents /etc modification

### Access Control
- Command accesses EROFS images for pristine configuration
- Command accesses ESP partition for bootloader operations
- Command manages system state for deployment management

## Best Practices

### Regular Operations
- Use systemd service for execution
- Execute early in boot process
- Monitor service status and logs
- Implement proper error handling

### Development
- Use in composefs-backend branch
- Test with staged deployments
- Document procedures
- Monitor system health

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

## Troubleshooting Steps

1. **Check service status**
   ```bash
   systemctl status composefs-finalize-staged.service
   ```

2. **Check service logs**
   ```bash
   journalctl -u composefs-finalize-staged.service --since "1 hour ago"
   ```

3. **Check staged deployment**
   ```bash
   ls -la /var/lib/composefs-transient-state/
   cat /var/lib/composefs-transient-state/staged-deployment
   ```

4. **Check composefs state**
   ```bash
   ls -la /sysroot/composefs/
   ```

5. **Check EROFS support**
   ```bash
   modprobe erofs
   lsmod | grep erofs
   ```

6. **Check ESP partition**
   ```bash
   lsblk | grep -i efi
   ls -la /boot/efi/
   ```

## Quick Scripts

### Health Check
```bash
#!/bin/bash
systemctl is-active composefs-finalize-staged.service && echo "Service healthy"
```

### Service Restart
```bash
#!/bin/bash
systemctl restart composefs-finalize-staged.service && echo "Service restarted"
```

### Log Check
```bash
#!/bin/bash
journalctl -u composefs-finalize-staged.service -n 50
```

### Staged Deployment Check
```bash
#!/bin/bash
[ -f "/var/lib/composefs-transient-state/staged-deployment" ] && echo "Staged deployment found" || echo "No staged deployment"
```

## Integration Examples

### Systemd Service
```bash
# Create service file
cat > /etc/systemd/system/composefs-finalize-staged.service << EOF
[Unit]
Description=Composefs Finalize Staged Deployment
Documentation=man:bootc(1)
DefaultDependencies=no

RequiresMountsFor=/sysroot
After=local-fs.target
Before=basic.target final.target
After=systemd-journal-flush.service
Conflicts=final.target

[Service]
Type=oneshot
RemainAfterExit=yes
ExecStop=/usr/bin/bootc composefs-finalize-staged
TimeoutStopSec=5m
ProtectHome=yes
ReadOnlyPaths=/etc
EOF

# Enable service
systemctl daemon-reload
systemctl enable composefs-finalize-staged.service
```

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

### Monitoring
```bash
# Check service health
if ! systemctl is-active composefs-finalize-staged.service > /dev/null 2>&1; then
    echo "WARNING: Composefs finalize staged service not active"
    # Send alert
fi
```

## Service Configuration

### Service Dependencies
- `RequiresMountsFor=/sysroot` - Requires /sysroot to be mounted
- `After=local-fs.target` - Runs after local filesystems are mounted
- `Before=basic.target final.target` - Runs before basic and final targets
- `After=systemd-journal-flush.service` - Runs after journal is flushed

### Service Security
- `ProtectHome=yes` - Protects home directory
- `ReadOnlyPaths=/etc` - Makes /etc read-only
- `TimeoutStopSec=5m` - 5-minute timeout for operations

### Service Execution
- `Type=oneshot` - Runs once and exits
- `RemainAfterExit=yes` - Service remains active after completion
- `ExecStop=/usr/bin/bootc composefs-finalize-staged` - Command to execute

This quick reference provides essential information for using the bootc composefs-finalize-staged system effectively.