# bootc internals - Process Flowchart ## Overview This document provides a visual representation of the `bootc internals` process flow, showing the decision points, operations, and data structures involved in internal system operations. ## Main Process Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ bootc internals │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Parse Command Arguments │ │ │ │ • Parse internals subcommand │ │ • Parse command-specific options │ │ • Validate arguments │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Route to Subcommand │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Subcommand Type? │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Systemd │ │ Filesystem │ │ Proxy │ │ │ │ Generator │ │ Operations │ │ Commands │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ │ │ │ Generate ││ │ │ Fsck ││ │ │ OstreeExt ││ │ │ │ │ Units ││ │ │ Cleanup ││ │ │ Cfs ││ │ │ │ │ Fix Fstab ││ │ │ Relabel ││ │ │ OstreeCont ││ │ │ │ └─────────────┘│ │ │ Fsverity ││ │ └─────────────┘│ │ │ └─────────────────┘ │ └─────────────┘│ └─────────────────┘ │ │ │ │ │ │ ┌─────────────────┐ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Testing │ │ │ System │ │ Development │ │ │ │ Commands │ │ │ Operations │ │ Tools │ │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────┐│ │ │ ┌─────────────┐│ │ ┌─────────────┐│ │ │ │ │ TestComp ││ │ │ │ Reboot ││ │ │ PrintSchema ││ │ │ │ │ Loopback ││ │ │ │ InstallComp ││ │ │ DumpCliJson ││ │ │ │ │ DirDiff ││ │ │ │ RhsmFacts ││ │ │ DirDiff ││ │ │ │ └─────────────┘│ │ │ └─────────────┘│ │ └─────────────┘│ │ │ └─────────────────┘ │ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Success │ │ │ │ • Internal operation completed successfully │ │ • Results displayed or logged │ │ • System state updated if applicable │ └─────────────────────────────────────────────────────────────────┘ ``` ## Systemd Generator Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Systemd Generator Process │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Check System State │ │ │ │ • Check if system is ostree-booted │ │ • Verify /etc/fstab exists │ │ • Check for existing bootc stamps │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Analyze /etc/fstab │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Fstab Analysis │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────────────────────────┐ │ │ │ From Anaconda │ │ Not From Anaconda │ │ │ │ │ │ │ │ │ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │ │ │ │ Generate ││ │ │ No Action Needed ││ │ │ │ │ Fstab Editor││ │ │ ││ │ │ │ │ Service ││ │ │ • Return false ││ │ │ │ │ ││ │ │ • Exit cleanly ││ │ │ │ └─────────────┘│ │ └─────────────────────────────────┘│ │ │ └─────────────────┘ └─────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Generate Systemd Unit │ │ │ │ • Create bootc-fstab-edit.service │ │ • Set up service dependencies │ │ • Configure service execution │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Success │ │ │ │ • Systemd unit generated successfully │ │ • Service ready for execution │ │ • Fstab will be updated on next boot │ └─────────────────────────────────────────────────────────────────┘ ``` ## Filesystem Consistency Check Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Fsck Process │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Initialize Storage │ │ │ │ • Get storage instance │ │ • Open OSTree repository │ │ • Prepare output stream │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Run Consistency Checks │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Check Type? │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ OSTree │ │ Composefs │ │ Deployment │ │ │ │ Repository │ │ Repository │ State │ │ │ │ │ │ │ │ │ │ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ │ │ │ Check Repo ││ │ │ Check Repo ││ │ │ Check Depl ││ │ │ │ │ Integrity ││ │ │ Integrity ││ │ │ States ││ │ │ │ │ Validate ││ │ │ Validate ││ │ │ Validate ││ │ │ │ │ Objects ││ │ │ Images ││ │ │ Configs ││ │ │ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Report Results │ │ │ │ • Display check results │ │ • Report any errors found │ │ • Provide recommendations │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Success │ │ │ │ • All checks completed │ │ │ • System integrity verified │ │ │ • Issues reported if found │ │ │ • Recommendations provided │ └─────────────────────────────────────────────────────────────────┘ ``` ## Cleanup Operations Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Cleanup Process │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Initialize Storage │ │ │ │ • Get storage instance │ │ • Open OSTree repository │ │ • Prepare cleanup operations │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Identify Cleanup Targets │ │ │ │ • Find old deployments │ │ • Identify unused container images │ │ • Locate temporary files │ │ • Check for orphaned data │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Perform Cleanup │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Cleanup Type? │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ Deployments │ │ Images │ │ Temporary │ │ │ │ │ │ │ │ Files │ │ │ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ │ │ │ Remove Old ││ │ │ Remove ││ │ │ Remove ││ │ │ │ │ Deployments ││ │ │ Unused ││ │ │ Temp Files ││ │ │ │ │ Clean Refs ││ │ │ Images ││ │ │ Clean Cache ││ │ │ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Garbage Collection │ │ │ │ • Run OSTree garbage collection │ │ • Clean up repository objects │ │ • Update repository metadata │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Success │ │ │ │ • Cleanup completed successfully │ │ • Storage space freed │ │ • System optimized │ └─────────────────────────────────────────────────────────────────┘ ``` ## Proxy Commands Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Proxy Commands Process │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Determine Proxy Type │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Proxy Type? │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ OstreeExt │ │ Cfs │ │ OstreeCont │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ │ │ │ Parse Args ││ │ │ Parse Args ││ │ │ Parse Args ││ │ │ │ │ Call CLI ││ │ │ Call CLI ││ │ │ Call CLI ││ │ │ │ │ Return ││ │ │ Return ││ │ │ Return ││ │ │ │ │ Results ││ │ │ Results ││ │ │ Results ││ │ │ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Execute Proxy Command │ │ │ │ • Forward arguments to target CLI │ │ • Execute command with proper context │ │ • Return results to caller │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Success │ │ │ │ • Proxy command executed successfully │ │ • Results returned to caller │ │ • Target CLI completed │ └─────────────────────────────────────────────────────────────────┘ ``` ## Testing Commands Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Testing Commands Process │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Determine Test Type │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Test Type? │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ TestComp │ │ Loopback │ │ DirDiff │ │ │ │ │ │ │ │ │ │ │ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ │ │ │ Init Repo ││ │ │ Create Dev ││ │ │ Setup Dirs ││ │ │ │ │ Write Test ││ │ │ Test Ops ││ │ │ Run Merge ││ │ │ │ │ Verify ││ │ │ Cleanup ││ │ │ Verify ││ │ │ │ └─────────────┘│ │ └─────────────┘│ │ └─────────────┘│ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Execute Test │ │ │ │ • Run test operations │ │ • Verify expected results │ │ • Clean up test data │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Success │ │ │ │ • Test completed successfully │ │ • Results verified │ │ • System state restored │ └─────────────────────────────────────────────────────────────────┘ ``` ## Error Handling Flow ``` ┌─────────────────────────────────────────────────────────────────┐ │ Error Detection │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Error Classification │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ │ │ System │ │ Permission │ │ Resource │ │ │ │ Errors │ │ Errors │ │ Errors │ │ │ │ │ │ │ │ │ │ │ │ • Not Root │ │ • Access Denied │ │ • Out of Space │ │ │ │ • Not Booted │ │ • Invalid Path │ │ • Memory Error │ │ │ │ • Invalid State │ │ • File Not Found│ │ • Device Error │ │ │ │ │ │ │ │ │ │ │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Error Response │ │ │ │ • Display error message │ │ • Provide context information │ │ • Suggest remediation steps │ │ • Return appropriate exit code │ │ • Clean up any partial state │ └─────────────────────────────────────────────────────────────────┘ ``` ## State Transitions ``` ┌─────────────────────────────────────────────────────────────────┐ │ System States │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────────────────────────────┐ │ Initial State │ │ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ System Ready │ │ │ │ │ │ │ │ • All services running │ │ │ │ • Storage available │ │ │ │ • Permissions correct │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Execute Command │ │ │ │ │ │ │ │ • Parse arguments │ │ │ │ • Validate inputs │ │ │ │ • Check prerequisites │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Processing State │ │ │ │ │ │ │ │ • Command executing │ │ │ │ • System state changing │ │ │ │ • Resources being used │ │ │ └─────────────────────────────────────────────────────────────┘ │ │ │ │ │ ▼ │ │ ┌─────────────────────────────────────────────────────────────┐ │ │ │ Final State │ │ │ │ │ │ │ │ • Command completed │ │ │ │ • System state updated │ │ │ │ • Resources cleaned up │ │ │ └─────────────────────────────────────────────────────────────┘ │ └─────────────────────────────────────────────────────────────────┘ ``` This flowchart provides a comprehensive visual representation of the bootc internals process, showing all decision points, operations, and state transitions involved in internal system operations.