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

bootc rollback - 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 rollback system. Understanding these external dependencies is crucial for troubleshooting, monitoring, and integrating bootc rollback into larger systems.

Core System Commands

1. bootc Commands

bootc rollback

Purpose: Rollback to previous deployment Usage: bootc rollback [OPTIONS...] External Dependencies:

• ostree - For deployment management
• systemd - For service management and reboot
• kexec - For soft reboot support

# Rollback to previous deployment
bootc rollback

# Rollback and apply immediately
bootc rollback --apply

# Rollback with soft reboot
bootc rollback --apply --soft-reboot=auto

# Rollback with required soft reboot
bootc rollback --apply --soft-reboot=required

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 switch

Purpose: Switch to different container image reference Usage: bootc switch [OPTIONS...] <TARGET> External Dependencies:

• ostree - For deployment management
• podman - For container registry access

# 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

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

# Check with verbose output
ostree admin status --verbose

ostree admin rollback

Purpose: Rollback to previous deployment Usage: ostree admin rollback [OPTIONS...] Integration: Used internally by bootc for deployment switching

# Rollback to previous deployment
ostree admin rollback

# Rollback with specific options
ostree admin rollback --deployment=deployment-id

# Rollback with verbose output
ostree admin rollback --verbose

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

# Clean up with verbose output
ostree admin cleanup --verbose

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. 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 rollback --apply for system restart

# Reboot system
reboot

# Reboot with specific delay
reboot +5

# Reboot with message
reboot "Applying bootc rollback"

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 rollback"

Soft Reboot Commands

1. kexec Commands

kexec

Purpose: Load and execute new kernel Usage: kexec [OPTIONS...] Integration: Used for soft reboot functionality

# Load new kernel
kexec -l /boot/vmlinuz --initrd=/boot/initrd.img

# Execute loaded kernel
kexec -e

# Load kernel with command line
kexec -l /boot/vmlinuz --initrd=/boot/initrd.img --append="console=ttyS0"

# Unload loaded kernel
kexec -u

kexec-tools

Purpose: Kernel execution tools Usage: Various kexec utilities Integration: Used for soft reboot preparation

# Check kexec support
kexec --version

# Load kernel for soft reboot
kexec -l /boot/vmlinuz --initrd=/boot/initrd.img

# Execute soft reboot
kexec -e

2. System Information Commands

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

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

# Check rollback-specific logs
journalctl -u bootc-fetch-apply-updates.service | grep rollback

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

Network 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

Container Runtime Commands

1. Podman 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

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

Hardware Information Commands

1. System 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

lspci

Purpose: List PCI devices Usage: lspci [OPTIONS...] Integration: Used for hardware identification

# List all PCI devices
lspci

# List with verbose output
lspci -v

# List specific device class
lspci -d 8086:

lsusb

Purpose: List USB devices Usage: lsusb [OPTIONS...] Integration: Used for USB device identification

# List all USB devices
lsusb

# List with verbose output
lsusb -v

# List specific device
lsusb -d 1234:5678

Process Management Commands

1. Process Control

ps

Purpose: Display running processes Usage: ps [OPTIONS...] Integration: Used for process monitoring

# Display all processes
ps aux

# Display specific process
ps aux | grep bootc

# Display process tree
ps auxf

pgrep

Purpose: Find processes by name Usage: pgrep [OPTIONS...] PATTERN Integration: Used for process identification

# Find bootc processes
pgrep bootc

# Find with full command line
pgrep -f bootc

# Find with specific user
pgrep -u root bootc

pkill

Purpose: Kill processes by name Usage: pkill [OPTIONS...] PATTERN Integration: Used for process termination

# Kill bootc processes
pkill bootc

# Kill with signal
pkill -9 bootc

# Kill with specific user
pkill -u root bootc

kill

Purpose: Send signal to process Usage: kill [OPTIONS...] PID Integration: Used for process control

# Send TERM signal
kill 1234

# Send KILL signal
kill -9 1234

# Send HUP signal
kill -HUP 1234

System Information Commands

1. System Status

uptime

Purpose: Display system uptime Usage: uptime [OPTIONS...] Integration: Used for system status monitoring

# Display uptime
uptime

# Display with load average
uptime -p

who

Purpose: Display logged-in users Usage: who [OPTIONS...] Integration: Used for user session monitoring

# Display logged-in users
who

# Display with details
who -a

# Display with timestamps
who -T

w

Purpose: Display logged-in users and their processes Usage: w [OPTIONS...] Integration: Used for user activity monitoring

# Display user activity
w

# Display with specific format
w -s

# Display with timestamps
w -T

2. System Configuration

sysctl

Purpose: Configure kernel parameters Usage: sysctl [OPTIONS...] [PARAMETER...] Integration: Used for kernel configuration

# Display all parameters
sysctl -a

# Display specific parameter
sysctl kernel.version

# Set parameter
sysctl -w kernel.parameter=value

modprobe

Purpose: Load kernel modules Usage: modprobe [OPTIONS...] MODULE Integration: Used for kernel module management

# Load module
modprobe module_name

# Remove module
modprobe -r module_name

# List loaded modules
modprobe -l

This comprehensive external commands reference provides all the tools and commands needed to effectively manage, troubleshoot, and integrate with the bootc rollback system.