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

# bootc image - External Commands Reference

## Overview

This document provides a comprehensive reference for all external commands used by `bootc image` operations. These commands are essential for understanding the dependencies and integration points of the bootc image system.

## Core Commands

### bootc

**Purpose**: Main bootc command for image operations
**Usage**: `bootc image <subcommand> [options...]`
**Dependencies**: None (core command)

#### Subcommands
- `bootc image list` - List images in bootc storage
- `bootc image copy-to-storage` - Copy images to containers-storage
- `bootc image pull-from-default-storage` - Pull images from default storage
- `bootc image cmd` - Wrapper for podman image commands

#### Examples
```bash
# List all images
bootc image list

# List host images only
bootc image list --type=host

# List in JSON format
bootc image list --format=json

# Copy current image to containers-storage
bootc image copy-to-storage

# Copy specific image
bootc image copy-to-storage --source=quay.io/myorg/debian-bootc:v2.0

# Pull image from default storage
bootc image pull-from-default-storage quay.io/myorg/debian-bootc:v2.0
```

### podman

**Purpose**: Container runtime and image management
**Usage**: `podman image <subcommand> [options...]`
**Dependencies**: podman package, containers-storage

#### Image Subcommands
- `podman image list` - List images
- `podman image build` - Build images
- `podman image pull` - Pull images
- `podman image push` - Push images
- `podman image tag` - Tag images
- `podman image inspect` - Inspect images
- `podman image exists` - Check if image exists
- `podman image prune` - Remove unused images
- `podman image rmi` - Remove images

#### Examples
```bash
# List all images
podman image list

# Build image
podman image build -t myimage:latest .

# Pull image
podman image pull quay.io/myorg/debian-bootc:v2.0

# Push image
podman image push myimage:latest

# Tag image
podman image tag myimage:latest localhost/myimage:latest

# Inspect image
podman image inspect myimage:latest

# Check if image exists
podman image exists myimage:latest

# Remove unused images
podman image prune -a

# Remove specific image
podman image rmi myimage:latest
```

#### Storage Configuration
```bash
# Check podman info
podman info

# Check storage configuration
podman info --format=json | jq '.store'

# Check storage root
podman info --format=json | jq '.store.graphRoot'

# Check run root
podman info --format=json | jq '.store.runRoot'
```

## Storage Commands

### ostree

**Purpose**: OSTree repository operations
**Usage**: `ostree <subcommand> [options...]`
**Dependencies**: ostree package

#### Repository Commands
- `ostree log` - Show commit log
- `ostree show` - Show commit details
- `ostree refs` - List references
- `ostree ls` - List repository contents
- `ostree cat` - Show file contents
- `ostree checkout` - Checkout files
- `ostree admin status` - Show admin status
- `ostree admin pin` - Pin deployments
- `ostree admin unpin` - Unpin deployments

#### Examples
```bash
# Show repository status
ostree admin status

# List references
ostree refs

# Show commit details
ostree show <commit-hash>

# List repository contents
ostree ls <commit-hash>

# Show file contents
ostree cat <commit-hash> /path/to/file

# Checkout files
ostree checkout <commit-hash> /path/to/destination
```

### containers-storage

**Purpose**: Container storage management
**Usage**: `containers-storage <subcommand> [options...]`
**Dependencies**: containers-storage package

#### Storage Commands
- `containers-storage list` - List storage contents
- `containers-storage info` - Show storage information
- `containers-storage prune` - Clean up storage
- `containers-storage gc` - Garbage collect

#### Examples
```bash
# List storage contents
containers-storage list

# Show storage information
containers-storage info

# Clean up storage
containers-storage prune

# Garbage collect
containers-storage gc
```

## System Commands

### systemctl

**Purpose**: Systemd service management
**Usage**: `systemctl <subcommand> [options...]`
**Dependencies**: systemd

#### Service Commands
- `systemctl status` - Show service status
- `systemctl start` - Start service
- `systemctl stop` - Stop service
- `systemctl restart` - Restart service
- `systemctl enable` - Enable service
- `systemctl disable` - Disable service
- `systemctl reload` - Reload service

#### Examples
```bash
# Check service status
systemctl status bootc

# Start service
systemctl start bootc

# Stop service
systemctl stop bootc

# Restart service
systemctl restart bootc

# Enable service
systemctl enable bootc

# Disable service
systemctl disable bootc
```

### mount

**Purpose**: Filesystem mounting
**Usage**: `mount [options...] <device> <directory>`
**Dependencies**: util-linux

#### Mount Commands
- `mount` - Mount filesystem
- `umount` - Unmount filesystem
- `mountpoint` - Check if directory is mountpoint
- `findmnt` - Find mounted filesystems

#### Examples
```bash
# Mount filesystem
mount /dev/sda1 /mnt

# Unmount filesystem
umount /mnt

# Check mountpoint
mountpoint /mnt

# Find mounted filesystems
findmnt

# Find specific mount
findmnt /mnt
```

### df

**Purpose**: Disk space usage
**Usage**: `df [options...] [file...]`
**Dependencies**: coreutils

#### Examples
```bash
# Show disk usage
df -h

# Show specific filesystem
df -h /var/lib/bootc

# Show inode usage
df -i

# Show all filesystems
df -a
```

### du

**Purpose**: Directory space usage
**Usage**: `du [options...] [file...]`
**Dependencies**: coreutils

#### Examples
```bash
# Show directory usage
du -h /var/lib/bootc

# Show total usage
du -sh /var/lib/bootc

# Show usage by subdirectory
du -h --max-depth=1 /var/lib/bootc

# Show usage of all files
du -ah /var/lib/bootc
```

## Network Commands

### curl

**Purpose**: HTTP client for registry operations
**Usage**: `curl [options...] <url>`
**Dependencies**: curl

#### Examples
```bash
# Download file
curl -O https://example.com/file.tar

# Get HTTP headers
curl -I https://example.com

# POST data
curl -X POST -d "data" https://example.com

# With authentication
curl -u username:password https://example.com

# With custom headers
curl -H "Authorization: Bearer token" https://example.com
```

### wget

**Purpose**: HTTP client for downloading files
**Usage**: `wget [options...] <url>`
**Dependencies**: wget

#### Examples
```bash
# Download file
wget https://example.com/file.tar

# Download with progress
wget --progress=bar https://example.com/file.tar

# Download recursively
wget -r https://example.com/

# Download with authentication
wget --user=username --password=password https://example.com
```

### ping

**Purpose**: Network connectivity testing
**Usage**: `ping [options...] <host>`
**Dependencies**: iputils

#### Examples
```bash
# Ping host
ping example.com

# Ping with count
ping -c 4 example.com

# Ping with timeout
ping -W 5 example.com

# Ping IPv6
ping6 example.com
```

## Data Processing Commands

### jq

**Purpose**: JSON processing
**Usage**: `jq [options...] <filter> [file...]`
**Dependencies**: jq

#### Examples
```bash
# Pretty print JSON
echo '{"key":"value"}' | jq .

# Extract value
echo '{"key":"value"}' | jq '.key'

# Filter array
echo '[{"name":"a"},{"name":"b"}]' | jq '.[] | select(.name == "a")'

# Transform data
echo '{"key":"value"}' | jq '{newkey: .key}'

# Read from file
jq '.key' file.json
```

### yq

**Purpose**: YAML processing
**Usage**: `yq [options...] <expression> [file...]`
**Dependencies**: yq

#### Examples
```bash
# Pretty print YAML
yq eval '.' file.yaml

# Extract value
yq eval '.key' file.yaml

# Set value
yq eval '.key = "newvalue"' file.yaml

# Delete key
yq eval 'del(.key)' file.yaml

# Convert to JSON
yq eval -o=json file.yaml
```

### grep

**Purpose**: Text searching
**Usage**: `grep [options...] <pattern> [file...]`
**Dependencies**: grep

#### Examples
```bash
# Search in file
grep "pattern" file.txt

# Search recursively
grep -r "pattern" /path/to/dir

# Case insensitive
grep -i "pattern" file.txt

# Show line numbers
grep -n "pattern" file.txt

# Show context
grep -C 3 "pattern" file.txt
```

### sed

**Purpose**: Text editing
**Usage**: `sed [options...] <script> [file...]`
**Dependencies**: sed

#### Examples
```bash
# Replace text
sed 's/old/new/g' file.txt

# Delete lines
sed '/pattern/d' file.txt

# Print specific lines
sed -n '1,10p' file.txt

# In-place editing
sed -i 's/old/new/g' file.txt
```

### awk

**Purpose**: Text processing
**Usage**: `awk [options...] <program> [file...]`
**Dependencies**: gawk

#### Examples
```bash
# Print specific field
awk '{print $1}' file.txt

# Print lines matching pattern
awk '/pattern/ {print}' file.txt

# Sum numbers
awk '{sum += $1} END {print sum}' file.txt

# Format output
awk '{printf "%-10s %s\n", $1, $2}' file.txt
```

## Logging Commands

### journalctl

**Purpose**: Systemd journal viewing
**Usage**: `journalctl [options...]`
**Dependencies**: systemd

#### Examples
```bash
# Show all logs
journalctl

# Show logs for service
journalctl -u bootc

# Show recent logs
journalctl -n 100

# Follow logs
journalctl -f

# Show logs since time
journalctl --since "1 hour ago"

# Show logs with priority
journalctl -p err
```

### dmesg

**Purpose**: Kernel message viewing
**Usage**: `dmesg [options...]`
**Dependencies**: util-linux

#### Examples
```bash
# Show kernel messages
dmesg

# Show recent messages
dmesg -T

# Show messages with timestamp
dmesg -T

# Show messages with level
dmesg -l err

# Clear ring buffer
dmesg -c
```

## Security Commands

### openssl

**Purpose**: SSL/TLS operations
**Usage**: `openssl <command> [options...]`
**Dependencies**: openssl

#### Examples
```bash
# Generate private key
openssl genrsa -out key.pem 2048

# Generate certificate
openssl req -new -x509 -key key.pem -out cert.pem

# Verify certificate
openssl verify cert.pem

# Check certificate details
openssl x509 -in cert.pem -text -noout

# Generate hash
openssl dgst -sha256 file.txt
```

### gpg

**Purpose**: GPG operations
**Usage**: `gpg [options...]`
**Dependencies**: gnupg

#### Examples
```bash
# Generate key pair
gpg --gen-key

# List keys
gpg --list-keys

# Sign file
gpg --sign file.txt

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

# Encrypt file
gpg --encrypt file.txt
```

## Performance Commands

### top

**Purpose**: Process monitoring
**Usage**: `top [options...]`
**Dependencies**: procps

#### Examples
```bash
# Show processes
top

# Show specific user
top -u username

# Show specific process
top -p 1234

# Show with custom delay
top -d 5

# Show with custom sort
top -o %CPU
```

### htop

**Purpose**: Interactive process monitoring
**Usage**: `htop [options...]`
**Dependencies**: htop

#### Examples
```bash
# Show processes
htop

# Show specific user
htop -u username

# Show specific process
htop -p 1234

# Show with custom delay
htop -d 5
```

### iotop

**Purpose**: I/O monitoring
**Usage**: `iotop [options...]`
**Dependencies**: iotop

#### Examples
```bash
# Show I/O usage
iotop

# Show only processes doing I/O
iotop -o

# Show with custom delay
iotop -d 5

# Show with custom refresh
iotop -n 10
```

### netstat

**Purpose**: Network statistics
**Usage**: `netstat [options...]`
**Dependencies**: net-tools

#### Examples
```bash
# Show all connections
netstat -a

# Show listening ports
netstat -l

# Show with process info
netstat -p

# Show with numeric addresses
netstat -n

# Show TCP connections
netstat -t
```

### ss

**Purpose**: Socket statistics
**Usage**: `ss [options...]`
**Dependencies**: iproute2

#### Examples
```bash
# Show all sockets
ss -a

# Show listening sockets
ss -l

# Show with process info
ss -p

# Show with numeric addresses
ss -n

# Show TCP sockets
ss -t
```

## File System Commands

### ls

**Purpose**: List directory contents
**Usage**: `ls [options...] [file...]`
**Dependencies**: coreutils

#### Examples
```bash
# List files
ls

# List with details
ls -l

# List all files
ls -a

# List with human readable sizes
ls -lh

# List with recursive
ls -R

# List with sort by time
ls -lt
```

### find

**Purpose**: Find files
**Usage**: `find [path...] [expression]`
**Dependencies**: findutils

#### Examples
```bash
# Find files by name
find /path -name "*.txt"

# Find files by type
find /path -type f

# Find files by size
find /path -size +100M

# Find files by modification time
find /path -mtime -7

# Find files by permissions
find /path -perm 644
```

### stat

**Purpose**: File status
**Usage**: `stat [options...] [file...]`
**Dependencies**: coreutils

#### Examples
```bash
# Show file status
stat file.txt

# Show in custom format
stat -c "%n %s %Y" file.txt

# Show filesystem status
stat -f /path

# Show with format
stat --format="%n: %s bytes" file.txt
```

### chmod

**Purpose**: Change file permissions
**Usage**: `chmod [options...] <mode> <file...>`
**Dependencies**: coreutils

#### Examples
```bash
# Set permissions
chmod 644 file.txt

# Add execute permission
chmod +x file.txt

# Remove write permission
chmod -w file.txt

# Set permissions recursively
chmod -R 755 /path

# Set permissions with reference
chmod --reference=ref.txt file.txt
```

### chown

**Purpose**: Change file ownership
**Usage**: `chown [options...] <owner>[:<group>] <file...>`
**Dependencies**: coreutils

#### Examples
```bash
# Change owner
chown user file.txt

# Change owner and group
chown user:group file.txt

# Change recursively
chown -R user:group /path

# Change with reference
chown --reference=ref.txt file.txt
```

## Archive Commands

### tar

**Purpose**: Archive operations
**Usage**: `tar [options...] <archive> [file...]`
**Dependencies**: tar

#### Examples
```bash
# Create archive
tar -cf archive.tar file1 file2

# Extract archive
tar -xf archive.tar

# List archive contents
tar -tf archive.tar

# Create compressed archive
tar -czf archive.tar.gz file1 file2

# Extract compressed archive
tar -xzf archive.tar.gz
```

### gzip

**Purpose**: Compression
**Usage**: `gzip [options...] [file...]`
**Dependencies**: gzip

#### Examples
```bash
# Compress file
gzip file.txt

# Decompress file
gzip -d file.txt.gz

# Compress with custom level
gzip -9 file.txt

# Keep original file
gzip -k file.txt
```

### zip

**Purpose**: ZIP archive operations
**Usage**: `zip [options...] <archive> [file...]`
**Dependencies**: zip

#### Examples
```bash
# Create ZIP archive
zip archive.zip file1 file2

# Extract ZIP archive
unzip archive.zip

# List ZIP contents
unzip -l archive.zip

# Extract to directory
unzip archive.zip -d /path/to/dir
```

## System Information Commands

### uname

**Purpose**: System information
**Usage**: `uname [options...]`
**Dependencies**: coreutils

#### Examples
```bash
# Show system name
uname

# Show all information
uname -a

# Show kernel name
uname -s

# Show kernel version
uname -r

# Show machine type
uname -m
```

### hostname

**Purpose**: Hostname operations
**Usage**: `hostname [options...]`
**Dependencies**: hostname

#### Examples
```bash
# Show hostname
hostname

# Show FQDN
hostname -f

# Show short hostname
hostname -s

# Show domain name
hostname -d
```

### lscpu

**Purpose**: CPU information
**Usage**: `lscpu [options...]`
**Dependencies**: util-linux

#### Examples
```bash
# Show CPU information
lscpu

# Show in JSON format
lscpu -J

# Show in extended format
lscpu -e

# Show in parseable format
lscpu -p
```

### free

**Purpose**: Memory information
**Usage**: `free [options...]`
**Dependencies**: procps

#### Examples
```bash
# Show memory usage
free

# Show in human readable format
free -h

# Show in bytes
free -b

# Show with total
free -t

# Show with wide format
free -w
```

### lspci

**Purpose**: PCI device information
**Usage**: `lspci [options...]`
**Dependencies**: pciutils

#### Examples
```bash
# Show PCI devices
lspci

# Show with details
lspci -v

# Show specific device
lspci -s 00:01.0

# Show in tree format
lspci -t

# Show with kernel modules
lspci -k
```

### lsusb

**Purpose**: USB device information
**Usage**: `lsusb [options...]`
**Dependencies**: usbutils

#### Examples
```bash
# Show USB devices
lsusb

# Show with details
lsusb -v

# Show specific device
lsusb -s 001:002

# Show in tree format
lsusb -t

# Show with kernel modules
lsusb -k
```

## Container Runtime Commands

### runc

**Purpose**: OCI runtime
**Usage**: `runc [options...] <command>`
**Dependencies**: runc

#### Examples
```bash
# List containers
runc list

# Start container
runc start container-id

# Stop container
runc stop container-id

# Delete container
runc delete container-id

# Create container
runc create container-id
```

### crictl

**Purpose**: CRI client
**Usage**: `crictl [options...] <command>`
**Dependencies**: cri-tools

#### Examples
```bash
# List pods
crictl pods

# List containers
crictl ps

# List images
crictl images

# Pull image
crictl pull image:tag

# Run container
crictl run image:tag
```

## Registry Commands

### skopeo

**Purpose**: Container image operations
**Usage**: `skopeo [options...] <command>`
**Dependencies**: skopeo

#### Examples
```bash
# Copy image
skopeo copy docker://image:tag docker://registry/image:tag

# Inspect image
skopeo inspect docker://image:tag

# List tags
skopeo list-tags docker://registry/image

# Delete image
skopeo delete docker://registry/image:tag
```

### buildah

**Purpose**: Container image building
**Usage**: `buildah [options...] <command>`
**Dependencies**: buildah

#### Examples
```bash
# Build image
buildah build -t image:tag .

# List images
buildah images

# Remove image
buildah rmi image:tag

# Push image
buildah push image:tag registry/image:tag
```

## Automation Commands

### cron

**Purpose**: Job scheduling
**Usage**: `cron [options...]`
**Dependencies**: cron

#### Examples
```bash
# Edit crontab
crontab -e

# List crontab
crontab -l

# Remove crontab
crontab -r

# Edit user crontab
crontab -u user -e
```

### at

**Purpose**: One-time job scheduling
**Usage**: `at [options...] <time>`
**Dependencies**: at

#### Examples
```bash
# Schedule job
at 15:30

# Schedule job with time
at now + 1 hour

# List jobs
atq

# Remove job
atrm job-id
```

### systemd-run

**Purpose**: Run commands as systemd service
**Usage**: `systemd-run [options...] <command>`
**Dependencies**: systemd

#### Examples
```bash
# Run command
systemd-run command

# Run with service name
systemd-run --unit=myservice command

# Run with user
systemd-run --user command

# Run with environment
systemd-run --setenv=VAR=value command
```

## Backup Commands

### rsync

**Purpose**: File synchronization
**Usage**: `rsync [options...] <source> <destination>`
**Dependencies**: rsync

#### Examples
```bash
# Sync directories
rsync -av /source/ /destination/

# Sync with progress
rsync -av --progress /source/ /destination/

# Sync with exclude
rsync -av --exclude='*.tmp' /source/ /destination/

# Sync with delete
rsync -av --delete /source/ /destination/

# Sync with compression
rsync -avz /source/ /destination/
```

### dd

**Purpose**: Data copying
**Usage**: `dd [options...]`
**Dependencies**: coreutils

#### Examples
```bash
# Copy file
dd if=input of=output

# Copy with progress
dd if=input of=output status=progress

# Copy with block size
dd if=input of=output bs=1M

# Copy with count
dd if=input of=output count=1000

# Copy with skip
dd if=input of=output skip=1000
```

### cp

**Purpose**: File copying
**Usage**: `cp [options...] <source> <destination>`
**Dependencies**: coreutils

#### Examples
```bash
# Copy file
cp file1 file2

# Copy recursively
cp -r dir1 dir2

# Copy with preserve
cp -p file1 file2

# Copy with verbose
cp -v file1 file2

# Copy with force
cp -f file1 file2
```

## Monitoring Commands

### watch

**Purpose**: Execute command repeatedly
**Usage**: `watch [options...] <command>`
**Dependencies**: procps

#### Examples
```bash
# Watch command
watch command

# Watch with interval
watch -n 5 command

# Watch with differences
watch -d command

# Watch with no title
watch -t command
```

### tail

**Purpose**: Show file tail
**Usage**: `tail [options...] [file...]`
**Dependencies**: coreutils

#### Examples
```bash
# Show last lines
tail file.txt

# Show last N lines
tail -n 100 file.txt

# Follow file
tail -f file.txt

# Follow with retry
tail -F file.txt

# Show with line numbers
tail -n +1 file.txt
```

### head

**Purpose**: Show file head
**Usage**: `head [options...] [file...]`
**Dependencies**: coreutils

#### Examples
```bash
# Show first lines
head file.txt

# Show first N lines
head -n 100 file.txt

# Show with line numbers
head -n +1 file.txt

# Show with bytes
head -c 1000 file.txt
```

This comprehensive reference covers all external commands used by the bootc image system, providing examples and usage patterns for each command.