# bonavadeur/netemu architecture

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

- Interactive diagram: https://gitdiagram.com/bonavadeur/netemu
- Repository: https://github.com/bonavadeur/netemu

## Overview

##### Project type and purpose
- This is an open-source command-line network emulation tool (“netemu”) that runs entirely on a Linux host.
- Its purpose is to create fixed, variable (jitter), or trace-based latency and bandwidth limits between multiple virtual machines by invoking Linux’s “tc”/”netem” subsystem.

##### File structure
- Top-level scripts:
- delayfix.sh        – applies a fixed delay
- delaynor.sh       – applies delay ± jitter plus bandwidth limit
- netem.py           – Python script that reads a CSV trace and drives netem parameters
- netem.sh           – helper that actually invokes “tc qdisc” commands on an interface
- undelay.sh         – cleans up all applied qdiscs
- latency.sh         – (possibly an alternative entrypoint for manual testing)
- delay.sh/delayfix.sh – small variants for specific modes
- Data assets:
- B_2018.01.19_07.31.48.csv – a sample 4G data-trace used by netem.py
- Project metadata:
- LICENSE
- README.md

##### README
- Describes a 3-VM topology (VM1, VM2, VM3) each connected via vnet interfaces on the host.
- Usage patterns:
- Constant delay (delayfix.sh)
- Variable delay + bandwidth limit (delaynor.sh)
- Trace-based delay + bandwidth (netem.py)

a. Virtual Machines
– VM1 (vnet0)
– VM2 (vnet1)
– VM3 (vnet2)
b. Host Machine
– Script Layer
- delayfix.sh / delaynor.sh wrappers
- netem.py (trace reader)
- netem.sh (tc invoker)
- undelay.sh (cleanup)
- latency.sh (helper/test)
– Linux Kernel “tc” subsystem
- netem qdisc
- tbf or htb classes (for bandwidth)
– Data Source
- CSV file containing bandwidth trace
c. Network Interfaces
– vnet0, vnet1, vnet2 bridges connecting VMs to host
d. External dependencies
– “tc” command (from iproute2)
– Python runtime (for netem.py)

##### Relationships and data flows
- The user invokes one of the wrapper scripts on the host.
- Wrapper parses parameters or hands off to Python.
- netem.py reads the CSV, generates per-interval tc commands.
- netem.sh executes “tc qdisc add/change” on vnet interfaces.
- undelay.sh reverses these qdisc settings.

##### Architectural patterns & design principles
- Modular script layer: wrappers → generic invoker → cleanup
- Separation of concerns: parameter parsing vs. tc invocation vs. trace reading
- Lean, single-host deployment: no external orchestrator

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Virtual Machines
    VM1["VM1\n(vnet0)"]:::network
    VM2["VM2\n(vnet1)"]:::network
    VM3["VM3\n(vnet2)"]:::network

    %% User Console
    User["User Console"]:::external

    %% Host Machine Container
    subgraph "Host Machine"
        subgraph "Script Layer"
            DF["delayfix.sh"]:::script
            DN["delaynor.sh"]:::script
            LAT["latency.sh"]:::script
            NP["netem.py"]:::script
            NS["netem.sh"]:::script
            UD["undelay.sh"]:::script
        end

        subgraph "Linux Kernel TC Subsystem"
            NETEMQ["netem qdisc"]:::kernel
            BW["tbf/htb classes"]:::kernel
        end

        DS["B_2018.01.19_07.31.48.csv"]:::data

        subgraph "Project Metadata"
            MD["README.md"]:::data
            LIC["LICENSE"]:::data
        end
    end

    %% External Dependencies
    PY["Python Runtime"]:::external
    TC["tc Command\n(iproute2)"]:::external

    %% Control Flow
    User -->|invoke script| DF
    User -->|invoke script| DN
    User -->|invoke script| LAT
    User -->|invoke script| NP
    DF -->|calls netem.sh| NS
    DN -->|calls netem.sh| NS
    LAT -->|calls netem.sh| NS
    NP -->|generates tc commands| NS
    NP -->|reads trace| DS
    NS -->|invoke tc| NETEMQ
    NS -->|invoke tc| BW

    %% Packet Flow
    VM1 <-->|packets| NETEMQ
    VM2 <-->|packets| NETEMQ
    VM3 <-->|packets| NETEMQ

    %% External Dependency Links
    NP -->|requires| PY
    NS -->|uses| TC

    %% Click Events
    click DF "https://github.com/bonavadeur/netemu/blob/master/delayfix.sh"
    click DN "https://github.com/bonavadeur/netemu/blob/master/delaynor.sh"
    click LAT "https://github.com/bonavadeur/netemu/blob/master/latency.sh"
    click NP "https://github.com/bonavadeur/netemu/blob/master/netem.py"
    click NS "https://github.com/bonavadeur/netemu/blob/master/netem.sh"
    click UD "https://github.com/bonavadeur/netemu/blob/master/undelay.sh"
    click DS "https://github.com/bonavadeur/netemu/blob/master/B_2018.01.19_07.31.48.csv"
    click MD "https://github.com/bonavadeur/netemu/blob/master/README.md"
    click LIC "https://github.com/bonavadeur/netemu/tree/master/LICENSE"

    %% Styles
    classDef script fill:#cce5ff,stroke:#005cbf,color:#004085
    classDef network fill:#d4edda,stroke:#155724,color:#155724
    classDef data fill:#fff3cd,stroke:#856404,color:#856404
    classDef kernel fill:#d1ecf1,stroke:#0c5460,color:#0c5460
    classDef external fill:#e2e3e5,stroke:#6c757d,color:#383d41
```
