qdeconinck · Hraf-Jr · Oct 8, 2025 · Oct 8, 2025 · Oct 8, 2025 · Oct 13, 2025
diff --git a/README.rst b/README.rst
@@ -1,63 +1,158 @@
 What ?
 ======
 
-Simple tool, based on `mininet <http://mininet.org/>`_, to boot a simple network
-with n paths and run experiments between two hosts.
+This repository provides a **Python runner** built on `Mininet <http://mininet.org/>`_ 
+to create and control simple network topologies with multiple paths.
 
+It can be used for a wide range of networking experiments (TCP, UDP, QUIC, etc.).
+In our case, we focus mainly on **QUIC** tests between two hosts.
 
-Usage
-=====
+Requirements
+============
+
+To run the experiments, you need the following environment:
+
+- **Operating system:** Ubuntu 20.04+ (or WSL2 with Ubuntu)
+- **Python:** version 3.8 or newer
+- **Mininet:** installed system-wide
+- **System tools:** ``iproute2``, ``ethtool``, ``tcpdump``, and ``tshark`` (for packet capture)
+- **Optional GUI:** Wireshark (to visualize pcap files)
+
+Quick installation:
 
 .. code-block:: console
 
-        ./mpPerf -t topo -x xp
+   sudo apt-get update
+   sudo apt-get install -y mininet iproute2 ethtool tcpdump tshark python3-pip
 
-The format for the topo file and xp file is simple but could be different based
-on the type of topo or experiments. Details should follow.
+---
 
-basic Example
-=============
+Optional – QUIC experiments (using *quiche*)
+--------------------------------------------
 
-1. Get the CLI
---------------
+If you plan to run **QUIC or Multipath QUIC** experiments, you will also need
+the `quiche <https://github.com/cloudflare/quiche>`_ library.
+
+Build the client and server binaries with:
 
 .. code-block:: console
 
-        ./mpPerf -t conf/topo/simple_para
+   git clone --recursive https://github.com/cloudflare/quiche.git
+   cd quiche
+   cargo build --release --bin quiche-server --bin quiche-client
+
+After compilation, you can use the following binaries in your experiment files:
+
+- ``target/release/quiche-server``
+- ``target/release/quiche-client``
+
+Simple Example
+=============================================
+
+1. The topology
+----------------------
+
+Start a multi-interface topology (in our case ``topo_2.yaml``) **without any experiment**
+to access the Mininet CLI:
+
+This topology creates a simple 3-node setup composed of:
+
+- a client host with two network interfaces (10.0.0.1 and 10.0.1.1),
+- a router connecting both subnets (10.0.x.0/24),
+- a server host reachable on the right subnet (10.1.0.1).
+
+Each interface of the client is connected to the router with its own link characteristics
+(delay, bandwidth, queue size). The server receives traffic coming from both paths through the router.
 
-The content of simple_para is:
 
 .. code-block:: console
 
-        desc:Simple configuration with two para link
-        topoType:MultiIf
-        leftSubnet:10.0.
-        rightSubnet:10.1.
-        #path_x:delay,queueSize(may be calc),bw
-        path_0:10,10,5
-        path_1:40,40,5
-        path_2:30,30,2
-        path_3:20,20,1
+   sudo python3 runner.py -t config/topo/topo_2
 
-``topoType`` just specifies that we want to have multiple interfaces, one for
-each path.
+This opens the interactive Mininet CLI with the nodes already connected
+(client, router, server).
 
-Each path is defined by 3 values, delay (one way, int, in ms), queue_size (int, 
-in packets), and bandwidth (float, in mbit/s).
+---
 
-Once the configuration is up, you have access to the CLI. You can check route
-configuration (policy routing etc.) Just by issuing regular commands preceded
-by ``Client`` or ``Server``
+To verify that the runner and topology are working correctly, you can start the
+topology and interact with it using the Mininet CLI:
+
+.. code-block:: console
 
-2. Simple experiment
---------------------
+   sudo python3 runner.py -t config/topo/topo_2.yaml
+
+This starts the network with three nodes:
+
+- ``Client_0`` (two interfaces)
+- ``Router_0``
+- ``Server_0``
+
+Inside the Mininet CLI, you can run simple connectivity tests, for example:
 
 .. code-block:: console
 
-        ./mpPerf -t conf/topo/simple_para -x conf/xp/4_nc
+   mininet> Client_0 ping -c 3 Server_0
+
+That confirms if the topology is functional without requiring a full QUIC
+experiment.
+
+
+YAML Support (New)
+==================
+
+The runner now supports **YAML configuration files** for defining topologies and experiments,
+in addition to the legacy ``.para`` format.
+
+This new format improves readability, structure, and automation.
+
+Legacy vs YAML Example
+----------------------
+
+**Legacy format (``topo_2``):**
+
+.. code-block:: text
+
+   leftSubnet:10.0
+   rightSubnet:10.1
+   path_c2r_0:100,20,4
+   path_c2r_1:1,20,4
+   path_r2s_0:10,20,10
+   topoType:MultIf
+
+**YAML format (``topo_2.yaml``):**
+
+.. code-block:: yaml
+
+   version: 1
+   topology:
+     type: MultiIf
+     subnets:
+       left: 10.0
+       right: 10.1
+
+     paths:
+       - link_type: c2r
+         id: 0
+         delay_ms: 100
+         queue_pkts: 20
+         bw_mbit: 4
+
+       - link_type: c2r
+         id: 1
+         delay_ms: 1
+         queue_pkts: 20
+         bw_mbit: 4
+
+       - link_type: r2s
+         id: 0
+         delay_ms: 10
+         queue_pkts: 20
+         bw_mbit: 10
+
+
+Runner Update
+-------------
+
+The ``runner.py`` script automatically detects and parse YAML files
 
-This command will start the same topology and run the experiment defined by 4_nc
-The result for this experiment is a simple pcap file.
 
-They are other options and experiments, but the documentation is still to be
-written.
diff --git a/config/topo/topo_1 b/config/topo/topo_1
diff --git a/config/topo/topo_1.yaml b/config/topo/topo_1.yaml
@@ -0,0 +1,19 @@
+version: 1
+topology:
+  type: MultiIf
+  subnets:
+    left: 10.0
+    right: 10.1
+
+  paths:
+    - link_type: c2r
+      id: 0
+      delay_ms: 10
+      queue_pkts: 10
+      bw_mbit: 4
+
+    - link_type: c2r
+      id: 1
+      delay_ms: 40
+      queue_pkts: 30
+      bw_mbit: 4
diff --git a/config/topo/topo_2 b/config/topo/topo_2
diff --git a/config/topo/topo_2.yaml b/config/topo/topo_2.yaml
@@ -0,0 +1,22 @@
+version: 1
+topology:
+  type: MultiIf
+  subnets:
+    left: 10.0.
+    right: 10.1.
+  paths:
+    - link_type: c2r
+      id: 0
+      delay_ms: 100
+      queue_pkts: 20
+      bw_mbit: 4
+    - link_type: c2r
+      id: 1
+      delay_ms: 1
+      queue_pkts: 20
+      bw_mbit: 4
+    - link_type: r2s
+      id: 0
+      delay_ms: 10
+      queue_pkts: 20
+      bw_mbit: 10
diff --git a/config/topo/topo_3 b/config/topo/topo_3
diff --git a/config/topo/topo_3.yaml b/config/topo/topo_3.yaml
@@ -0,0 +1,19 @@
+version: 1
+topology:
+  type: MultiIf
+  subnets:
+    left: 10.0
+    right: 10.1
+
+  paths:
+    - link_type: c2r
+      id: 0
+      delay_ms: 100
+      queue_pkts: 20
+      bw_mbit: 4
+
+    - link_type: r2s
+      id: 0
+      delay_ms: 10
+      queue_pkts: 20
+      bw_mbit: 10
diff --git a/config/topo/topo_4 b/config/topo/topo_4
diff --git a/config/topo/topo_4.yaml b/config/topo/topo_4.yaml
@@ -0,0 +1,37 @@
+version: 1
+topology:
+  type: MultiIf
+  subnets:
+    left: 10.0
+    right: 10.1
+
+  paths:
+    - link_type: c2r
+      id: 0
+      delay_ms: 100
+      queue_pkts: 20
+      bw_mbit: 4
+
+    - link_type: c2r
+      id: 1
+      delay_ms: 100
+      queue_pkts: 20
+      bw_mbit: 4
+
+    - link_type: c2r
+      id: 2
+      delay_ms: 100
+      queue_pkts: 20
+      bw_mbit: 4
+
+    - link_type: r2s
+      id: 0
+      delay_ms: 10
+      queue_pkts: 20
+      bw_mbit: 10
+
+    - link_type: r2s
+      id: 1
+      delay_ms: 10
+      queue_pkts: 20
+      bw_mbit: 10
diff --git a/config/topo/topo_5 b/config/topo/topo_5
diff --git a/config/topo/topo_5.yaml b/config/topo/topo_5.yaml
@@ -0,0 +1,37 @@
+version: 1
+topology:
+  type: MultiIf
+  subnets:
+    left: 10.0
+    right: 10.1
+
+  paths:
+    - link_type: c2r
+      id: 0
+      delay_ms: 100
+      queue_pkts: 20
+      bw_mbit: 4
+
+    - link_type: c2r
+      id: 1
+      delay_ms: 100
+      queue_pkts: 20
+      bw_mbit: 4
+
+    - link_type: r2s
+      id: 0
+      delay_ms: 10
+      queue_pkts: 20
+      bw_mbit: 10
+
+    - link_type: r2s
+      id: 1
+      delay_ms: 10
+      queue_pkts: 20
+      bw_mbit: 10
+
+    - link_type: r2s
+      id: 2
+      delay_ms: 10
+      queue_pkts: 20
+      bw_mbit: 10
diff --git a/config/topo/topo_cong b/config/topo/topo_cong
diff --git a/config/xp/pquic b/config/xp/pquic
@@ -0,0 +1,7 @@
+xpType:pquic
+pquicPlugins:/home/achraf/pquic/plugins/multipath/multipath.plugin
+pquicClientPlugins:
+pquicServerPlugins:
+pquicSize:2000000
+clientPcap:yes
+serverPcap:yes
diff --git a/config/xp/quic b/config/xp/quic
@@ -0,0 +1,9 @@
+xpType:quic
+fileSizeBytes:0
+quicImpl:quiche
+quicPort:6121
+quicCertPath:/home/achraf/quiche/certs
+quicNoVerify:1
+quicMultipath:0
+clientPcap:yes
+serverPcap:yes