# nvidia/enroot architecture

> Architecture diagram of the GitHub repository nvidia/enroot, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/nvidia/enroot
- Repository: https://github.com/nvidia/enroot

## Overview

##### Project type and purpose
- Enroot is a CLI‐based, unprivileged “container” tool written in C (under bin/) and Bash (under src/).
- It imports container images (e.g., Docker), creates sandboxed root filesystems (squashfs/overlay), sets up user & mount namespaces, and launches processes without requiring root privileges.

##### File structure
- bin/ (C sources): core engine for namespace setup (enroot‐nsenter), mounting (enroot‐mount), rootfs conversion (enroot‐mksquashovlfs, enroot‐aufs2ovlfs), switching root (enroot‐switchroot).
- src/ (shell scripts): high‐level commands & workflows (bundle.sh, docker.sh, runtime.sh, common.sh).
- conf/: system‐wide & per‐user configuration files (enroot.conf.d, mounts, environ) and hook scripts (conf/hooks).
- deps/: bundled third‐party code (libbsd, musl, linux‐headers, makeself).
- pkg/: packaging logic (deb, rpm).
- doc/: user & developer documentation for commands, configuration, image format.

##### README for additional insights
- Emphasis on a KISS, daemon-less approach using Linux user/mount namespaces.
- Key workflow stages: import → create → start.
- Extensibility via standard hooks and a simple image format (squashfs).

##### Main components & relationships
a. CLI Front-End
- src/*.sh scripts parse user commands (import, create, start, exec).
b. Image Importer
- docker.sh fetches layers from a registry; enroot‐mksquashovlfs (or aufs2ovlfs) converts layers into a single squashfs.
c. Configuration & Hook Subsystem
- conf/enroot.conf.d and conf/hooks/*.sh are loaded at each lifecycle stage. Hooks run in the namespace to customize mounts, environment, or GPU support (e.g., 98‐nvidia.sh).
d. Container Runtime Core
- bin/enroot-mount mounts the squashfs (and overlay if needed).
- bin/enroot-nsenter + bin/enroot-switchroot enter user & mount namespaces, pivot root, and launch the target process.
e. Environment Scripts
- runtime.sh applies environment variables (conf/environ/*), executes hooks, then execs the user’s command.
f. Kernel Interfaces
- Uses unprivileged user namespace, mount namespace, pivot_root, mount(), etc.
g. Optional Libraries
- Bundled libbsd for portability; integration with libnvidia-container via hooks for GPU.

##### Architectural patterns & design principles
- Modular pipeline: import → conversion → mount → namespace entry → run.
- Separation of concerns: C code for syscalls & performance; shell scripts for orchestration & configuration.
- Extensible via hook scripts and a flat config directory.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Services
    Registry(("Docker Registry")):::external

    %% Import Stage
    subgraph "Import Stage"
        direction TB
        DockerScript["docker.sh"]:::script
        Mksquashfs["enroot-mksquashovlfs"]:::binary
        Aufs2ovlfs["enroot-aufs2ovlfs"]:::binary
        SquashFS[("squashfs Image")]:::artifact
    end

    Registry -->|"fetch layers"| DockerScript
    DockerScript -->|"convert layers"| Mksquashfs
    DockerScript -->|"convert layers"| Aufs2ovlfs
    Mksquashfs --> SquashFS
    Aufs2ovlfs --> SquashFS

    %% Create Stage
    subgraph "Create Stage"
        direction TB
        MountBin["enroot-mount"]:::binary
        Overlay[("overlayfs Overlay")]:::artifact
        RootFS[("Target RootFS Dir")]:::artifact
    end

    SquashFS -->|"mount image"| MountBin
    MountBin --> Overlay
    MountBin --> RootFS

    %% Start Stage
    subgraph "Start Stage"
        direction TB
        NsenterBin["enroot-nsenter"]:::binary
        SwitchRoot["enroot-switchroot"]:::binary
        RuntimeScript["runtime.sh"]:::script
        EnvFile["10-terminal.env"]:::config
        UserProcess(("User Process")):::process
    end

    RootFS --> NsenterBin
    NsenterBin --> SwitchRoot
    SwitchRoot --> RuntimeScript
    RuntimeScript --> EnvFile
    RuntimeScript -->|"exec"| UserProcess

    %% Configuration & Hooks
    subgraph "Configuration & Hooks"
        direction TB
        ConfDir["conf/enroot.conf.d"]:::config
        subgraph Hooks
            direction TB
            Hook1["10-aptfix.sh"]:::hook
            Hook2["10-cgroups.sh"]:::hook
            Hook3["10-devices.sh"]:::hook
            Hook4["10-home.sh"]:::hook
            Hook5["10-localtime.sh"]:::hook
            Hook6["10-shadow.sh"]:::hook
            Hook7["98-nvidia.sh"]:::hook
            Hook8["99-mellanox.sh"]:::hook
            Hook9["50-mig-config.sh"]:::hook
            Hook10["50-sharp.sh"]:::hook
            Hook11["50-slurm-pmi.sh"]:::hook
            Hook12["50-slurm-pytorch.sh"]:::hook
        end
    end

    %% Hook Integration
    ConfDir -.-> DockerScript
    ConfDir -.-> MountBin
    ConfDir -.-> NsenterBin
    ConfDir -.-> RuntimeScript

    Hooks -.-> MountBin
    Hooks -.-> RuntimeScript

    %% Kernel Interfaces
    Kernel(("Kernel\n(userns, mountns,\npivot_root,mount)")):::kernel
    NsenterBin --> Kernel
    MountBin --> Kernel
    SwitchRoot --> Kernel

    %% Bundled Dependencies & Packaging
    Deps["deps/libbsd"]:::deps
    PackagingDeb["pkg/deb"]:::pkg
    PackagingRpm["pkg/rpm"]:::pkg

    Deps -.-> RuntimeScript
    PackagingDeb -.-> DockerScript
    PackagingRpm -.-> DockerScript

    %% Click Events
    click DockerScript "https://github.com/nvidia/enroot/blob/main/src/docker.sh"
    click Mksquashfs "https://github.com/nvidia/enroot/blob/main/bin/enroot-mksquashovlfs.c"
    click Aufs2ovlfs "https://github.com/nvidia/enroot/blob/main/bin/enroot-aufs2ovlfs.c"
    click MountBin "https://github.com/nvidia/enroot/blob/main/bin/enroot-mount.c"
    click NsenterBin "https://github.com/nvidia/enroot/blob/main/bin/enroot-nsenter.c"
    click SwitchRoot "https://github.com/nvidia/enroot/blob/main/bin/enroot-switchroot.c"
    click RuntimeScript "https://github.com/nvidia/enroot/blob/main/src/runtime.sh"
    click EnvFile "https://github.com/nvidia/enroot/blob/main/conf/environ/10-terminal.env"
    click ConfDir "https://github.com/nvidia/enroot/tree/main/conf/enroot.conf.d/"
    click Hook1 "https://github.com/nvidia/enroot/blob/main/conf/hooks/10-aptfix.sh"
    click Hook2 "https://github.com/nvidia/enroot/blob/main/conf/hooks/10-cgroups.sh"
    click Hook3 "https://github.com/nvidia/enroot/blob/main/conf/hooks/10-devices.sh"
    click Hook4 "https://github.com/nvidia/enroot/blob/main/conf/hooks/10-home.sh"
    click Hook5 "https://github.com/nvidia/enroot/blob/main/conf/hooks/10-localtime.sh"
    click Hook6 "https://github.com/nvidia/enroot/blob/main/conf/hooks/10-shadow.sh"
    click Hook7 "https://github.com/nvidia/enroot/blob/main/conf/hooks/98-nvidia.sh"
    click Hook8 "https://github.com/nvidia/enroot/blob/main/conf/hooks/99-mellanox.sh"
    click Hook9 "https://github.com/nvidia/enroot/blob/main/conf/hooks/extra/50-mig-config.sh"
    click Hook10 "https://github.com/nvidia/enroot/blob/main/conf/hooks/extra/50-sharp.sh"
    click Hook11 "https://github.com/nvidia/enroot/blob/main/conf/hooks/extra/50-slurm-pmi.sh"
    click Hook12 "https://github.com/nvidia/enroot/blob/main/conf/hooks/extra/50-slurm-pytorch.sh"
    click Deps "https://github.com/nvidia/enroot/tree/main/deps/libbsd/"
    click PackagingDeb "https://github.com/nvidia/enroot/tree/main/pkg/deb/"
    click PackagingRpm "https://github.com/nvidia/enroot/tree/main/pkg/rpm/"

    %% Styles
    classDef binary fill:#cce5ff,stroke:#004085,color:#004085;
    classDef script fill:#d4edda,stroke:#155724,color:#155724;
    classDef config fill:#fff3cd,stroke:#856404,color:#856404;
    classDef hook fill:#ffeeba,stroke:#856404,color:#856404;
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#6c757d;
    classDef kernel fill:#f5c6cb,stroke:#721c24,color:#721c24;
    classDef artifact fill:#fff,stroke:#343a40,color:#343a40;
    classDef process fill:#d1ecf1,stroke:#0c5460,color:#0c5460;
    classDef deps fill:#e8dfff,stroke:#5a32a3,color:#5a32a3;
    classDef pkg fill:#d6d8db,stroke:#1b1e21,color:#1b1e21;
```
