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
This commit is contained in:
robojerk
commit
526f1c1afd
67 changed files with 34174 additions and 0 deletions
883
edit/bootc-edit-external-commands.md
Normal file
883
edit/bootc-edit-external-commands.md
Normal file
|
|
@ -0,0 +1,883 @@
|
|||
# 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.
|
||||
321
edit/bootc-edit-flowchart.md
Normal file
321
edit/bootc-edit-flowchart.md
Normal file
|
|
@ -0,0 +1,321 @@
|
|||
# bootc edit - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc edit` process flow, showing the decision points, operations, and state transitions involved in editing bootc host specifications.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc edit │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initialize System │
|
||||
│ • Get storage interface │
|
||||
│ • Get OSTree repository │
|
||||
│ • Get current system status │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Load Configuration │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Filename │ │ Interactive Mode │ │
|
||||
│ │ Provided? │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Load from File │ │ • Create temporary file │ │
|
||||
│ │ • Open file │ │ • Write current config to temp │ │
|
||||
│ │ • Parse YAML │ │ • Spawn editor with temp file │ │
|
||||
│ │ • Validate │ │ • Wait for editor completion │ │
|
||||
│ └─────────────────┘ │ • Read modified config │ │
|
||||
│ │ └─────────────────────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ └───────────┬───────────────┘ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Parse and Validate YAML │ │
|
||||
│ │ • Deserialize to Host structure │ │
|
||||
│ │ • Validate schema │ │
|
||||
│ │ • Check required fields │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Compare Configurations │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ new_host.spec == host.spec? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Print: ││ │ │ Validate Transition ││ │
|
||||
│ │ │ "Edit ││ │ │ • Check image changes ││ │
|
||||
│ │ │ cancelled, ││ │ │ • Validate boot order ││ │
|
||||
│ │ │ no changes ││ │ │ • Verify system state ││ │
|
||||
│ │ │ made" ││ │ └─────────────────────────────────┘│ │
|
||||
│ │ └─────────────┘│ │ │ │ │
|
||||
│ │ │ │ ▼ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Return ││ │ │ Create RequiredHostSpec ││ │
|
||||
│ │ │ Success ││ │ │ • Extract image reference ││ │
|
||||
│ │ └─────────────┘│ │ │ • Validate required fields ││ │
|
||||
│ └─────────────────┘ │ └─────────────────────────────────┘│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Change Type │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ boot_order changed? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Execute ││ │ │ Image Change Process ││ │
|
||||
│ │ │ Rollback ││ │ │ ││ │
|
||||
│ │ │ • Call ││ │ │ ┌─────────────────────────────┐││ │
|
||||
│ │ │ rollback ││ │ │ │ Pull New Image │││ │
|
||||
│ │ │ • Update ││ │ │ │ • Authenticate with │││ │
|
||||
│ │ │ boot ││ │ │ │ registry │││ │
|
||||
│ │ │ order ││ │ │ │ • Download image layers │││ │
|
||||
│ │ └─────────────┘│ │ │ │ • Convert to OSTree │││ │
|
||||
│ │ │ │ │ │ • Validate image │││ │
|
||||
│ │ ┌─────────────┐│ │ │ └─────────────────────────────┘││ │
|
||||
│ │ │ Return ││ │ │ │ ││ │
|
||||
│ │ │ Success ││ │ │ ▼ ││ │
|
||||
│ │ └─────────────┘│ │ │ ┌─────────────────────────────┐││ │
|
||||
│ └─────────────────┘ │ │ │ Stage New Deployment │││ │
|
||||
│ │ │ │ • Create new deployment │││ │
|
||||
│ │ │ │ • Configure bootloader │││ │
|
||||
│ │ │ │ • Update system status │││ │
|
||||
│ │ │ │ • Preserve /etc and /var │││ │
|
||||
│ │ │ └─────────────────────────────┘││ │
|
||||
│ │ └─────────────────────────────────┘│ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Update System Status │
|
||||
│ │
|
||||
│ • Update system modification time │
|
||||
│ • Refresh system status │
|
||||
│ • Update deployment information │
|
||||
│ • Log configuration changes │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Configuration applied successfully │
|
||||
│ • System ready for next boot │
|
||||
│ • Changes staged for application │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Editor Integration Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Editor Selection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Environment │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ $EDITOR set? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Use $EDITOR ││ │ │ Check Backup Editors ││ │
|
||||
│ │ │ • Split ││ │ │ • nano ││ │
|
||||
│ │ │ command ││ │ │ • vim ││ │
|
||||
│ │ │ • Extract ││ │ │ • vi ││ │
|
||||
│ │ │ program ││ │ │ • Check /usr/bin/ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ │ │ │ │
|
||||
│ │ │ ▼ │ │
|
||||
│ │ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ │ Editor Found? ││ │
|
||||
│ │ │ └─────────────────────────────────┘│ │
|
||||
│ │ │ │ │ │
|
||||
│ │ │ ▼ │ │
|
||||
│ │ │ ┌─────────────────┐ ┌─────────┐│ │
|
||||
│ │ │ │ Yes │ │ No ││ │
|
||||
│ │ │ │ │ │ ││ │
|
||||
│ │ │ │ ┌─────────────┐│ │ ┌─────┐││ │
|
||||
│ │ │ │ │ Use Backup ││ │ │Error│││ │
|
||||
│ │ │ │ │ Editor ││ │ │ │││ │
|
||||
│ │ │ │ └─────────────┘│ │ └─────┘││ │
|
||||
│ │ │ └─────────────────┘ └─────────┘│ │
|
||||
│ │ └─────────────────────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ └───────────┬───────────┘ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Launch Editor │ │
|
||||
│ │ • Create command with editor program │ │
|
||||
│ │ • Add editor arguments │ │
|
||||
│ │ • Add temporary file path │ │
|
||||
│ │ • Execute with lifecycle binding │ │
|
||||
│ │ • Wait for completion │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Editor │ │ Configuration │ │ System │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • $EDITOR │ │ • Invalid YAML │ │ • Not bootc │ │
|
||||
│ │ unset │ │ • Schema │ │ compatible │ │
|
||||
│ │ • Editor not │ │ validation │ │ • Image not │ │
|
||||
│ │ found │ │ • Missing │ │ found │ │
|
||||
│ │ • Editor │ │ fields │ │ • Registry │ │
|
||||
│ │ execution │ │ • Invalid │ │ error │ │
|
||||
│ │ failed │ │ values │ │ • OSTree error │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Response │
|
||||
│ │
|
||||
│ • Display error message │
|
||||
│ • Provide context information │
|
||||
│ • Suggest remediation steps │
|
||||
│ • Return appropriate exit code │
|
||||
│ • Clean up temporary files │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## State Transitions
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ System States │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Current State │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Normal │ │ Rollback │ │
|
||||
│ │ Boot │ │ Queued │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • Image: v1.0 │ │ • Image: v1.0 │ │
|
||||
│ │ • Boot: normal │ │ • Boot: rollback │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Edit Operation │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────────────────────┐ │ │
|
||||
│ │ │ Image │ │ Boot Order │ │ │
|
||||
│ │ │ Change │ │ Change │ │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ │ • Pull new │ │ • Execute rollback │ │ │
|
||||
│ │ │ image │ │ • Update boot order │ │ │
|
||||
│ │ │ • Stage │ │ • Preserve state │ │ │
|
||||
│ │ │ deployment │ │ │ │ │
|
||||
│ │ └─────────────────┘ └─────────────────────────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │ │
|
||||
│ ▼ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ New State │ │ New State │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • Image: v2.0 │ │ • Image: v1.0 │ │
|
||||
│ │ • Boot: normal │ │ • Boot: normal │ │
|
||||
│ │ • Staged: v2.0 │ │ • Rollback: queued │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Configuration Validation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Configuration Input │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ YAML Parsing │
|
||||
│ │
|
||||
│ • Parse YAML syntax │
|
||||
│ • Deserialize to Host structure │
|
||||
│ • Validate required fields │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Schema Validation │
|
||||
│ │
|
||||
│ • Validate Host structure │
|
||||
│ • Check HostSpec fields │
|
||||
│ • Verify ImageReference format │
|
||||
│ • Validate BootOrder values │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Transition Validation │
|
||||
│ │
|
||||
│ • Compare with current configuration │
|
||||
│ • Check for valid state transitions │
|
||||
│ • Verify image accessibility │
|
||||
│ • Validate boot order changes │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Validation Result │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Valid │ │ Invalid │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • Proceed with │ │ • Display error message │ │
|
||||
│ │ changes │ │ • Provide context │ │
|
||||
│ │ • Apply │ │ • Suggest fixes │ │
|
||||
│ │ configuration │ │ • Return error │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc edit process, showing all decision points, operations, and state transitions involved in editing bootc host specifications.
|
||||
476
edit/bootc-edit-technical-guide.md
Normal file
476
edit/bootc-edit-technical-guide.md
Normal file
|
|
@ -0,0 +1,476 @@
|
|||
# bootc edit - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc edit` is a declarative configuration management command that allows users to modify the host specification of a bootc-managed system. It operates similarly to `kubectl apply`, providing both interactive and programmatic interfaces for system configuration changes.
|
||||
|
||||
## Purpose
|
||||
|
||||
The edit command serves several critical functions:
|
||||
|
||||
1. **Declarative Configuration**: Apply changes to system configuration declaratively
|
||||
2. **Interactive Editing**: Use system editor for interactive configuration changes
|
||||
3. **Programmatic Interface**: Apply configuration from files for automation
|
||||
4. **State Management**: Maintain system state consistency across changes
|
||||
5. **Validation**: Ensure configuration changes are valid and safe
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc edit [OPTIONS...]
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Interactive editing (opens in $EDITOR)
|
||||
bootc edit
|
||||
|
||||
# Edit from file
|
||||
bootc edit --filename /path/to/config.yaml
|
||||
|
||||
# Quiet mode (no progress output)
|
||||
bootc edit --quiet
|
||||
```
|
||||
|
||||
## Command Options
|
||||
|
||||
| Option | Description | Default | Required |
|
||||
|--------|-------------|---------|----------|
|
||||
| `-f`, `--filename` | Use filename to edit system specification | `None` | No |
|
||||
| `--quiet` | Don't display progress | `false` | No |
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### 1. Configuration Structure
|
||||
|
||||
The bootc edit system operates on a `Host` structure that contains:
|
||||
|
||||
```rust
|
||||
pub struct Host {
|
||||
pub resource: k8sapitypes::Resource, // Kubernetes-style metadata
|
||||
pub spec: HostSpec, // Host specification
|
||||
pub status: HostStatus, // Current system status
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Host Specification
|
||||
|
||||
The `HostSpec` contains the editable configuration:
|
||||
|
||||
```rust
|
||||
pub struct HostSpec {
|
||||
pub image: Option<ImageReference>, // Container image reference
|
||||
pub boot_order: BootOrder, // Boot ordering configuration
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Supported Changes
|
||||
|
||||
Only changes to the `spec` section are honored:
|
||||
- **Image Reference**: Change the container image source
|
||||
- **Boot Order**: Modify boot ordering (rollback configuration)
|
||||
|
||||
## Technical Implementation
|
||||
|
||||
### 1. Edit Command Structure
|
||||
|
||||
```rust
|
||||
pub(crate) struct EditOpts {
|
||||
pub(crate) filename: Option<String>, // Optional file input
|
||||
pub(crate) quiet: bool, // Progress suppression
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Edit Process Flow
|
||||
|
||||
```rust
|
||||
async fn edit(opts: EditOpts) -> Result<()> {
|
||||
// 1. Get system storage and OSTree
|
||||
let sysroot = &get_storage().await?;
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let repo = &ostree.repo();
|
||||
|
||||
// 2. Get current system status
|
||||
let (booted_deployment, _deployments, host) =
|
||||
crate::status::get_status_require_booted(ostree)?;
|
||||
|
||||
// 3. Load new configuration
|
||||
let new_host: Host = if let Some(filename) = opts.filename {
|
||||
// Load from file
|
||||
let mut r = std::io::BufReader::new(std::fs::File::open(filename)?);
|
||||
serde_yaml::from_reader(&mut r)?
|
||||
} else {
|
||||
// Interactive editing
|
||||
let tmpf = tempfile::NamedTempFile::new()?;
|
||||
serde_yaml::to_writer(std::io::BufWriter::new(tmpf.as_file()), &host)?;
|
||||
crate::utils::spawn_editor(&tmpf)?;
|
||||
tmpf.as_file().seek(std::io::SeekFrom::Start(0))?;
|
||||
serde_yaml::from_reader(&mut tmpf.as_file())?
|
||||
};
|
||||
|
||||
// 4. Validate changes
|
||||
if new_host.spec == host.spec {
|
||||
println!("Edit cancelled, no changes made.");
|
||||
return Ok(());
|
||||
}
|
||||
|
||||
// 5. Verify transition
|
||||
host.spec.verify_transition(&new_host.spec)?;
|
||||
let new_spec = RequiredHostSpec::from_spec(&new_host.spec)?;
|
||||
|
||||
// 6. Apply changes
|
||||
if host.spec.boot_order != new_host.spec.boot_order {
|
||||
return crate::deploy::rollback(sysroot).await;
|
||||
}
|
||||
|
||||
// 7. Pull and stage new image
|
||||
let fetched = crate::deploy::pull(repo, new_spec.image, None, opts.quiet, prog.clone()).await?;
|
||||
let stateroot = booted_deployment.osname();
|
||||
crate::deploy::stage(sysroot, &stateroot, &fetched, &new_spec, prog.clone()).await?;
|
||||
|
||||
// 8. Update system
|
||||
sysroot.update_mtime()?;
|
||||
|
||||
Ok(())
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Editor Integration
|
||||
|
||||
The system supports multiple editors through the `spawn_editor` function:
|
||||
|
||||
```rust
|
||||
pub(crate) fn spawn_editor(tmpf: &tempfile::NamedTempFile) -> Result<()> {
|
||||
let editor_variables = ["EDITOR"];
|
||||
let backup_editors = ["nano", "vim", "vi"];
|
||||
|
||||
let editor = editor_variables.into_iter().find_map(std::env::var_os);
|
||||
let editor = if let Some(e) = editor.as_ref() {
|
||||
e.to_str()
|
||||
} else {
|
||||
backup_editors
|
||||
.into_iter()
|
||||
.find(|v| std::path::Path::new("/usr/bin").join(v).exists())
|
||||
};
|
||||
|
||||
let editor = editor.ok_or_else(|| anyhow::anyhow!("$EDITOR is unset, and no backup editor found"))?;
|
||||
let mut editor_args = editor.split_ascii_whitespace();
|
||||
let argv0 = editor_args.next().ok_or_else(|| anyhow::anyhow!("Invalid editor: {editor}"))?;
|
||||
|
||||
Command::new(argv0)
|
||||
.args(editor_args)
|
||||
.arg(tmpf.path())
|
||||
.lifecycle_bind()
|
||||
.run_inherited()
|
||||
.with_context(|| format!("Invoking editor {editor} failed"))
|
||||
}
|
||||
```
|
||||
|
||||
## Configuration Format
|
||||
|
||||
### 1. YAML Structure
|
||||
|
||||
The configuration is stored in YAML format with the following structure:
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Host
|
||||
metadata:
|
||||
name: localhost
|
||||
namespace: default
|
||||
spec:
|
||||
image: quay.io/myorg/debian-bootc:latest
|
||||
bootOrder: "normal" # or "rollback"
|
||||
status:
|
||||
staged: null
|
||||
booted:
|
||||
image: quay.io/myorg/debian-bootc:v1.0.0
|
||||
digest: sha256:abc123...
|
||||
version: "1.0.0"
|
||||
rollback:
|
||||
image: quay.io/myorg/debian-bootc:v0.9.0
|
||||
digest: sha256:def456...
|
||||
version: "0.9.0"
|
||||
rollbackQueued: false
|
||||
otherDeployments: []
|
||||
```
|
||||
|
||||
### 2. Image Reference Format
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
image:
|
||||
transport: "registry"
|
||||
name: "quay.io/myorg/debian-bootc"
|
||||
tag: "latest"
|
||||
# or
|
||||
digest: "sha256:abc123..."
|
||||
```
|
||||
|
||||
### 3. Boot Order Options
|
||||
|
||||
```yaml
|
||||
spec:
|
||||
bootOrder: "normal" # Normal boot order
|
||||
# or
|
||||
bootOrder: "rollback" # Rollback to previous deployment
|
||||
```
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### 1. Interactive Editing
|
||||
|
||||
```bash
|
||||
# Set editor environment variable
|
||||
export EDITOR=vim
|
||||
|
||||
# Edit configuration interactively
|
||||
bootc edit
|
||||
```
|
||||
|
||||
**Process**:
|
||||
1. Current configuration is written to temporary file
|
||||
2. System editor is launched with temporary file
|
||||
3. User makes changes and saves
|
||||
4. Changes are validated and applied
|
||||
|
||||
### 2. File-Based Editing
|
||||
|
||||
```bash
|
||||
# Create configuration file
|
||||
cat > config.yaml << EOF
|
||||
apiVersion: v1
|
||||
kind: Host
|
||||
metadata:
|
||||
name: localhost
|
||||
spec:
|
||||
image: quay.io/myorg/debian-bootc:v2.0.0
|
||||
bootOrder: "normal"
|
||||
EOF
|
||||
|
||||
# Apply configuration
|
||||
bootc edit --filename config.yaml
|
||||
```
|
||||
|
||||
**Process**:
|
||||
1. Configuration is loaded from file
|
||||
2. Changes are validated
|
||||
3. Configuration is applied to system
|
||||
|
||||
### 3. Image Switching
|
||||
|
||||
```bash
|
||||
# Switch to different image
|
||||
bootc edit --filename - << EOF
|
||||
apiVersion: v1
|
||||
kind: Host
|
||||
metadata:
|
||||
name: localhost
|
||||
spec:
|
||||
image: quay.io/myorg/debian-bootc:v2.0.0
|
||||
EOF
|
||||
```
|
||||
|
||||
### 4. Rollback Configuration
|
||||
|
||||
```bash
|
||||
# Configure rollback
|
||||
bootc edit --filename - << EOF
|
||||
apiVersion: v1
|
||||
kind: Host
|
||||
metadata:
|
||||
name: localhost
|
||||
spec:
|
||||
image: quay.io/myorg/debian-bootc:latest
|
||||
bootOrder: "rollback"
|
||||
EOF
|
||||
```
|
||||
|
||||
## State Transitions
|
||||
|
||||
### 1. Image Changes
|
||||
|
||||
When the image reference changes:
|
||||
1. **Validation**: Verify new image exists and is accessible
|
||||
2. **Download**: Pull new container image from registry
|
||||
3. **Staging**: Stage new image for next boot
|
||||
4. **Status Update**: Update system status
|
||||
|
||||
### 2. Boot Order Changes
|
||||
|
||||
When boot order changes:
|
||||
1. **Validation**: Verify rollback deployment exists
|
||||
2. **Rollback**: Execute rollback operation
|
||||
3. **Status Update**: Update boot order configuration
|
||||
|
||||
### 3. No Changes
|
||||
|
||||
When no changes are detected:
|
||||
1. **Message**: Display "Edit cancelled, no changes made"
|
||||
2. **Exit**: Return without making changes
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Editor Errors
|
||||
|
||||
```rust
|
||||
// Editor not found
|
||||
$EDITOR is unset, and no backup editor found
|
||||
|
||||
// Editor execution failed
|
||||
Invoking editor vim failed
|
||||
```
|
||||
|
||||
### 2. Configuration Errors
|
||||
|
||||
```rust
|
||||
// Invalid YAML
|
||||
Error parsing YAML: invalid syntax
|
||||
|
||||
// Invalid configuration
|
||||
Error: invalid host specification
|
||||
```
|
||||
|
||||
### 3. System Errors
|
||||
|
||||
```rust
|
||||
// System not bootc compatible
|
||||
Error: system is not bootc compatible
|
||||
|
||||
// Image not found
|
||||
Error: image not found in registry
|
||||
```
|
||||
|
||||
## Integration Points
|
||||
|
||||
### 1. OSTree Integration
|
||||
|
||||
- **Deployment Management**: Uses OSTree for deployment operations
|
||||
- **Status Queries**: Queries OSTree for current system state
|
||||
- **Staging**: Uses OSTree staging for new deployments
|
||||
|
||||
### 2. Container Registry Integration
|
||||
|
||||
- **Image Pulling**: Uses container registry for image downloads
|
||||
- **Authentication**: Supports registry authentication
|
||||
- **Signature Verification**: Validates image signatures
|
||||
|
||||
### 3. Systemd Integration
|
||||
|
||||
- **Service Management**: Coordinates with systemd services
|
||||
- **Status Updates**: Updates system status through systemd
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Configuration Validation
|
||||
|
||||
- **Schema Validation**: Validates configuration against schema
|
||||
- **Transition Validation**: Ensures safe state transitions
|
||||
- **Image Verification**: Verifies image signatures and authenticity
|
||||
|
||||
### 2. Editor Security
|
||||
|
||||
- **Editor Selection**: Uses secure editor selection process
|
||||
- **Temporary Files**: Uses secure temporary file handling
|
||||
- **Process Isolation**: Isolates editor process execution
|
||||
|
||||
### 3. System Security
|
||||
|
||||
- **Privilege Escalation**: Requires appropriate privileges
|
||||
- **State Consistency**: Maintains system state consistency
|
||||
- **Rollback Safety**: Ensures safe rollback operations
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### 1. Configuration Loading
|
||||
|
||||
- **File I/O**: Efficient file reading and writing
|
||||
- **Memory Usage**: Minimal memory footprint for configuration
|
||||
- **Parsing**: Fast YAML parsing and validation
|
||||
|
||||
### 2. Editor Launch
|
||||
|
||||
- **Process Spawning**: Efficient editor process creation
|
||||
- **Temporary Files**: Fast temporary file operations
|
||||
- **Editor Detection**: Quick editor availability checking
|
||||
|
||||
### 3. System Updates
|
||||
|
||||
- **Incremental Updates**: Only updates changed components
|
||||
- **Status Caching**: Caches system status for performance
|
||||
- **Validation Caching**: Caches validation results
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Editor Issues
|
||||
|
||||
```bash
|
||||
# Check editor availability
|
||||
which vim nano vi
|
||||
|
||||
# Set editor explicitly
|
||||
export EDITOR=/usr/bin/vim
|
||||
bootc edit
|
||||
```
|
||||
|
||||
### 2. Configuration Issues
|
||||
|
||||
```bash
|
||||
# Validate YAML syntax
|
||||
yaml-lint config.yaml
|
||||
|
||||
# Check configuration schema
|
||||
bootc edit --filename config.yaml --dry-run
|
||||
```
|
||||
|
||||
### 3. System Issues
|
||||
|
||||
```bash
|
||||
# Check system status
|
||||
bootc status
|
||||
|
||||
# Check system compatibility
|
||||
bootc status --json | jq '.status.booted'
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Configuration Management
|
||||
|
||||
- **Version Control**: Store configurations in version control
|
||||
- **Validation**: Validate configurations before applying
|
||||
- **Backup**: Backup current configuration before changes
|
||||
- **Testing**: Test configurations in staging environment
|
||||
|
||||
### 2. Editor Usage
|
||||
|
||||
- **Editor Selection**: Use reliable editors (vim, nano)
|
||||
- **Environment Variables**: Set EDITOR environment variable
|
||||
- **Backup Editors**: Ensure backup editors are available
|
||||
- **Editor Configuration**: Configure editor for YAML editing
|
||||
|
||||
### 3. System Integration
|
||||
|
||||
- **Automation**: Use file-based editing for automation
|
||||
- **Monitoring**: Monitor system status after changes
|
||||
- **Rollback**: Test rollback procedures regularly
|
||||
- **Documentation**: Document configuration changes
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
|
||||
- **Dry Run Mode**: Preview changes without applying
|
||||
- **Configuration Templates**: Predefined configuration templates
|
||||
- **Validation Rules**: Custom validation rules
|
||||
- **Change Tracking**: Track configuration changes over time
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
- **API Support**: REST API for configuration management
|
||||
- **Web Interface**: Web-based configuration editor
|
||||
- **Configuration Sync**: Synchronize configurations across systems
|
||||
- **Audit Logging**: Comprehensive audit logging
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc edit system's architecture, implementation, and usage patterns.
|
||||
Loading…
Add table
Add a link
Reference in a new issue