# opensvc/multipath-tools architecture

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

- Interactive diagram: https://gitdiagram.com/opensvc/multipath-tools
- Repository: https://github.com/opensvc/multipath-tools

## Overview

##### Project Type and Purpose
- This project is a set of system-level tools for Linux that work with the device mapper multipathing driver.
- Its purpose is to provide several command‐line utilities and daemons (e.g., multipath, multipathd, multipathc, mpathpersist, and kpartx) to automate device mapper configuration, manage persistent SCSI reservations, and create device maps from partition tables.
- The README confirms that these tools interact directly with kernel subsystems (device mapper, SCSI, NVMe) and relies on a variety of system-level libraries.

##### Analyzing the File Structure
- The project is organized into several top-level directories and files:
– .github directory: Contains CI/CD configuration (actions, workflows) that automate building, unit tests, and ABI checks.
– Individual directories for each of the binaries: “multipath”, “multipathd”, “mpathpersist”, “kpartx”, with their source files in subdirectories.
– Several libraries or “lib” directories (libdmmp, libmpathcmd, libmpathpersist, libmpathutil, libmpathvalid, libmultipath) that encapsulate common functionality: interacting with device mapper, persistent reservations, configuration parsing, logging, etc.
– The tests directory includes unit tests that validate behaviors.
- The Makefiles and build scripts (e.g., create-config.mk, Makefile.inc) provide insight into the build process and the specific configurable paths, linking with external libraries (libdevmapper, libsystemd, etc.).

##### Key Components and Their Relationships
- Main Binaries and Daemons:
- multipath: Performs automatic configuration for device mapper multipathing.
- multipathd: Acts as a persistent daemon, coordinating with the kernel’s device mapper and handling dynamic events.
- multipathc: An interactive client for communicating with multipathd.
- mpathpersist: Manages SCSI persistent reservations on multipath devices.
- kpartx: Creates device maps from partition tables.
- Core Libraries:
- libmultipath and the other libmpath* directories: Provide the underlying functionality (e.g., configuration parsing, logging, device scanning, and error handling) that are shared across multiple binaries.
- libdmmp: Offers abstractions and interfaces for interacting with the device mapper multipathing components.
- External Dependencies:
- The build depends on libraries such as libdevmapper, libaio, libudev, libjson-c, liburcu, and libsystemd.
- There is support for command line editing via libedit or libreadline (conditional upon build settings).
- Build and Continuous Integration:
- GitHub workflows in the .github directory define various CI steps (building on different architectures, unit testing, and ABI verification).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% User/Operator Interface Layer
    subgraph "User/Operator Interface Layer"
        A["Multipath CLI (multipath)"]:::cli
        B["Interactive Client (multipathc)"]:::cli
    end

    %% Core Service / Daemon Layer
    subgraph "Core Service / Daemon Layer"
        C["Multipath Daemon (multipathd)"]:::daemon
    end

    %% Support/Helper Tools
    subgraph "Support/Helper Tools"
        D["Persistent Reservation Manager (mpathpersist)"]:::helper
        E["Partition Mapping Utility (kpartx)"]:::helper
    end

    %% Library Layer
    subgraph "Library Layer"
        F["Library for Device Mapper Multipathing (libdmmp)"]:::lib
        G["Command Utility Library (libmpathcmd)"]:::lib
        H["Persistent Reservation Library (libmpathpersist)"]:::lib
        I["Utility Library (libmpathutil)"]:::lib
        J["Validation Library (libmpathvalid)"]:::lib
        K["Core Multipath Library (libmultipath)"]:::lib
    end

    %% External System Interfaces
    subgraph "External System Interfaces"
        L["Linux Kernel Interfaces"]:::external
    end

    %% Build & CI/CD Infrastructure
    subgraph "Build & CI/CD Infrastructure"
        M["Build & CI/CD (.github)"]:::build
    end

    %% Relationships and Data Flow
    A -->|"triggers"| C
    B -->|"IPC"| C
    C -->|"manages"| L

    %% Dependencies on Libraries (representative dependency using Core Multipath Library)
    A -->|"uses"| K
    C -->|"uses"| K
    D -->|"uses"| K
    E -->|"uses"| K

    %% Build & CI/CD triggers builds for binaries and tools
    M -->|"builds"| A
    M -->|"builds"| C
    M -->|"builds"| D
    M -->|"builds"| E

    %% Click Events
    click A "https://github.com/opensvc/multipath-tools/blob/master/multipath/main.c"
    click B "https://github.com/opensvc/multipath-tools/blob/master/multipathd/multipathc.c"
    click C "https://github.com/opensvc/multipath-tools/blob/master/multipathd/main.c"
    click D "https://github.com/opensvc/multipath-tools/blob/master/mpathpersist/main.c"
    click E "https://github.com/opensvc/multipath-tools/blob/master/kpartx/kpartx.c"
    click F "https://github.com/opensvc/multipath-tools/blob/master/libdmmp/libdmmp.c"
    click G "https://github.com/opensvc/multipath-tools/blob/master/libmpathcmd/mpath_cmd.c"
    click H "https://github.com/opensvc/multipath-tools/blob/master/libmpathpersist/mpath_persist.c"
    click I "https://github.com/opensvc/multipath-tools/blob/master/libmpathutil/util.c"
    click J "https://github.com/opensvc/multipath-tools/blob/master/libmpathvalid/mpath_valid.c"
    click K "https://github.com/opensvc/multipath-tools/blob/master/libmultipath/alias.c"
    click M "https://github.com/opensvc/multipath-tools/tree/master/.github/"

    %% Styles
    classDef cli fill:#ffcccc,stroke:#333,stroke-width:2px;
    classDef daemon fill:#ccffcc,stroke:#333,stroke-width:2px;
    classDef helper fill:#ccccff,stroke:#333,stroke-width:2px;
    classDef lib fill:#ffffcc,stroke:#333,stroke-width:2px;
    classDef external fill:#cceeff,stroke:#333,stroke-width:2px;
    classDef build fill:#ffdd99,stroke:#333,stroke-width:2px;
```
