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
459 lines
44 KiB
Markdown
459 lines
44 KiB
Markdown
# bootc status - Process Flowchart
|
|
|
|
## Overview
|
|
|
|
This document provides a visual representation of the `bootc status` process flow, showing the decision points, operations, and data structures involved in displaying system status information.
|
|
|
|
## Main Process Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ bootc status │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Validate Format Version │
|
|
│ │
|
|
│ • Check format version (0, 1 supported) │
|
|
│ • Error if unsupported version │
|
|
│ • Default to version 1 │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Check OSTree Boot Status │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────┐ │
|
|
│ │ ostree_booted()? │ │
|
|
│ └─────────────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
|
│ │ No │ │ Yes │ │
|
|
│ │ │ │ │ │
|
|
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
|
│ │ │ Return ││ │ │ Get System Status ││ │
|
|
│ │ │ Default ││ │ │ ││ │
|
|
│ │ │ Empty ││ │ │ • Get storage interface ││ │
|
|
│ │ │ Status ││ │ │ • Get OSTree repository ││ │
|
|
│ │ └─────────────┘│ │ │ • Get booted deployment ││ │
|
|
│ │ │ │ │ • Call get_status() ││ │
|
|
│ │ ┌─────────────┐│ │ └─────────────────────────────────┘│ │
|
|
│ │ │ Skip to ││ │ │ │
|
|
│ │ │ Output ││ │ │ │
|
|
│ │ └─────────────┘│ │ │ │
|
|
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Filter to Booted Deployment │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────┐ │
|
|
│ │ --booted specified? │ │
|
|
│ └─────────────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
|
│ │ Yes │ │ No │ │
|
|
│ │ │ │ │ │
|
|
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
|
│ │ │ Filter to ││ │ │ Keep All Deployments ││ │
|
|
│ │ │ Booted ││ │ │ ││ │
|
|
│ │ │ Slot Only ││ │ │ • Include all deployment info ││ │
|
|
│ │ │ ││ │ │ • Show staged, booted, rollback││ │
|
|
│ │ └─────────────┘│ │ │ ││ │
|
|
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Determine Output Format │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────┐ │
|
|
│ │ Format specified? │ │
|
|
│ └─────────────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
|
│ │ Yes │ │ No │ │
|
|
│ │ │ │ │ │
|
|
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
|
│ │ │ Use ││ │ │ Auto-detect Format ││ │
|
|
│ │ │ Specified ││ │ │ ││ │
|
|
│ │ │ Format ││ │ │ • Check --json flag ││ │
|
|
│ │ │ • JSON ││ │ │ • Check if terminal ││ │
|
|
│ │ │ • YAML ││ │ │ • Default to YAML ││ │
|
|
│ │ │ • Human ││ │ │ ││ │
|
|
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
|
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Output in Requested Format │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────┐ │
|
|
│ │ Format Type? │ │
|
|
│ └─────────────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
|
│ │ JSON │ │ YAML │ │ Human Readable│ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ ┌─────────────┐│ │ ┌─────────────┐│ │ ┌─────────────┐│ │
|
|
│ │ │ Serialize ││ │ │ Serialize ││ │ │ Format for ││ │
|
|
│ │ │ to JSON ││ │ │ to YAML ││ │ │ human ││ │
|
|
│ │ │ • Canonical ││ │ │ • Standard ││ │ │ reading ││ │
|
|
│ │ │ format ││ │ │ format ││ │ │ • Include ││ │
|
|
│ │ │ • Machine ││ │ │ • Machine ││ │ │ verbose ││ │
|
|
│ │ │ readable ││ │ │ readable ││ │ │ info if ││ │
|
|
│ │ └─────────────┘│ │ └─────────────┘│ │ │ requested ││ │
|
|
│ └─────────────────┘ └─────────────────┘ │ └─────────────┘│ │
|
|
│ └─────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Success │
|
|
│ │
|
|
│ • Status information displayed successfully │
|
|
│ • Format appropriate for use case │
|
|
│ • All deployment information included │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Core Status Gathering Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Core Status Gathering │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Get Stateroot Name │
|
|
│ │
|
|
│ • Extract stateroot from booted deployment │
|
|
│ • Use for filtering related deployments │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Partition Deployments │
|
|
│ │
|
|
│ • Get all deployments from sysroot │
|
|
│ • Separate related deployments from others │
|
|
│ • Filter by stateroot name │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Find Staged Deployment │
|
|
│ │
|
|
│ • Search for deployment marked as staged │
|
|
│ • Remove from related deployments list │
|
|
│ • Store for later processing │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Filter Booted Deployment │
|
|
│ │
|
|
│ • Remove booted deployment from related list │
|
|
│ • Keep for separate processing │
|
|
│ • Ensure no duplicates │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Get Rollback Deployment │
|
|
│ │
|
|
│ • Pop first deployment from related list │
|
|
│ • This becomes rollback deployment │
|
|
│ • Remaining deployments become "other" │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Determine Rollback Status │
|
|
│ │
|
|
│ • Compare rollback and booted deployment indices │
|
|
│ • Set rollback_queued flag │
|
|
│ • Determine boot order state │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Create Boot Entries │
|
|
│ │
|
|
│ • Process staged deployment │
|
|
│ • Process booted deployment │
|
|
│ • Process rollback deployment │
|
|
│ • Process other deployments │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Extract Image Information │
|
|
│ │
|
|
│ • Parse OCI image configuration │
|
|
│ • Extract image metadata │
|
|
│ • Create ImageStatus structures │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Create Host Specification │
|
|
│ │
|
|
│ • Determine image reference │
|
|
│ • Set boot order │
|
|
│ • Create HostSpec structure │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Determine Host Type │
|
|
│ │
|
|
│ • Check if booted deployment has image │
|
|
│ • Set HostType::BootcHost if container-based │
|
|
│ • Set to None if not container-based │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Create Host Status │
|
|
│ │
|
|
│ • Combine all deployment information │
|
|
│ • Set rollback_queued flag │
|
|
│ • Set host type │
|
|
│ • Create HostStatus structure │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Success │
|
|
│ │
|
|
│ • Complete status information gathered │
|
|
│ • All deployments processed │
|
|
│ • Image information extracted │
|
|
│ • Ready for output formatting │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Boot Entry Creation Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Boot Entry Creation │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Extract Deployment Info │
|
|
│ │
|
|
│ • Get deployment checksum │
|
|
│ • Get deployment osname │
|
|
│ • Create DeploymentInfo structure │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Check for Image Reference │
|
|
│ │
|
|
│ • Parse deployment origin │
|
|
│ • Look for refspec in origin │
|
|
│ • Parse OSTree image reference │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Query Image Commit │
|
|
│ │
|
|
│ • Query OSTree repository for image commit │
|
|
│ • Get cached update information │
|
|
│ • Extract image configuration │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Create Image Status │
|
|
│ │
|
|
│ • Parse OCI image configuration │
|
|
│ • Extract labels and metadata │
|
|
│ • Create ImageStatus structure │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Create Boot Entry │
|
|
│ │
|
|
│ • Combine deployment info and image status │
|
|
│ • Create BootEntry structure │
|
|
│ • Return complete boot entry │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Image Status Creation Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Image Status Creation │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Extract Image Labels │
|
|
│ │
|
|
│ • Get labels from image configuration │
|
|
│ • Look for version information │
|
|
│ • Look for timestamp information │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Parse Timestamp │
|
|
│ │
|
|
│ • Look for ANNOTATION_CREATED label │
|
|
│ • Parse RFC3339 timestamp │
|
|
│ • Convert to UTC timezone │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Extract Architecture │
|
|
│ │
|
|
│ • Get architecture from image configuration │
|
|
│ • Default to "unknown" if not found │
|
|
│ • Convert to string │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Create Image Status │
|
|
│ │
|
|
│ • Combine image reference and metadata │
|
|
│ • Set version, timestamp, digest, architecture │
|
|
│ • Create ImageStatus structure │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Format Selection Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Format Selection │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Check Format Option │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────┐ │
|
|
│ │ --format specified? │ │
|
|
│ └─────────────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
|
│ │ Yes │ │ No │ │
|
|
│ │ │ │ │ │
|
|
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
|
│ │ │ Use ││ │ │ Check Legacy Options ││ │
|
|
│ │ │ Specified ││ │ │ ││ │
|
|
│ │ │ Format ││ │ │ • Check --json flag ││ │
|
|
│ │ │ • JSON ││ │ │ • Check if terminal ││ │
|
|
│ │ │ • YAML ││ │ │ • Default to YAML ││ │
|
|
│ │ │ • Human ││ │ │ ││ │
|
|
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
|
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Check Legacy Options │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────┐ │
|
|
│ │ --json specified? │ │
|
|
│ └─────────────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
|
│ │ Yes │ │ No │ │
|
|
│ │ │ │ │ │
|
|
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
|
│ │ │ Use JSON ││ │ │ Check Terminal ││ │
|
|
│ │ │ Format ││ │ │ ││ │
|
|
│ │ └─────────────┘│ │ │ • Check if stdout is terminal ││ │
|
|
│ │ │ │ │ • Use Human Readable if yes ││ │
|
|
│ │ │ │ │ • Use YAML if no ││ │
|
|
│ │ │ │ │ ││ │
|
|
│ │ │ │ └─────────────────────────────────┘│ │
|
|
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Check Terminal Status │
|
|
│ │
|
|
│ ┌─────────────────────────────────────────────────────────────┐ │
|
|
│ │ stdout.is_terminal()? │ │
|
|
│ └─────────────────────────────────────────────────────────────┘ │
|
|
│ │ │
|
|
│ ▼ │
|
|
│ ┌─────────────────┐ ┌─────────────────────────────────────┐ │
|
|
│ │ Yes │ │ No │ │
|
|
│ │ │ │ │ │
|
|
│ │ ┌─────────────┐│ │ ┌─────────────────────────────────┐│ │
|
|
│ │ │ Use Human ││ │ │ Use YAML Format ││ │
|
|
│ │ │ Readable ││ │ │ ││ │
|
|
│ │ │ Format ││ │ │ • Machine readable ││ │
|
|
│ │ │ ││ │ │ • Programmatic parsing ││ │
|
|
│ │ │ • Interactive││ │ │ • Standard format ││ │
|
|
│ │ │ use ││ │ │ ││ │
|
|
│ │ │ • Human ││ │ │ ││ │
|
|
│ │ │ friendly ││ │ │ ││ │
|
|
│ │ └─────────────┘│ │ └─────────────────────────────────┘│ │
|
|
│ └─────────────────┘ └─────────────────────────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## Error Handling Flow
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Error Detection │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Error Classification │
|
|
│ │
|
|
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │
|
|
│ │ Format │ │ System │ │ Deployment │ │
|
|
│ │ Errors │ │ Errors │ │ Errors │ │
|
|
│ │ │ │ │ │ │ │
|
|
│ │ • Unsupported │ │ • Not OSTree │ │ • No deployments│ │
|
|
│ │ format │ │ booted │ │ found │ │
|
|
│ │ version │ │ • Storage │ │ • Invalid │ │
|
|
│ │ • Invalid │ │ access │ │ deployment │ │
|
|
│ │ format │ │ failed │ │ structure │ │
|
|
│ │ • JSON/YAML │ │ • OSTree │ │ • Image │ │
|
|
│ │ parsing │ │ repository │ │ parsing │ │
|
|
│ │ failed │ │ error │ │ failed │ │
|
|
│ └─────────────────┘ └─────────────────┘ └─────────────────┘ │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────────┐
|
|
│ Error Response │
|
|
│ │
|
|
│ • Display error message │
|
|
│ • Provide context information │
|
|
│ • Suggest remediation steps │
|
|
│ • Return appropriate exit code │
|
|
│ • Clean up any partial state │
|
|
└─────────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
This flowchart provides a comprehensive visual representation of the bootc status process, showing all decision points, operations, and data structures involved in displaying system status information.
|