# bootc composefs-finalize-staged - External Commands Reference

## Overview

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

## Core Commands

### bootc

**Purpose**: Main bootc command for composefs-finalize-staged operations
**Usage**: `bootc composefs-finalize-staged`
**Dependencies**: None (core command)

#### Examples
```bash
# Execute composefs-finalize-staged command
bootc composefs-finalize-staged

# Check if command is available
bootc --help | grep composefs-finalize-staged
```

## Systemd Commands

### systemctl

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

#### Examples
```bash
# Start composefs-finalize-staged service
systemctl start composefs-finalize-staged.service

# Enable service for automatic start
systemctl enable composefs-finalize-staged.service

# Check service status
systemctl status composefs-finalize-staged.service

# Stop service
systemctl stop composefs-finalize-staged.service

# Restart service
systemctl restart composefs-finalize-staged.service

# Reload systemd configuration
systemctl daemon-reload
```

### journalctl

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

#### Examples
```bash
# Show logs for composefs-finalize-staged service
journalctl -u composefs-finalize-staged.service

# Show recent logs
journalctl -u composefs-finalize-staged.service -n 100

# Follow logs in real-time
journalctl -u composefs-finalize-staged.service -f

# Show logs since specific time
journalctl -u composefs-finalize-staged.service --since "1 hour ago"

# Show logs with priority
journalctl -u composefs-finalize-staged.service -p err

# Show logs with timestamps
journalctl -u composefs-finalize-staged.service -o short-precise
```

## Filesystem Commands

### mount

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

#### Examples
```bash
# Mount EROFS image
mount -t erofs /dev/loop0 /mnt/erofs

# Mount ESP partition
mount /dev/sda1 /mnt/esp

# Mount with specific options
mount -o ro,noexec /dev/loop0 /mnt/erofs

# Mount bind
mount --bind /source /target

# Show mounted filesystems
mount | grep composefs
```

### umount

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

#### Examples
```bash
# Unmount filesystem
umount /mnt/erofs

# Force unmount
umount -f /mnt/erofs

# Lazy unmount
umount -l /mnt/erofs

# Unmount all
umount -a
```

### losetup

**Purpose**: Loop device management
**Usage**: `losetup [options...]`
**Dependencies**: util-linux

#### Examples
```bash
# List loop devices
losetup -a

# Create loop device
losetup /dev/loop0 /path/to/image.erofs

# Delete loop device
losetup -d /dev/loop0

# Show loop device info
losetup -l /dev/loop0
```

### fsync

**Purpose**: Synchronize filesystem
**Usage**: `fsync [options...] <file>`
**Dependencies**: coreutils

#### Examples
```bash
# Sync filesystem
fsync /path/to/file

# Sync directory
fsync /path/to/directory

# Force sync
fsync -f /path/to/file
```

## EROFS Commands

### mkfs.erofs

**Purpose**: Create EROFS filesystem
**Usage**: `mkfs.erofs [options...] <image> <directory>`
**Dependencies**: erofs-utils

#### Examples
```bash
# Create EROFS image
mkfs.erofs -z lz4 /path/to/image.erofs /source/directory

# Create with compression
mkfs.erofs -z lz4hc /path/to/image.erofs /source/directory

# Create with specific block size
mkfs.erofs -b 4096 /path/to/image.erofs /source/directory

# Create with file system label
mkfs.erofs -L "composefs-image" /path/to/image.erofs /source/directory
```

### erofs-fuse

**Purpose**: Mount EROFS image using FUSE
**Usage**: `erofs-fuse [options...] <image> <mountpoint>`
**Dependencies**: erofs-utils

#### Examples
```bash
# Mount EROFS image with FUSE
erofs-fuse /path/to/image.erofs /mnt/erofs

# Mount with specific options
erofs-fuse -o allow_other /path/to/image.erofs /mnt/erofs

# Mount in background
erofs-fuse -f /path/to/image.erofs /mnt/erofs
```

## Bootloader Commands

### grub-mkconfig

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

#### Examples
```bash
# 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

# Generate for specific OS
grub-mkconfig -o /boot/grub/grub.cfg --os-prober
```

### grub-install

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

#### Examples
```bash
# 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

# Install with UEFI support
grub-install --target=x86_64-efi --efi-directory=/boot/efi /dev/sda
```

### efibootmgr

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

#### Examples
```bash
# List boot entries
efibootmgr

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

# Delete boot entry
efibootmgr -b 0000 -B

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

# Set next boot
efibootmgr -n 0000
```

### bootctl

**Purpose**: systemd-boot manager
**Usage**: `bootctl [options...]`
**Dependencies**: systemd-boot

#### Examples
```bash
# List boot entries
bootctl list

# Install systemd-boot
bootctl install

# Update boot entries
bootctl update

# Set default boot entry
bootctl set-default "composefs-1.0.0"

# Show boot status
bootctl status
```

## File Operations Commands

### cp

**Purpose**: Copy files and directories
**Usage**: `cp [options...] <source> <destination>`
**Dependencies**: coreutils

#### Examples
```bash
# Copy file
cp /source/file /destination/

# Copy directory recursively
cp -r /source/directory /destination/

# Copy with preserve attributes
cp -a /source/file /destination/

# Copy with verbose output
cp -v /source/file /destination/
```

### mv

**Purpose**: Move/rename files and directories
**Usage**: `mv [options...] <source> <destination>`
**Dependencies**: coreutils

#### Examples
```bash
# Move file
mv /source/file /destination/

# Rename file
mv oldname newname

# Move directory
mv /source/directory /destination/

# Move with verbose output
mv -v /source/file /destination/
```

### rm

**Purpose**: Remove files and directories
**Usage**: `rm [options...] <file>`
**Dependencies**: coreutils

#### Examples
```bash
# Remove file
rm /path/to/file

# Remove directory recursively
rm -r /path/to/directory

# Force remove
rm -f /path/to/file

# Remove with verbose output
rm -v /path/to/file
```

### ln

**Purpose**: Create links
**Usage**: `ln [options...] <target> <link>`
**Dependencies**: coreutils

#### Examples
```bash
# Create symbolic link
ln -s /target/file /link/file

# Create hard link
ln /target/file /link/file

# Create link with verbose output
ln -v /target/file /link/file
```

## Directory Operations Commands

### mkdir

**Purpose**: Create directories
**Usage**: `mkdir [options...] <directory>`
**Dependencies**: coreutils

#### Examples
```bash
# Create directory
mkdir /path/to/directory

# Create directory with parents
mkdir -p /path/to/directory

# Create directory with permissions
mkdir -m 755 /path/to/directory

# Create multiple directories
mkdir dir1 dir2 dir3
```

### rmdir

**Purpose**: Remove empty directories
**Usage**: `rmdir [options...] <directory>`
**Dependencies**: coreutils

#### Examples
```bash
# Remove empty directory
rmdir /path/to/directory

# Remove directory with parents
rmdir -p /path/to/directory

# Remove multiple directories
rmdir dir1 dir2 dir3
```

### ls

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

#### Examples
```bash
# 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
```

## Process Commands

### ps

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

#### Examples
```bash
# Show all processes
ps aux

# Show process tree
ps -ef

# Show specific process
ps -p 1234

# Show processes by user
ps -u username

# Show processes by command
ps -C bootc
```

### kill

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

#### Examples
```bash
# Kill process
kill 1234

# Force kill process
kill -9 1234

# Send signal
kill -TERM 1234

# Kill by name
pkill bootc
```

## System Information Commands

### uname

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

#### Examples
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```

## Storage Commands

### df

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

#### Examples
```bash
# Show disk usage
df -h

# Show specific filesystem
df -h /sysroot

# Show inode usage
df -i

# Show all filesystems
df -a
```

### du

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

#### Examples
```bash
# Show directory usage
du -h /sysroot

# Show total usage
du -sh /sysroot

# Show usage by subdirectory
du -h --max-depth=1 /sysroot

# Show usage of all files
du -ah /sysroot
```

### lsblk

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

#### Examples
```bash
# List block devices
lsblk

# Show device tree
lsblk -f

# Show device sizes
lsblk -b

# Show device types
lsblk -d
```

## Network Commands

### curl

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

#### Examples
```bash
# 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
```bash
# 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
```

## Archive Commands

### tar

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

#### Examples
```bash
# 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
```bash
# 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
```

## Monitoring Commands

### top

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

#### Examples
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```bash
# 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
```

## Development Commands

### make

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

#### Examples
```bash
# 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
```bash
# 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
```bash
# 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
```

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