# multiarch/qemu-user-static architecture

> Architecture diagram of the GitHub repository multiarch/qemu-user-static, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/multiarch/qemu-user-static
- Repository: https://github.com/multiarch/qemu-user-static

## Overview

##### Project type and purpose
- This is a container-based tooling project that publishes Docker (and Podman/Singularity) images to enable the execution of foreign-architecture Linux binaries via QEMU user-mode emulation and the Linux kernel’s binfmt_misc subsystem.
- Its primary function is to provide:
- A “register” image that runs a shell script to configure binfmt_misc entries in the host kernel
- Per-architecture images containing the QEMU static interpreter(s)
- A convenience “latest” image bundling all supported QEMU-arch binaries plus the register script

##### File structure
- Top-level:
- containers/latest/Dockerfile & register.sh – builds the all-in-one image
- containers/register/.gitkeep – holds the register image’s context
- run.sh, test.sh – helpers for local development/testing
- docs/ – markdown guides on usage, developer workflows, examples
- .github/workflows/actions.yml – CI for building/publishing images
- Key files:
- containers/latest/Dockerfile – installs qemu-<arch>-static binaries + register.sh
- register.sh – the script that writes to /proc/sys/fs/binfmt_misc to register/unregister interpreters

##### Extract architecture details from README
- Components described:
- Host OS & kernel with binfmt_misc mounted at /proc/sys/fs/binfmt_misc
- Container runtime (Docker/Podman/Singularity)
- QEMU user-mode static binaries (/usr/bin/qemu-*-static) inside images
- register.sh which orchestrates configuration
- Usage flows:
- “docker run --privileged multiarch/qemu-user-static --reset -p yes” → kernel config
- Subsequent “docker run arm64v8/ubuntu uname -m” → kernel invokes QEMU interpreter

##### Main components
a. Host Machine
- Linux kernel
- binfmt_misc pseudo-filesystem
- Docker daemon (or Podman/Singularity runtime)
b. multiarch/qemu-user-static Container Images
- “register” image running register.sh
- “latest” and per-arch images bundling QEMU static binaries
c. QEMU user-mode static binaries
- qemu-aarch64-static, qemu-arm-static, etc.
d. Target Multi-arch Container (e.g., arm64v8/ubuntu)
e. Developer Workstation (build/test scripts, CI pipeline)
f. Docker Hub (image registry)
g. External Tools: qemu-binfmt-conf.sh from QEMU project

##### Relationships and interactions
- (1) CI pipeline builds images → pushes to Docker Hub
- (2) User runs “docker run --privileged multiarch/qemu-user-static:register” → register.sh writes entries under /proc/sys/fs/binfmt_misc
- (3) User pulls QEMU images (latest or per-arch) as needed
- (4) User runs foreign-arch container (arm64v8/ubuntu) → kernel sees ELF magic → binfmt_misc invokes /usr/bin/qemu-<arch>-static from registered path → interpreter executes the binary
- (5) run.sh/test.sh simulate local dev/test flows

##### Architectural patterns and design principles
- Separation of concerns:
- Registration logic isolated in a minimal “register” image
- Interpreter binaries isolated per-arch (or all-in-one in “latest”)
- Micro-tooling approach:
- Leverages existing container runtimes and kernel features
- No custom daemons or services—pure shell + binfmt_misc
- CI/CD automation:
- GitHub Actions automates multi-arch builds and Docker Hub publishes

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Top Layer: Developer Workstation & CI
    subgraph "Developer Layer"
        DScripts["run.sh"]:::script
        TScripts["test.sh"]:::script
        CI["CI Pipeline\n(actions.yml)"]:::ci
    end

    %% Documentation Layer
    subgraph "Documentation"
        DocsDir["/docs"]:::docs
        CIguide["developers_guide.md"]:::docs
        Examples["examples.md"]:::docs
        Compat["compatible_images.md"]:::docs
        ImagesFolder["images/"]:::docs
    end

    %% Middle Layer: Registry & Images
    DockerHub[(Docker Hub)]:::registry

    subgraph "Container Images"
        RegImg["multiarch/qemu-user-static:register"]:::container
        LatestImg["multiarch/qemu-user-static:latest"]:::container
        PerArch["Per-Arch Images\n(qemu-*-static)"]:::container
    end

    %% Bottom Layer: Host Stack
    subgraph "Host Stack"
        Kernel["Linux Kernel"]:::kernel
        BfmtFS["/proc/sys/fs/binfmt_misc"]:::kernel
        Runtime["Container Runtime\n(Docker/Podman/Singularity)"]:::runtime
        QEMUStatic["QEMU Static Interpreters\n(/usr/bin/qemu-*-static)"]:::kernel
    end

    %% Flows
    DScripts --> CI
    TScripts --> CI
    CI -->|"Push images"| DockerHub

    DockerHub -->|"Pull"| RegImg
    DockerHub -->|"Pull"| LatestImg
    DockerHub -->|"Pull"| PerArch

    RegImg -->|"Run --privileged"| BfmtFS
    RegImg -->|"Exec register.sh"| BfmtFS

    PerArch -->|"Run target container"| Runtime
    LatestImg -->|"Run target container"| Runtime

    Runtime -->|"Container launch"| Kernel
    Kernel -->|"ELF magic detection"| BfmtFS
    BfmtFS -->|"Invoke interpreter"| QEMUStatic
    QEMUStatic -->|"Execute binary"| Kernel

    %% Click Events
    click DScripts "https://github.com/multiarch/qemu-user-static/blob/master//run.sh"
    click TScripts "https://github.com/multiarch/qemu-user-static/blob/master//test.sh"
    click CI "https://github.com/multiarch/qemu-user-static/blob/master//.github/workflows/actions.yml"
    click RegImg "https://github.com/multiarch/qemu-user-static/blob/master//containers/register/.gitkeep"
    click LatestImg "https://github.com/multiarch/qemu-user-static/tree/master//containers/latest/Dockerfile"
    click QEMUStatic "https://github.com/multiarch/qemu-user-static/blob/master//containers/latest/register.sh"
    click DocsDir "https://github.com/multiarch/qemu-user-static/tree/master//docs"
    click CIguide "https://github.com/multiarch/qemu-user-static/blob/master//docs/developers_guide.md"
    click Examples "https://github.com/multiarch/qemu-user-static/blob/master//docs/examples.md"
    click Compat "https://github.com/multiarch/qemu-user-static/blob/master//docs/compatible_images.md"
    click ImagesFolder "https://github.com/multiarch/qemu-user-static/tree/master//docs/images"

    %% Styles
    classDef container fill:#ADD8E6,stroke:#000,stroke-width:1px;
    classDef kernel fill:#90EE90,stroke:#000,stroke-width:1px;
    classDef runtime fill:#FFA500,stroke:#000,stroke-width:1px;
    classDef registry fill:#D3D3D3,stroke:#000,stroke-width:1px;
    classDef script fill:#E6E6FA,stroke:#000,stroke-width:1px;
    classDef ci fill:#F0E68C,stroke:#000,stroke-width:1px;
    classDef docs fill:#FFFACD,stroke:#000,stroke-width:1px;
```
