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:

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

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

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:

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:

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

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

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

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

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

# 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

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

2. Command with Capture

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

3. Async Command Execution

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

# 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

# List container images
podman images

# Check container storage
podman system df

# Inspect container image
podman inspect <image>

3. Boot Information

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

# Repair repository
ostree admin init-fs --modern .

Bootloader Installation Failure:

# Reinstall bootloader
bootupctl install --force

Filesystem Mount Issues:

# Check mount options
mount | grep <device>
# Remount with correct options
mount -o remount,<options> <device>

2. Log Analysis

Systemd Journal:

# Check bootc logs
journalctl -u bootc*

# Check installation logs
journalctl -f | grep bootc

OSTree Logs:

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