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
40 KiB
40 KiB
bootc composefs-finalize-staged - Process Flowchart
Overview
This document provides a visual representation of the bootc composefs-finalize-staged process flow, showing the decision points, operations, and system state changes involved in finalizing staged composefs deployments.
Main Process Flow
┌─────────────────────────────────────────────────────────────────┐
│ bootc composefs-finalize-staged │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Get Deployment Status │
│ │
│ • Get composefs deployment status │
│ • Validate booted composefs deployment │
│ • Check for staged deployment │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Validate Staged Deployment │
│ │
│ • Check if staged deployment exists │
│ • Validate staged deployment is composefs │
│ • Get staged composefs configuration │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Mount EROFS Image │
│ │
│ • Open sysroot directory │
│ • Mount booted EROFS image │
│ • Create temporary mount point │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Perform /etc Merge │
│ │
│ • Access pristine /etc from EROFS │
│ • Access current /etc from system │
│ • Access new /etc from staged deployment │
│ • Perform 3-way merge │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Unmount EROFS Image │
│ │
│ • Drop temporary mount │
│ • Clean up EROFS mount │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Mount ESP Partition │
│ │
│ • Get sysroot parent device │
│ • Get ESP partition │
│ • Mount ESP partition │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Update Bootloader Entries │
│ │
│ • Determine bootloader type (GRUB vs systemd-boot) │
│ • Determine boot type (BLS vs UKI) │
│ • Update appropriate bootloader entries │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Complete Finalization │
│ │
│ • Sync filesystem changes │
│ • Update deployment state │
│ • Complete finalization process │
└─────────────────────────────────────────────────────────────────┘
Detailed Process Flow
┌─────────────────────────────────────────────────────────────────┐
│ Deployment Status Retrieval │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Get Composefs Status │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ composefs_deployment_status │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Check Kernel Cmdline │ │
│ │ │ │
│ │ • Parse composefs parameter │ │
│ │ • Extract composefs digest │ │
│ │ • Validate composefs state │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Staged Deployment Validation │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Check Staged Deployment │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Staged Deployment Check │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ No Staged │ │ Staged Found │ │
│ │ Deployment │ │ │ │
│ │ │ │ ┌─────────────────────────────────┐│ │
│ │ ┌─────────────┐│ │ │ Check Composefs Type ││ │
│ │ │ Return OK ││ │ │ ││ │
│ │ │ (No Action) ││ │ │ • Validate composefs deployment ││ │
│ │ └─────────────┘│ │ │ • Get composefs configuration ││ │
│ └─────────────────┘ │ └─────────────────────────────────┘│ │
│ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ EROFS Image Operations │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Mount EROFS Image │
│ │
│ • Open /sysroot directory │
│ • Mount booted EROFS image using verity digest │
│ • Create temporary mount point │
│ • Access pristine /etc configuration │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ /etc Configuration Merge │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Three-Way Merge Process │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Pristine │ │ Current │ │ New │ │
│ │ /etc │ │ /etc │ │ /etc │ │
│ │ │ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
│ │ │ From EROFS ││ │ │ From System ││ │ │ From Staged ││ │
│ │ │ Image ││ │ │ /etc ││ │ │ Deployment ││ │
│ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
│ │ │ │ │
│ └─────────────────────┼─────────────────────┘ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Compute Differences │ │
│ │ │ │
│ │ • Compare pristine vs current │ │
│ │ • Identify changes made by user │ │
│ │ • Prepare for merge operation │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Perform Merge │ │
│ │ │ │
│ │ • Apply pristine configuration as base │ │
│ │ • Apply user changes from current │ │
│ │ • Apply new changes from staged deployment │ │
│ │ • Resolve conflicts if any │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ EROFS Cleanup │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Unmount EROFS Image │
│ │
│ • Drop temporary mount │
│ • Clean up EROFS mount │
│ • Release file descriptors │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ ESP Partition Operations │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Mount ESP Partition │
│ │
│ • Get sysroot parent device │
│ • Get ESP partition information │
│ • Mount ESP partition │
│ • Access bootloader entries │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Bootloader Management │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Determine Bootloader Type │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Bootloader Type Check │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ GRUB │ │ systemd-boot │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ BLS Entries ││ │ │ BLS Entries ││ │
│ │ │ UKI Entries ││ │ │ UKI Entries ││ │
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Bootloader Operations Flow
┌─────────────────────────────────────────────────────────────────┐
│ Bootloader Operations │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ GRUB Bootloader │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Determine Boot Type │
│ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ BLS Entries │ │ UKI Entries │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ Update BLS ││ │ │ Update UKI Entries ││ │
│ │ │ Entries ││ │ │ ││ │
│ │ │ ││ │ │ • Rename staged UKI files ││ │
│ │ │ • Exchange ││ │ │ • Update GRUB configuration ││ │
│ │ │ entries ││ │ │ • Sync filesystem ││ │
│ │ │ • Update ││ │ └─────────────────────────────────┘│ │
│ │ │ order ││ │ │ │
│ │ └─────────────┘│ │ │ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ systemd-boot Bootloader │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Determine Boot Type │
│ │
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
│ │ BLS Entries │ │ UKI Entries │ │
│ │ │ │ │ │
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
│ │ │ Update BLS ││ │ │ Update UKI Entries ││ │
│ │ │ Entries ││ │ │ ││ │
│ │ │ ││ │ │ • Rename staged UKI files ││ │
│ │ │ • Exchange ││ │ │ • Sync filesystem ││ │
│ │ │ entries ││ │ │ • Update boot order ││ │
│ │ │ • Update ││ │ └─────────────────────────────────┘│ │
│ │ │ order ││ │ │ │
│ │ └─────────────┘│ │ │ │
│ └─────────────────┘ └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
Error Handling Flow
┌─────────────────────────────────────────────────────────────────┐
│ Error Detection │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Error Classification │
│ │
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
│ │ Deployment │ │ Filesystem │ │ Bootloader │ │
│ │ Errors │ │ Errors │ │ Errors │ │
│ │ │ │ │ │ │ │
│ │ • No Staged │ │ • EROFS Mount │ │ • Entry Update │ │
│ │ Deployment │ │ Failed │ │ Failed │ │
│ │ • Non-Composefs │ │ • ESP Mount │ │ • Sync Failed │ │
│ │ Deployment │ │ Failed │ │ • Permission │ │
│ │ • Invalid State │ │ • Access Denied │ │ Denied │ │
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Error Response │
│ │
│ • Log error details │
│ • Provide context information │
│ • Return appropriate error code │
│ • Clean up resources │
│ • Notify systemd service │
└─────────────────────────────────────────────────────────────────┘
Systemd Service Integration Flow
┌─────────────────────────────────────────────────────────────────┐
│ Systemd Service Lifecycle │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Service Start │
│ │
│ • Service starts early in boot process │
│ • After local-fs.target │
│ • Before basic.target and final.target │
│ • After systemd-journal-flush.service │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Command Execution │
│ │
│ • Execute bootc composefs-finalize-staged │
│ • With 5-minute timeout │
│ • With sandboxing enabled │
│ • With /etc read-only protection │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Service Completion │
│ │
│ • Command completes successfully or fails │
│ • Service remains active (RemainAfterExit=yes) │
│ • System continues boot process │
│ • Logs are written to journal │
└─────────────────────────────────────────────────────────────────┘
State Transitions Flow
┌─────────────────────────────────────────────────────────────────┐
│ System States │
└─────────────────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────────┐
│ Initial State │
│ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Staged Deployment Present │ │
│ │ │ │
│ │ • Staged composefs deployment exists │ │
│ │ • Booted composefs deployment active │ │
│ │ • System ready for finalization │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Finalization Process │ │
│ │ │ │
│ │ • Mount EROFS image │ │
│ │ • Perform /etc merge │ │
│ │ • Update bootloader entries │ │
│ │ • Sync filesystem changes │ │
│ └─────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌─────────────────────────────────────────────────────────────┐ │
│ │ Final State │ │
│ │ │ │
│ │ • Staged deployment finalized │ │
│ │ • Bootloader entries updated │ │
│ │ • System ready for next boot │ │
│ │ • Staged deployment becomes active │ │
│ └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
This flowchart provides a comprehensive visual representation of the bootc composefs-finalize-staged process, showing all decision points, operations, and state transitions involved in finalizing staged composefs deployments.