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

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

Core System Commands

1. bootc Commands

bootc edit

Purpose: Edit host specification declaratively Usage: bootc edit [OPTIONS...] External Dependencies:

• ostree - For deployment management
• podman - For container registry access
• systemd - For service management
• editor - For interactive editing

# Interactive editing
bootc edit

# Edit from file
bootc edit --filename config.yaml

# Quiet mode
bootc edit --quiet

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

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

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

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

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

Editor Commands

1. Text Editors

vim

Purpose: Vi IMproved text editor Usage: vim [OPTIONS...] [FILE...] Integration: Primary editor for interactive editing

# Edit file
vim config.yaml

# Edit with specific options
vim -c "set syntax=yaml" config.yaml

# Edit in read-only mode
vim -R config.yaml

nano

Purpose: Nano's ANOther editor Usage: nano [OPTIONS...] [FILE...] Integration: User-friendly editor for interactive editing

# Edit file
nano config.yaml

# Edit with specific options
nano -w config.yaml

# Edit with line numbers
nano -l config.yaml

vi

Purpose: Visual editor Usage: vi [OPTIONS...] [FILE...] Integration: Fallback editor for interactive editing

# Edit file
vi config.yaml

# Edit with specific options
vi -c "set syntax=yaml" config.yaml

emacs

Purpose: GNU Emacs editor Usage: emacs [OPTIONS...] [FILE...] Integration: Alternative editor for interactive editing

# Edit file
emacs config.yaml

# Edit in terminal mode
emacs -nw config.yaml

# Edit with specific options
emacs --eval "(yaml-mode)" config.yaml

2. Editor Configuration

Environment Variables

# Set default editor
export EDITOR=vim

# Set editor with options
export EDITOR="vim -c 'set syntax=yaml'"

# Set alternative editor
export EDITOR=nano

Editor Detection

# Check available editors
which vim nano vi emacs

# Check editor in PATH
command -v vim

# Test editor availability
vim --version

File System Commands

1. File Operations

cat

Purpose: Display file contents Usage: cat [OPTIONS...] [FILE...] Integration: Used for displaying configuration files

# Display file contents
cat config.yaml

# Display with line numbers
cat -n config.yaml

# Display non-printing characters
cat -v config.yaml

cp

Purpose: Copy files Usage: cp [OPTIONS...] SOURCE DEST Integration: Used for backing up configuration files

# Copy file
cp config.yaml config.yaml.backup

# Copy with preserve attributes
cp -p config.yaml config.yaml.backup

# Copy recursively
cp -r config/ config.backup/

mv

Purpose: Move or rename files Usage: mv [OPTIONS...] SOURCE DEST Integration: Used for renaming configuration files

# Rename file
mv config.yaml config.yaml.old

# Move file
mv config.yaml /backup/config.yaml

rm

Purpose: Remove files Usage: rm [OPTIONS...] FILE... Integration: Used for cleaning up temporary files

# Remove file
rm config.yaml

# Remove with confirmation
rm -i config.yaml

# Remove recursively
rm -r config/

2. Directory Operations

mkdir

Purpose: Create directories Usage: mkdir [OPTIONS...] DIRECTORY... Integration: Used for creating configuration directories

# 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

# 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

# Find configuration files
find /etc -name "*.yaml" -type f

# Find files modified recently
find /etc/bootc -mtime -1 -type f

YAML Processing Commands

1. YAML Tools

yq

Purpose: YAML processor Usage: yq [COMMAND] [OPTIONS...] [FILE...] Integration: Used for YAML manipulation and validation

# Read YAML value
yq eval '.spec.image' config.yaml

# Set YAML value
yq eval '.spec.image = "quay.io/myorg/debian-bootc:v2.0"' config.yaml

# Validate YAML
yq eval '.' config.yaml

yaml-lint

Purpose: YAML syntax validator Usage: yaml-lint [OPTIONS...] [FILE...] Integration: Used for YAML validation

# Validate YAML syntax
yaml-lint config.yaml

# Validate with specific options
yaml-lint --config /etc/yaml-lint.conf config.yaml

python3 -m yaml

Purpose: Python YAML module Usage: python3 -m yaml [OPTIONS...] [FILE...] Integration: Used for YAML processing

# Validate YAML
python3 -c "import yaml; yaml.safe_load(open('config.yaml'))"

# Pretty print YAML
python3 -c "import yaml; print(yaml.dump(yaml.safe_load(open('config.yaml')), default_flow_style=False))"

2. JSON Tools

jq

Purpose: JSON processor Usage: jq [OPTIONS...] [FILTER] [FILE...] Integration: Used for JSON processing and validation

# Process JSON
jq '.spec.image' config.json

# Validate JSON
jq '.' config.json

# Convert YAML to JSON
yq eval -o=json config.yaml | jq '.'

System Management Commands

1. Process Management

ps

Purpose: Display process information Usage: ps [OPTIONS...] Integration: Used for monitoring bootc processes

# 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 finding bootc processes

# Find bootc processes
pgrep bootc

# Find with full command line
pgrep -f bootc

pkill

Purpose: Kill processes by name Usage: pkill [OPTIONS...] PATTERN Integration: Used for terminating bootc processes

# Kill bootc processes
pkill bootc

# Kill with signal
pkill -TERM bootc

2. System Information

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

hostname

Purpose: Display or set hostname Usage: hostname [OPTIONS...] [NAME] Integration: Used for system identification

# Display hostname
hostname

# Set hostname
hostname newhostname

whoami

Purpose: Display current user Usage: whoami [OPTIONS...] Integration: Used for user identification

# Display current user
whoami

# Display user ID
id

Network Commands

1. Connectivity Testing

ping

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

# Test connectivity
ping quay.io

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

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

curl

Purpose: HTTP client Usage: curl [OPTIONS...] URL Integration: Used for registry API calls

# 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

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

2. DNS Resolution

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

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

Logging and Monitoring Commands

1. System Logs

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

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

2. File Monitoring

tail

Purpose: Display last lines of files Usage: tail [OPTIONS...] [FILE...] Integration: Used for monitoring log files

# 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

# Display first lines
head -n 20 config.yaml

# Display first bytes
head -c 100 config.yaml

Backup and Recovery Commands

1. Archive Commands

tar

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

# 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

# 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

# Initialize repository
git init

# Add files
git add config.yaml

# Commit changes
git commit -m "Update configuration"

# Check status
git status

Security Commands

1. File Permissions

chmod

Purpose: Change file permissions Usage: chmod [OPTIONS...] MODE FILE... Integration: Used for setting file permissions

# Set permissions
chmod 644 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

# Change ownership
chown root:root config.yaml

# Change ownership recursively
chown -R root:root /etc/bootc

umask

Purpose: Set file creation mask Usage: umask [OPTIONS...] [MASK] Integration: Used for setting default permissions

# Set umask
umask 022

# Display current umask
umask

2. Encryption

gpg

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

# 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

# Check certificate
openssl x509 -in certificate.crt -text -noout

# Verify certificate chain
openssl verify -CAfile ca.crt certificate.crt

Performance Monitoring Commands

1. System Resources

top

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

# Display processes
top

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

htop

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

# Start htop
htop

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

free

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

# 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

# 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

# Check directory usage
du -sh /etc/bootc

# Check OSTree usage
du -sh /sysroot/ostree

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