bootc-docs/edit/bootc-edit-external-commands.md
robojerk 526f1c1afd Initial commit: Comprehensive Debian bootc documentation
- Complete documentation for all bootc commands and subcommands
- Debian-specific adaptations and workarounds
- Manual installation methods to bypass bootc reliability issues
- Technical guides with Rust source code analysis
- Flowcharts and external command references
- Hidden command documentation (bootc internals, state, etc.)
- Composefs integration analysis
- Base image creation guides (with and without bootc binary)
- Management scripts and automation
- Comprehensive troubleshooting and examples
2025-09-15 14:02:28 -07:00

883 lines
17 KiB
Markdown

# 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
```bash
# 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
```bash
# 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
```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
```
#### 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
```
### 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 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
```
#### 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
```
### 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
```
## Editor Commands
### 1. Text Editors
#### vim
**Purpose**: Vi IMproved text editor
**Usage**: `vim [OPTIONS...] [FILE...]`
**Integration**: Primary editor for interactive editing
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```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
```
## YAML Processing Commands
### 1. YAML Tools
#### yq
**Purpose**: YAML processor
**Usage**: `yq [COMMAND] [OPTIONS...] [FILE...]`
**Integration**: Used for YAML manipulation and validation
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```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 finding bootc processes
```bash
# 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
```bash
# 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
```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
```
#### whoami
**Purpose**: Display current user
**Usage**: `whoami [OPTIONS...]`
**Integration**: Used for user identification
```bash
# 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
```bash
# 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
```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
```
#### 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
```
### 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
```
## 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
```
#### 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 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
```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 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
```bash
# 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
```bash
# 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
```bash
# Set umask
umask 022
# Display current umask
umask
```
### 2. Encryption
#### 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
```
## 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
```
This comprehensive external commands reference provides all the tools and commands needed to effectively manage, troubleshoot, and integrate with the bootc edit system.