bootc-docs/usr-overlay/bootc-usr-overlay-external-commands.md

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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Display hostname
hostname

# Set hostname
hostname newhostname

whoami

Purpose: Display current user Usage: whoami [OPTIONS...] Integration: Used for user identification

# 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

# Display CPU information
lscpu

# Display in specific format
lscpu --extended

lsblk

Purpose: List block devices Usage: lsblk [OPTIONS...] Integration: Used for storage device identification

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# 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

# Display processes
top

# Display specific process
top -p $(pgrep bootc)

htop

Purpose: Interactive process viewer Usage: htop [OPTIONS...] Integration: Used for system resource monitoring

# Start htop
htop

# Monitor specific process
htop -p $(pgrep bootc)

free

Purpose: Display memory usage Usage: free [OPTIONS...] Integration: Used for memory monitoring

# 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

# 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

# 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

#!/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

#!/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

# 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

# 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

# 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

# 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

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