bootc-docs/internals/bootc-internals-quick-reference.md

# bootc internals - Quick Reference

## Command Summary

| Command | Purpose | Usage |
|---------|---------|-------|
| `systemd-generator` | Generate systemd units | `bootc internals systemd-generator <dir>` |
| `fixup-etc-fstab` | Fix /etc/fstab | `bootc internals fixup-etc-fstab` |
| `print-json-schema` | Generate JSON schemas | `bootc internals print-json-schema --of <type>` |
| `fsverity` | Filesystem verity ops | `bootc internals fsverity <subcommand>` |
| `fsck` | Filesystem consistency | `bootc internals fsck` |
| `cleanup` | System cleanup | `bootc internals cleanup` |
| `relabel` | SELinux relabeling | `bootc internals relabel <path>` |
| `ostree-ext` | Proxy to ostree-ext | `bootc internals ostree-ext [args...]` |
| `cfs` | Proxy to cfsctl | `bootc internals cfs [args...]` |
| `ostree-container` | Proxy to ostree container | `bootc internals ostree-container [args...]` |
| `test-composefs` | Test composefs repo | `bootc internals test-composefs` |
| `loopback-cleanup-helper` | Loopback cleanup | `bootc internals loopback-cleanup-helper --device <dev>` |
| `allocate-cleanup-loopback` | Test loopback | `bootc internals allocate-cleanup-loopback --file-path <path>` |
| `bootc-install-completion` | Complete installation | `bootc internals bootc-install-completion --sysroot <path> --stateroot <name>` |
| `reboot` | Initiate reboot | `bootc internals reboot` |
| `publish-rhsm-facts` | Publish RHSM facts | `bootc internals publish-rhsm-facts` |
| `dump-cli-json` | Dump CLI JSON | `bootc internals dump-cli-json` |
| `dir-diff` | Test directory diff | `bootc internals dir-diff <pristine> <current> <new> [--perform-merge]` |

## Fsverity Subcommands

| Subcommand | Purpose | Usage |
|------------|---------|-------|
| `measure` | Measure file digest | `bootc internals fsverity measure --path <file>` |
| `enable` | Enable verity | `bootc internals fsverity enable --path <file>` |

## Common Options

| Option | Purpose | Example |
|--------|---------|---------|
| `--help` | Show help | `bootc internals --help` |
| `--verbose` | Verbose output | `bootc internals fsck --verbose` |
| `--quiet` | Quiet output | `bootc internals cleanup --quiet` |

## Quick Commands

### System Maintenance
```bash
# Daily maintenance
bootc internals fsck && bootc internals cleanup

# Check system status
bootc status

# Check storage usage
df -h /var/lib/bootc
```

### Development
```bash
# Test composefs
bootc internals test-composefs

# Test loopback device
bootc internals allocate-cleanup-loopback --file-path /tmp/test.img

# Test directory diff
bootc internals dir-diff /tmp/pristine /tmp/current /tmp/new --perform-merge
```

### Debugging
```bash
# Enable debug logging
RUST_LOG=debug bootc internals fsck

# Check systemd services
systemctl status bootc-*

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

### Systemd Integration
```bash
# Generate units
bootc internals systemd-generator /run/systemd/system

# Fix fstab
bootc internals fixup-etc-fstab

# Reload systemd
systemctl daemon-reload
```

### Proxy Commands
```bash
# OSTree operations
bootc internals ostree-ext container pull quay.io/myorg/image:latest

# Composefs operations
bootc internals cfs create-fs myimage /tmp/output

# Legacy ostree container
bootc internals ostree-container pull quay.io/myorg/image:latest
```

## Error Codes

| Code | Meaning | Solution |
|------|---------|----------|
| 1 | General error | Check logs for details |
| 2 | Permission denied | Run as root |
| 3 | Resource error | Check storage/memory |
| 4 | Configuration error | Check configuration files |
| 5 | System error | Check system status |

## Common Issues

### Permission Denied
```bash
# Check user
whoami

# Run as root
sudo bootc internals <command>
```

### Storage Full
```bash
# Check usage
df -h /var/lib/bootc

# Clean up
bootc internals cleanup

# Remove old deployments
ostree admin cleanup
```

### Systemd Issues
```bash
# Check status
systemctl status bootc-*

# Reload configuration
systemctl daemon-reload

# Restart services
systemctl restart bootc-*
```

### Filesystem Errors
```bash
# Check integrity
bootc internals fsck

# Repair if needed
ostree fsck --repair

# Restore from backup
ostree admin deploy --from-commit <backup>
```

## 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` |
| Systemd units | Generated units | `/run/systemd/system/` |
| OSTree repo | Repository data | `/var/lib/bootc/ostree/` |
| Composefs repo | Composefs data | `/var/lib/bootc/composefs/` |

## 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 Storage
```bash
# Regular cleanup
bootc internals cleanup

# Compress repository
ostree admin cleanup --compress

# Remove old deployments
ostree admin cleanup --keep=3
```

### Optimize Performance
```bash
# Check system load
uptime

# Check memory usage
free -h

# Check disk I/O
iotop
```

### Monitor System
```bash
# Check system status
bootc status

# Check filesystem integrity
bootc internals fsck

# Check storage usage
df -h /var/lib/bootc
```

## Security Considerations

### Root Privileges
- All internals commands require root privileges
- Use `sudo` or switch to root user
- Check current user with `whoami`

### Input Validation
- All paths are validated for security
- Path traversal attacks are prevented
- Absolute paths are required

### Resource Limits
- Memory usage is limited
- CPU usage is monitored
- Storage usage is tracked

## Best Practices

### Regular Maintenance
- Run `fsck` daily
- Run `cleanup` weekly
- Monitor storage usage
- Check system logs

### Development
- Use test environments
- Test commands before production
- Document custom usage
- Monitor system health

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

## Troubleshooting Steps

1. **Check system status**
   ```bash
   bootc status
   systemctl status bootc-*
   ```

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
   bootc internals fsck
   bootc internals cleanup
   ```

5. **Check configuration**
   ```bash
   cat /etc/bootc/config.toml
   systemctl daemon-reload
   ```

## Quick Scripts

### Health Check
```bash
#!/bin/bash
bootc status && bootc internals fsck && echo "System healthy"
```

### Maintenance
```bash
#!/bin/bash
bootc internals fsck && bootc internals cleanup && echo "Maintenance complete"
```

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

This quick reference provides essential information for using the bootc internals system effectively.