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

# Daily maintenance
bootc internals fsck && bootc internals cleanup

# Check system status
bootc status

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

Development

# 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

# 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

# Generate units
bootc internals systemd-generator /run/systemd/system

# Fix fstab
bootc internals fixup-etc-fstab

# Reload systemd
systemctl daemon-reload

Proxy Commands

# 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

# Check user
whoami

# Run as root
sudo bootc internals <command>

Storage Full

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

# Clean up
bootc internals cleanup

# Remove old deployments
ostree admin cleanup

Systemd Issues

# Check status
systemctl status bootc-*

# Reload configuration
systemctl daemon-reload

# Restart services
systemctl restart bootc-*

Filesystem Errors

# 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

# Regular cleanup
bootc internals cleanup

# Compress repository
ostree admin cleanup --compress

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

Optimize Performance

# Check system load
uptime

# Check memory usage
free -h

# Check disk I/O
iotop

Monitor System

# 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

   bootc status
   systemctl status bootc-*
   

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

   bootc internals fsck
   bootc internals cleanup
   

5. Check configuration

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

Quick Scripts

Health Check

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

Maintenance

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

Monitoring

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