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
969
status/bootc-status-external-commands.md
Normal file
969
status/bootc-status-external-commands.md
Normal file
|
|
@ -0,0 +1,969 @@
|
|||
# bootc status - 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 status` system. Understanding these external dependencies is crucial for troubleshooting, monitoring, and integrating bootc status into larger systems.
|
||||
|
||||
## Core System Commands
|
||||
|
||||
### 1. bootc Commands
|
||||
|
||||
#### bootc status
|
||||
**Purpose**: Display system status and deployment information
|
||||
**Usage**: `bootc status [OPTIONS...]`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment information
|
||||
- `systemd` - For service status
|
||||
- `jq` - For JSON parsing (optional)
|
||||
|
||||
```bash
|
||||
# Show current system status
|
||||
bootc status
|
||||
|
||||
# Show status in JSON format
|
||||
bootc status --format=json
|
||||
|
||||
# Show detailed status with verbose output
|
||||
bootc status --verbose
|
||||
|
||||
# Show only booted deployment status
|
||||
bootc status --booted
|
||||
|
||||
# Show status in YAML format
|
||||
bootc status --format=yaml
|
||||
```
|
||||
|
||||
#### bootc upgrade
|
||||
**Purpose**: Update current image to newer version
|
||||
**Usage**: `bootc upgrade [OPTIONS...]`
|
||||
**Integration**: Used to check status before/after upgrades
|
||||
|
||||
```bash
|
||||
# Check status before upgrade
|
||||
bootc status
|
||||
bootc upgrade --apply
|
||||
bootc status
|
||||
|
||||
# Check for updates
|
||||
bootc upgrade --check
|
||||
```
|
||||
|
||||
#### bootc switch
|
||||
**Purpose**: Switch to different container image reference
|
||||
**Usage**: `bootc switch [OPTIONS...] <TARGET>`
|
||||
**Integration**: Used to check status before/after switches
|
||||
|
||||
```bash
|
||||
# Check status before switch
|
||||
bootc status
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
bootc status
|
||||
```
|
||||
|
||||
#### bootc rollback
|
||||
**Purpose**: Rollback to previous deployment
|
||||
**Usage**: `bootc rollback [OPTIONS...]`
|
||||
**Integration**: Used to check status before/after rollbacks
|
||||
|
||||
```bash
|
||||
# Check status before rollback
|
||||
bootc status
|
||||
bootc rollback
|
||||
bootc status
|
||||
```
|
||||
|
||||
### 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
|
||||
|
||||
# Check with verbose output
|
||||
ostree admin status --verbose
|
||||
```
|
||||
|
||||
#### 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 internally by bootc 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
|
||||
```
|
||||
|
||||
#### ostree refs
|
||||
**Purpose**: List OSTree references
|
||||
**Usage**: `ostree refs [OPTIONS...]`
|
||||
**Integration**: Used for reference management
|
||||
|
||||
```bash
|
||||
# List all references
|
||||
ostree refs
|
||||
|
||||
# List references for specific remote
|
||||
ostree refs --remote=quay.io
|
||||
|
||||
# List references with details
|
||||
ostree refs --list
|
||||
```
|
||||
|
||||
### 3. System Management Commands
|
||||
|
||||
#### systemctl
|
||||
**Purpose**: Control systemd services and units
|
||||
**Usage**: `systemctl [COMMAND] [UNIT...]`
|
||||
**Integration**: Used for service management and status checking
|
||||
|
||||
```bash
|
||||
# Check service status
|
||||
systemctl status bootc-fetch-apply-updates.service
|
||||
|
||||
# Start service
|
||||
systemctl start bootc-fetch-apply-updates.service
|
||||
|
||||
# Enable service
|
||||
systemctl enable bootc-fetch-apply-updates.service
|
||||
|
||||
# Restart service
|
||||
systemctl restart bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
#### reboot
|
||||
**Purpose**: Reboot the system
|
||||
**Usage**: `reboot [OPTIONS...]`
|
||||
**Integration**: Used for system restart after status changes
|
||||
|
||||
```bash
|
||||
# Reboot system
|
||||
reboot
|
||||
|
||||
# Reboot with specific delay
|
||||
reboot +5
|
||||
|
||||
# Reboot with message
|
||||
reboot "Applying bootc changes"
|
||||
```
|
||||
|
||||
#### shutdown
|
||||
**Purpose**: Shutdown the system
|
||||
**Usage**: `shutdown [OPTIONS...]`
|
||||
**Integration**: Used for controlled shutdown
|
||||
|
||||
```bash
|
||||
# Shutdown system
|
||||
shutdown -h now
|
||||
|
||||
# Shutdown with delay
|
||||
shutdown -h +5
|
||||
|
||||
# Shutdown with message
|
||||
shutdown -h now "Applying bootc changes"
|
||||
```
|
||||
|
||||
## Data Processing Commands
|
||||
|
||||
### 1. JSON Processing
|
||||
|
||||
#### jq
|
||||
**Purpose**: JSON processor and query tool
|
||||
**Usage**: `jq [OPTIONS...] [FILTER] [FILE...]`
|
||||
**Integration**: Used for parsing and processing JSON output
|
||||
|
||||
```bash
|
||||
# Parse JSON output
|
||||
bootc status --format=json | jq '.status.booted'
|
||||
|
||||
# Check if system is bootc compatible
|
||||
bootc status --format=json | jq '.status.booted != null'
|
||||
|
||||
# Get current image version
|
||||
bootc status --format=json | jq -r '.status.booted.image.version // "unknown"'
|
||||
|
||||
# Check rollback status
|
||||
bootc status --format=json | jq '.status.rollbackQueued'
|
||||
|
||||
# Get image digest
|
||||
bootc status --format=json | jq -r '.status.booted.image.imageDigest'
|
||||
|
||||
# List all deployments
|
||||
bootc status --format=json | jq '.status | keys'
|
||||
```
|
||||
|
||||
#### yq
|
||||
**Purpose**: YAML processor and query tool
|
||||
**Usage**: `yq [OPTIONS...] [EXPRESSION] [FILE...]`
|
||||
**Integration**: Used for parsing and processing YAML output
|
||||
|
||||
```bash
|
||||
# Parse YAML output
|
||||
bootc status --format=yaml | yq '.status.booted'
|
||||
|
||||
# Get current image version
|
||||
bootc status --format=yaml | yq '.status.booted.image.version'
|
||||
|
||||
# Check rollback status
|
||||
bootc status --format=yaml | yq '.status.rollbackQueued'
|
||||
|
||||
# Get image digest
|
||||
bootc status --format=yaml | yq '.status.booted.image.imageDigest'
|
||||
```
|
||||
|
||||
### 2. Text Processing
|
||||
|
||||
#### grep
|
||||
**Purpose**: Search text patterns
|
||||
**Usage**: `grep [OPTIONS...] PATTERN [FILE...]`
|
||||
**Integration**: Used for filtering and searching output
|
||||
|
||||
```bash
|
||||
# Search for specific image
|
||||
bootc status | grep "quay.io/myorg"
|
||||
|
||||
# Search for rollback status
|
||||
bootc status | grep "Rollback Queued"
|
||||
|
||||
# Search for version information
|
||||
bootc status | grep "Version:"
|
||||
```
|
||||
|
||||
#### awk
|
||||
**Purpose**: Text processing and data extraction
|
||||
**Usage**: `awk [OPTIONS...] 'PROGRAM' [FILE...]`
|
||||
**Integration**: Used for extracting specific fields
|
||||
|
||||
```bash
|
||||
# Extract image name
|
||||
bootc status | awk '/Image:/ {print $2}'
|
||||
|
||||
# Extract version
|
||||
bootc status | awk '/Version:/ {print $2}'
|
||||
|
||||
# Extract digest
|
||||
bootc status | awk '/Digest:/ {print $2}'
|
||||
```
|
||||
|
||||
#### sed
|
||||
**Purpose**: Stream editor for filtering and transforming text
|
||||
**Usage**: `sed [OPTIONS...] SCRIPT [FILE...]`
|
||||
**Integration**: Used for text transformation
|
||||
|
||||
```bash
|
||||
# Remove leading whitespace
|
||||
bootc status | sed 's/^[[:space:]]*//'
|
||||
|
||||
# Extract specific lines
|
||||
bootc status | sed -n '/Image:/p'
|
||||
|
||||
# Replace text
|
||||
bootc status | sed 's/quay.io/myorg/quay.io/otherorg/g'
|
||||
```
|
||||
|
||||
### 3. Data Formatting
|
||||
|
||||
#### column
|
||||
**Purpose**: Format text into columns
|
||||
**Usage**: `column [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for formatting output
|
||||
|
||||
```bash
|
||||
# Format status output in columns
|
||||
bootc status | column -t
|
||||
|
||||
# Format with specific separator
|
||||
bootc status | column -s ':' -t
|
||||
```
|
||||
|
||||
#### sort
|
||||
**Purpose**: Sort lines of text
|
||||
**Usage**: `sort [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for sorting output
|
||||
|
||||
```bash
|
||||
# Sort status output
|
||||
bootc status | sort
|
||||
|
||||
# Sort by specific field
|
||||
bootc status | sort -k2
|
||||
```
|
||||
|
||||
#### uniq
|
||||
**Purpose**: Remove duplicate lines
|
||||
**Usage**: `uniq [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for removing duplicates
|
||||
|
||||
```bash
|
||||
# Remove duplicate lines
|
||||
bootc status | uniq
|
||||
|
||||
# Count unique lines
|
||||
bootc status | uniq -c
|
||||
```
|
||||
|
||||
## 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
|
||||
|
||||
# Check status-related logs
|
||||
journalctl -u bootc-fetch-apply-updates.service | grep status
|
||||
```
|
||||
|
||||
#### 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 /etc/bootc/config.yaml
|
||||
|
||||
# Display first bytes
|
||||
head -c 100 /etc/bootc/config.yaml
|
||||
```
|
||||
|
||||
## Network Commands
|
||||
|
||||
### 1. HTTP Clients
|
||||
|
||||
#### curl
|
||||
**Purpose**: HTTP client for registry communication
|
||||
**Usage**: `curl [OPTIONS...] URL`
|
||||
**Integration**: Used for registry API calls and authentication
|
||||
|
||||
```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/v2.0
|
||||
|
||||
# Authenticate with registry
|
||||
curl -u username:password https://quay.io/v2/token
|
||||
```
|
||||
|
||||
#### 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/v2.0
|
||||
|
||||
# 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
|
||||
```
|
||||
|
||||
### 3. Network Troubleshooting
|
||||
|
||||
#### 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
|
||||
```
|
||||
|
||||
#### traceroute
|
||||
**Purpose**: Trace network path
|
||||
**Usage**: `traceroute [OPTIONS...] HOST`
|
||||
**Integration**: Used for network path analysis
|
||||
|
||||
```bash
|
||||
# Trace path to registry
|
||||
traceroute quay.io
|
||||
|
||||
# Trace with specific options
|
||||
traceroute -n quay.io
|
||||
```
|
||||
|
||||
## Container Runtime Commands
|
||||
|
||||
### 1. Podman Commands
|
||||
|
||||
#### podman pull
|
||||
**Purpose**: Pull container images from registry
|
||||
**Usage**: `podman pull [OPTIONS...] IMAGE`
|
||||
**Integration**: Used by bootc for downloading images
|
||||
|
||||
```bash
|
||||
# Pull image from registry
|
||||
podman pull quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Pull with authentication
|
||||
podman pull --creds=username:password quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Pull specific tag
|
||||
podman pull quay.io/myorg/debian-bootc:latest
|
||||
```
|
||||
|
||||
#### 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:v2.0
|
||||
|
||||
# Inspect specific configuration
|
||||
podman inspect --format='{{.Config.Labels}}' quay.io/myorg/debian-bootc:v2.0
|
||||
|
||||
# Inspect manifest
|
||||
podman inspect --format='{{.Manifest}}' quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
#### podman images
|
||||
**Purpose**: List container images
|
||||
**Usage**: `podman images [OPTIONS...]`
|
||||
**Integration**: Used for image management
|
||||
|
||||
```bash
|
||||
# List all images
|
||||
podman images
|
||||
|
||||
# List images with specific format
|
||||
podman images --format "table {{.Repository}} {{.Tag}} {{.ID}}"
|
||||
|
||||
# List images with filters
|
||||
podman images --filter "reference=quay.io/myorg/*"
|
||||
```
|
||||
|
||||
### 2. Docker Commands (Alternative)
|
||||
|
||||
#### docker
|
||||
**Purpose**: Alternative container runtime
|
||||
**Usage**: `docker [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Alternative to podman
|
||||
|
||||
```bash
|
||||
# List containers
|
||||
docker ps -a
|
||||
|
||||
# List images
|
||||
docker images
|
||||
|
||||
# Inspect image
|
||||
docker inspect quay.io/myorg/debian-bootc:v2.0
|
||||
```
|
||||
|
||||
## 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 /etc/bootc/config.yaml
|
||||
|
||||
# Display with line numbers
|
||||
cat -n /etc/bootc/config.yaml
|
||||
|
||||
# Display non-printing characters
|
||||
cat -v /etc/bootc/config.yaml
|
||||
```
|
||||
|
||||
#### cp
|
||||
**Purpose**: Copy files
|
||||
**Usage**: `cp [OPTIONS...] SOURCE DEST`
|
||||
**Integration**: Used for backing up configuration files
|
||||
|
||||
```bash
|
||||
# Copy file
|
||||
cp /etc/bootc/config.yaml /etc/bootc/config.yaml.backup
|
||||
|
||||
# Copy with preserve attributes
|
||||
cp -p /etc/bootc/config.yaml /etc/bootc/config.yaml.backup
|
||||
|
||||
# Copy recursively
|
||||
cp -r /etc/bootc/ /etc/bootc.backup/
|
||||
```
|
||||
|
||||
#### mv
|
||||
**Purpose**: Move or rename files
|
||||
**Usage**: `mv [OPTIONS...] SOURCE DEST`
|
||||
**Integration**: Used for renaming configuration files
|
||||
|
||||
```bash
|
||||
# Rename file
|
||||
mv /etc/bootc/config.yaml /etc/bootc/config.yaml.old
|
||||
|
||||
# Move file
|
||||
mv /etc/bootc/config.yaml /backup/config.yaml
|
||||
```
|
||||
|
||||
#### rm
|
||||
**Purpose**: Remove files
|
||||
**Usage**: `rm [OPTIONS...] FILE...`
|
||||
**Integration**: Used for cleaning up temporary files
|
||||
|
||||
```bash
|
||||
# Remove file
|
||||
rm /etc/bootc/config.yaml
|
||||
|
||||
# Remove with confirmation
|
||||
rm -i /etc/bootc/config.yaml
|
||||
|
||||
# Remove recursively
|
||||
rm -r /etc/bootc/
|
||||
```
|
||||
|
||||
### 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
|
||||
```
|
||||
|
||||
## 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
|
||||
```
|
||||
|
||||
## System Information Commands
|
||||
|
||||
### 1. 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
|
||||
```
|
||||
|
||||
### 2. Hardware Information
|
||||
|
||||
#### lscpu
|
||||
**Purpose**: Display CPU information
|
||||
**Usage**: `lscpu [OPTIONS...]`
|
||||
**Integration**: Used for system resource analysis
|
||||
|
||||
```bash
|
||||
# Display CPU information
|
||||
lscpu
|
||||
|
||||
# Display in specific format
|
||||
lscpu --extended
|
||||
```
|
||||
|
||||
#### lsblk
|
||||
**Purpose**: List block devices
|
||||
**Usage**: `lsblk [OPTIONS...]`
|
||||
**Integration**: Used for storage device identification
|
||||
|
||||
```bash
|
||||
# List all block devices
|
||||
lsblk
|
||||
|
||||
# List with filesystem information
|
||||
lsblk -f
|
||||
|
||||
# List specific device
|
||||
lsblk /dev/sda
|
||||
```
|
||||
|
||||
## Automation and Scripting Commands
|
||||
|
||||
### 1. Shell Scripting
|
||||
|
||||
#### bash
|
||||
**Purpose**: Bourne Again Shell
|
||||
**Usage**: `bash [OPTIONS...] [FILE]`
|
||||
**Integration**: Used for automation scripts
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Check if system is bootc compatible
|
||||
if bootc status --format=json | jq -e '.status.booted != null' > /dev/null; then
|
||||
echo "System is bootc compatible"
|
||||
else
|
||||
echo "System is not bootc compatible"
|
||||
fi
|
||||
```
|
||||
|
||||
#### sh
|
||||
**Purpose**: POSIX shell
|
||||
**Usage**: `sh [OPTIONS...] [FILE]`
|
||||
**Integration**: Used for portable scripts
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
# Check rollback status
|
||||
if bootc status --format=json | jq -r '.status.rollbackQueued' | grep -q true; then
|
||||
echo "Rollback is queued"
|
||||
fi
|
||||
```
|
||||
|
||||
### 2. Process Control
|
||||
|
||||
#### ps
|
||||
**Purpose**: Display running processes
|
||||
**Usage**: `ps [OPTIONS...]`
|
||||
**Integration**: Used for process monitoring
|
||||
|
||||
```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 process identification
|
||||
|
||||
```bash
|
||||
# Find bootc processes
|
||||
pgrep bootc
|
||||
|
||||
# Find with full command line
|
||||
pgrep -f bootc
|
||||
|
||||
# Find with specific user
|
||||
pgrep -u root bootc
|
||||
```
|
||||
|
||||
#### pkill
|
||||
**Purpose**: Kill processes by name
|
||||
**Usage**: `pkill [OPTIONS...] PATTERN`
|
||||
**Integration**: Used for process termination
|
||||
|
||||
```bash
|
||||
# Kill bootc processes
|
||||
pkill bootc
|
||||
|
||||
# Kill with signal
|
||||
pkill -9 bootc
|
||||
|
||||
# Kill with specific user
|
||||
pkill -u root bootc
|
||||
```
|
||||
|
||||
## 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 /etc/bootc/config.yaml
|
||||
|
||||
# Commit changes
|
||||
git commit -m "Update configuration"
|
||||
|
||||
# Check status
|
||||
git status
|
||||
```
|
||||
|
||||
This comprehensive external commands reference provides all the tools and commands needed to effectively manage, troubleshoot, and integrate with the bootc status system.
|
||||
459
status/bootc-status-flowchart.md
Normal file
459
status/bootc-status-flowchart.md
Normal file
|
|
@ -0,0 +1,459 @@
|
|||
# bootc status - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc status` process flow, showing the decision points, operations, and data structures involved in displaying system status information.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc status │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Validate Format Version │
|
||||
│ │
|
||||
│ • Check format version (0, 1 supported) │
|
||||
│ • Error if unsupported version │
|
||||
│ • Default to version 1 │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check OSTree Boot Status │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ ostree_booted()? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ No │ │ Yes │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Return ││ │ │ Get System Status ││ │
|
||||
│ │ │ Default ││ │ │ ││ │
|
||||
│ │ │ Empty ││ │ │ • Get storage interface ││ │
|
||||
│ │ │ Status ││ │ │ • Get OSTree repository ││ │
|
||||
│ │ └─────────────┘│ │ │ • Get booted deployment ││ │
|
||||
│ │ │ │ │ • Call get_status() ││ │
|
||||
│ │ ┌─────────────┐│ │ └─────────────────────────────────┘│ │
|
||||
│ │ │ Skip to ││ │ │ │
|
||||
│ │ │ Output ││ │ │ │
|
||||
│ │ └─────────────┘│ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Filter to Booted Deployment │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --booted specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Filter to ││ │ │ Keep All Deployments ││ │
|
||||
│ │ │ Booted ││ │ │ ││ │
|
||||
│ │ │ Slot Only ││ │ │ • Include all deployment info ││ │
|
||||
│ │ │ ││ │ │ • Show staged, booted, rollback││ │
|
||||
│ │ └─────────────┘│ │ │ ││ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Output Format │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Format specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Use ││ │ │ Auto-detect Format ││ │
|
||||
│ │ │ Specified ││ │ │ ││ │
|
||||
│ │ │ Format ││ │ │ • Check --json flag ││ │
|
||||
│ │ │ • JSON ││ │ │ • Check if terminal ││ │
|
||||
│ │ │ • YAML ││ │ │ • Default to YAML ││ │
|
||||
│ │ │ • Human ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Output in Requested Format │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Format Type? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ JSON │ │ YAML │ │ Human Readable│ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
||||
│ │ │ Serialize ││ │ │ Serialize ││ │ │ Format for ││ │
|
||||
│ │ │ to JSON ││ │ │ to YAML ││ │ │ human ││ │
|
||||
│ │ │ • Canonical ││ │ │ • Standard ││ │ │ reading ││ │
|
||||
│ │ │ format ││ │ │ format ││ │ │ • Include ││ │
|
||||
│ │ │ • Machine ││ │ │ • Machine ││ │ │ verbose ││ │
|
||||
│ │ │ readable ││ │ │ readable ││ │ │ info if ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────┘│ │ │ requested ││ │
|
||||
│ └─────────────────┘ └─────────────────┘ │ └─────────────┘│ │
|
||||
│ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Status information displayed successfully │
|
||||
│ • Format appropriate for use case │
|
||||
│ • All deployment information included │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Core Status Gathering Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Core Status Gathering │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Get Stateroot Name │
|
||||
│ │
|
||||
│ • Extract stateroot from booted deployment │
|
||||
│ • Use for filtering related deployments │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Partition Deployments │
|
||||
│ │
|
||||
│ • Get all deployments from sysroot │
|
||||
│ • Separate related deployments from others │
|
||||
│ • Filter by stateroot name │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Find Staged Deployment │
|
||||
│ │
|
||||
│ • Search for deployment marked as staged │
|
||||
│ • Remove from related deployments list │
|
||||
│ • Store for later processing │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Filter Booted Deployment │
|
||||
│ │
|
||||
│ • Remove booted deployment from related list │
|
||||
│ • Keep for separate processing │
|
||||
│ • Ensure no duplicates │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Get Rollback Deployment │
|
||||
│ │
|
||||
│ • Pop first deployment from related list │
|
||||
│ • This becomes rollback deployment │
|
||||
│ • Remaining deployments become "other" │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Rollback Status │
|
||||
│ │
|
||||
│ • Compare rollback and booted deployment indices │
|
||||
│ • Set rollback_queued flag │
|
||||
│ • Determine boot order state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Boot Entries │
|
||||
│ │
|
||||
│ • Process staged deployment │
|
||||
│ • Process booted deployment │
|
||||
│ • Process rollback deployment │
|
||||
│ • Process other deployments │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Extract Image Information │
|
||||
│ │
|
||||
│ • Parse OCI image configuration │
|
||||
│ • Extract image metadata │
|
||||
│ • Create ImageStatus structures │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Host Specification │
|
||||
│ │
|
||||
│ • Determine image reference │
|
||||
│ • Set boot order │
|
||||
│ • Create HostSpec structure │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Determine Host Type │
|
||||
│ │
|
||||
│ • Check if booted deployment has image │
|
||||
│ • Set HostType::BootcHost if container-based │
|
||||
│ • Set to None if not container-based │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Host Status │
|
||||
│ │
|
||||
│ • Combine all deployment information │
|
||||
│ • Set rollback_queued flag │
|
||||
│ • Set host type │
|
||||
│ • Create HostStatus structure │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Complete status information gathered │
|
||||
│ • All deployments processed │
|
||||
│ • Image information extracted │
|
||||
│ • Ready for output formatting │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Boot Entry Creation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Boot Entry Creation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Extract Deployment Info │
|
||||
│ │
|
||||
│ • Get deployment checksum │
|
||||
│ • Get deployment osname │
|
||||
│ • Create DeploymentInfo structure │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check for Image Reference │
|
||||
│ │
|
||||
│ • Parse deployment origin │
|
||||
│ • Look for refspec in origin │
|
||||
│ • Parse OSTree image reference │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Query Image Commit │
|
||||
│ │
|
||||
│ • Query OSTree repository for image commit │
|
||||
│ • Get cached update information │
|
||||
│ • Extract image configuration │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Image Status │
|
||||
│ │
|
||||
│ • Parse OCI image configuration │
|
||||
│ • Extract labels and metadata │
|
||||
│ • Create ImageStatus structure │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Boot Entry │
|
||||
│ │
|
||||
│ • Combine deployment info and image status │
|
||||
│ • Create BootEntry structure │
|
||||
│ • Return complete boot entry │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Image Status Creation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Image Status Creation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Extract Image Labels │
|
||||
│ │
|
||||
│ • Get labels from image configuration │
|
||||
│ • Look for version information │
|
||||
│ • Look for timestamp information │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Parse Timestamp │
|
||||
│ │
|
||||
│ • Look for ANNOTATION_CREATED label │
|
||||
│ • Parse RFC3339 timestamp │
|
||||
│ • Convert to UTC timezone │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Extract Architecture │
|
||||
│ │
|
||||
│ • Get architecture from image configuration │
|
||||
│ • Default to "unknown" if not found │
|
||||
│ • Convert to string │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Image Status │
|
||||
│ │
|
||||
│ • Combine image reference and metadata │
|
||||
│ • Set version, timestamp, digest, architecture │
|
||||
│ • Create ImageStatus structure │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Format Selection Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Format Selection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Format Option │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --format specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Use ││ │ │ Check Legacy Options ││ │
|
||||
│ │ │ Specified ││ │ │ ││ │
|
||||
│ │ │ Format ││ │ │ • Check --json flag ││ │
|
||||
│ │ │ • JSON ││ │ │ • Check if terminal ││ │
|
||||
│ │ │ • YAML ││ │ │ • Default to YAML ││ │
|
||||
│ │ │ • Human ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Legacy Options │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ --json specified? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Use JSON ││ │ │ Check Terminal ││ │
|
||||
│ │ │ Format ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ │ • Check if stdout is terminal ││ │
|
||||
│ │ │ │ │ • Use Human Readable if yes ││ │
|
||||
│ │ │ │ │ • Use YAML if no ││ │
|
||||
│ │ │ │ │ ││ │
|
||||
│ │ │ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Terminal Status │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ stdout.is_terminal()? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Use Human ││ │ │ Use YAML Format ││ │
|
||||
│ │ │ Readable ││ │ │ ││ │
|
||||
│ │ │ Format ││ │ │ • Machine readable ││ │
|
||||
│ │ │ ││ │ │ • Programmatic parsing ││ │
|
||||
│ │ │ • Interactive││ │ │ • Standard format ││ │
|
||||
│ │ │ use ││ │ │ ││ │
|
||||
│ │ │ • Human ││ │ │ ││ │
|
||||
│ │ │ friendly ││ │ │ ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Format │ │ System │ │ Deployment │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Unsupported │ │ • Not OSTree │ │ • No deployments│ │
|
||||
│ │ format │ │ booted │ │ found │ │
|
||||
│ │ version │ │ • Storage │ │ • Invalid │ │
|
||||
│ │ • Invalid │ │ access │ │ deployment │ │
|
||||
│ │ format │ │ failed │ │ structure │ │
|
||||
│ │ • JSON/YAML │ │ • OSTree │ │ • Image │ │
|
||||
│ │ parsing │ │ repository │ │ parsing │ │
|
||||
│ │ failed │ │ error │ │ failed │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Response │
|
||||
│ │
|
||||
│ • Display error message │
|
||||
│ • Provide context information │
|
||||
│ • Suggest remediation steps │
|
||||
│ • Return appropriate exit code │
|
||||
│ • Clean up any partial state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc status process, showing all decision points, operations, and data structures involved in displaying system status information.
|
||||
832
status/bootc-status-technical-guide.md
Normal file
832
status/bootc-status-technical-guide.md
Normal file
|
|
@ -0,0 +1,832 @@
|
|||
# bootc status - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc status` is a command for displaying the current state of a bootc-managed system. It provides comprehensive information about deployments, boot order, image references, and system configuration. The command supports multiple output formats and can be used both interactively and programmatically.
|
||||
|
||||
## Purpose
|
||||
|
||||
The status command serves several critical functions:
|
||||
|
||||
1. **System State Display**: Show current bootc system state
|
||||
2. **Deployment Information**: Display staged, booted, and rollback deployments
|
||||
3. **Image References**: Show container image information and metadata
|
||||
4. **Boot Order Status**: Indicate current boot order configuration
|
||||
5. **Programmatic Access**: Provide structured data for automation
|
||||
6. **Troubleshooting**: Help diagnose system issues
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc status [OPTIONS...]
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Show current system status
|
||||
bootc status
|
||||
|
||||
# Show status in JSON format
|
||||
bootc status --format=json
|
||||
|
||||
# Show detailed status with verbose output
|
||||
bootc status --verbose
|
||||
|
||||
# Show only booted deployment status
|
||||
bootc status --booted
|
||||
|
||||
# Show status in YAML format
|
||||
bootc status --format=yaml
|
||||
```
|
||||
|
||||
## Command Options
|
||||
|
||||
| Option | Description | Default | Required |
|
||||
|--------|-------------|---------|----------|
|
||||
| `--format` | Output format (humanreadable, yaml, json) | `auto` | No |
|
||||
| `--format-version` | Format version (0, 1) | `1` | No |
|
||||
| `--booted` | Only display booted deployment | `false` | No |
|
||||
| `--verbose`, `-v` | Include additional fields | `false` | No |
|
||||
| `--json` | Output in JSON format (deprecated) | `false` | No |
|
||||
|
||||
### Output Formats
|
||||
|
||||
| Format | Description | Use Case |
|
||||
|--------|-------------|----------|
|
||||
| `humanreadable` | Human-friendly text output | Interactive use |
|
||||
| `yaml` | YAML-formatted output | Programmatic parsing |
|
||||
| `json` | JSON-formatted output | Programmatic parsing |
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### 1. Status Command Structure
|
||||
|
||||
```rust
|
||||
pub(crate) struct StatusOpts {
|
||||
pub(crate) json: bool, // JSON output (deprecated)
|
||||
pub(crate) format: Option<OutputFormat>, // Output format
|
||||
pub(crate) format_version: Option<u32>, // Format version
|
||||
pub(crate) booted: bool, // Only booted deployment
|
||||
pub(crate) verbose: bool, // Verbose output
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Status Process Flow
|
||||
|
||||
```rust
|
||||
pub(crate) async fn status(opts: StatusOpts) -> Result<()> {
|
||||
// 1. Validate format version
|
||||
match opts.format_version.unwrap_or_default() {
|
||||
0 | 1 => {} // Both 0 and 1 mean "v1"
|
||||
o => anyhow::bail!("Unsupported format version: {o}"),
|
||||
};
|
||||
|
||||
// 2. Get system status
|
||||
let mut host = if !ostree_booted()? {
|
||||
Default::default()
|
||||
} else {
|
||||
let sysroot = super::cli::get_storage().await?;
|
||||
let ostree = sysroot.get_ostree()?;
|
||||
let booted_deployment = ostree.booted_deployment();
|
||||
let (_deployments, host) = get_status(&ostree, booted_deployment.as_ref())?;
|
||||
host
|
||||
};
|
||||
|
||||
// 3. Filter to booted deployment if requested
|
||||
if opts.booted {
|
||||
host.filter_to_slot(Slot::Booted);
|
||||
}
|
||||
|
||||
// 4. Determine output format
|
||||
let out = std::io::stdout();
|
||||
let mut out = out.lock();
|
||||
let legacy_opt = if opts.json {
|
||||
OutputFormat::Json
|
||||
} else if std::io::stdout().is_terminal() {
|
||||
OutputFormat::HumanReadable
|
||||
} else {
|
||||
OutputFormat::Yaml
|
||||
};
|
||||
let format = opts.format.unwrap_or(legacy_opt);
|
||||
|
||||
// 5. Output in requested format
|
||||
match format {
|
||||
OutputFormat::Json => host.to_canon_json_writer(&mut out),
|
||||
OutputFormat::Yaml => serde_yaml::to_writer(&mut out, &host),
|
||||
OutputFormat::HumanReadable => {
|
||||
human_readable_output(&mut out, &host, opts.verbose)
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Core Status Gathering
|
||||
|
||||
```rust
|
||||
pub(crate) fn get_status(
|
||||
sysroot: &SysrootLock,
|
||||
booted_deployment: Option<&ostree::Deployment>,
|
||||
) -> Result<(Deployments, Host)> {
|
||||
// 1. Get stateroot name
|
||||
let stateroot = booted_deployment.as_ref().map(|d| d.osname());
|
||||
|
||||
// 2. Partition deployments
|
||||
let (mut related_deployments, other_deployments) = sysroot
|
||||
.deployments()
|
||||
.into_iter()
|
||||
.partition::<VecDeque<_>, _>(|d| Some(d.osname()) == stateroot);
|
||||
|
||||
// 3. Find staged deployment
|
||||
let staged = related_deployments
|
||||
.iter()
|
||||
.position(|d| d.is_staged())
|
||||
.map(|i| related_deployments.remove(i).unwrap());
|
||||
|
||||
// 4. Filter out booted deployment
|
||||
if let Some(booted) = booted_deployment.as_ref() {
|
||||
related_deployments.retain(|f| !f.equal(booted));
|
||||
}
|
||||
|
||||
// 5. Get rollback deployment
|
||||
let rollback = related_deployments.pop_front();
|
||||
|
||||
// 6. Determine rollback queued status
|
||||
let rollback_queued = match (booted_deployment.as_ref(), rollback.as_ref()) {
|
||||
(Some(booted), Some(rollback)) => rollback.index() < booted.index(),
|
||||
_ => false,
|
||||
};
|
||||
|
||||
// 7. Determine boot order
|
||||
let boot_order = if rollback_queued {
|
||||
BootOrder::Rollback
|
||||
} else {
|
||||
BootOrder::Default
|
||||
};
|
||||
|
||||
// 8. Create deployments structure
|
||||
let deployments = Deployments {
|
||||
staged,
|
||||
rollback,
|
||||
other: related_deployments,
|
||||
};
|
||||
|
||||
// 9. Create boot entries
|
||||
let staged = deployments.staged
|
||||
.as_ref()
|
||||
.map(|d| boot_entry_from_deployment(sysroot, d))
|
||||
.transpose()
|
||||
.context("Staged deployment")?;
|
||||
|
||||
let booted = booted_deployment
|
||||
.as_ref()
|
||||
.map(|d| boot_entry_from_deployment(sysroot, d))
|
||||
.transpose()
|
||||
.context("Booted deployment")?;
|
||||
|
||||
let rollback = deployments.rollback
|
||||
.as_ref()
|
||||
.map(|d| boot_entry_from_deployment(sysroot, d))
|
||||
.transpose()
|
||||
.context("Rollback deployment")?;
|
||||
|
||||
// 10. Create host specification
|
||||
let spec = staged
|
||||
.as_ref()
|
||||
.or(booted.as_ref())
|
||||
.and_then(|entry| entry.image.as_ref())
|
||||
.map(|img| HostSpec {
|
||||
image: Some(img.image.clone()),
|
||||
boot_order,
|
||||
})
|
||||
.unwrap_or_default();
|
||||
|
||||
// 11. Determine host type
|
||||
let ty = if booted
|
||||
.as_ref()
|
||||
.map(|b| b.image.is_some())
|
||||
.unwrap_or_default()
|
||||
{
|
||||
Some(HostType::BootcHost)
|
||||
} else {
|
||||
None
|
||||
};
|
||||
|
||||
// 12. Create host status
|
||||
let mut host = Host::new(spec);
|
||||
host.status = HostStatus {
|
||||
staged,
|
||||
booted,
|
||||
rollback,
|
||||
other_deployments: other_deployments,
|
||||
rollback_queued,
|
||||
ty,
|
||||
};
|
||||
|
||||
Ok((deployments, host))
|
||||
}
|
||||
```
|
||||
|
||||
## Data Structures
|
||||
|
||||
### 1. Host Structure
|
||||
|
||||
```rust
|
||||
pub struct Host {
|
||||
pub resource: k8sapitypes::Resource,
|
||||
pub spec: HostSpec,
|
||||
pub status: HostStatus,
|
||||
}
|
||||
```
|
||||
|
||||
### 2. Host Specification
|
||||
|
||||
```rust
|
||||
pub struct HostSpec {
|
||||
pub image: Option<ImageReference>,
|
||||
pub boot_order: BootOrder,
|
||||
}
|
||||
```
|
||||
|
||||
### 3. Host Status
|
||||
|
||||
```rust
|
||||
pub struct HostStatus {
|
||||
pub staged: Option<BootEntry>,
|
||||
pub booted: Option<BootEntry>,
|
||||
pub rollback: Option<BootEntry>,
|
||||
pub other_deployments: Vec<BootEntry>,
|
||||
pub rollback_queued: bool,
|
||||
pub ty: Option<HostType>,
|
||||
}
|
||||
```
|
||||
|
||||
### 4. Boot Entry
|
||||
|
||||
```rust
|
||||
pub struct BootEntry {
|
||||
pub deployment: DeploymentInfo,
|
||||
pub image: Option<ImageStatus>,
|
||||
}
|
||||
```
|
||||
|
||||
### 5. Image Status
|
||||
|
||||
```rust
|
||||
pub struct ImageStatus {
|
||||
pub image: ImageReference,
|
||||
pub version: Option<String>,
|
||||
pub timestamp: Option<chrono::DateTime<chrono::Utc>>,
|
||||
pub image_digest: String,
|
||||
pub architecture: String,
|
||||
}
|
||||
```
|
||||
|
||||
## Output Formats
|
||||
|
||||
### 1. Human Readable Format
|
||||
|
||||
**Default for terminal output**
|
||||
|
||||
```
|
||||
System is deployed via bootc.
|
||||
|
||||
Image: quay.io/myorg/debian-bootc:v2.0
|
||||
Version: 2.0.0
|
||||
Digest: sha256:abc123def456...
|
||||
Architecture: x86_64
|
||||
|
||||
Boot Order: Default
|
||||
Rollback Queued: false
|
||||
|
||||
Deployments:
|
||||
Staged: None
|
||||
Booted: quay.io/myorg/debian-bootc:v2.0
|
||||
Rollback: quay.io/myorg/debian-bootc:v1.0
|
||||
```
|
||||
|
||||
### 2. YAML Format
|
||||
|
||||
**Default for non-terminal output**
|
||||
|
||||
```yaml
|
||||
apiVersion: v1
|
||||
kind: Host
|
||||
metadata:
|
||||
name: localhost
|
||||
spec:
|
||||
image:
|
||||
image: quay.io/myorg/debian-bootc:v2.0
|
||||
transport: registry
|
||||
bootOrder: Default
|
||||
status:
|
||||
staged: null
|
||||
booted:
|
||||
deployment:
|
||||
id: abc123def456...
|
||||
osname: debian-bootc
|
||||
checksum: def456ghi789...
|
||||
image:
|
||||
image:
|
||||
image: quay.io/myorg/debian-bootc:v2.0
|
||||
transport: registry
|
||||
version: "2.0.0"
|
||||
timestamp: "2024-01-15T10:30:00Z"
|
||||
imageDigest: sha256:abc123def456...
|
||||
architecture: x86_64
|
||||
rollback:
|
||||
deployment:
|
||||
id: def456ghi789...
|
||||
osname: debian-bootc
|
||||
checksum: ghi789jkl012...
|
||||
image:
|
||||
image:
|
||||
image: quay.io/myorg/debian-bootc:v1.0
|
||||
transport: registry
|
||||
version: "1.0.0"
|
||||
timestamp: "2024-01-10T15:45:00Z"
|
||||
imageDigest: sha256:def456ghi789...
|
||||
architecture: x86_64
|
||||
otherDeployments: []
|
||||
rollbackQueued: false
|
||||
ty: BootcHost
|
||||
```
|
||||
|
||||
### 3. JSON Format
|
||||
|
||||
**For programmatic access**
|
||||
|
||||
```json
|
||||
{
|
||||
"apiVersion": "v1",
|
||||
"kind": "Host",
|
||||
"metadata": {
|
||||
"name": "localhost"
|
||||
},
|
||||
"spec": {
|
||||
"image": {
|
||||
"image": "quay.io/myorg/debian-bootc:v2.0",
|
||||
"transport": "registry"
|
||||
},
|
||||
"bootOrder": "Default"
|
||||
},
|
||||
"status": {
|
||||
"staged": null,
|
||||
"booted": {
|
||||
"deployment": {
|
||||
"id": "abc123def456...",
|
||||
"osname": "debian-bootc",
|
||||
"checksum": "def456ghi789..."
|
||||
},
|
||||
"image": {
|
||||
"image": {
|
||||
"image": "quay.io/myorg/debian-bootc:v2.0",
|
||||
"transport": "registry"
|
||||
},
|
||||
"version": "2.0.0",
|
||||
"timestamp": "2024-01-15T10:30:00Z",
|
||||
"imageDigest": "sha256:abc123def456...",
|
||||
"architecture": "x86_64"
|
||||
}
|
||||
},
|
||||
"rollback": {
|
||||
"deployment": {
|
||||
"id": "def456ghi789...",
|
||||
"osname": "debian-bootc",
|
||||
"checksum": "ghi789jkl012..."
|
||||
},
|
||||
"image": {
|
||||
"image": {
|
||||
"image": "quay.io/myorg/debian-bootc:v1.0",
|
||||
"transport": "registry"
|
||||
},
|
||||
"version": "1.0.0",
|
||||
"timestamp": "2024-01-10T15:45:00Z",
|
||||
"imageDigest": "sha256:def456ghi789...",
|
||||
"architecture": "x86_64"
|
||||
}
|
||||
},
|
||||
"otherDeployments": [],
|
||||
"rollbackQueued": false,
|
||||
"ty": "BootcHost"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Deployment Detection
|
||||
|
||||
### 1. OSTree Boot Detection
|
||||
|
||||
```rust
|
||||
if !ostree_booted()? {
|
||||
Default::default()
|
||||
} else {
|
||||
// Get system status
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Check if system is booted via OSTree
|
||||
**Process**: Verify OSTree boot environment
|
||||
|
||||
### 2. Deployment Partitioning
|
||||
|
||||
```rust
|
||||
let (mut related_deployments, other_deployments) = sysroot
|
||||
.deployments()
|
||||
.into_iter()
|
||||
.partition::<VecDeque<_>, _>(|d| Some(d.osname()) == stateroot);
|
||||
```
|
||||
|
||||
**Purpose**: Separate related deployments from others
|
||||
**Process**: Filter deployments by stateroot name
|
||||
|
||||
### 3. Staged Deployment Detection
|
||||
|
||||
```rust
|
||||
let staged = related_deployments
|
||||
.iter()
|
||||
.position(|d| d.is_staged())
|
||||
.map(|i| related_deployments.remove(i).unwrap());
|
||||
```
|
||||
|
||||
**Purpose**: Find staged deployment for next boot
|
||||
**Process**: Look for deployment marked as staged
|
||||
|
||||
### 4. Rollback Detection
|
||||
|
||||
```rust
|
||||
let rollback = related_deployments.pop_front();
|
||||
let rollback_queued = match (booted_deployment.as_ref(), rollback.as_ref()) {
|
||||
(Some(booted), Some(rollback)) => rollback.index() < booted.index(),
|
||||
_ => false,
|
||||
};
|
||||
```
|
||||
|
||||
**Purpose**: Determine rollback deployment and queued status
|
||||
**Process**: Check deployment order and indices
|
||||
|
||||
## Boot Order Management
|
||||
|
||||
### 1. Boot Order States
|
||||
|
||||
```rust
|
||||
let boot_order = if rollback_queued {
|
||||
BootOrder::Rollback
|
||||
} else {
|
||||
BootOrder::Default
|
||||
};
|
||||
```
|
||||
|
||||
**States**:
|
||||
- **Default**: Current deployment first, rollback second
|
||||
- **Rollback**: Rollback deployment first, current second
|
||||
|
||||
### 2. Rollback Queued Detection
|
||||
|
||||
```rust
|
||||
let rollback_queued = match (booted_deployment.as_ref(), rollback.as_ref()) {
|
||||
(Some(booted), Some(rollback)) => rollback.index() < booted.index(),
|
||||
_ => false,
|
||||
};
|
||||
```
|
||||
|
||||
**Purpose**: Determine if rollback is queued for next boot
|
||||
**Process**: Compare deployment indices
|
||||
|
||||
## Image Information Extraction
|
||||
|
||||
### 1. Image Status Creation
|
||||
|
||||
```rust
|
||||
fn create_imagestatus(
|
||||
image: ImageReference,
|
||||
manifest_digest: &Digest,
|
||||
config: &ImageConfiguration,
|
||||
) -> ImageStatus {
|
||||
let labels = labels_of_config(config);
|
||||
let timestamp = labels
|
||||
.and_then(|l| {
|
||||
l.get(oci_spec::image::ANNOTATION_CREATED)
|
||||
.map(|s| s.as_str())
|
||||
})
|
||||
.and_then(|s| chrono::DateTime::parse_from_rfc3339(s).ok())
|
||||
.map(|dt| dt.with_timezone(&chrono::Utc));
|
||||
|
||||
let architecture = config.architecture().unwrap_or("unknown").to_string();
|
||||
|
||||
ImageStatus {
|
||||
image,
|
||||
version: labels.and_then(|l| l.get("version").cloned()),
|
||||
timestamp,
|
||||
image_digest: manifest_digest.to_string(),
|
||||
architecture,
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Extract image metadata and configuration
|
||||
**Process**: Parse OCI image configuration and labels
|
||||
|
||||
### 2. Boot Entry Creation
|
||||
|
||||
```rust
|
||||
fn boot_entry_from_deployment(
|
||||
sysroot: &SysrootLock,
|
||||
deployment: &ostree::Deployment,
|
||||
) -> Result<BootEntry> {
|
||||
let deployment_info = DeploymentInfo {
|
||||
id: deployment.csum().to_string(),
|
||||
osname: deployment.osname().to_string(),
|
||||
checksum: deployment.csum().to_string(),
|
||||
};
|
||||
|
||||
let image = if let Ok(origin) = deployment.origin() {
|
||||
if let Some(refspec) = origin.optional_string("origin", "refspec")? {
|
||||
if let Ok(ostree_ref) = ostree::parse_refspec(&refspec) {
|
||||
if let Ok(image_ref) = ostree_container::OstreeImageReference::try_from(ostree_ref) {
|
||||
let image_ref = ImageReference::from(image_ref);
|
||||
let repo = &sysroot.repo();
|
||||
let imgstate = ostree_container::store::query_image_commit(repo, &deployment.csum())?;
|
||||
let cached = imgstate.cached_update
|
||||
.map(|cached| create_imagestatus(image_ref, &cached.manifest_digest, &cached.config));
|
||||
cached
|
||||
} else {
|
||||
None
|
||||
}
|
||||
} else {
|
||||
None
|
||||
}
|
||||
} else {
|
||||
None
|
||||
}
|
||||
} else {
|
||||
None
|
||||
};
|
||||
|
||||
Ok(BootEntry {
|
||||
deployment: deployment_info,
|
||||
image,
|
||||
})
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Create boot entry from OSTree deployment
|
||||
**Process**: Extract deployment info and image metadata
|
||||
|
||||
## Format Detection
|
||||
|
||||
### 1. Automatic Format Selection
|
||||
|
||||
```rust
|
||||
let legacy_opt = if opts.json {
|
||||
OutputFormat::Json
|
||||
} else if std::io::stdout().is_terminal() {
|
||||
OutputFormat::HumanReadable
|
||||
} else {
|
||||
OutputFormat::Yaml
|
||||
};
|
||||
```
|
||||
|
||||
**Logic**:
|
||||
- **JSON**: If `--json` flag specified
|
||||
- **Human Readable**: If output is a terminal
|
||||
- **YAML**: If output is not a terminal
|
||||
|
||||
### 2. Format Version Support
|
||||
|
||||
```rust
|
||||
match opts.format_version.unwrap_or_default() {
|
||||
0 | 1 => {} // Both 0 and 1 mean "v1"
|
||||
o => anyhow::bail!("Unsupported format version: {o}"),
|
||||
};
|
||||
```
|
||||
|
||||
**Purpose**: Support multiple format versions
|
||||
**Current**: Version 1 (exposed as both 0 and 1)
|
||||
|
||||
## Filtering Options
|
||||
|
||||
### 1. Booted Deployment Filter
|
||||
|
||||
```rust
|
||||
if opts.booted {
|
||||
host.filter_to_slot(Slot::Booted);
|
||||
}
|
||||
```
|
||||
|
||||
**Purpose**: Show only booted deployment information
|
||||
**Use Case**: Focus on current deployment
|
||||
|
||||
### 2. Verbose Output
|
||||
|
||||
```rust
|
||||
human_readable_output(&mut out, &host, opts.verbose)
|
||||
```
|
||||
|
||||
**Purpose**: Include additional fields in human readable format
|
||||
**Use Case**: Detailed troubleshooting information
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. OSTree Boot Detection Errors
|
||||
|
||||
```rust
|
||||
if !ostree_booted()? {
|
||||
Default::default()
|
||||
}
|
||||
```
|
||||
|
||||
**Error**: System not booted via OSTree
|
||||
**Response**: Return default empty status
|
||||
|
||||
### 2. Deployment Access Errors
|
||||
|
||||
```rust
|
||||
let (_deployments, host) = get_status(&ostree, booted_deployment.as_ref())?;
|
||||
```
|
||||
|
||||
**Error**: Cannot access deployments
|
||||
**Response**: Propagate error up the call stack
|
||||
|
||||
### 3. Format Version Errors
|
||||
|
||||
```rust
|
||||
match opts.format_version.unwrap_or_default() {
|
||||
0 | 1 => {}
|
||||
o => anyhow::bail!("Unsupported format version: {o}"),
|
||||
};
|
||||
```
|
||||
|
||||
**Error**: Unsupported format version
|
||||
**Response**: Return error with message
|
||||
|
||||
## Usage Patterns
|
||||
|
||||
### 1. Interactive Use
|
||||
|
||||
```bash
|
||||
# Check system status
|
||||
bootc status
|
||||
|
||||
# Check with verbose output
|
||||
bootc status --verbose
|
||||
|
||||
# Check only booted deployment
|
||||
bootc status --booted
|
||||
```
|
||||
|
||||
### 2. Programmatic Use
|
||||
|
||||
```bash
|
||||
# Get JSON output for parsing
|
||||
bootc status --format=json
|
||||
|
||||
# Get YAML output for parsing
|
||||
bootc status --format=yaml
|
||||
|
||||
# Check if system is bootc compatible
|
||||
bootc status --format=json | jq '.status.booted != null'
|
||||
```
|
||||
|
||||
### 3. Automation Scripts
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# Check if rollback is queued
|
||||
if bootc status --format=json | jq -r '.status.rollbackQueued' | grep -q true; then
|
||||
echo "Rollback is queued for next boot"
|
||||
fi
|
||||
|
||||
# Get current image version
|
||||
CURRENT_VERSION=$(bootc status --format=json | jq -r '.status.booted.image.version // "unknown"')
|
||||
echo "Current version: $CURRENT_VERSION"
|
||||
```
|
||||
|
||||
## Integration with Other Commands
|
||||
|
||||
### 1. Relationship to bootc upgrade
|
||||
|
||||
**Status Before Upgrade**:
|
||||
```bash
|
||||
bootc status
|
||||
bootc upgrade --apply
|
||||
bootc status
|
||||
```
|
||||
|
||||
**Status After Upgrade**:
|
||||
- Shows new staged deployment
|
||||
- Shows updated booted deployment
|
||||
- Shows previous deployment as rollback
|
||||
|
||||
### 2. Relationship to bootc switch
|
||||
|
||||
**Status Before Switch**:
|
||||
```bash
|
||||
bootc status
|
||||
bootc switch quay.io/myorg/debian-bootc:v2.0
|
||||
bootc status
|
||||
```
|
||||
|
||||
**Status After Switch**:
|
||||
- Shows new image reference
|
||||
- Shows staged deployment
|
||||
- Shows updated boot order
|
||||
|
||||
### 3. Relationship to bootc rollback
|
||||
|
||||
**Status Before Rollback**:
|
||||
```bash
|
||||
bootc status
|
||||
bootc rollback
|
||||
bootc status
|
||||
```
|
||||
|
||||
**Status After Rollback**:
|
||||
- Shows rollback queued status
|
||||
- Shows updated boot order
|
||||
- Shows deployment reordering
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### System Not Bootc Compatible
|
||||
```bash
|
||||
# Check if system is bootc compatible
|
||||
bootc status --format=json | jq '.status.booted != null'
|
||||
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
#### No Deployments Found
|
||||
```bash
|
||||
# Check deployment status
|
||||
ostree admin status
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
```
|
||||
|
||||
#### Format Parsing Errors
|
||||
```bash
|
||||
# Use specific format
|
||||
bootc status --format=json
|
||||
|
||||
# Check format version
|
||||
bootc status --format-version=1
|
||||
```
|
||||
|
||||
### 2. Debug Commands
|
||||
|
||||
```bash
|
||||
# Enable debug logging
|
||||
RUST_LOG=debug bootc status
|
||||
|
||||
# Check system logs
|
||||
journalctl -u bootc-fetch-apply-updates.service
|
||||
|
||||
# Check OSTree status
|
||||
ostree admin status --verbose
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Programmatic Usage
|
||||
|
||||
- **Use JSON/YAML**: For programmatic parsing
|
||||
- **Check Format Version**: Specify format version explicitly
|
||||
- **Handle Errors**: Check for null values and errors
|
||||
- **Validate Output**: Verify expected fields exist
|
||||
|
||||
### 2. Interactive Usage
|
||||
|
||||
- **Use Human Readable**: For interactive use
|
||||
- **Use Verbose**: For detailed information
|
||||
- **Check Booted**: Focus on current deployment
|
||||
- **Monitor Changes**: Track status over time
|
||||
|
||||
### 3. Automation
|
||||
|
||||
- **Parse JSON**: Use `jq` for JSON parsing
|
||||
- **Check Compatibility**: Verify bootc compatibility
|
||||
- **Monitor Status**: Track deployment changes
|
||||
- **Handle Errors**: Implement proper error handling
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
|
||||
- **Additional Formats**: Support for more output formats
|
||||
- **Filtering Options**: More granular filtering
|
||||
- **Status History**: Track status changes over time
|
||||
- **Health Checks**: Include system health information
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
- **API Support**: REST API for status queries
|
||||
- **Web Interface**: Web-based status display
|
||||
- **Monitoring Integration**: Integration with monitoring systems
|
||||
- **Alerting**: Status-based alerting
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc status system's architecture, implementation, and usage patterns.
|
||||
Loading…
Add table
Add a link
Reference in a new issue