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

38 KiB

Raw Permalink Blame History

bootc usr-overlay - Process Flowchart

Overview

This document provides a visual representation of the bootc usr-overlay process flow, showing the decision points, operations, and filesystem changes involved in creating a transient writable overlay on the /usr directory.

Main Process Flow

┌─────────────────────────────────────────────────────────────────┐
│                    bootc usr-overlay                           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Validate Prerequisites                      │
│                                                                 │
│  • Check if running as root or with appropriate privileges     │
│  • Verify OSTree is available and accessible                   │
│  • Check if system is bootc-compatible                         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Check Current State                         │
│                                                                 │
│  • Check if /usr is currently read-only                       │
│  • Verify OSTree deployment status                            │
│  • Check if overlay is already active                         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Execute OSTree Unlock                       │
│                                                                 │
│  • Call `ostree admin unlock` command                         │
│  • Create overlay filesystem on /usr                          │
│  • Make /usr directory writable                                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Verify Overlay Creation                     │
│                                                                 │
│  • Check if overlay filesystem is mounted                     │
│  • Verify /usr is now writable                                │
│  • Confirm overlay structure is correct                        │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Provide User Feedback                       │
│                                                                 │
│  • Display success message                                     │
│  • Inform user about overlay status                            │
│  • Provide usage instructions                                 │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • Transient overlay active on /usr                           │
│  • /usr directory is now writable                              │
│  • Changes will be discarded on reboot                         │
└─────────────────────────────────────────────────────────────────┘

OSTree Unlock Process Flow

┌─────────────────────────────────────────────────────────────────┐
│                    OSTree Admin Unlock                         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Check Deployment Status                      │
│                                                                 │
│  • Get current OSTree deployment                              │
│  • Check if deployment is locked                               │
│  • Verify deployment is bootable                               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Create Overlay Filesystem                   │
│                                                                 │
│  • Set up overlay filesystem structure                         │
│  • Create lower layer (original /usr)                         │
│  • Create upper layer (writable overlay)                      │
│  • Create work directory (temporary files)                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Mount Overlay on /usr                       │
│                                                                 │
│  • Mount overlay filesystem on /usr                           │
│  • Set up copy-on-write mechanism                             │
│  • Enable write operations on /usr                            │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Update OSTree State                         │
│                                                                 │
│  • Mark deployment as unlocked                                 │
│  • Update deployment metadata                                  │
│  • Set up auto-lock on reboot                                 │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • Overlay filesystem active                                   │
│  • /usr directory writable                                     │
│  • Changes will be transient                                   │
└─────────────────────────────────────────────────────────────────┘

Overlay Filesystem Structure

┌─────────────────────────────────────────────────────────────────┐
│                    Overlay Filesystem Structure                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    /usr (Mount Point)                          │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Overlay Mount                            │ │
│  │                                                             │ │
│  │  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────┐ │ │
│  │  │   Lower Layer   │  │   Upper Layer   │  │ Work Layer  │ │ │
│  │  │                 │  │                 │  │             │ │ │
│  │  │ • Original /usr │  │ • Writable      │  │ • Temporary │ │ │
│  │  │ • Read-only     │  │ • Changes       │  │ • COW files │ │ │
│  │  │ • Base system   │  │ • New files     │  │ • Metadata  │ │ │
│  │  │ • Immutable     │  │ • Modifications │  │ • Operations│ │ │
│  │  └─────────────────┘  └─────────────────┘  └─────────────┘ │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Package Installation Flow

┌─────────────────────────────────────────────────────────────────┐
│                    Package Installation                        │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Check Overlay Status                        │
│                                                                 │
│  • Verify /usr is writable                                     │
│  • Check overlay filesystem is active                          │
│  • Confirm package manager can operate                         │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Package Manager Operation                   │
│                                                                 │
│  • Update package lists (apt update, dnf check-update)        │
│  • Download package files                                      │
│  • Install packages to overlay                                 │
│  • Update package database                                     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Overlay Write Operations                    │
│                                                                 │
│  • Files written to upper layer                               │
│  • Copy-on-write for modified files                           │
│  • Metadata updated in overlay                                │
│  • Original files preserved in lower layer                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Verify Installation                         │
│                                                                 │
│  • Check if packages are accessible                           │
│  │  • Verify files are in overlay                             │
│  │  • Test package functionality                              │
│  │  • Confirm changes are transient                           │
└─────────────────────────────────────────────────────────────────┘

Unmounting Process Flow

┌─────────────────────────────────────────────────────────────────┐
│                    Unmounting Overlay                          │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Check Active Processes                       │
│                                                                 │
│  • Identify processes using /usr files                        │
│  • Check for open file handles                                │
│  • Determine if unmount is safe                               │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Choose Unmount Method                       │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Can unmount safely?                           │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │      Yes        │    │               No                    │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ Regular     ││    │  │     Lazy Unmount                ││ │
│  │  │ Unmount     ││    │  │                                 ││ │
│  │  │ • umount    ││    │  │  • umount -l /usr               ││ │
│  │  │   /usr      ││    │  │  • Unmount when references      ││ │
│  │  │ • Immediate ││    │  │    released                      ││ │
│  │  │   unmount   ││    │  │  • Safer for active processes   ││ │
│  │  └─────────────┘│    │  └─────────────────────────────────┘│ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Clean Up Overlay                            │
│                                                                 │
│  • Remove overlay filesystem                                   │
│  • Clean up work directory                                     │
│  • Restore original /usr state                                 │
│  • Update OSTree deployment status                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Verify Unmount                              │
│                                                                 │
│  • Check /usr is no longer writable                           │
│  • Verify overlay is removed                                  │
│  • Confirm original state restored                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                        Success                                  │
│                                                                 │
│  • Overlay successfully removed                                │
│  • /usr returned to read-only state                           │
│  • All changes discarded                                       │
└─────────────────────────────────────────────────────────────────┘

Error Handling Flow

┌─────────────────────────────────────────────────────────────────┐
│                    Error Detection                              │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Error Classification                         │
│                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Permission    │  │   OSTree        │  │   System        │ │
│  │   Errors        │  │   Errors        │  │   Errors        │ │
│  │                 │  │                 │  │                 │ │
│  │ • Not root      │  │ • OSTree not    │  │ • /usr already  │ │
│  │ • Permission    │  │   available     │  │   writable      │ │
│  │   denied        │  │ • Deployment    │  │ • Overlay       │ │
│  │ • Insufficient  │  │   locked        │  │   already       │ │
│  │   privileges    │  │ • Command       │  │   active        │ │
│  │                 │  │   failed        │  │ • Mount         │ │
│  │                 │  │                 │  │   failed        │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    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                                │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │   /usr Read-only State                                      │ │
│  │                                                             │ │
│  │ • /usr mounted read-only                                    │ │
│  │ • OSTree deployment locked                                  │ │
│  │ • No overlay filesystem                                     │ │
│  │ • Immutable system state                                    │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    bootc usr-overlay                        │ │
│  │                                                             │ │
│  │  • Call ostree admin unlock                                 │ │
│  │  • Create overlay filesystem                                │ │
│  │  • Mount overlay on /usr                                    │ │
│  │  • Enable write operations                                  │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │   /usr Writable State                                       │ │
│  │                                                             │ │
│  │ • /usr mounted with overlay                                 │ │
│  │ • OSTree deployment unlocked                                │ │
│  │ • Overlay filesystem active                                 │ │
│  │ • Writable system state                                     │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Package Operations                       │ │
│  │                                                             │ │
│  │  • Install packages to overlay                             │ │
│  │  • Modify files in overlay                                 │ │
│  │  • Use installed tools                                     │ │
│  │  • Changes are transient                                   │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Reboot or Unmount                       │ │
│  │                                                             │ │
│  │  • Reboot: Auto-restore to read-only                      │ │
│  │  • Unmount: Manual restore to read-only                   │ │
│  │  • All changes discarded                                   │ │
│  │  • Return to initial state                                 │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Filesystem Impact

┌─────────────────────────────────────────────────────────────────┐
│                    Filesystem Impact                            │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Before Overlay                               │
│                                                                 │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │      /usr       │    │            /etc                     │ │
│  │                 │    │                                     │ │
│  │ • Read-only     │    │ • Writable                          │ │
│  │ • Immutable     │    │ • Persistent                        │ │
│  │ • Base system   │    │ • Configuration                     │ │
│  │ • OSTree        │    │ • Not affected by overlay           │ │
│  │   managed       │    │                                     │ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    /var                                     │ │
│  │                                                             │ │
│  │ • Writable                                                  │ │
│  │ • Persistent                                                │ │
│  │ • Runtime data                                              │ │
│  │ • Not affected by overlay                                   │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    After Overlay                                │
│                                                                 │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │      /usr       │    │            /etc                     │ │
│  │                 │    │                                     │ │
│  │ • Writable      │    │ • Writable                          │ │
│  │ • Overlay       │    │ • Persistent                        │ │
│  │ • Transient     │    │ • Configuration                     │ │
│  │ • Changes       │    │ • Not affected by overlay           │ │
│  │   discarded     │    │                                     │ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    /var                                     │ │
│  │                                                             │ │
│  │ • Writable                                                  │ │
│  │ • Persistent                                                │ │
│  │ • Runtime data                                              │ │
│  │ • Not affected by overlay                                   │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

This flowchart provides a comprehensive visual representation of the bootc usr-overlay process, showing all decision points, operations, and filesystem changes involved in creating and managing a transient writable overlay on the /usr directory.

38 KiB Raw Permalink Blame History