# 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 ``` **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 \ bootc install to-disk /dev/target ``` **Container Environment Variables**: - `CONTAINER_ENGINE=podman` - `CONTAINER_IMAGE_ID=` - `CONTAINER_IMAGE=` - `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 # Open LUKS device cryptsetup open # Create LUKS device cryptsetup luksFormat ``` **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-.img # Regenerate with specific modules dracut --add-drivers --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 ``` ### 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 # Remount with correct options mount -o remount, ``` ### 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 ``` This reference provides comprehensive information about all external commands used by bootc, their purposes, usage patterns, and troubleshooting approaches.