Initial commit: Comprehensive Debian bootc documentation

- Complete documentation for all bootc commands and subcommands - Debian-specific adaptations and workarounds - Manual installation methods to bypass bootc reliability issues - Technical guides with Rust source code analysis - Flowcharts and external command references - Hidden command documentation (bootc internals, state, etc.) - Composefs integration analysis - Base image creation guides (with and without bootc binary) - Management scripts and automation - Comprehensive troubleshooting and examples
2025-09-15 14:02:28 -07:00 · 2025-09-15 14:02:28 -07:00 · 526f1c1afd
commit 526f1c1afd
67 changed files with 34174 additions and 0 deletions
--- a/switch/bootc-switch-external-commands.md
+++ b/switch/bootc-switch-external-commands.md
@ -0,0 +1,897 @@
+# bootc switch - External Commands Reference
+
+## Overview
+
+This document provides a comprehensive reference for all external commands, system services, and tools that interact with or are used by the `bootc switch` system. Understanding these external dependencies is crucial for troubleshooting, monitoring, and integrating bootc switch into larger systems.
+
+## Core System Commands
+
+### 1. bootc Commands
+
+#### bootc switch
+**Purpose**: Switch to different container image reference
+**Usage**: `bootc switch [OPTIONS...] <TARGET>`
+**External Dependencies**:
+- `ostree` - For deployment management
+- `podman` - For container registry access
+- `systemd` - For service management and reboot
+
+```bash
+# Switch to different image version
+bootc switch quay.io/myorg/debian-bootc:v2.0
+
+# Switch and apply immediately
+bootc switch --apply quay.io/myorg/debian-bootc:v2.0
+
+# Switch with soft reboot
+bootc switch --apply --soft-reboot=auto quay.io/myorg/debian-bootc:v2.0
+
+# Switch with specific transport
+bootc switch --transport=oci-archive quay.io/myorg/debian-bootc:v2.0
+```
+
+#### bootc status
+**Purpose**: Check system status and deployment state
+**Usage**: `bootc status [OPTIONS...]`
+**External Dependencies**:
+- `ostree` - For deployment information
+- `systemd` - For service status
+
+```bash
+# Check current status
+bootc status
+
+# Check status in JSON format
+bootc status --json
+
+# Check specific deployment
+bootc status --deployment=deployment-id
+```
+
+#### bootc upgrade
+**Purpose**: Update current image to newer version
+**Usage**: `bootc upgrade [OPTIONS...]`
+**External Dependencies**:
+- `ostree` - For deployment management
+- `podman` - For container registry access
+
+```bash
+# Check for updates
+bootc upgrade --check
+
+# Download and stage updates
+bootc upgrade
+
+# Apply updates and reboot
+bootc upgrade --apply
+```
+
+#### bootc rollback
+**Purpose**: Rollback to previous deployment
+**Usage**: `bootc rollback [OPTIONS...]`
+**External Dependencies**:
+- `ostree` - For deployment switching
+- `systemd` - For service management
+
+```bash
+# Rollback to previous version
+bootc rollback
+
+# Rollback to specific deployment
+bootc rollback --deployment=deployment-id
+```
+
+### 2. OSTree Commands
+
+#### ostree admin status
+**Purpose**: Check OSTree deployment status
+**Usage**: `ostree admin status`
+**Integration**: Used by `bootc status` for deployment information
+
+```bash
+# Check deployment status
+ostree admin status
+
+# Check specific deployment
+ostree admin status --deployment=deployment-id
+```
+
+#### ostree admin deploy
+**Purpose**: Deploy new OSTree deployment
+**Usage**: `ostree admin deploy [OPTIONS...]`
+**Integration**: Used internally by bootc for staging updates
+
+```bash
+# Deploy new deployment
+ostree admin deploy --os=debian-bootc deployment-id
+
+# Deploy with specific options
+ostree admin deploy --os=debian-bootc --karg=console=ttyS0 deployment-id
+```
+
+#### ostree admin rollback
+**Purpose**: Rollback to previous deployment
+**Usage**: `ostree admin rollback [OPTIONS...]`
+**Integration**: Used by `bootc rollback` for deployment switching
+
+```bash
+# Rollback to previous deployment
+ostree admin rollback
+
+# Rollback with specific options
+ostree admin rollback --deployment=deployment-id
+```
+
+#### ostree admin cleanup
+**Purpose**: Clean up old deployments and free space
+**Usage**: `ostree admin cleanup [OPTIONS...]`
+**Integration**: Used for disk space management
+
+```bash
+# Clean up old deployments
+ostree admin cleanup
+
+# Clean up with specific options
+ostree admin cleanup --keep=2
+```
+
+#### ostree refs
+**Purpose**: List OSTree references
+**Usage**: `ostree refs [OPTIONS...]`
+**Integration**: Used for reference management
+
+```bash
+# List all references
+ostree refs
+
+# List references for specific remote
+ostree refs --remote=quay.io
+
+# List references with details
+ostree refs --list
+```
+
+### 3. Container Registry Commands
+
+#### podman pull
+**Purpose**: Pull container images from registry
+**Usage**: `podman pull [OPTIONS...] IMAGE`
+**Integration**: Used by bootc for downloading images
+
+```bash
+# Pull image from registry
+podman pull quay.io/myorg/debian-bootc:v2.0
+
+# Pull with authentication
+podman pull --creds=username:password quay.io/myorg/debian-bootc:v2.0
+
+# Pull specific tag
+podman pull quay.io/myorg/debian-bootc:latest
+```
+
+#### podman login
+**Purpose**: Authenticate with container registry
+**Usage**: `podman login [OPTIONS...] REGISTRY`
+**Integration**: Required for private registry access
+
+```bash
+# Login to registry
+podman login quay.io
+
+# Login with specific credentials
+podman login --username=myuser --password=mypass quay.io
+
+# Login with token
+podman login --authfile=/path/to/auth.json quay.io
+```
+
+#### podman inspect
+**Purpose**: Inspect container image metadata
+**Usage**: `podman inspect [OPTIONS...] IMAGE`
+**Integration**: Used for image validation and metadata extraction
+
+```bash
+# Inspect image
+podman inspect quay.io/myorg/debian-bootc:v2.0
+
+# Inspect specific configuration
+podman inspect --format='{{.Config.Labels}}' quay.io/myorg/debian-bootc:v2.0
+
+# Inspect manifest
+podman inspect --format='{{.Manifest}}' quay.io/myorg/debian-bootc:v2.0
+```
+
+#### podman images
+**Purpose**: List container images
+**Usage**: `podman images [OPTIONS...]`
+**Integration**: Used for image management
+
+```bash
+# List all images
+podman images
+
+# List images with specific format
+podman images --format "table {{.Repository}} {{.Tag}} {{.ID}}"
+
+# List images with filters
+podman images --filter "reference=quay.io/myorg/*"
+```
+
+#### podman rmi
+**Purpose**: Remove container images
+**Usage**: `podman rmi [OPTIONS...] IMAGE`
+**Integration**: Used for image cleanup
+
+```bash
+# Remove specific image
+podman rmi quay.io/myorg/debian-bootc:v1.0
+
+# Remove image by ID
+podman rmi abc123def456
+
+# Remove unused images
+podman image prune
+```
+
+### 4. System Management Commands
+
+#### systemctl
+**Purpose**: Control systemd services and units
+**Usage**: `systemctl [COMMAND] [UNIT...]`
+**Integration**: Used for service management and reboot coordination
+
+```bash
+# Check service status
+systemctl status bootc-fetch-apply-updates.service
+
+# Start service
+systemctl start bootc-fetch-apply-updates.service
+
+# Enable service
+systemctl enable bootc-fetch-apply-updates.service
+
+# Restart service
+systemctl restart bootc-fetch-apply-updates.service
+```
+
+#### reboot
+**Purpose**: Reboot the system
+**Usage**: `reboot [OPTIONS...]`
+**Integration**: Used by `bootc switch --apply` for system restart
+
+```bash
+# Reboot system
+reboot
+
+# Reboot with specific delay
+reboot +5
+
+# Reboot with message
+reboot "Applying bootc switch"
+```
+
+#### shutdown
+**Purpose**: Shutdown the system
+**Usage**: `shutdown [OPTIONS...]`
+**Integration**: Used for controlled shutdown before reboot
+
+```bash
+# Shutdown system
+shutdown -h now
+
+# Shutdown with delay
+shutdown -h +5
+
+# Shutdown with message
+shutdown -h now "Applying bootc switch"
+```
+
+## Network and Registry Commands
+
+### 1. HTTP Clients
+
+#### curl
+**Purpose**: HTTP client for registry communication
+**Usage**: `curl [OPTIONS...] URL`
+**Integration**: Used for registry API calls and authentication
+
+```bash
+# Test registry connectivity
+curl -I https://quay.io/v2/
+
+# Check registry API
+curl -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
+     https://quay.io/v2/myorg/debian-bootc/manifests/v2.0
+
+# Authenticate with registry
+curl -u username:password https://quay.io/v2/token
+```
+
+#### wget
+**Purpose**: Download files from web servers
+**Usage**: `wget [OPTIONS...] URL`
+**Integration**: Alternative to curl for registry communication
+
+```bash
+# Download registry manifest
+wget -O manifest.json https://quay.io/v2/myorg/debian-bootc/manifests/v2.0
+
+# Download with authentication
+wget --user=username --password=password https://quay.io/v2/token
+```
+
+### 2. DNS Resolution
+
+#### dig
+**Purpose**: DNS lookup tool
+**Usage**: `dig [OPTIONS...] DOMAIN`
+**Integration**: Used for DNS resolution troubleshooting
+
+```bash
+# Resolve registry domain
+dig quay.io
+
+# Check specific DNS record
+dig quay.io A
+
+# Check DNS server
+dig @8.8.8.8 quay.io
+```
+
+#### nslookup
+**Purpose**: DNS lookup tool
+**Usage**: `nslookup [OPTIONS...] DOMAIN`
+**Integration**: Alternative to dig for DNS troubleshooting
+
+```bash
+# Resolve registry domain
+nslookup quay.io
+
+# Check specific DNS record
+nslookup -type=A quay.io
+```
+
+### 3. Network Troubleshooting
+
+#### ping
+**Purpose**: Test network connectivity
+**Usage**: `ping [OPTIONS...] HOST`
+**Integration**: Used for testing registry connectivity
+
+```bash
+# Test connectivity
+ping quay.io
+
+# Test with specific count
+ping -c 4 quay.io
+
+# Test with specific interface
+ping -I eth0 quay.io
+```
+
+#### traceroute
+**Purpose**: Trace network path
+**Usage**: `traceroute [OPTIONS...] HOST`
+**Integration**: Used for network path analysis
+
+```bash
+# Trace path to registry
+traceroute quay.io
+
+# Trace with specific options
+traceroute -n quay.io
+```
+
+## File System Commands
+
+### 1. File Operations
+
+#### cat
+**Purpose**: Display file contents
+**Usage**: `cat [OPTIONS...] [FILE...]`
+**Integration**: Used for displaying configuration files
+
+```bash
+# Display file contents
+cat /etc/bootc/config.yaml
+
+# Display with line numbers
+cat -n /etc/bootc/config.yaml
+
+# Display non-printing characters
+cat -v /etc/bootc/config.yaml
+```
+
+#### cp
+**Purpose**: Copy files
+**Usage**: `cp [OPTIONS...] SOURCE DEST`
+**Integration**: Used for backing up configuration files
+
+```bash
+# Copy file
+cp /etc/bootc/config.yaml /etc/bootc/config.yaml.backup
+
+# Copy with preserve attributes
+cp -p /etc/bootc/config.yaml /etc/bootc/config.yaml.backup
+
+# Copy recursively
+cp -r /etc/bootc/ /etc/bootc.backup/
+```
+
+#### mv
+**Purpose**: Move or rename files
+**Usage**: `mv [OPTIONS...] SOURCE DEST`
+**Integration**: Used for renaming configuration files
+
+```bash
+# Rename file
+mv /etc/bootc/config.yaml /etc/bootc/config.yaml.old
+
+# Move file
+mv /etc/bootc/config.yaml /backup/config.yaml
+```
+
+#### rm
+**Purpose**: Remove files
+**Usage**: `rm [OPTIONS...] FILE...`
+**Integration**: Used for cleaning up temporary files
+
+```bash
+# Remove file
+rm /etc/bootc/config.yaml
+
+# Remove with confirmation
+rm -i /etc/bootc/config.yaml
+
+# Remove recursively
+rm -r /etc/bootc/
+```
+
+### 2. Directory Operations
+
+#### mkdir
+**Purpose**: Create directories
+**Usage**: `mkdir [OPTIONS...] DIRECTORY...`
+**Integration**: Used for creating configuration directories
+
+```bash
+# Create directory
+mkdir -p /etc/bootc
+
+# Create with specific permissions
+mkdir -m 755 /etc/bootc
+```
+
+#### ls
+**Purpose**: List directory contents
+**Usage**: `ls [OPTIONS...] [FILE...]`
+**Integration**: Used for listing configuration files
+
+```bash
+# List files
+ls -la /etc/bootc/
+
+# List with specific format
+ls -l --time-style=full-iso /etc/bootc/
+```
+
+#### find
+**Purpose**: Search for files
+**Usage**: `find [PATH...] [EXPRESSION...]`
+**Integration**: Used for finding configuration files
+
+```bash
+# Find configuration files
+find /etc -name "*.yaml" -type f
+
+# Find files modified recently
+find /etc/bootc -mtime -1 -type f
+```
+
+## Logging and Monitoring Commands
+
+### 1. System Logs
+
+#### journalctl
+**Purpose**: Query systemd journal
+**Usage**: `journalctl [OPTIONS...]`
+**Integration**: Used for service and system log analysis
+
+```bash
+# Check bootc service logs
+journalctl -u bootc-fetch-apply-updates.service
+
+# Check recent logs
+journalctl -n 100
+
+# Check logs since boot
+journalctl -b
+
+# Follow logs in real-time
+journalctl -f
+```
+
+#### dmesg
+**Purpose**: Display kernel ring buffer
+**Usage**: `dmesg [OPTIONS...]`
+**Integration**: Used for kernel-level troubleshooting
+
+```bash
+# Display kernel messages
+dmesg
+
+# Display recent messages
+dmesg -T
+
+# Display with timestamps
+dmesg -T | tail -50
+```
+
+### 2. File Monitoring
+
+#### tail
+**Purpose**: Display last lines of files
+**Usage**: `tail [OPTIONS...] [FILE...]`
+**Integration**: Used for monitoring log files
+
+```bash
+# Follow log file
+tail -f /var/log/bootc.log
+
+# Display last lines
+tail -n 100 /var/log/bootc.log
+```
+
+#### head
+**Purpose**: Display first lines of files
+**Usage**: `head [OPTIONS...] [FILE...]`
+**Integration**: Used for viewing file headers
+
+```bash
+# Display first lines
+head -n 20 /etc/bootc/config.yaml
+
+# Display first bytes
+head -c 100 /etc/bootc/config.yaml
+```
+
+## Security Commands
+
+### 1. Signature Verification
+
+#### gpg
+**Purpose**: GNU Privacy Guard
+**Usage**: `gpg [COMMAND] [OPTIONS...]`
+**Integration**: Used for signature verification
+
+```bash
+# Verify signature
+gpg --verify signature.asc config.yaml
+
+# Import public key
+gpg --import public.key
+
+# List keys
+gpg --list-keys
+```
+
+#### openssl
+**Purpose**: OpenSSL command line tool
+**Usage**: `openssl [COMMAND] [OPTIONS...]`
+**Integration**: Used for certificate and key management
+
+```bash
+# Check certificate
+openssl x509 -in certificate.crt -text -noout
+
+# Verify certificate chain
+openssl verify -CAfile ca.crt certificate.crt
+
+# Generate key pair
+openssl genrsa -out private.key 2048
+```
+
+### 2. File Permissions
+
+#### chmod
+**Purpose**: Change file permissions
+**Usage**: `chmod [OPTIONS...] MODE FILE...`
+**Integration**: Used for setting file permissions
+
+```bash
+# Set permissions
+chmod 644 /etc/bootc/config.yaml
+
+# Set permissions recursively
+chmod -R 755 /etc/bootc
+```
+
+#### chown
+**Purpose**: Change file ownership
+**Usage**: `chown [OPTIONS...] OWNER[:GROUP] FILE...`
+**Integration**: Used for setting file ownership
+
+```bash
+# Change ownership
+chown root:root /etc/bootc/config.yaml
+
+# Change ownership recursively
+chown -R root:root /etc/bootc
+```
+
+## Performance Monitoring Commands
+
+### 1. System Resources
+
+#### top
+**Purpose**: Display running processes
+**Usage**: `top [OPTIONS...]`
+**Integration**: Used for process monitoring
+
+```bash
+# Display processes
+top
+
+# Display specific process
+top -p $(pgrep bootc)
+```
+
+#### htop
+**Purpose**: Interactive process viewer
+**Usage**: `htop [OPTIONS...]`
+**Integration**: Used for system resource monitoring
+
+```bash
+# Start htop
+htop
+
+# Monitor specific process
+htop -p $(pgrep bootc)
+```
+
+#### free
+**Purpose**: Display memory usage
+**Usage**: `free [OPTIONS...]`
+**Integration**: Used for memory monitoring
+
+```bash
+# Display memory usage
+free -h
+
+# Display in specific format
+free -m
+```
+
+### 2. Disk Usage
+
+#### df
+**Purpose**: Display filesystem disk space usage
+**Usage**: `df [OPTIONS...] [FILE...]`
+**Integration**: Used for disk space monitoring
+
+```bash
+# Check disk usage
+df -h
+
+# Check specific filesystem
+df -h /sysroot
+
+# Check inode usage
+df -i
+```
+
+#### du
+**Purpose**: Display directory space usage
+**Usage**: `du [OPTIONS...] [FILE...]`
+**Integration**: Used for directory space analysis
+
+```bash
+# Check directory usage
+du -sh /etc/bootc
+
+# Check OSTree usage
+du -sh /sysroot/ostree
+```
+
+## Container Runtime Commands
+
+### 1. Podman Commands
+
+#### podman run
+**Purpose**: Run container
+**Usage**: `podman run [OPTIONS...] IMAGE [COMMAND...]`
+**Integration**: Used for testing container images
+
+```bash
+# Run container
+podman run -it quay.io/myorg/debian-bootc:v2.0
+
+# Run with specific options
+podman run --rm quay.io/myorg/debian-bootc:v2.0
+
+# Run with environment variables
+podman run -e VAR=value quay.io/myorg/debian-bootc:v2.0
+```
+
+#### podman ps
+**Purpose**: List containers
+**Usage**: `podman ps [OPTIONS...]`
+**Integration**: Used for container management
+
+```bash
+# List running containers
+podman ps
+
+# List all containers
+podman ps -a
+
+# List with specific format
+podman ps --format "table {{.Names}} {{.Image}} {{.Status}}"
+```
+
+#### podman rm
+**Purpose**: Remove containers
+**Usage**: `podman rm [OPTIONS...] CONTAINER...`
+**Integration**: Used for container cleanup
+
+```bash
+# Remove specific container
+podman rm container-id
+
+# Remove all stopped containers
+podman container prune
+
+# Remove with force
+podman rm -f container-id
+```
+
+### 2. Docker Commands (Alternative)
+
+#### docker
+**Purpose**: Alternative container runtime
+**Usage**: `docker [COMMAND] [OPTIONS...]`
+**Integration**: Alternative to podman
+
+```bash
+# List containers
+docker ps -a
+
+# List images
+docker images
+
+# Run container
+docker run -it quay.io/myorg/debian-bootc:v2.0
+```
+
+## Backup and Recovery Commands
+
+### 1. Archive Commands
+
+#### tar
+**Purpose**: Archive files
+**Usage**: `tar [OPTIONS...] [FILE...]`
+**Integration**: Used for backup creation
+
+```bash
+# Create backup
+tar -czf backup.tar.gz /etc/bootc
+
+# Extract backup
+tar -xzf backup.tar.gz
+
+# List archive contents
+tar -tzf backup.tar.gz
+```
+
+#### rsync
+**Purpose**: Synchronize files
+**Usage**: `rsync [OPTIONS...] SRC DEST`
+**Integration**: Used for backup synchronization
+
+```bash
+# Synchronize files
+rsync -av /etc/bootc/ /backup/bootc/
+
+# Synchronize with remote
+rsync -av /etc/bootc/ user@host:/backup/bootc/
+```
+
+### 2. Version Control
+
+#### git
+**Purpose**: Version control system
+**Usage**: `git [COMMAND] [OPTIONS...]`
+**Integration**: Used for configuration version control
+
+```bash
+# Initialize repository
+git init
+
+# Add files
+git add /etc/bootc/config.yaml
+
+# Commit changes
+git commit -m "Update configuration"
+
+# Check status
+git status
+```
+
+## System Information Commands
+
+### 1. System Information
+
+#### uname
+**Purpose**: Display system information
+**Usage**: `uname [OPTIONS...]`
+**Integration**: Used for system identification
+
+```bash
+# Display system information
+uname -a
+
+# Display kernel version
+uname -r
+
+# Display architecture
+uname -m
+```
+
+#### hostname
+**Purpose**: Display or set hostname
+**Usage**: `hostname [OPTIONS...] [NAME]`
+**Integration**: Used for system identification
+
+```bash
+# Display hostname
+hostname
+
+# Set hostname
+hostname newhostname
+```
+
+#### whoami
+**Purpose**: Display current user
+**Usage**: `whoami [OPTIONS...]`
+**Integration**: Used for user identification
+
+```bash
+# Display current user
+whoami
+
+# Display user ID
+id
+```
+
+### 2. Hardware Information
+
+#### lscpu
+**Purpose**: Display CPU information
+**Usage**: `lscpu [OPTIONS...]`
+**Integration**: Used for system resource analysis
+
+```bash
+# Display CPU information
+lscpu
+
+# Display in specific format
+lscpu --extended
+```
+
+#### lsblk
+**Purpose**: List block devices
+**Usage**: `lsblk [OPTIONS...]`
+**Integration**: Used for storage device identification
+
+```bash
+# List all block devices
+lsblk
+
+# List with filesystem information
+lsblk -f
+
+# List specific device
+lsblk /dev/sda
+```
+
+This comprehensive external commands reference provides all the tools and commands needed to effectively manage, troubleshoot, and integrate with the bootc switch system.