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

# bootc internals - External Commands Reference

## Overview

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

## Core Commands

### bootc

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

#### Internals Subcommands
- `bootc internals systemd-generator` - Generate systemd units
- `bootc internals fixup-etc-fstab` - Fix /etc/fstab
- `bootc internals print-json-schema` - Generate JSON schemas
- `bootc internals fsverity` - Filesystem verity operations
- `bootc internals fsck` - Filesystem consistency check
- `bootc internals cleanup` - Perform cleanup operations
- `bootc internals relabel` - SELinux relabeling
- `bootc internals ostree-ext` - Proxy to ostree-ext CLI
- `bootc internals cfs` - Proxy to cfsctl CLI
- `bootc internals ostree-container` - Proxy to ostree container CLI
- `bootc internals test-composefs` - Test composefs repository
- `bootc internals loopback-cleanup-helper` - Loopback device cleanup
- `bootc internals allocate-cleanup-loopback` - Test loopback allocation
- `bootc internals bootc-install-completion` - Complete installation
- `bootc internals reboot` - Initiate reboot
- `bootc internals publish-rhsm-facts` - Publish RHSM facts
- `bootc internals dump-cli-json` - Dump CLI structure as JSON
- `bootc internals dir-diff` - Test directory diff functionality

#### Examples
```bash
# Generate systemd units
bootc internals systemd-generator /run/systemd/system

# Fix /etc/fstab
bootc internals fixup-etc-fstab

# Run filesystem check
bootc internals fsck

# Clean up system
bootc internals cleanup

# Test composefs
bootc internals test-composefs

# Reboot system
bootc internals reboot
```

## Systemd 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
```bash
# Check service status
systemctl status bootc-systemd-generator

# Start service
systemctl start bootc-systemd-generator

# Enable service
systemctl enable bootc-systemd-generator

# Reload systemd configuration
systemctl daemon-reload
```

### journalctl

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

#### Examples
```bash
# Show all logs
journalctl

# Show logs for service
journalctl -u bootc-systemd-generator

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

## OSTree Commands

### ostree

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

#### Repository Commands
- `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 status` - Show admin status
- `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

#### Examples
```bash
# Show repository status
ostree admin status

# List 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
```

### ostree-ext

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

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

## Composefs Commands

### cfsctl

**Purpose**: Composefs control operations
**Usage**: `cfsctl <subcommand> [options...]`
**Dependencies**: composefs package

#### Examples
```bash
# Create repository
cfsctl repo create /path/to/repo

# Import layer
cfsctl oci import-layer <sha256> <name>

# List layers
cfsctl oci ls-layer <name>

# Create filesystem
cfsctl create-fs <name> <output>

# Write boot entries
cfsctl write-boot <name> <output>
```

## Filesystem Commands

### fsverity

**Purpose**: Filesystem verity operations
**Usage**: `fsverity <subcommand> [options...]`
**Dependencies**: fsverity-utils

#### Examples
```bash
# Measure file digest
fsverity measure /path/to/file

# Enable verity
fsverity enable /path/to/file

# Show verity status
fsverity status /path/to/file
```

### mount

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

#### Examples
```bash
# 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
```bash
# Unmount filesystem
umount /mnt

# Force unmount
umount -f /mnt

# Lazy unmount
umount -l /mnt
```

### losetup

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

#### Examples
```bash
# Create loop device
losetup -f /path/to/image

# List loop devices
losetup -a

# Detach loop device
losetup -d /dev/loop0

# Show loop device info
losetup -l
```

## SELinux Commands

### setsebool

**Purpose**: Set SELinux boolean values
**Usage**: `setsebool [options...] <boolean> <value>`
**Dependencies**: policycoreutils

#### Examples
```bash
# Set boolean value
setsebool -P httpd_can_network_connect 1

# List boolean values
getsebool -a

# Show boolean value
getsebool httpd_can_network_connect
```

### restorecon

**Purpose**: Restore SELinux contexts
**Usage**: `restorecon [options...] <path>`
**Dependencies**: policycoreutils

#### Examples
```bash
# Restore context
restorecon -R /path/to/directory

# Restore with verbose output
restorecon -v /path/to/file

# Restore with force
restorecon -F /path/to/file
```

### chcon

**Purpose**: Change SELinux context
**Usage**: `chcon [options...] <context> <path>`
**Dependencies**: coreutils

#### Examples
```bash
# Change context
chcon -t httpd_exec_t /path/to/file

# Change context recursively
chcon -R -t httpd_exec_t /path/to/directory

# Change context with reference
chcon --reference /path/to/reference /path/to/target
```

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

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

### 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 process_name
```

### pkill

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

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

### find

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

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

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

## Container Commands

### podman

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

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

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

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