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

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

Core System Commands

1. bootc Commands

bootc status

Purpose: Display system status and deployment information Usage: bootc status [OPTIONS...] External Dependencies:

• ostree - For deployment information
• systemd - For service status
• jq - For JSON parsing (optional)

# Show current system status
bootc status

# Show status in JSON format
bootc status --format=json

# Show detailed status with verbose output
bootc status --verbose

# Show only booted deployment status
bootc status --booted

# Show status in YAML format
bootc status --format=yaml

bootc upgrade

Purpose: Update current image to newer version Usage: bootc upgrade [OPTIONS...] Integration: Used to check status before/after upgrades

# Check status before upgrade
bootc status
bootc upgrade --apply
bootc status

# Check for updates
bootc upgrade --check

bootc switch

Purpose: Switch to different container image reference Usage: bootc switch [OPTIONS...] <TARGET> Integration: Used to check status before/after switches

# Check status before switch
bootc status
bootc switch quay.io/myorg/debian-bootc:v2.0
bootc status

bootc rollback

Purpose: Rollback to previous deployment Usage: bootc rollback [OPTIONS...] Integration: Used to check status before/after rollbacks

# Check status before rollback
bootc status
bootc rollback
bootc status

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 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 internally by bootc 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. System Management Commands

systemctl

Purpose: Control systemd services and units Usage: systemctl [COMMAND] [UNIT...] Integration: Used for service management and status checking

# 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 for system restart after status changes

# Reboot system
reboot

# Reboot with specific delay
reboot +5

# Reboot with message
reboot "Applying bootc changes"

shutdown

Purpose: Shutdown the system Usage: shutdown [OPTIONS...] Integration: Used for controlled shutdown

# Shutdown system
shutdown -h now

# Shutdown with delay
shutdown -h +5

# Shutdown with message
shutdown -h now "Applying bootc changes"

Data Processing Commands

1. JSON Processing

jq

Purpose: JSON processor and query tool Usage: jq [OPTIONS...] [FILTER] [FILE...] Integration: Used for parsing and processing JSON output

# Parse JSON output
bootc status --format=json | jq '.status.booted'

# Check if system is bootc compatible
bootc status --format=json | jq '.status.booted != null'

# Get current image version
bootc status --format=json | jq -r '.status.booted.image.version // "unknown"'

# Check rollback status
bootc status --format=json | jq '.status.rollbackQueued'

# Get image digest
bootc status --format=json | jq -r '.status.booted.image.imageDigest'

# List all deployments
bootc status --format=json | jq '.status | keys'

yq

Purpose: YAML processor and query tool Usage: yq [OPTIONS...] [EXPRESSION] [FILE...] Integration: Used for parsing and processing YAML output

# Parse YAML output
bootc status --format=yaml | yq '.status.booted'

# Get current image version
bootc status --format=yaml | yq '.status.booted.image.version'

# Check rollback status
bootc status --format=yaml | yq '.status.rollbackQueued'

# Get image digest
bootc status --format=yaml | yq '.status.booted.image.imageDigest'

2. Text Processing

grep

Purpose: Search text patterns Usage: grep [OPTIONS...] PATTERN [FILE...] Integration: Used for filtering and searching output

# Search for specific image
bootc status | grep "quay.io/myorg"

# Search for rollback status
bootc status | grep "Rollback Queued"

# Search for version information
bootc status | grep "Version:"

awk

Purpose: Text processing and data extraction Usage: awk [OPTIONS...] 'PROGRAM' [FILE...] Integration: Used for extracting specific fields

# Extract image name
bootc status | awk '/Image:/ {print $2}'

# Extract version
bootc status | awk '/Version:/ {print $2}'

# Extract digest
bootc status | awk '/Digest:/ {print $2}'

sed

Purpose: Stream editor for filtering and transforming text Usage: sed [OPTIONS...] SCRIPT [FILE...] Integration: Used for text transformation

# Remove leading whitespace
bootc status | sed 's/^[[:space:]]*//'

# Extract specific lines
bootc status | sed -n '/Image:/p'

# Replace text
bootc status | sed 's/quay.io/myorg/quay.io/otherorg/g'

3. Data Formatting

column

Purpose: Format text into columns Usage: column [OPTIONS...] [FILE...] Integration: Used for formatting output

# Format status output in columns
bootc status | column -t

# Format with specific separator
bootc status | column -s ':' -t

sort

Purpose: Sort lines of text Usage: sort [OPTIONS...] [FILE...] Integration: Used for sorting output

# Sort status output
bootc status | sort

# Sort by specific field
bootc status | sort -k2

uniq

Purpose: Remove duplicate lines Usage: uniq [OPTIONS...] [FILE...] Integration: Used for removing duplicates

# Remove duplicate lines
bootc status | uniq

# Count unique lines
bootc status | uniq -c

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 status-related logs
journalctl -u bootc-fetch-apply-updates.service | grep status

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

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 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/*"

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

# Inspect image
docker inspect quay.io/myorg/debian-bootc:v2.0

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

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

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

Automation and Scripting Commands

1. Shell Scripting

bash

Purpose: Bourne Again Shell Usage: bash [OPTIONS...] [FILE] Integration: Used for automation scripts

#!/bin/bash
# Check if system is bootc compatible
if bootc status --format=json | jq -e '.status.booted != null' > /dev/null; then
    echo "System is bootc compatible"
else
    echo "System is not bootc compatible"
fi

sh

Purpose: POSIX shell Usage: sh [OPTIONS...] [FILE] Integration: Used for portable scripts

#!/bin/sh
# Check rollback status
if bootc status --format=json | jq -r '.status.rollbackQueued' | grep -q true; then
    echo "Rollback is queued"
fi

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

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

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