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