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

40 KiB

Raw Blame History

bootc exec-in-host-mount-namespace - Process Flowchart

Overview

This document provides a visual representation of the bootc exec-in-host-mount-namespace process flow, showing the decision points, operations, and system state changes involved in executing commands in the host mount namespace.

Main Process Flow

┌─────────────────────────────────────────────────────────────────┐
│              bootc exec-in-host-mount-namespace                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Parse Command Arguments                      │
│                                                                 │
│  • Parse command and arguments                                 │
│  • Validate arguments                                          │
│  • Check command availability                                  │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Validate Prerequisites                      │
│                                                                 │
│  • Check if command is provided                                │
│  • Verify argument structure                                   │
│  • Validate command syntax                                     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Access Host Mount Namespace                 │
│                                                                 │
│  • Open /proc/1/ns/mnt                                         │
│  • Get host mount namespace file descriptor                    │
│  • Prepare for namespace switching                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Switch to Host Namespace                    │
│                                                                 │
│  • Use setns system call                                       │
│  • Switch to host mount namespace                              │
│  • Update process mount view                                   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Prepare Execution Environment               │
│                                                                 │
│  • Change to root directory                                    │
│  • Handle supermin workaround                                  │
│  • Set up execution context                                    │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Execute Command                             │
│                                                                 │
│  • Replace current process with target command                 │
│  • Execute command with arguments                              │
│  • Return execution result                                     │
└─────────────────────────────────────────────────────────────────┘

Detailed Process Flow

┌─────────────────────────────────────────────────────────────────┐
│                    Command Parsing                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Split Arguments                              │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Argument Structure                             │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Command       │  │   Arguments     │  │   Validation    │ │
│  │                 │  │                 │  │                 │ │
│  │  ┌─────────────┐│  │  ┌─────────────┐│  │  ┌─────────────┐│ │
│  │  │ First Arg   ││  │  │ Remaining   ││  │  │ Check Args  ││ │
│  │  │ (Command)   ││  │  │ Arguments   ││  │  │ Structure   ││ │
│  │  └─────────────┘│  │  └─────────────┘│  │  └─────────────┘│ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Namespace Access                            │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Open Host Namespace                         │
│                                                                 │
│  • Open /proc/1/ns/mnt file                                    │
│  • Get file descriptor for host mount namespace                │
│  • Prepare for setns operation                                 │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Namespace Switching                         │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              setns Operation                               │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                move_into_link_name_space                   │ │
│  │                                                             │ │
│  │  • Use rustix::thread::move_into_link_name_space           │ │
│  │  • Specify Mount namespace type                            │ │
│  │  • Switch to host mount namespace                          │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Environment Setup                           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Directory Operations                        │
│                                                                 │
│  • Change to root directory (chdir("/"))                       │
│  • Check for supermin workaround conditions                    │
│  • Handle chroot if necessary                                  │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Supermin Workaround                         │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │              Check Conditions                              │ │
│  └─────────────────────────────────────────────────────────────┘ │
│                       │                                         │
│                       ▼                                         │
│  ┌─────────────────┐    ┌─────────────────────────────────────┐ │
│  │   Normal Path   │    │           Supermin Path             │ │
│  │                 │    │                                     │ │
│  │  ┌─────────────┐│    │  ┌─────────────────────────────────┐│ │
│  │  │ /usr exists ││    │  │ /usr doesn't exist              ││ │
│  │  │ Continue    ││    │  │ /root/usr exists                ││ │
│  │  │ normally    ││    │  │ chroot("/root")                 ││ │
│  │  └─────────────┘│    │  └─────────────────────────────────┘│ │
│  └─────────────────┘    └─────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Command Execution                           │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Process Replacement                         │
│                                                                 │
│  • Create Command with target command and arguments            │
│  • Set process name (arg0)                                     │
│  • Execute command (exec)                                      │
│  • Replace current process                                     │
└─────────────────────────────────────────────────────────────────┘

Namespace Operations Flow

┌─────────────────────────────────────────────────────────────────┐
│                    Namespace Operations                        │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Current Namespace                           │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │   Container/Isolated Namespace                             │ │
│  │                                                             │ │
│  │ • Limited filesystem view                                  │ │
│  │ • Isolated mount points                                    │ │
│  │ • Restricted access                                        │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    setns Operation                         │ │
│  │                                                             │ │
│  │  • Open /proc/1/ns/mnt                                     │ │
│  │  • Get file descriptor                                     │ │
│  │  • Call setns system call                                  │ │
│  │  • Switch to host namespace                                │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Host Namespace                          │ │
│  │                                                             │ │
│  │ • Full filesystem view                                     │ │
│  │ • Host mount points                                        │ │
│  │ • Complete access                                          │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Error Handling Flow

┌─────────────────────────────────────────────────────────────────┐
│                    Error Detection                              │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Error Classification                         │
│                                                                 │
│  ┌─────────────────┐  ┌─────────────────┐  ┌─────────────────┐ │
│  │   Argument      │  │   Namespace     │  │   Execution     │ │
│  │   Errors        │  │   Errors        │  │   Errors        │ │
│  │                 │  │                 │  │                 │ │
│  │ • Missing Cmd   │  │ • Access Denied │  │ • Command Not   │ │
│  │ • Invalid Args  │  │ • Namespace Not │  │   Found         │ │
│  │ • Bad Syntax    │  │   Available     │  │ • Permission    │ │
│  │                 │  │ • setns Failed  │  │   Denied        │ │
│  └─────────────────┘  └─────────────────┘  └─────────────────┘ │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Error Response                               │
│                                                                 │
│  • Display error message                                        │
│  • Provide context information                                  │
│  • Suggest remediation steps                                    │
│  • Return appropriate exit code                                 │
│  • Log error details                                            │
└─────────────────────────────────────────────────────────────────┘

System State Transitions

┌─────────────────────────────────────────────────────────────────┐
│                    System States                                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Initial State                                │
│                                                                 │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │   Container/Isolated Environment                           │ │
│  │                                                             │ │
│  │ • Limited filesystem access                                │ │
│  │ • Isolated mount namespace                                 │ │
│  │ • Restricted system view                                   │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Execute Command                         │ │
│  │                                                             │ │
│  │  • Parse arguments                                          │ │
│  │  • Access host namespace                                    │ │
│  │  • Switch namespaces                                        │ │
│  └─────────────────────────────────────────────────────────────┘ │
│           │                                                     │
│           ▼                                                     │
│  ┌─────────────────────────────────────────────────────────────┐ │
│  │                    Final State                              │ │
│  │                                                             │ │
│  │ • Host mount namespace access                              │ │
│  │ • Full filesystem view                                     │ │
│  │ • Command executed in host context                         │ │
│  └─────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────┘

Command Execution Flow

┌─────────────────────────────────────────────────────────────────┐
│                    Command Execution                            │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Prepare Command                              │
│                                                                 │
│  • Create Command struct                                        │
│  • Set command name                                             │
│  • Set arguments                                                │
│  • Set process name (arg0)                                     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Execute Command                             │
│                                                                 │
│  • Use exec() to replace current process                       │
│  • Execute command with arguments                              │
│  • Return execution result                                     │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Process Replacement                         │
│                                                                 │
│  • Current process is replaced                                 │
│  • Target command becomes new process                          │
│  • Execution continues in host namespace                       │
└─────────────────────────────────────────────────────────────────┘

Helper Function Flow

┌─────────────────────────────────────────────────────────────────┐
│                    Helper Functions                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    run_in_host_mountns                         │
│                                                                 │
│  • Create Command for host mount namespace execution           │
│  • Set executable path                                          │
│  • Add exec-in-host-mount-namespace argument                   │
│  • Return prepared Command                                      │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    ensure_self_unshared_mount_namespace        │
│                                                                 │
│  • Check if already in mount namespace                         │
│  • Check if root user                                           │
│  • Unshare mount namespace if needed                           │
│  • Re-exec with unshared namespace                             │
└─────────────────────────────────────────────────────────────────┘

Use Case Flows

1. Container Operations

┌─────────────────────────────────────────────────────────────────┐
│                    Container Operations                        │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Container Environment                       │
│                                                                 │
│  • Limited filesystem view                                     │
│  • Isolated mount namespace                                    │
│  • Restricted access to host                                   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Execute in Host Namespace                   │
│                                                                 │
│  • Switch to host mount namespace                              │
│  • Access host filesystem                                      │
│  • Perform host operations                                     │
└─────────────────────────────────────────────────────────────────┘

2. Installation Support

┌─────────────────────────────────────────────────────────────────┐
│                    Installation Support                        │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Installation Process                        │
│                                                                 │
│  • Running in container context                                │
│  • Need access to host filesystem                              │
│  • Perform installation operations                             │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Host Filesystem Access                      │
│                                                                 │
│  • Execute commands in host namespace                          │
│  • Access host filesystem                                      │
│  • Complete installation                                       │
└─────────────────────────────────────────────────────────────────┘

3. Debugging and Maintenance

┌─────────────────────────────────────────────────────────────────┐
│                    Debugging and Maintenance                   │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Debug Environment                           │
│                                                                 │
│  • Isolated debugging environment                              │
│  • Need access to host system                                  │
│  • Perform debugging operations                                │
└─────────────────────────────────────────────────────────────────┘
                                │
                                ▼
┌─────────────────────────────────────────────────────────────────┐
│                    Host System Access                          │
│                                                                 │
│  • Execute debugging commands in host namespace                │
│  │  • Check host filesystem                                    │
│  │  • View host processes                                      │
│  │  • Monitor host system                                      │
│  • Complete debugging operations                               │
└─────────────────────────────────────────────────────────────────┘

This flowchart provides a comprehensive visual representation of the bootc exec-in-host-mount-namespace process, showing all decision points, operations, and state transitions involved in executing commands in the host mount namespace.

40 KiB Raw Blame History