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

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

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

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

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

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

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

```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 rollback
**Purpose**: Rollback to previous deployment
**Usage**: `ostree admin rollback [OPTIONS...]`
**Integration**: Used by `bootc rollback` for deployment switching

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

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

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

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

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

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

```ini
[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**:
```bash
# 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`

```ini
[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**:
```bash
# 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

```ini
[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**:
```bash
# 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

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

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

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

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

## Storage and Filesystem Commands

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

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

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

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

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

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

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

### 3. 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)
```

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

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

```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. gpg
**Purpose**: GNU Privacy Guard
**Usage**: `gpg [COMMAND] [OPTIONS...]`
**Integration**: Used for signature verification

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

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

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

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

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

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

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

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

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

```bash
# Display CPU information
lscpu

# Display in specific format
lscpu --extended
```

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

### 4. uptime
**Purpose**: Display system uptime
**Usage**: `uptime [OPTIONS...]`
**Integration**: Used for system status monitoring

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

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

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

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

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

```bash
# Display processes
top

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

### 2. ps
**Purpose**: Display process information
**Usage**: `ps [OPTIONS...]`
**Integration**: Used for process analysis

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

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