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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

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