# 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

```bash
# 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

```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 switch
**Purpose**: Switch to different container image reference
**Usage**: `bootc switch [OPTIONS...] <TARGET>`
**External Dependencies**:
- `ostree` - For deployment management
- `podman` - For container registry access

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

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

# 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

```bash
# 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

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

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

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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

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

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

# 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

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

## Network 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
```

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

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

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

## Hardware Information Commands

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

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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# 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

```bash
# Display uptime
uptime

# Display with load average
uptime -p
```

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

```bash
# 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

```bash
# 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

```bash
# 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

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