bootc-docs/state/bootc-state-external-commands.md

bootc state - External Commands Reference

Overview

This document provides a comprehensive reference for all external commands used by bootc state operations. These commands are essential for understanding the dependencies and integration points of the bootc state system.

Core Commands

bootc

Purpose: Main bootc command for state operations Usage: bootc state <subcommand> [options...] Dependencies: None (core command)

State Subcommands

• bootc state wipe-ostree - Remove all OSTree deployments
• bootc state help - Show help information

Examples

# Wipe all OSTree deployments
bootc state wipe-ostree

# Show help
bootc state --help
bootc state wipe-ostree --help

OSTree Commands

ostree

Purpose: OSTree repository operations Usage: ostree <subcommand> [options...] Dependencies: ostree package

Repository Commands

• ostree admin status - Show admin status
• ostree log - Show commit log
• ostree show - Show commit details
• ostree refs - List references
• ostree ls - List repository contents
• ostree cat - Show file contents
• ostree checkout - Checkout files
• ostree admin pin - Pin deployments
• ostree admin unpin - Unpin deployments
• ostree admin deploy - Deploy commits
• ostree admin rollback - Rollback deployments
• ostree admin cleanup - Clean up deployments
• ostree fsck - Check repository integrity

Examples

# Show current status
ostree admin status

# List all references
ostree refs

# Show commit details
ostree show <commit-hash>

# List repository contents
ostree ls <commit-hash>

# Show file contents
ostree cat <commit-hash> /path/to/file

# Checkout files
ostree checkout <commit-hash> /path/to/destination

# Deploy commit
ostree admin deploy <commit-hash>

# Rollback deployment
ostree admin rollback

# Clean up deployments
ostree admin cleanup

# Check repository integrity
ostree fsck

ostree-ext

Purpose: Extended OSTree operations Usage: ostree-ext <subcommand> [options...] Dependencies: ostree-ext package

Examples

# Container operations
ostree-ext container pull quay.io/myorg/image:latest

# Repository operations
ostree-ext repo create /path/to/repo

# Image operations
ostree-ext image build /path/to/image

System Commands

systemctl

Purpose: Systemd service management Usage: systemctl <subcommand> [options...] Dependencies: systemd

Service Commands

• systemctl status - Show service status
• systemctl start - Start service
• systemctl stop - Stop service
• systemctl restart - Restart service
• systemctl enable - Enable service
• systemctl disable - Disable service
• systemctl reload - Reload service
• systemctl daemon-reload - Reload systemd configuration

Examples

# Check service status
systemctl status bootc-*

# Start service
systemctl start bootc-*

# Enable service
systemctl enable bootc-*

# Reload systemd configuration
systemctl daemon-reload

journalctl

Purpose: Systemd journal viewing Usage: journalctl [options...] Dependencies: systemd

Examples

# Show all logs
journalctl

# Show logs for service
journalctl -u bootc-*

# Show recent logs
journalctl -n 100

# Follow logs
journalctl -f

# Show logs since time
journalctl --since "1 hour ago"

# Show logs with priority
journalctl -p err

Filesystem Commands

mount

Purpose: Filesystem mounting Usage: mount [options...] <device> <directory> Dependencies: util-linux

Examples

# Mount filesystem
mount /dev/sda1 /mnt

# Unmount filesystem
umount /mnt

# Check mount points
findmnt

# Mount with options
mount -o ro,noexec /dev/sda1 /mnt

umount

Purpose: Unmount filesystems Usage: umount [options...] <directory> Dependencies: util-linux

Examples

# Unmount filesystem
umount /mnt

# Force unmount
umount -f /mnt

# Lazy unmount
umount -l /mnt

df

Purpose: Disk space usage Usage: df [options...] [file...] Dependencies: coreutils

Examples

# Show disk usage
df -h

# Show specific filesystem
df -h /var/lib/bootc

# Show inode usage
df -i

# Show all filesystems
df -a

du

Purpose: Directory space usage Usage: du [options...] [file...] Dependencies: coreutils

Examples

# Show directory usage
du -h /var/lib/bootc

# Show total usage
du -sh /var/lib/bootc

# Show usage by subdirectory
du -h --max-depth=1 /var/lib/bootc

# Show usage of all files
du -ah /var/lib/bootc

lsblk

Purpose: List block devices Usage: lsblk [options...] Dependencies: util-linux

Examples

# List block devices
lsblk

# Show device tree
lsblk -f

# Show device sizes
lsblk -b

# Show device types
lsblk -d

Process Commands

ps

Purpose: Process status Usage: ps [options...] Dependencies: procps

Examples

# Show all processes
ps aux

# Show process tree
ps -ef

# Show specific process
ps -p 1234

# Show processes by user
ps -u username

kill

Purpose: Send signals to processes Usage: kill [options...] <pid> Dependencies: util-linux

Examples

# Kill process
kill 1234

# Force kill process
kill -9 1234

# Send signal
kill -TERM 1234

# Kill by name
pkill process_name

pkill

Purpose: Kill processes by name Usage: pkill [options...] <pattern> Dependencies: procps

Examples

# Kill by name
pkill process_name

# Force kill by name
pkill -9 process_name

# Kill by pattern
pkill -f "pattern"

File Commands

ls

Purpose: List directory contents Usage: ls [options...] [file...] Dependencies: coreutils

Examples

# List files
ls

# List with details
ls -l

# List all files
ls -a

# List with human readable sizes
ls -lh

# List with recursive
ls -R

# List with sort by time
ls -lt

find

Purpose: Find files Usage: find [path...] [expression] Dependencies: findutils

Examples

# Find files by name
find /path -name "*.txt"

# Find files by type
find /path -type f

# Find files by size
find /path -size +100M

# Find files by modification time
find /path -mtime -7

# Find files by permissions
find /path -perm 644

stat

Purpose: File status Usage: stat [options...] [file...] Dependencies: coreutils

Examples

# Show file status
stat file.txt

# Show in custom format
stat -c "%n %s %Y" file.txt

# Show filesystem status
stat -f /path

# Show with format
stat --format="%n: %s bytes" file.txt

Archive Commands

tar

Purpose: Archive operations Usage: tar [options...] <archive> [file...] Dependencies: tar

Examples

# Create archive
tar -cf archive.tar file1 file2

# Extract archive
tar -xf archive.tar

# List archive contents
tar -tf archive.tar

# Create compressed archive
tar -czf archive.tar.gz file1 file2

# Extract compressed archive
tar -xzf archive.tar.gz

gzip

Purpose: Compression Usage: gzip [options...] [file...] Dependencies: gzip

Examples

# Compress file
gzip file.txt

# Decompress file
gzip -d file.txt.gz

# Compress with custom level
gzip -9 file.txt

# Keep original file
gzip -k file.txt

System Information Commands

uname

Purpose: System information Usage: uname [options...] Dependencies: coreutils

Examples

# Show system name
uname

# Show all information
uname -a

# Show kernel name
uname -s

# Show kernel version
uname -r

# Show machine type
uname -m

hostname

Purpose: Hostname operations Usage: hostname [options...] Dependencies: hostname

Examples

# Show hostname
hostname

# Show FQDN
hostname -f

# Show short hostname
hostname -s

# Show domain name
hostname -d

lscpu

Purpose: CPU information Usage: lscpu [options...] Dependencies: util-linux

Examples

# Show CPU information
lscpu

# Show in JSON format
lscpu -J

# Show in extended format
lscpu -e

# Show in parseable format
lscpu -p

free

Purpose: Memory information Usage: free [options...] Dependencies: procps

Examples

# Show memory usage
free

# Show in human readable format
free -h

# Show in bytes
free -b

# Show with total
free -t

# Show with wide format
free -w

Network Commands

curl

Purpose: HTTP client for registry operations Usage: curl [options...] <url> Dependencies: curl

Examples

# Download file
curl -O https://example.com/file.tar

# Get HTTP headers
curl -I https://example.com

# POST data
curl -X POST -d "data" https://example.com

# With authentication
curl -u username:password https://example.com

# With custom headers
curl -H "Authorization: Bearer token" https://example.com

wget

Purpose: HTTP client for downloading files Usage: wget [options...] <url> Dependencies: wget

Examples

# Download file
wget https://example.com/file.tar

# Download with progress
wget --progress=bar https://example.com/file.tar

# Download recursively
wget -r https://example.com/

# Download with authentication
wget --user=username --password=password https://example.com

Container Commands

podman

Purpose: Container runtime Usage: podman <subcommand> [options...] Dependencies: podman

Examples

# List containers
podman ps

# List images
podman images

# Pull image
podman pull quay.io/myorg/image:latest

# Run container
podman run -it image:latest

# Build image
podman build -t myimage:latest .

# Inspect image
podman inspect image:latest

docker

Purpose: Alternative container runtime Usage: docker <subcommand> [options...] Dependencies: docker

Examples

# List containers
docker ps

# List images
docker images

# Pull image
docker pull quay.io/myorg/image:latest

# Run container
docker run -it image:latest

# Build image
docker build -t myimage:latest .

Development Commands

make

Purpose: Build automation Usage: make [target...] Dependencies: make

Examples

# Build project
make

# Clean build
make clean

# Install
make install

# Run tests
make test

# Update generated files
make update-generated

cargo

Purpose: Rust package manager Usage: cargo <subcommand> [options...] Dependencies: rust

Examples

# Build project
cargo build

# Run project
cargo run

# Run tests
cargo test

# Check code
cargo check

# Update dependencies
cargo update

git

Purpose: Version control Usage: git <subcommand> [options...] Dependencies: git

Examples

# Clone repository
git clone https://github.com/containers/bootc.git

# Check status
git status

# Add files
git add .

# Commit changes
git commit -m "message"

# Push changes
git push

Monitoring Commands

top

Purpose: Process monitoring Usage: top [options...] Dependencies: procps

Examples

# Show processes
top

# Show specific user
top -u username

# Show specific process
top -p 1234

# Show with custom delay
top -d 5

# Show with custom sort
top -o %CPU

htop

Purpose: Interactive process monitoring Usage: htop [options...] Dependencies: htop

Examples

# Show processes
htop

# Show specific user
htop -u username

# Show specific process
htop -p 1234

# Show with custom delay
htop -d 5

iotop

Purpose: I/O monitoring Usage: iotop [options...] Dependencies: iotop

Examples

# Show I/O usage
iotop

# Show only processes doing I/O
iotop -o

# Show with custom delay
iotop -d 5

# Show with custom refresh
iotop -n 10

Security Commands

openssl

Purpose: SSL/TLS operations Usage: openssl <command> [options...] Dependencies: openssl

Examples

# Generate private key
openssl genrsa -out key.pem 2048

# Generate certificate
openssl req -new -x509 -key key.pem -out cert.pem

# Verify certificate
openssl verify cert.pem

# Check certificate details
openssl x509 -in cert.pem -text -noout

# Generate hash
openssl dgst -sha256 file.txt

gpg

Purpose: GPG operations Usage: gpg [options...] Dependencies: gnupg

Examples

# Generate key pair
gpg --gen-key

# List keys
gpg --list-keys

# Sign file
gpg --sign file.txt

# Verify signature
gpg --verify file.txt.asc

# Encrypt file
gpg --encrypt file.txt

Bootloader Commands

grub-mkconfig

Purpose: Generate GRUB configuration Usage: grub-mkconfig [options...] Dependencies: grub2

Examples

# Generate GRUB config
grub-mkconfig -o /boot/grub/grub.cfg

# Generate with specific output
grub-mkconfig -o /boot/grub2/grub.cfg

# Generate with verbose output
grub-mkconfig -v -o /boot/grub/grub.cfg

grub-install

Purpose: Install GRUB bootloader Usage: grub-install [options...] <device> Dependencies: grub2

Examples

# Install GRUB
grub-install /dev/sda

# Install with specific directory
grub-install --boot-directory=/boot /dev/sda

# Install with verbose output
grub-install -v /dev/sda

efibootmgr

Purpose: EFI boot manager Usage: efibootmgr [options...] Dependencies: efibootmgr

Examples

# List boot entries
efibootmgr

# Create boot entry
efibootmgr -c -d /dev/sda -p 1 -L "Bootc" -l /EFI/bootc/grubx64.efi

# Delete boot entry
efibootmgr -b 0000 -B

# Set boot order
efibootmgr -o 0000,0001,0002

Recovery Commands

chroot

Purpose: Change root directory Usage: chroot [options...] <directory> <command> Dependencies: coreutils

Examples

# Change root
chroot /mnt /bin/bash

# Change root with specific command
chroot /mnt /bin/ls

# Change root with environment
chroot /mnt env -i /bin/bash

mount

Purpose: Mount filesystems for recovery Usage: mount [options...] <device> <directory> Dependencies: util-linux

Examples

# Mount root filesystem
mount /dev/sda1 /mnt

# Mount boot filesystem
mount /dev/sda2 /mnt/boot

# Mount with specific options
mount -o ro /dev/sda1 /mnt

umount

Purpose: Unmount filesystems after recovery Usage: umount [options...] <directory> Dependencies: util-linux

Examples

# Unmount filesystem
umount /mnt

# Unmount all filesystems
umount -a

# Force unmount
umount -f /mnt

This comprehensive reference covers all external commands used by the bootc state system, providing examples and usage patterns for each command.