bootc-docs/upgrade/external-commands-reference.md

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

Core System Commands

1. bootc Commands

bootc upgrade

Purpose: Primary upgrade command Usage: bootc upgrade [OPTIONS...] External Dependencies:

• ostree - For deployment management
• podman - For container registry access
• systemd - For service management and reboot

# Check for updates
bootc upgrade --check

# Download and stage updates
bootc upgrade

# Apply updates and reboot
bootc upgrade --apply

# Apply with soft reboot
bootc upgrade --apply --soft-reboot=auto

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

bootc switch

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

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

# Switch to different image
bootc switch quay.io/myorg/debian-bootc:v2.0

# Switch and apply immediately
bootc switch quay.io/myorg/debian-bootc:v2.0 --apply

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

3. Container Registry Commands

podman pull

Purpose: Pull container images from registry Usage: podman pull [OPTIONS...] IMAGE Integration: Used by bootc for downloading updates

# Pull image from registry
podman pull quay.io/myorg/debian-bootc:latest

# Pull with authentication
podman pull --creds=username:password quay.io/myorg/debian-bootc:latest

# Pull specific tag
podman pull quay.io/myorg/debian-bootc:v1.2.3

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

# Inspect specific configuration
podman inspect --format='{{.Config.Labels}}' quay.io/myorg/debian-bootc:latest

# Inspect manifest
podman inspect --format='{{.Manifest}}' quay.io/myorg/debian-bootc:latest

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

# Reboot system
reboot

# Reboot with specific delay
reboot +5

# Reboot with message
reboot "Applying bootc update"

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

System Services

1. bootc-fetch-apply-updates.service

Purpose: Automated update fetching and application File: /usr/lib/systemd/system/bootc-fetch-apply-updates.service Dependencies:

• network-online.target
• bootc command
• ostree system

[Unit]
Description=Download and apply bootc updates
After=network-online.target
Wants=network-online.target

[Service]
Type=oneshot
ExecStart=/usr/bin/bootc upgrade --apply
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Management Commands:

# Check service status
systemctl status bootc-fetch-apply-updates.service

# Start service manually
systemctl start bootc-fetch-apply-updates.service

# Enable service
systemctl enable bootc-fetch-apply-updates.service

# Check service logs
journalctl -u bootc-fetch-apply-updates.service

2. bootc-fetch-apply-updates.timer

Purpose: Schedule automated updates File: /usr/lib/systemd/system/bootc-fetch-apply-updates.timer Dependencies:

• bootc-fetch-apply-updates.service

[Unit]
Description=Download and apply bootc updates daily
Requires=bootc-fetch-apply-updates.service

[Timer]
OnCalendar=daily
Persistent=true

[Install]
WantedBy=timers.target

Management Commands:

# Check timer status
systemctl status bootc-fetch-apply-updates.timer

# List timers
systemctl list-timers bootc-fetch-apply-updates.timer

# Start timer
systemctl start bootc-fetch-apply-updates.timer

# Enable timer
systemctl enable bootc-fetch-apply-updates.timer

3. ostree-finalize-staged.service

Purpose: Finalize staged OSTree deployments File: /usr/lib/systemd/system/ostree-finalize-staged.service Dependencies:

• ostree system
• systemd reboot coordination

[Unit]
Description=Finalize staged OSTree deployment
After=ostree-remount.service
Before=systemd-reboot.service

[Service]
Type=oneshot
ExecStart=/usr/bin/ostree admin finalize-staged
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target

Management Commands:

# Check service status
systemctl status ostree-finalize-staged.service

# Check service logs
journalctl -u ostree-finalize-staged.service

# Manually run service
systemctl start ostree-finalize-staged.service

Network and Registry Commands

1. 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/latest

# Authenticate with registry
curl -u username:password https://quay.io/v2/token

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

# Download with authentication
wget --user=username --password=password https://quay.io/v2/token

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

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

Storage and Filesystem Commands

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

2. du

Purpose: Display directory space usage Usage: du [OPTIONS...] [FILE...] Integration: Used for directory space analysis

# Check directory usage
du -sh /sysroot

# Check OSTree usage
du -sh /sysroot/ostree

# Check specific deployment
du -sh /sysroot/ostree/deploy/debian-bootc

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

4. mount

Purpose: Mount filesystems Usage: mount [OPTIONS...] DEVICE DIR Integration: Used for filesystem mounting

# List mounted filesystems
mount

# Mount specific device
mount /dev/sda1 /mnt

# Mount with options
mount -o ro /dev/sda1 /mnt

Monitoring and Logging Commands

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

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

3. htop

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

# Start htop
htop

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

4. iostat

Purpose: I/O statistics Usage: iostat [OPTIONS...] Integration: Used for disk I/O monitoring

# Display I/O statistics
iostat

# Display with interval
iostat 1

# Display specific device
iostat /dev/sda

Security and Authentication Commands

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

Purpose: GNU Privacy Guard Usage: gpg [COMMAND] [OPTIONS...] Integration: Used for signature verification

# Verify signature
gpg --verify signature.asc file.txt

# Import public key
gpg --import public.key

# List keys
gpg --list-keys

3. ssh

Purpose: Secure shell client Usage: ssh [OPTIONS...] [USER@]HOST [COMMAND] Integration: Used for remote system management

# Connect to remote system
ssh user@hostname

# Execute remote command
ssh user@hostname 'bootc upgrade --check'

# Copy files
scp file.txt user@hostname:/path/to/destination

Network Troubleshooting Commands

1. ping

Purpose: Test network connectivity Usage: ping [OPTIONS...] HOST Integration: Used for network connectivity testing

# Test connectivity
ping quay.io

# Test with specific count
ping -c 4 quay.io

# Test with specific interface
ping -I eth0 quay.io

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

3. netstat

Purpose: Display network connections Usage: netstat [OPTIONS...] Integration: Used for network connection analysis

# Display all connections
netstat -an

# Display listening ports
netstat -ln

# Display with process information
netstat -tulpn

4. ss

Purpose: Socket statistics Usage: ss [OPTIONS...] Integration: Modern alternative to netstat

# Display all sockets
ss -an

# Display listening sockets
ss -ln

# Display with process information
ss -tulpn

Container Runtime Commands

1. podman

Purpose: Container runtime Usage: podman [COMMAND] [OPTIONS...] Integration: Primary container runtime for bootc

# List containers
podman ps -a

# List images
podman images

# Run container
podman run -it quay.io/myorg/debian-bootc:latest

# Remove containers
podman rm -f container-id

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

System Information Commands

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

2. lscpu

Purpose: Display CPU information Usage: lscpu [OPTIONS...] Integration: Used for system resource analysis

# Display CPU information
lscpu

# Display in specific format
lscpu --extended

3. free

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

# Display memory usage
free -h

# Display in specific format
free -m

4. uptime

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

# Display uptime
uptime

# Display with load average
uptime -p

Configuration Management Commands

1. bootc edit

Purpose: Edit bootc configuration Usage: bootc edit [OPTIONS...] Integration: Used for configuration management

# Edit configuration
bootc edit

# Edit specific deployment
bootc edit --deployment=deployment-id

2. bootc config

Purpose: Display bootc configuration Usage: bootc config [OPTIONS...] Integration: Used for configuration inspection

# Display configuration
bootc config

# Display in specific format
bootc config --json

Backup and Recovery Commands

1. tar

Purpose: Archive files Usage: tar [OPTIONS...] [FILE...] Integration: Used for backup creation

# Create backup
tar -czf backup.tar.gz /sysroot

# Extract backup
tar -xzf backup.tar.gz

# List archive contents
tar -tzf backup.tar.gz

2. rsync

Purpose: Synchronize files Usage: rsync [OPTIONS...] SRC DEST Integration: Used for backup synchronization

# Synchronize files
rsync -av /sysroot/ /backup/sysroot/

# Synchronize with remote
rsync -av /sysroot/ user@host:/backup/sysroot/

Performance Monitoring Commands

1. top

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

# Display processes
top

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

2. ps

Purpose: Display process information Usage: ps [OPTIONS...] Integration: Used for process analysis

# Display all processes
ps aux

# Display specific process
ps aux | grep bootc

# Display process tree
ps auxf

3. vmstat

Purpose: Display virtual memory statistics Usage: vmstat [OPTIONS...] Integration: Used for system performance monitoring

# Display statistics
vmstat

# Display with interval
vmstat 1

# Display specific count
vmstat 5 10

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