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
870
usr-overlay/bootc-usr-overlay-external-commands.md
Normal file
870
usr-overlay/bootc-usr-overlay-external-commands.md
Normal file
|
|
@ -0,0 +1,870 @@
|
|||
# bootc usr-overlay - 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 usr-overlay` system. Understanding these external dependencies is crucial for troubleshooting, monitoring, and integrating bootc usr-overlay into larger systems.
|
||||
|
||||
## Core System Commands
|
||||
|
||||
### 1. bootc Commands
|
||||
|
||||
#### bootc usr-overlay
|
||||
**Purpose**: Add transient writable overlayfs on /usr
|
||||
**Usage**: `bootc usr-overlay [OPTIONS...]`
|
||||
**External Dependencies**:
|
||||
- `ostree` - For deployment unlocking
|
||||
- `mount` - For overlay filesystem operations
|
||||
- `umount` - For overlay unmounting
|
||||
|
||||
```bash
|
||||
# Add transient writable overlay on /usr
|
||||
bootc usr-overlay
|
||||
|
||||
# Alternative command name
|
||||
bootc usroverlay
|
||||
```
|
||||
|
||||
#### bootc status
|
||||
**Purpose**: Check system status and deployment information
|
||||
**Usage**: `bootc status [OPTIONS...]`
|
||||
**Integration**: Used to check system state before/after overlay
|
||||
|
||||
```bash
|
||||
# Check system status before overlay
|
||||
bootc status
|
||||
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Check system status after overlay
|
||||
bootc status
|
||||
```
|
||||
|
||||
### 2. OSTree Commands
|
||||
|
||||
#### ostree admin unlock
|
||||
**Purpose**: Unlock OSTree deployment for modifications
|
||||
**Usage**: `ostree admin unlock [OPTIONS...]`
|
||||
**Integration**: Core command used by bootc usr-overlay
|
||||
|
||||
```bash
|
||||
# Unlock current deployment
|
||||
ostree admin unlock
|
||||
|
||||
# Unlock with verbose output
|
||||
ostree admin unlock --verbose
|
||||
|
||||
# Check unlock status
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
#### ostree admin status
|
||||
**Purpose**: Check OSTree deployment status
|
||||
**Usage**: `ostree admin status [OPTIONS...]`
|
||||
**Integration**: Used to verify deployment state
|
||||
|
||||
```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 lock
|
||||
**Purpose**: Lock OSTree deployment
|
||||
**Usage**: `ostree admin lock [OPTIONS...]`
|
||||
**Integration**: Used to restore read-only state
|
||||
|
||||
```bash
|
||||
# Lock current deployment
|
||||
ostree admin lock
|
||||
|
||||
# Lock with verbose output
|
||||
ostree admin lock --verbose
|
||||
```
|
||||
|
||||
### 3. Filesystem Commands
|
||||
|
||||
#### mount
|
||||
**Purpose**: Mount filesystems
|
||||
**Usage**: `mount [OPTIONS...] [DEVICE] [DIRECTORY]`
|
||||
**Integration**: Used for overlay filesystem operations
|
||||
|
||||
```bash
|
||||
# List all mounts
|
||||
mount
|
||||
|
||||
# List mounts for specific directory
|
||||
mount | grep /usr
|
||||
|
||||
# Mount overlay filesystem
|
||||
mount -t overlay overlay -o lowerdir=/usr,upperdir=/tmp/upper,workdir=/tmp/work /usr
|
||||
```
|
||||
|
||||
#### umount
|
||||
**Purpose**: Unmount filesystems
|
||||
**Usage**: `umount [OPTIONS...] [DIRECTORY]`
|
||||
**Integration**: Used for unmounting overlay
|
||||
|
||||
```bash
|
||||
# Unmount /usr
|
||||
umount /usr
|
||||
|
||||
# Lazy unmount /usr
|
||||
umount -l /usr
|
||||
|
||||
# Force unmount /usr
|
||||
umount -f /usr
|
||||
```
|
||||
|
||||
#### mountpoint
|
||||
**Purpose**: Check if directory is mount point
|
||||
**Usage**: `mountpoint [OPTIONS...] [DIRECTORY]`
|
||||
**Integration**: Used to verify mount status
|
||||
|
||||
```bash
|
||||
# Check if /usr is mount point
|
||||
mountpoint /usr
|
||||
|
||||
# Check with verbose output
|
||||
mountpoint -v /usr
|
||||
```
|
||||
|
||||
## Package Manager Commands
|
||||
|
||||
### 1. APT Commands (Debian/Ubuntu)
|
||||
|
||||
#### apt
|
||||
**Purpose**: Advanced Package Tool
|
||||
**Usage**: `apt [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Used for package installation in overlay
|
||||
|
||||
```bash
|
||||
# Update package lists
|
||||
apt update
|
||||
|
||||
# Install packages
|
||||
apt install -y package-name
|
||||
|
||||
# Install multiple packages
|
||||
apt install -y strace gdb valgrind
|
||||
|
||||
# Search packages
|
||||
apt search package-name
|
||||
|
||||
# Show package information
|
||||
apt show package-name
|
||||
```
|
||||
|
||||
#### apt-get
|
||||
**Purpose**: APT package handling utility
|
||||
**Usage**: `apt-get [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Alternative to apt command
|
||||
|
||||
```bash
|
||||
# Update package lists
|
||||
apt-get update
|
||||
|
||||
# Install packages
|
||||
apt-get install -y package-name
|
||||
|
||||
# Remove packages
|
||||
apt-get remove package-name
|
||||
|
||||
# Clean package cache
|
||||
apt-get clean
|
||||
```
|
||||
|
||||
#### dpkg
|
||||
**Purpose**: Debian package manager
|
||||
**Usage**: `dpkg [OPTIONS...] [PACKAGE...]`
|
||||
**Integration**: Low-level package operations
|
||||
|
||||
```bash
|
||||
# Install package
|
||||
dpkg -i package.deb
|
||||
|
||||
# List installed packages
|
||||
dpkg -l
|
||||
|
||||
# Show package information
|
||||
dpkg -s package-name
|
||||
|
||||
# Check package status
|
||||
dpkg -l | grep package-name
|
||||
```
|
||||
|
||||
### 2. DNF Commands (Fedora/RHEL)
|
||||
|
||||
#### dnf
|
||||
**Purpose**: Dandified YUM
|
||||
**Usage**: `dnf [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Used for package installation in overlay
|
||||
|
||||
```bash
|
||||
# Update package lists
|
||||
dnf check-update
|
||||
|
||||
# Install packages
|
||||
dnf install -y package-name
|
||||
|
||||
# Install multiple packages
|
||||
dnf install -y strace gdb valgrind
|
||||
|
||||
# Search packages
|
||||
dnf search package-name
|
||||
|
||||
# Show package information
|
||||
dnf info package-name
|
||||
```
|
||||
|
||||
#### yum
|
||||
**Purpose**: Yellowdog Updater Modified
|
||||
**Usage**: `yum [COMMAND] [OPTIONS...]`
|
||||
**Integration**: Alternative to dnf command
|
||||
|
||||
```bash
|
||||
# Update package lists
|
||||
yum check-update
|
||||
|
||||
# Install packages
|
||||
yum install -y package-name
|
||||
|
||||
# Remove packages
|
||||
yum remove package-name
|
||||
|
||||
# Clean package cache
|
||||
yum clean all
|
||||
```
|
||||
|
||||
#### rpm
|
||||
**Purpose**: RPM Package Manager
|
||||
**Usage**: `rpm [OPTIONS...] [PACKAGE...]`
|
||||
**Integration**: Low-level package operations
|
||||
|
||||
```bash
|
||||
# Install package
|
||||
rpm -i package.rpm
|
||||
|
||||
# List installed packages
|
||||
rpm -qa
|
||||
|
||||
# Show package information
|
||||
rpm -qi package-name
|
||||
|
||||
# Check package status
|
||||
rpm -q package-name
|
||||
```
|
||||
|
||||
## System Monitoring Commands
|
||||
|
||||
### 1. Process Monitoring
|
||||
|
||||
#### lsof
|
||||
**Purpose**: List open files
|
||||
**Usage**: `lsof [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used to check processes using /usr
|
||||
|
||||
```bash
|
||||
# List processes using /usr
|
||||
lsof /usr
|
||||
|
||||
# List processes using specific file
|
||||
lsof /usr/bin/package
|
||||
|
||||
# List all open files
|
||||
lsof
|
||||
|
||||
# List files for specific process
|
||||
lsof -p PID
|
||||
```
|
||||
|
||||
#### ps
|
||||
**Purpose**: Display running processes
|
||||
**Usage**: `ps [OPTIONS...]`
|
||||
**Integration**: Used for process monitoring
|
||||
|
||||
```bash
|
||||
# Display all processes
|
||||
ps aux
|
||||
|
||||
# Display processes using /usr
|
||||
ps aux | grep /usr
|
||||
|
||||
# Display process tree
|
||||
ps auxf
|
||||
```
|
||||
|
||||
#### pgrep
|
||||
**Purpose**: Find processes by name
|
||||
**Usage**: `pgrep [OPTIONS...] PATTERN`
|
||||
**Integration**: Used for process identification
|
||||
|
||||
```bash
|
||||
# Find processes by name
|
||||
pgrep package-name
|
||||
|
||||
# Find processes with full command line
|
||||
pgrep -f package-name
|
||||
|
||||
# Find processes using /usr
|
||||
pgrep -f /usr
|
||||
```
|
||||
|
||||
### 2. Filesystem Monitoring
|
||||
|
||||
#### df
|
||||
**Purpose**: Display filesystem disk space usage
|
||||
**Usage**: `df [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for disk space monitoring
|
||||
|
||||
```bash
|
||||
# Check disk usage
|
||||
df -h
|
||||
|
||||
# Check /usr usage
|
||||
df -h /usr
|
||||
|
||||
# Check inode usage
|
||||
df -i /usr
|
||||
```
|
||||
|
||||
#### du
|
||||
**Purpose**: Display directory space usage
|
||||
**Usage**: `du [OPTIONS...] [FILE...]`
|
||||
**Integration**: Used for directory space analysis
|
||||
|
||||
```bash
|
||||
# Check /usr usage
|
||||
du -sh /usr
|
||||
|
||||
# Check overlay usage
|
||||
du -sh /tmp/upper
|
||||
|
||||
# Check work directory usage
|
||||
du -sh /tmp/work
|
||||
```
|
||||
|
||||
#### find
|
||||
**Purpose**: Search for files
|
||||
**Usage**: `find [PATH...] [EXPRESSION...]`
|
||||
**Integration**: Used for finding files in overlay
|
||||
|
||||
```bash
|
||||
# Find files in /usr
|
||||
find /usr -name "package-name"
|
||||
|
||||
# Find recently modified files
|
||||
find /usr -mtime -1
|
||||
|
||||
# Find files by size
|
||||
find /usr -size +100M
|
||||
```
|
||||
|
||||
## System Information Commands
|
||||
|
||||
### 1. System Status
|
||||
|
||||
#### 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
|
||||
```
|
||||
|
||||
## 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 /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
|
||||
```
|
||||
|
||||
## 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/
|
||||
```
|
||||
|
||||
## 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. I/O Monitoring
|
||||
|
||||
#### iostat
|
||||
**Purpose**: Display I/O statistics
|
||||
**Usage**: `iostat [OPTIONS...] [INTERVAL] [COUNT]`
|
||||
**Integration**: Used for I/O performance monitoring
|
||||
|
||||
```bash
|
||||
# Display I/O statistics
|
||||
iostat
|
||||
|
||||
# Display with interval
|
||||
iostat 1 5
|
||||
|
||||
# Display specific devices
|
||||
iostat -x /dev/sda
|
||||
```
|
||||
|
||||
#### iotop
|
||||
**Purpose**: Display I/O usage by process
|
||||
**Usage**: `iotop [OPTIONS...]`
|
||||
**Integration**: Used for I/O process monitoring
|
||||
|
||||
```bash
|
||||
# Display I/O usage
|
||||
iotop
|
||||
|
||||
# Display only processes doing I/O
|
||||
iotop -o
|
||||
|
||||
# Display with batch mode
|
||||
iotop -b
|
||||
```
|
||||
|
||||
## 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 overlay is active
|
||||
if mount | grep -q overlay; then
|
||||
echo "Overlay is active"
|
||||
else
|
||||
echo "Overlay is not active"
|
||||
fi
|
||||
```
|
||||
|
||||
#### sh
|
||||
**Purpose**: POSIX shell
|
||||
**Usage**: `sh [OPTIONS...] [FILE]`
|
||||
**Integration**: Used for portable scripts
|
||||
|
||||
```bash
|
||||
#!/bin/sh
|
||||
# Check if /usr is writable
|
||||
if touch /usr/test-file 2>/dev/null; then
|
||||
echo "/usr is writable"
|
||||
rm -f /usr/test-file
|
||||
else
|
||||
echo "/usr is read-only"
|
||||
fi
|
||||
```
|
||||
|
||||
### 2. Process Control
|
||||
|
||||
#### pkill
|
||||
**Purpose**: Kill processes by name
|
||||
**Usage**: `pkill [OPTIONS...] PATTERN`
|
||||
**Integration**: Used for process termination
|
||||
|
||||
```bash
|
||||
# Kill processes by name
|
||||
pkill package-name
|
||||
|
||||
# Kill with signal
|
||||
pkill -9 package-name
|
||||
|
||||
# Kill with specific user
|
||||
pkill -u root package-name
|
||||
```
|
||||
|
||||
#### kill
|
||||
**Purpose**: Send signal to process
|
||||
**Usage**: `kill [OPTIONS...] PID`
|
||||
**Integration**: Used for process control
|
||||
|
||||
```bash
|
||||
# Send TERM signal
|
||||
kill 1234
|
||||
|
||||
# Send KILL signal
|
||||
kill -9 1234
|
||||
|
||||
# Send HUP signal
|
||||
kill -HUP 1234
|
||||
```
|
||||
|
||||
## 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 usr-overlay system.
|
||||
421
usr-overlay/bootc-usr-overlay-flowchart.md
Normal file
421
usr-overlay/bootc-usr-overlay-flowchart.md
Normal file
|
|
@ -0,0 +1,421 @@
|
|||
# bootc usr-overlay - Process Flowchart
|
||||
|
||||
## Overview
|
||||
|
||||
This document provides a visual representation of the `bootc usr-overlay` process flow, showing the decision points, operations, and filesystem changes involved in creating a transient writable overlay on the `/usr` directory.
|
||||
|
||||
## Main Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ bootc usr-overlay │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Validate Prerequisites │
|
||||
│ │
|
||||
│ • Check if running as root or with appropriate privileges │
|
||||
│ • Verify OSTree is available and accessible │
|
||||
│ • Check if system is bootc-compatible │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Current State │
|
||||
│ │
|
||||
│ • Check if /usr is currently read-only │
|
||||
│ • Verify OSTree deployment status │
|
||||
│ • Check if overlay is already active │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Execute OSTree Unlock │
|
||||
│ │
|
||||
│ • Call `ostree admin unlock` command │
|
||||
│ • Create overlay filesystem on /usr │
|
||||
│ • Make /usr directory writable │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Overlay Creation │
|
||||
│ │
|
||||
│ • Check if overlay filesystem is mounted │
|
||||
│ • Verify /usr is now writable │
|
||||
│ • Confirm overlay structure is correct │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Provide User Feedback │
|
||||
│ │
|
||||
│ • Display success message │
|
||||
│ • Inform user about overlay status │
|
||||
│ • Provide usage instructions │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Transient overlay active on /usr │
|
||||
│ • /usr directory is now writable │
|
||||
│ • Changes will be discarded on reboot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## OSTree Unlock Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ OSTree Admin Unlock │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Deployment Status │
|
||||
│ │
|
||||
│ • Get current OSTree deployment │
|
||||
│ • Check if deployment is locked │
|
||||
│ • Verify deployment is bootable │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Create Overlay Filesystem │
|
||||
│ │
|
||||
│ • Set up overlay filesystem structure │
|
||||
│ • Create lower layer (original /usr) │
|
||||
│ • Create upper layer (writable overlay) │
|
||||
│ • Create work directory (temporary files) │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Mount Overlay on /usr │
|
||||
│ │
|
||||
│ • Mount overlay filesystem on /usr │
|
||||
│ • Set up copy-on-write mechanism │
|
||||
│ • Enable write operations on /usr │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Update OSTree State │
|
||||
│ │
|
||||
│ • Mark deployment as unlocked │
|
||||
│ • Update deployment metadata │
|
||||
│ • Set up auto-lock on reboot │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Overlay filesystem active │
|
||||
│ • /usr directory writable │
|
||||
│ • Changes will be transient │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Overlay Filesystem Structure
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Overlay Filesystem Structure │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ /usr (Mount Point) │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Overlay Mount │ │
|
||||
│ │ │ │
|
||||
│ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────┐ │ │
|
||||
│ │ │ Lower Layer │ │ Upper Layer │ │ Work Layer │ │ │
|
||||
│ │ │ │ │ │ │ │ │ │
|
||||
│ │ │ • Original /usr │ │ • Writable │ │ • Temporary │ │ │
|
||||
│ │ │ • Read-only │ │ • Changes │ │ • COW files │ │ │
|
||||
│ │ │ • Base system │ │ • New files │ │ • Metadata │ │ │
|
||||
│ │ │ • Immutable │ │ • Modifications │ │ • Operations│ │ │
|
||||
│ │ └─────────────────┘ └─────────────────┘ └─────────────┘ │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Package Installation Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Package Installation │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Overlay Status │
|
||||
│ │
|
||||
│ • Verify /usr is writable │
|
||||
│ • Check overlay filesystem is active │
|
||||
│ • Confirm package manager can operate │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Package Manager Operation │
|
||||
│ │
|
||||
│ • Update package lists (apt update, dnf check-update) │
|
||||
│ • Download package files │
|
||||
│ • Install packages to overlay │
|
||||
│ • Update package database │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Overlay Write Operations │
|
||||
│ │
|
||||
│ • Files written to upper layer │
|
||||
│ • Copy-on-write for modified files │
|
||||
│ • Metadata updated in overlay │
|
||||
│ • Original files preserved in lower layer │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Installation │
|
||||
│ │
|
||||
│ • Check if packages are accessible │
|
||||
│ │ • Verify files are in overlay │
|
||||
│ │ • Test package functionality │
|
||||
│ │ • Confirm changes are transient │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Unmounting Process Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Unmounting Overlay │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Check Active Processes │
|
||||
│ │
|
||||
│ • Identify processes using /usr files │
|
||||
│ • Check for open file handles │
|
||||
│ • Determine if unmount is safe │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Choose Unmount Method │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Can unmount safely? │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ Yes │ │ No │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
||||
│ │ │ Regular ││ │ │ Lazy Unmount ││ │
|
||||
│ │ │ Unmount ││ │ │ ││ │
|
||||
│ │ │ • umount ││ │ │ • umount -l /usr ││ │
|
||||
│ │ │ /usr ││ │ │ • Unmount when references ││ │
|
||||
│ │ │ • Immediate ││ │ │ released ││ │
|
||||
│ │ │ unmount ││ │ │ • Safer for active processes ││ │
|
||||
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Clean Up Overlay │
|
||||
│ │
|
||||
│ • Remove overlay filesystem │
|
||||
│ • Clean up work directory │
|
||||
│ • Restore original /usr state │
|
||||
│ • Update OSTree deployment status │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Verify Unmount │
|
||||
│ │
|
||||
│ • Check /usr is no longer writable │
|
||||
│ • Verify overlay is removed │
|
||||
│ • Confirm original state restored │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Success │
|
||||
│ │
|
||||
│ • Overlay successfully removed │
|
||||
│ • /usr returned to read-only state │
|
||||
│ • All changes discarded │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Error Handling Flow
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Detection │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Classification │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
||||
│ │ Permission │ │ OSTree │ │ System │ │
|
||||
│ │ Errors │ │ Errors │ │ Errors │ │
|
||||
│ │ │ │ │ │ │ │
|
||||
│ │ • Not root │ │ • OSTree not │ │ • /usr already │ │
|
||||
│ │ • Permission │ │ available │ │ writable │ │
|
||||
│ │ denied │ │ • Deployment │ │ • Overlay │ │
|
||||
│ │ • Insufficient │ │ locked │ │ already │ │
|
||||
│ │ privileges │ │ • Command │ │ active │ │
|
||||
│ │ │ │ failed │ │ • Mount │ │
|
||||
│ │ │ │ │ │ failed │ │
|
||||
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Error Response │
|
||||
│ │
|
||||
│ • Display error message │
|
||||
│ • Provide context information │
|
||||
│ • Suggest remediation steps │
|
||||
│ • Return appropriate exit code │
|
||||
│ • Clean up any partial state │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## State Transitions
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ System States │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Initial State │
|
||||
│ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ /usr Read-only State │ │
|
||||
│ │ │ │
|
||||
│ │ • /usr mounted read-only │ │
|
||||
│ │ • OSTree deployment locked │ │
|
||||
│ │ • No overlay filesystem │ │
|
||||
│ │ • Immutable system state │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ bootc usr-overlay │ │
|
||||
│ │ │ │
|
||||
│ │ • Call ostree admin unlock │ │
|
||||
│ │ • Create overlay filesystem │ │
|
||||
│ │ • Mount overlay on /usr │ │
|
||||
│ │ • Enable write operations │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ /usr Writable State │ │
|
||||
│ │ │ │
|
||||
│ │ • /usr mounted with overlay │ │
|
||||
│ │ • OSTree deployment unlocked │ │
|
||||
│ │ • Overlay filesystem active │ │
|
||||
│ │ • Writable system state │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Package Operations │ │
|
||||
│ │ │ │
|
||||
│ │ • Install packages to overlay │ │
|
||||
│ │ • Modify files in overlay │ │
|
||||
│ │ • Use installed tools │ │
|
||||
│ │ • Changes are transient │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ Reboot or Unmount │ │
|
||||
│ │ │ │
|
||||
│ │ • Reboot: Auto-restore to read-only │ │
|
||||
│ │ • Unmount: Manual restore to read-only │ │
|
||||
│ │ • All changes discarded │ │
|
||||
│ │ • Return to initial state │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
## Filesystem Impact
|
||||
|
||||
```
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Filesystem Impact │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ Before Overlay │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ /usr │ │ /etc │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • Read-only │ │ • Writable │ │
|
||||
│ │ • Immutable │ │ • Persistent │ │
|
||||
│ │ • Base system │ │ • Configuration │ │
|
||||
│ │ • OSTree │ │ • Not affected by overlay │ │
|
||||
│ │ managed │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ /var │ │
|
||||
│ │ │ │
|
||||
│ │ • Writable │ │
|
||||
│ │ • Persistent │ │
|
||||
│ │ • Runtime data │ │
|
||||
│ │ • Not affected by overlay │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
│
|
||||
▼
|
||||
┌─────────────────────────────────────────────────────────────────┐
|
||||
│ After Overlay │
|
||||
│ │
|
||||
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
||||
│ │ /usr │ │ /etc │ │
|
||||
│ │ │ │ │ │
|
||||
│ │ • Writable │ │ • Writable │ │
|
||||
│ │ • Overlay │ │ • Persistent │ │
|
||||
│ │ • Transient │ │ • Configuration │ │
|
||||
│ │ • Changes │ │ • Not affected by overlay │ │
|
||||
│ │ discarded │ │ │ │
|
||||
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
||||
│ │ │
|
||||
│ ▼ │
|
||||
│ ┌─────────────────────────────────────────────────────────────┐ │
|
||||
│ │ /var │ │
|
||||
│ │ │ │
|
||||
│ │ • Writable │ │
|
||||
│ │ • Persistent │ │
|
||||
│ │ • Runtime data │ │
|
||||
│ │ • Not affected by overlay │ │
|
||||
│ └─────────────────────────────────────────────────────────────┘ │
|
||||
└─────────────────────────────────────────────────────────────────┘
|
||||
```
|
||||
|
||||
This flowchart provides a comprehensive visual representation of the bootc usr-overlay process, showing all decision points, operations, and filesystem changes involved in creating and managing a transient writable overlay on the `/usr` directory.
|
||||
628
usr-overlay/bootc-usr-overlay-technical-guide.md
Normal file
628
usr-overlay/bootc-usr-overlay-technical-guide.md
Normal file
|
|
@ -0,0 +1,628 @@
|
|||
# bootc usr-overlay - Technical Guide
|
||||
|
||||
## Overview
|
||||
|
||||
`bootc usr-overlay` is a command for adding a transient writable overlay filesystem on the `/usr` directory. This overlay allows temporary modifications to the `/usr` directory that will be discarded on reboot, enabling package installation and system modifications while maintaining the integrity of the base system.
|
||||
|
||||
## Purpose
|
||||
|
||||
The usr-overlay command serves several critical functions:
|
||||
|
||||
1. **Temporary Package Installation**: Install packages that aren't in the base image
|
||||
2. **Debugging Tools**: Install tracing and debugging tools like `strace`
|
||||
3. **System Modifications**: Make temporary changes to `/usr` without persistence
|
||||
4. **Development Workflows**: Enable development and testing workflows
|
||||
5. **System Maintenance**: Allow maintenance operations without permanent changes
|
||||
|
||||
## Command Syntax
|
||||
|
||||
```bash
|
||||
bootc usr-overlay [OPTIONS...]
|
||||
```
|
||||
|
||||
### Basic Usage
|
||||
|
||||
```bash
|
||||
# Add transient writable overlay on /usr
|
||||
bootc usr-overlay
|
||||
|
||||
# Alternative command name
|
||||
bootc usroverlay
|
||||
```
|
||||
|
||||
## Command Options
|
||||
|
||||
Currently, `bootc usr-overlay` has no command-line options. It's a simple command that either succeeds or fails.
|
||||
|
||||
## Architecture Overview
|
||||
|
||||
### 1. Implementation Structure
|
||||
|
||||
```rust
|
||||
/// Implementation of `bootc usroverlay`
|
||||
async fn usroverlay() -> Result<()> {
|
||||
// This is just a pass-through today. At some point we may make this a libostree API
|
||||
// or even oxidize it.
|
||||
Err(Command::new("ostree")
|
||||
.args(["admin", "unlock"])
|
||||
.exec()
|
||||
.into())
|
||||
}
|
||||
```
|
||||
|
||||
**Current Implementation**:
|
||||
- **Pass-through Command**: Currently delegates to `ostree admin unlock`
|
||||
- **Future Plans**: May become a native libostree API or Rust implementation
|
||||
- **Simple Interface**: No complex options or configuration
|
||||
|
||||
### 2. OSTree Integration
|
||||
|
||||
The command currently uses `ostree admin unlock` which:
|
||||
- **Unlocks the OSTree deployment**: Makes `/usr` writable
|
||||
- **Creates Overlay**: Sets up a transient overlay filesystem
|
||||
- **Preserves Base**: Keeps the original `/usr` intact
|
||||
- **Enables Modifications**: Allows temporary changes
|
||||
|
||||
### 3. Overlay Filesystem Mechanism
|
||||
|
||||
```bash
|
||||
# What happens internally (simplified)
|
||||
ostree admin unlock
|
||||
# This creates an overlay filesystem on /usr
|
||||
# - Lower layer: Original read-only /usr
|
||||
# - Upper layer: Writable overlay
|
||||
# - Work layer: Temporary files during operations
|
||||
```
|
||||
|
||||
## Use Cases
|
||||
|
||||
### 1. Debugging and Tracing Tools
|
||||
|
||||
**Scenario**: Need to install debugging tools not in base image
|
||||
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install debugging tools
|
||||
apt update
|
||||
apt install -y strace gdb valgrind
|
||||
|
||||
# Use tools
|
||||
strace -p 1234
|
||||
gdb /path/to/process
|
||||
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
### 2. Package Manager Operations
|
||||
|
||||
**Scenario**: Install packages temporarily for testing
|
||||
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install packages
|
||||
apt install -y python3-pip
|
||||
pip3 install requests
|
||||
|
||||
# Test application
|
||||
python3 -c "import requests; print('Success')"
|
||||
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
### 3. Development Workflows
|
||||
|
||||
**Scenario**: Development and testing without permanent changes
|
||||
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install development tools
|
||||
apt install -y build-essential git
|
||||
|
||||
# Clone and build project
|
||||
git clone https://github.com/user/project.git
|
||||
cd project
|
||||
make
|
||||
|
||||
# Test and develop
|
||||
./project
|
||||
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
### 4. System Maintenance
|
||||
|
||||
**Scenario**: Temporary system modifications for maintenance
|
||||
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install maintenance tools
|
||||
apt install -y htop iotop nethogs
|
||||
|
||||
# Perform maintenance
|
||||
htop
|
||||
iotop
|
||||
nethogs
|
||||
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
## Filesystem Behavior
|
||||
|
||||
### 1. /usr Directory
|
||||
|
||||
**Before Overlay**:
|
||||
- **Read-only**: `/usr` is mounted read-only
|
||||
- **Immutable**: Cannot be modified
|
||||
- **Base System**: Contains original system files
|
||||
|
||||
**After Overlay**:
|
||||
- **Writable**: `/usr` becomes writable
|
||||
- **Overlay**: Changes go to overlay layer
|
||||
- **Transient**: Changes discarded on reboot
|
||||
|
||||
### 2. /etc and /var Directories
|
||||
|
||||
**Important**: The overlay only affects `/usr`, not `/etc` or `/var`
|
||||
|
||||
**/etc Directory**:
|
||||
- **Persistent**: Changes persist across reboots
|
||||
- **Configuration**: System configuration files
|
||||
- **Not Affected**: Overlay doesn't apply here
|
||||
|
||||
**/var Directory**:
|
||||
- **Persistent**: Changes persist across reboots
|
||||
- **Runtime Data**: Logs, caches, temporary files
|
||||
- **Not Affected**: Overlay doesn't apply here
|
||||
|
||||
### 3. Overlay Structure
|
||||
|
||||
```
|
||||
/usr (overlay mount point)
|
||||
├── lower (original read-only /usr)
|
||||
├── upper (writable overlay layer)
|
||||
└── work (temporary work directory)
|
||||
```
|
||||
|
||||
## OSTree Integration
|
||||
|
||||
### 1. OSTree Admin Unlock
|
||||
|
||||
The command delegates to `ostree admin unlock` which:
|
||||
|
||||
```bash
|
||||
ostree admin unlock
|
||||
```
|
||||
|
||||
**What it does**:
|
||||
- **Unlocks Deployment**: Makes the current deployment writable
|
||||
- **Creates Overlay**: Sets up overlay filesystem
|
||||
- **Preserves Base**: Keeps original content intact
|
||||
- **Enables Changes**: Allows modifications
|
||||
|
||||
### 2. OSTree Deployment State
|
||||
|
||||
**Before Unlock**:
|
||||
- **Read-only**: Deployment is read-only
|
||||
- **Immutable**: Cannot be modified
|
||||
- **Base State**: Original system state
|
||||
|
||||
**After Unlock**:
|
||||
- **Writable**: Deployment becomes writable
|
||||
- **Overlay Active**: Overlay filesystem active
|
||||
- **Changes Allowed**: Modifications possible
|
||||
|
||||
### 3. OSTree Lock Management
|
||||
|
||||
**Lock States**:
|
||||
- **Locked**: Read-only, immutable
|
||||
- **Unlocked**: Writable, overlay active
|
||||
- **Auto-lock**: Locks on reboot
|
||||
|
||||
## Package Manager Integration
|
||||
|
||||
### 1. APT Integration
|
||||
|
||||
**Debian/Ubuntu Systems**:
|
||||
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Update package lists
|
||||
apt update
|
||||
|
||||
# Install packages
|
||||
apt install -y package-name
|
||||
|
||||
# Packages installed to overlay
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
**Package Installation**:
|
||||
- **Overlay Target**: Packages installed to overlay
|
||||
- **Transient**: Changes don't persist
|
||||
- **Base Preserved**: Original system unchanged
|
||||
|
||||
### 2. DNF Integration
|
||||
|
||||
**Fedora/RHEL Systems**:
|
||||
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install packages
|
||||
dnf install -y package-name
|
||||
|
||||
# Packages installed to overlay
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
**Package Installation**:
|
||||
- **Overlay Target**: Packages installed to overlay
|
||||
- **Transient**: Changes don't persist
|
||||
- **Base Preserved**: Original system unchanged
|
||||
|
||||
### 3. Package Manager Detection
|
||||
|
||||
**Recommended Integration**:
|
||||
Package managers should detect overlay state and inform users:
|
||||
|
||||
```bash
|
||||
# Example error message
|
||||
error: read-only /usr detected, refusing to operate.
|
||||
See `man apt-image-based` for more information.
|
||||
```
|
||||
|
||||
**Detection Methods**:
|
||||
- **Read-only Check**: Check if `/usr` is read-only
|
||||
- **Overlay Detection**: Detect overlay filesystem
|
||||
- **Bootc Detection**: Check if system is bootc-managed
|
||||
|
||||
## Unmounting the Overlay
|
||||
|
||||
### 1. Lazy Unmount
|
||||
|
||||
**Standard Unmount**:
|
||||
```bash
|
||||
umount /usr
|
||||
# May fail if processes hold references
|
||||
```
|
||||
|
||||
**Lazy Unmount**:
|
||||
```bash
|
||||
umount -l /usr
|
||||
# Unmounts when references are released
|
||||
```
|
||||
|
||||
### 2. Process References
|
||||
|
||||
**Common Holders**:
|
||||
- **Package Managers**: `apt`, `dnf` processes
|
||||
- **System Services**: Services using `/usr` files
|
||||
- **User Processes**: Applications with open files
|
||||
|
||||
**Solution**:
|
||||
- **Lazy Unmount**: Use `umount -l /usr`
|
||||
- **Process Termination**: Stop processes holding references
|
||||
- **Reboot**: Automatic unmount on reboot
|
||||
|
||||
### 3. Unmount Process
|
||||
|
||||
```bash
|
||||
# Check what's using /usr
|
||||
lsof /usr
|
||||
|
||||
# Lazy unmount
|
||||
umount -l /usr
|
||||
|
||||
# Verify unmount
|
||||
mount | grep /usr
|
||||
```
|
||||
|
||||
## Error Handling
|
||||
|
||||
### 1. Common Errors
|
||||
|
||||
#### OSTree Not Available
|
||||
```bash
|
||||
Error: ostree command not found
|
||||
```
|
||||
|
||||
**Solution**: Install OSTree
|
||||
```bash
|
||||
apt install -y ostree
|
||||
# or
|
||||
dnf install -y ostree
|
||||
```
|
||||
|
||||
#### Permission Denied
|
||||
```bash
|
||||
Error: Permission denied
|
||||
```
|
||||
|
||||
**Solution**: Run with appropriate privileges
|
||||
```bash
|
||||
sudo bootc usr-overlay
|
||||
```
|
||||
|
||||
#### Already Unlocked
|
||||
```bash
|
||||
Error: Deployment already unlocked
|
||||
```
|
||||
|
||||
**Solution**: Check current state
|
||||
```bash
|
||||
ostree admin status
|
||||
```
|
||||
|
||||
### 2. Troubleshooting
|
||||
|
||||
#### Check Overlay Status
|
||||
```bash
|
||||
# Check if overlay is active
|
||||
mount | grep overlay
|
||||
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check /usr mount
|
||||
mount | grep /usr
|
||||
```
|
||||
|
||||
#### Verify Changes
|
||||
```bash
|
||||
# Test if /usr is writable
|
||||
touch /usr/test-file
|
||||
|
||||
# Check if file exists
|
||||
ls -la /usr/test-file
|
||||
|
||||
# File should exist until reboot
|
||||
```
|
||||
|
||||
## Security Considerations
|
||||
|
||||
### 1. Transient Nature
|
||||
|
||||
**Security Benefits**:
|
||||
- **No Persistence**: Changes don't persist
|
||||
- **Base Integrity**: Original system unchanged
|
||||
- **Clean State**: System returns to known state
|
||||
|
||||
**Security Implications**:
|
||||
- **Temporary Access**: Allows temporary modifications
|
||||
- **Package Installation**: Can install arbitrary packages
|
||||
- **System Changes**: Can modify system behavior
|
||||
|
||||
### 2. Access Control
|
||||
|
||||
**Privilege Requirements**:
|
||||
- **Root Access**: Requires root privileges
|
||||
- **OSTree Access**: Needs OSTree admin access
|
||||
- **Mount Privileges**: Requires mount capabilities
|
||||
|
||||
**Best Practices**:
|
||||
- **Minimal Use**: Use only when necessary
|
||||
- **Audit Changes**: Monitor what's installed
|
||||
- **Clean Up**: Unmount when done
|
||||
|
||||
### 3. Overlay Security
|
||||
|
||||
**Overlay Isolation**:
|
||||
- **Separate Layer**: Changes in separate layer
|
||||
- **Base Protection**: Original system protected
|
||||
- **Clean Separation**: Clear boundary between layers
|
||||
|
||||
## Performance Considerations
|
||||
|
||||
### 1. Overlay Overhead
|
||||
|
||||
**Performance Impact**:
|
||||
- **Overlay Layer**: Additional filesystem layer
|
||||
- **Copy-on-Write**: COW operations for modifications
|
||||
- **Metadata Overhead**: Additional metadata for overlay
|
||||
|
||||
**Mitigation**:
|
||||
- **Minimal Changes**: Make only necessary changes
|
||||
- **Unmount When Done**: Remove overlay when not needed
|
||||
- **Efficient Operations**: Use efficient package operations
|
||||
|
||||
### 2. Storage Usage
|
||||
|
||||
**Storage Impact**:
|
||||
- **Overlay Storage**: Additional storage for overlay
|
||||
- **Temporary Files**: Work directory usage
|
||||
- **Package Caches**: Package manager caches
|
||||
|
||||
**Management**:
|
||||
- **Clean Caches**: Clean package caches
|
||||
- **Unmount Overlay**: Remove overlay when done
|
||||
- **Monitor Usage**: Monitor storage usage
|
||||
|
||||
## Integration Patterns
|
||||
|
||||
### 1. Development Workflows
|
||||
|
||||
**Development Setup**:
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install development tools
|
||||
apt install -y build-essential git python3-pip
|
||||
|
||||
# Install project dependencies
|
||||
pip3 install -r requirements.txt
|
||||
|
||||
# Develop and test
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
### 2. Debugging Workflows
|
||||
|
||||
**Debugging Setup**:
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install debugging tools
|
||||
apt install -y strace gdb valgrind
|
||||
|
||||
# Debug application
|
||||
strace -f ./application
|
||||
gdb ./application
|
||||
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
### 3. Testing Workflows
|
||||
|
||||
**Testing Setup**:
|
||||
```bash
|
||||
# Add overlay
|
||||
bootc usr-overlay
|
||||
|
||||
# Install test tools
|
||||
apt install -y test-package
|
||||
|
||||
# Run tests
|
||||
./run-tests.sh
|
||||
|
||||
# Changes discarded on reboot
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### 1. Usage Guidelines
|
||||
|
||||
**When to Use**:
|
||||
- **Debugging**: Install debugging tools
|
||||
- **Development**: Temporary development setup
|
||||
- **Testing**: Test new packages
|
||||
- **Maintenance**: System maintenance tasks
|
||||
|
||||
**When Not to Use**:
|
||||
- **Production**: Avoid in production systems
|
||||
- **Persistent Changes**: Don't use for permanent changes
|
||||
- **System Modifications**: Avoid core system changes
|
||||
|
||||
### 2. Workflow Management
|
||||
|
||||
**Before Overlay**:
|
||||
- **Plan Changes**: Know what you need to install
|
||||
- **Check Dependencies**: Verify package dependencies
|
||||
- **Prepare Commands**: Have commands ready
|
||||
|
||||
**During Overlay**:
|
||||
- **Minimal Changes**: Make only necessary changes
|
||||
- **Document Changes**: Keep track of what's installed
|
||||
- **Test Thoroughly**: Test all functionality
|
||||
|
||||
**After Overlay**:
|
||||
- **Clean Up**: Remove unnecessary packages
|
||||
- **Unmount**: Unmount overlay when done
|
||||
- **Document**: Document what was done
|
||||
|
||||
### 3. System Management
|
||||
|
||||
**Monitoring**:
|
||||
- **Check Status**: Monitor overlay status
|
||||
- **Track Changes**: Keep track of modifications
|
||||
- **Monitor Performance**: Watch for performance impact
|
||||
|
||||
**Maintenance**:
|
||||
- **Regular Cleanup**: Clean up regularly
|
||||
- **Unmount When Done**: Remove overlay when not needed
|
||||
- **Reboot Periodically**: Reboot to clean state
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
### 1. Planned Features
|
||||
|
||||
**Native Implementation**:
|
||||
- **Rust Implementation**: Native Rust implementation
|
||||
- **libostree API**: Direct libostree API usage
|
||||
- **Better Integration**: Improved OSTree integration
|
||||
|
||||
**Enhanced Functionality**:
|
||||
- **Selective Overlay**: Overlay specific directories
|
||||
- **Persistent Overlay**: Option for persistent overlays
|
||||
- **Overlay Management**: Better overlay management
|
||||
|
||||
### 2. Integration Improvements
|
||||
|
||||
**Package Manager Integration**:
|
||||
- **Automatic Detection**: Auto-detect overlay state
|
||||
- **User Warnings**: Warn about transient changes
|
||||
- **Better Error Messages**: Improved error messages
|
||||
|
||||
**System Integration**:
|
||||
- **Service Integration**: Systemd service integration
|
||||
- **Configuration**: Configuration file support
|
||||
- **Logging**: Better logging and monitoring
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### 1. Common Issues
|
||||
|
||||
#### Overlay Not Working
|
||||
```bash
|
||||
# Check if overlay is active
|
||||
mount | grep overlay
|
||||
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check /usr mount
|
||||
mount | grep /usr
|
||||
```
|
||||
|
||||
#### Package Installation Fails
|
||||
```bash
|
||||
# Check if /usr is writable
|
||||
touch /usr/test-file
|
||||
|
||||
# Check package manager status
|
||||
apt update
|
||||
# or
|
||||
dnf check-update
|
||||
```
|
||||
|
||||
#### Cannot Unmount
|
||||
```bash
|
||||
# Check what's using /usr
|
||||
lsof /usr
|
||||
|
||||
# Use lazy unmount
|
||||
umount -l /usr
|
||||
```
|
||||
|
||||
### 2. Debug Commands
|
||||
|
||||
```bash
|
||||
# Check overlay status
|
||||
mount | grep overlay
|
||||
|
||||
# Check OSTree status
|
||||
ostree admin status
|
||||
|
||||
# Check /usr mount
|
||||
mount | grep /usr
|
||||
|
||||
# Check processes using /usr
|
||||
lsof /usr
|
||||
|
||||
# Check overlay filesystem
|
||||
cat /proc/mounts | grep overlay
|
||||
```
|
||||
|
||||
This technical guide provides comprehensive understanding of the bootc usr-overlay system's architecture, implementation, and usage patterns.
|
||||
Loading…
Add table
Add a link
Reference in a new issue