Initial commit: Comprehensive Debian bootc documentation
- Complete documentation for all bootc commands and subcommands - Debian-specific adaptations and workarounds - Manual installation methods to bypass bootc reliability issues - Technical guides with Rust source code analysis - Flowcharts and external command references - Hidden command documentation (bootc internals, state, etc.) - Composefs integration analysis - Base image creation guides (with and without bootc binary) - Management scripts and automation - Comprehensive troubleshooting and examples
This commit is contained in:
robojerk
commit
526f1c1afd
67 changed files with 34174 additions and 0 deletions
422
install/external-commands-reference.md
Normal file
422
install/external-commands-reference.md
Normal file
|
|
@ -0,0 +1,422 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue