bootc-docs/install/external-commands-reference.md

# bootc External Commands Reference

## Overview

This document provides a comprehensive reference for all external commands used by bootc during the installation process. These commands are executed by bootc to perform various system operations that cannot be handled internally.

## Required Commands

### 1. ostree - OSTree Repository Management

**Purpose**: Manages OSTree repositories for atomic updates and deployments

**Package**: `ostree`

**Key Commands Used**:

```bash
# Initialize OSTree filesystem
ostree admin init-fs --modern .

# Configure repository settings
ostree config --repo ostree/repo set sysroot.bootloader none
ostree config --repo ostree/repo set sysroot.bootprefix true
ostree config --repo ostree/repo set sysroot.readonly true

# Parse commit information
ostree --repo=/ostree/repo rev-parse --single

# Read commit metadata
ostree read-commit <commit-hash>
```

**Configuration Files**:
- Repository config: `ostree/repo/config`
- Deployment config: `ostree/deploy/*/var/lib/ostree/config`

**Error Handling**:
- Repository corruption detection
- Commit validation
- Configuration validation

### 2. bootupd - Bootloader Management

**Purpose**: Manages bootloader installation and configuration

**Package**: `bootupd`

**Key Commands Used**:

```bash
# Install bootloader
bootupctl install

# Generate bootloader configuration
bootupctl generate

# Check bootloader status
bootupctl status

# Update bootloader
bootupctl update
```

**Configuration Files**:
- Bootloader state: `/boot/bootupd-state.json`
- GRUB config: `/boot/grub2/grub.cfg`
- EFI config: `/boot/efi/EFI/*/grub.cfg`

**Architecture Support**:
- x86_64: GRUB2
- aarch64: GRUB2
- s390x: zipl (via separate implementation)

### 3. podman - Container Runtime

**Purpose**: Container runtime for running bootc installation

**Package**: `podman`

**Required Flags**:
```bash
podman run --rm --privileged --pid=host \
  -v /var/lib/containers:/var/lib/containers \
  -v /dev:/dev \
  --security-opt label=type:unconfined_t \
  <image> bootc install to-disk /dev/target
```

**Container Environment Variables**:
- `CONTAINER_ENGINE=podman`
- `CONTAINER_IMAGE_ID=<image-id>`
- `CONTAINER_IMAGE=<image-name>`
- `CONTAINER_ROOTLESS=<0|1>`

### 4. Filesystem Management Commands

#### fstrim - Filesystem Optimization

**Purpose**: Trim filesystem to optimize performance

**Package**: `util-linux`

**Command Used**:
```bash
fstrim --quiet-unsupported -v /target
```

**Options**:
- `--quiet-unsupported`: Suppress errors for unsupported filesystems
- `-v`: Verbose output

#### mount/umount - Filesystem Mounting

**Purpose**: Mount and unmount filesystems

**Package**: `util-linux`

**Commands Used**:
```bash
# Mount filesystem
mount /dev/target /mnt

# Remount read-only
mount -o remount,ro /target

# Unmount filesystem
umount -R /target
```

#### fsfreeze - Filesystem Freeze/Thaw

**Purpose**: Freeze and thaw filesystems for consistency

**Package**: `util-linux`

**Commands Used**:
```bash
# Freeze filesystem
fsfreeze -f /target

# Thaw filesystem
fsfreeze -u /target
```

## Optional Commands

### 1. cryptsetup - LUKS Encryption

**Purpose**: Handle LUKS encrypted devices

**Package**: `cryptsetup`

**Commands Used**:
```bash
# Close LUKS device
cryptsetup close <device-name>

# Open LUKS device
cryptsetup open <device> <name>

# Create LUKS device
cryptsetup luksFormat <device>
```

**Integration**:
- TPM2-LUKS support via systemd-cryptenroll
- LUKS device detection and management
- Encryption key handling

### 2. grub2-mkconfig - GRUB Configuration

**Purpose**: Generate GRUB configuration files

**Package**: `grub2-tools`

**Commands Used**:
```bash
# Generate GRUB configuration
grub2-mkconfig -o /boot/grub2/grub.cfg

# Generate EFI configuration
grub2-mkconfig -o /boot/efi/EFI/*/grub.cfg
```

**Configuration Files**:
- GRUB config: `/etc/default/grub`
- GRUB scripts: `/etc/grub.d/*`
- Generated config: `/boot/grub2/grub.cfg`

### 3. dracut - Initramfs Generation

**Purpose**: Generate initramfs for boot

**Package**: `dracut`

**Commands Used**:
```bash
# Generate initramfs
dracut --force /boot/initramfs-<version>.img <version>

# Regenerate with specific modules
dracut --add-drivers <modules> --force
```

**Integration**:
- Initramfs generation during container build
- Module detection and inclusion
- Boot-time filesystem setup

### 4. Filesystem Creation Commands

#### mkfs.* - Filesystem Creation

**Purpose**: Create various filesystem types

**Package**: `util-linux`, `e2fsprogs`, `xfsprogs`, `btrfs-progs`

**Commands Used**:
```bash
# Create XFS filesystem
mkfs.xfs /dev/target

# Create ext4 filesystem
mkfs.ext4 /dev/target

# Create Btrfs filesystem
mkfs.btrfs /dev/target
```

**Configuration**:
- Filesystem type determined by install config
- Default type: XFS
- Configurable via `/usr/lib/bootc/install/*.toml`

## Command Execution Patterns

### 1. Task Execution

```rust
// From install.rs - Task execution pattern
Task::new("Operation description", "command")
    .args(["arg1", "arg2"])
    .cwd(target_directory)?
    .run()?;
```

### 2. Command with Capture

```rust
// From install.rs - Command with stderr capture
Command::new("command")
    .args(["arg1", "arg2"])
    .cwd_dir(target_directory)
    .run_capture_stderr()?;
```

### 3. Async Command Execution

```rust
// From install.rs - Async command execution
let result = tokio::task::spawn_blocking(move || {
    Command::new("command")
        .args(["arg1", "arg2"])
        .run()
}).await??;
```

## Error Handling

### 1. Command Not Found

**Detection**: Process exit code 127
**Handling**: Check package installation
**Recovery**: Install required package

### 2. Permission Denied

**Detection**: Process exit code 13
**Handling**: Check user privileges
**Recovery**: Run with appropriate privileges

### 3. Resource Exhaustion

**Detection**: Process exit code 28
**Handling**: Check disk space, memory
**Recovery**: Free up resources

### 4. Filesystem Errors

**Detection**: Process exit code 1
**Handling**: Check filesystem state
**Recovery**: Repair filesystem if possible

## Security Considerations

### 1. Command Injection Prevention

- All commands use structured arguments
- No shell interpretation
- Input validation and sanitization

### 2. Privilege Escalation

- Commands run with minimal required privileges
- SELinux context preservation
- Capability dropping where possible

### 3. Resource Limits

- Disk space validation before operations
- Memory usage monitoring
- File descriptor limits

## Performance Optimization

### 1. Parallel Execution

- Independent commands run in parallel
- I/O operations optimized
- Resource usage balanced

### 2. Caching

- OSTree repository caching
- Container image layer caching
- Configuration caching

### 3. Resource Management

- Temporary file cleanup
- Memory usage optimization
- Disk I/O optimization

## Debugging Commands

### 1. System Information

```bash
# Check OSTree status
ostree admin status

# Check bootloader status
bootupctl status

# Check filesystem usage
df -h

# Check mounted filesystems
mount | grep -E "(ostree|boot)"
```

### 2. Container Information

```bash
# List container images
podman images

# Check container storage
podman system df

# Inspect container image
podman inspect <image>
```

### 3. Boot Information

```bash
# Check kernel command line
cat /proc/cmdline

# Check bootloader entries
ls /boot/loader/entries/

# Check EFI variables
efibootmgr -v
```

## Troubleshooting

### 1. Common Issues

**OSTree Repository Corruption**:
```bash
# Repair repository
ostree admin init-fs --modern .
```

**Bootloader Installation Failure**:
```bash
# Reinstall bootloader
bootupctl install --force
```

**Filesystem Mount Issues**:
```bash
# Check mount options
mount | grep <device>
# Remount with correct options
mount -o remount,<options> <device>
```

### 2. Log Analysis

**Systemd Journal**:
```bash
# Check bootc logs
journalctl -u bootc*

# Check installation logs
journalctl -f | grep bootc
```

**OSTree Logs**:
```bash
# Check OSTree operations
journalctl -u ostree*

# Check repository operations
ostree log <commit>
```

This reference provides comprehensive information about all external commands used by bootc, their purposes, usage patterns, and troubleshooting approaches.