bootc-docs/switch/bootc-switch-external-commands.md

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Display processes
top

# Display specific process
top -p $(pgrep bootc)

htop

Purpose: Interactive process viewer Usage: htop [OPTIONS...] Integration: Used for system resource monitoring

# Start htop
htop

# Monitor specific process
htop -p $(pgrep bootc)

free

Purpose: Display memory usage Usage: free [OPTIONS...] Integration: Used for memory monitoring

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Display hostname
hostname

# Set hostname
hostname newhostname

whoami

Purpose: Display current user Usage: whoami [OPTIONS...] Integration: Used for user identification

# 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

# Display CPU information
lscpu

# Display in specific format
lscpu --extended

lsblk

Purpose: List block devices Usage: lsblk [OPTIONS...] Integration: Used for storage device identification

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