# 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.