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
This commit is contained in:
robojerk
commit
526f1c1afd
67 changed files with 34174 additions and 0 deletions
421
usr-overlay/bootc-usr-overlay-flowchart.md
Normal file
421
usr-overlay/bootc-usr-overlay-flowchart.md
Normal file
|
|
@ -0,0 +1,421 @@
|
|||
# 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.
|
||||
Loading…
Add table
Add a link
Reference in a new issue