526f1c1afd
- 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
282 lines
24 KiB
Markdown
282 lines
24 KiB
Markdown
# bootc Installation Process Flowchart
|
|
|
|
## High-Level Installation Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ bootc Installation Process │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Phase 1: Preparation │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ 1.1 Container Environment Detection │
|
|
│ ├─ Check podman runtime │
|
|
│ ├─ Validate container execution info │
|
|
│ └─ Verify privileged access │
|
|
│ │
|
|
│ 1.2 Privilege and Namespace Validation │
|
|
│ ├─ Require --pid=host flag │
|
|
│ ├─ Validate host user namespace │
|
|
│ └─ Check root privileges │
|
|
│ │
|
|
│ 1.3 SELinux State Management │
|
|
│ ├─ Detect SELinux policy in container │
|
|
│ ├─ Check host SELinux state │
|
|
│ └─ Re-execute if needed for proper labeling │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Phase 2: Filesystem Setup │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ 2.1 OSTree Repository Initialization │
|
|
│ ├─ Check for existing ostree/repo │
|
|
│ ├─ Run: ostree admin init-fs --modern . │
|
|
│ ├─ Configure repository settings │
|
|
│ └─ Set up stateroot │
|
|
│ │
|
|
│ 2.2 Container Image Deployment │
|
|
│ ├─ Prepare container image for pull │
|
|
│ ├─ Check disk space requirements │
|
|
│ ├─ Pull image into OSTree repository │
|
|
│ ├─ Deploy container to target filesystem │
|
|
│ └─ Set up deployment metadata │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Phase 3: Bootloader Setup │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ 3.1 Bootupd Integration │
|
|
│ ├─ Detect target architecture │
|
|
│ ├─ Configure bootloader type │
|
|
│ └─ Install via bootupd │
|
|
│ │
|
|
│ 3.2 Architecture-Specific Bootloaders │
|
|
│ ├─ x86_64/aarch64: GRUB2 via bootupd │
|
|
│ ├─ s390x: zipl │
|
|
│ └─ Other: Platform-specific │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Phase 4: Kernel Configuration │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ 4.1 Kernel Argument Processing │
|
|
│ ├─ Extract kargs from OSTree root │
|
|
│ ├─ Merge install config kargs │
|
|
│ ├─ Apply container image kargs.d │
|
|
│ └─ Add CLI-specified kargs │
|
|
│ │
|
|
│ 4.2 Initramfs Integration │
|
|
│ ├─ Locate kernel: /usr/lib/modules/$kver/vmlinuz │
|
|
│ ├─ Locate initramfs: /usr/lib/modules/$kver/initramfs.img │
|
|
│ └─ Configure bootloader entries │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Phase 5: Finalization │
|
|
├─────────────────────────────────────────────────────────────────┤
|
|
│ 5.1 Filesystem Optimization │
|
|
│ ├─ Run: fstrim --quiet-unsupported -v /target │
|
|
│ ├─ Run: mount -o remount,ro /target │
|
|
│ └─ Run: fsfreeze -f /target && fsfreeze -u /target │
|
|
│ │
|
|
│ 5.2 Cleanup and Validation │
|
|
│ ├─ Close file descriptors │
|
|
│ ├─ Unmount target filesystem │
|
|
│ ├─ Close LUKS devices (if any) │
|
|
│ └─ Validate installation │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Installation Complete │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Detailed Installation Modes
|
|
|
|
### 1. to-disk Installation Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ bootc install to-disk │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 1. Validate Target Device │
|
|
│ ├─ Check if device is block device or file │
|
|
│ ├─ Handle loopback device if --via-loopback │
|
|
│ └─ Validate device permissions │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 2. Create Filesystem │
|
|
│ ├─ Determine filesystem type from config │
|
|
│ ├─ Run: mkfs.$fstype /dev/target │
|
|
│ └─ Set up partition table if needed │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 3. Mount and Deploy │
|
|
│ ├─ Mount: /dev/target /mnt │
|
|
│ ├─ Run: bootc install to-filesystem /mnt │
|
|
│ └─ Configure kernel arguments │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 4. Finalize │
|
|
│ ├─ Unmount: umount -R /mnt │
|
|
│ ├─ Close LUKS devices │
|
|
│ └─ Close loopback devices │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 2. to-filesystem Installation Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ bootc install to-filesystem │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 1. Validate Target Filesystem │
|
|
│ ├─ Check if target is directory │
|
|
│ ├─ Verify it's a mountpoint │
|
|
│ ├─ Detect if already OSTree system │
|
|
│ └─ Handle alongside installation │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 2. Clean Target (if needed) │
|
|
│ ├─ Wipe mode: Remove all contents │
|
|
│ ├─ Alongside mode: Clean boot directories │
|
|
│ └─ Default: Require empty root directory │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 3. Deploy Container Image │
|
|
│ ├─ Initialize OSTree repository │
|
|
│ ├─ Pull container image │
|
|
│ ├─ Deploy to target filesystem │
|
|
│ └─ Configure bootloader │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 4. Finalize │
|
|
│ ├─ Run: bootc install finalize │
|
|
│ ├─ Optimize filesystem │
|
|
│ └─ Validate installation │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 3. to-existing-root Installation Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ bootc install to-existing-root │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 1. Mount Host Root │
|
|
│ ├─ Mount: /:/target (if not already mounted) │
|
|
│ ├─ Detect existing OSTree system │
|
|
│ └─ Find physical root in /sysroot │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 2. Clean Boot Directories │
|
|
│ ├─ Remove existing bootloader configuration │
|
|
│ ├─ Clean /boot directory │
|
|
│ └─ Clean /boot/efi directory (if exists) │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 3. Deploy Alongside │
|
|
│ ├─ Initialize OSTree repository │
|
|
│ ├─ Deploy container image │
|
|
│ ├─ Configure bootloader │
|
|
│ └─ Set up cleanup service │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 4. Setup Cleanup │
|
|
│ ├─ Create bootc-destructive-cleanup.service │
|
|
│ ├─ Configure for first boot cleanup │
|
|
│ └─ Preserve existing data in /sysroot │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Error Handling Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Error Detection │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 1. Validation Errors │
|
|
│ ├─ Container environment issues │
|
|
│ ├─ Privilege/permission errors │
|
|
│ └─ SELinux policy conflicts │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 2. Resource Errors │
|
|
│ ├─ Insufficient disk space │
|
|
│ ├─ Memory allocation failures │
|
|
│ └─ File descriptor limits │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 3. Deployment Errors │
|
|
│ ├─ Container image pull failures │
|
|
│ ├─ OSTree repository issues │
|
|
│ └─ Bootloader installation failures │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ 4. Recovery Actions │
|
|
│ ├─ Rollback OSTree deployment │
|
|
│ ├─ Restore bootloader configuration │
|
|
│ └─ Clean up partial installation │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## External Command Dependencies
|
|
|
|
### Required Commands
|
|
- `ostree` - OSTree repository management
|
|
- `bootupd` - Bootloader management
|
|
- `podman` - Container runtime
|
|
- `fstrim` - Filesystem optimization
|
|
- `mount`/`umount` - Filesystem mounting
|
|
- `fsfreeze` - Filesystem freeze/thaw
|
|
|
|
### Optional Commands
|
|
- `cryptsetup` - LUKS encryption
|
|
- `grub2-mkconfig` - GRUB configuration
|
|
- `dracut` - Initramfs generation
|
|
- `mkfs.*` - Filesystem creation
|
|
|
|
This flowchart provides a comprehensive view of the bootc installation process, showing the sequential phases, decision points, and error handling paths.
|