robojerk 526f1c1afd 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

2025-09-15 14:02:28 -07:00

44 KiB

Raw Blame History

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.

44 KiB Raw Blame History