{"id":16454976,"url":"https://github.com/lucadibello/mininet-yaml","last_synced_at":"2025-08-17T22:32:07.037Z","repository":{"id":231121897,"uuid":"780944043","full_name":"lucadibello/mininet-yaml","owner":"lucadibello","description":"🛜 Create and manage virtual networks through simple YAML configuration files","archived":false,"fork":false,"pushed_at":"2024-06-12T06:50:09.000Z","size":1595,"stargazers_count":16,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"main","last_synced_at":"2024-10-30T07:28:28.697Z","etag":null,"topics":["linear-programming","mininet","network-analysis","traffic-engineering","virtual-networking"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/lucadibello.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-04-02T13:07:35.000Z","updated_at":"2024-10-27T12:06:45.000Z","dependencies_parsed_at":"2024-04-23T16:27:05.202Z","dependency_job_id":"89024c54-5adb-4bc9-8de0-6c61ca65930f","html_url":"https://github.com/lucadibello/mininet-yaml","commit_stats":null,"previous_names":["lucadibello/mininet-yaml"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/lucadibello/mininet-yaml","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucadibello%2Fmininet-yaml","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucadibello%2Fmininet-yaml/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucadibello%2Fmininet-yaml/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucadibello%2Fmininet-yaml/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/lucadibello","download_url":"https://codeload.github.com/lucadibello/mininet-yaml/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/lucadibello%2Fmininet-yaml/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270918297,"owners_count":24667664,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-17T02:00:09.016Z","response_time":129,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["linear-programming","mininet","network-analysis","traffic-engineering","virtual-networking"],"created_at":"2024-10-11T10:20:37.534Z","updated_at":"2025-08-17T22:32:05.879Z","avatar_url":"https://github.com/lucadibello.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Mininet-YAML \u003c!-- omit in toc --\u003e\n\n\u003cdiv style=\"width: 100%; display: block;\"\u003e\n    \u003cp align=\"center\"\u003e\n        \u003cpicture\u003e\n            \u003csource media=\"(prefers-color-scheme: dark)\" srcset=\"./docs/assets/logo/logo-dark.svg\"\u003e\n            \u003csource media=\"(prefers-color-scheme: light)\" srcset=\"./docs/assets/logo/logo-light.svg\"\u003e\n            \u003cimg alt=\"Mininet-YAML logo\" src=\"./doc/logo/logo-light.svg\" /\u003e\n        \u003c/picture\u003e\n    \u003c/p\u003e\n\u003c/div\u003e\n\n\u003cp align=\"center\"\u003e\u003cstrong\u003e🛜 Create and manage virtual networks through simple YAML configuration files\u003c/strong\u003e\u003c/p\u003e\n\n## Table of Contents \u003c!-- omit in toc --\u003e\n\n- [1. Introduction](#1-introduction)\n- [2. Key Features](#2-key-features)\n- [3. Getting started](#3-getting-started)\n- [4. Tool usage](#4-tool-usage)\n- [5. Defining Topologies](#5-defining-topologies)\n  - [5.1. Structure of the YAML file](#51-structure-of-the-yaml-file)\n    - [5.1.1. Routers](#511-routers)\n    - [5.1.2. Hosts](#512-hosts)\n    - [5.1.3. Demands (optional)](#513-demands-optional)\n  - [5.2. Functionality of Interface Costs](#52-functionality-of-interface-costs)\n- [6. Examples](#6-examples)\n  - [6.1. Example 1: Simple dumbbell network](#61-example-1-simple-dumbbell-network)\n  - [6.2. Example 2: Complex network with multiple routers and hosts](#62-example-2-complex-network-with-multiple-routers-and-hosts)\n  - [6.3. Example 3: Complex network with multiple routers, hosts and demands](#63-example-3-complex-network-with-multiple-routers-hosts-and-demands)\n- [7. Development environment](#7-development-environment)\n\n## 1. Introduction\n\nMininet-YAML simplifies the creation of virtual networks via YAML-configured topologies. Users define hosts, routers, and interfaces in a YAML file, deploying complex network topologies within seconds. Integrated with [Mininet](https://mininet.org/) and [Open vSwitch](https://www.openvswitch.org/), it emulates network environments, offering granularity akin to physical hardware.\n\nAdditionally, Mininet-YAML enables advanced traffic engineering. Users specify maximum transmission rates between network nodes, triggering automatic adjustments to achieve desired levels. Leveraging a *Mixed Integer Linear Programming* (MILP) model solved by the [CBC Solver](http://www.coin-or.org/Cbc/), it ensures optimal network performance tailored to user specifications.\n\n## 2. Key Features\n\n🚀 **Rapid Network Deployment**:\n\n- Quickly generate and deploy complex virtual network topologies from a simple YAML configuration file.\n\n📈 **Topology Visualization**:\n\n- Automatically generate a visual representation of your network in [Graphviz](https://graphviz.org/) format for easy analysis and sharing.\n\n🌍 **Automated Network Configuration**:\n\n- Seamlessly configure routing tables and propagate them across the network to ensure all nodes can communicate effectively.\n\n🚸 **Advanced Traffic Engineering**:\n\n- Leveraging a MILP model, the tool automatically adjusts link capacities and routing tables to meet specified demands and achieve optimal network performance, maximizing the minimum effective goodput between sources and destinations.\n\n🛠️ **Enhanced Network Interaction**:\n\n- Interact with network elements through a robust CLI, execute custom scripts, and use network diagnostic tools like `ping` and `wireshark` directly within virtual nodes.\n\n🖥️ **Extended Application Support**:\n\n- Support for GUI applications via X11 forwarding, allowing for graphical user interface operations on virtual hosts.\n\n## 3. Getting started\n\nPlease, refer to the [Getting Started](./docs/getting-started.md) guide to learn how to install the tool and run your first virtual network.\n\n## 4. Tool usage\n\nVia `emulation.py`, users can either draw the network topology as a graph or create a virtual network leveraging *Mininet*. The tool accepts the following arguments:\n\n```text\nusage: emulation.py [-h] [-d] [-l] [-p] [-ld LOG_DIR] [-v] [-s] definition\n\nThis tool is able to read a network definition from a YAML file and either draw the network topology as a graph or create a virtual network leveraging Mininet.\n\npositional arguments:\n  definition            path to the YAML file containing the network definition\n\noptional arguments:\n  -h, --help            show this help message and exit\n  -d, --draw            output to stdout the router topology as an undirected graph in Graphviz format\n  -l, --lp              output to stdout the network engineering optimization problem in CPLEX format generated from the specified demands in the YAML file\n  -p, --print           output to stdout the optimal goodput archievable for each of the flows listed in the demands in the YAML file (if any)\n  -ld LOG_DIR, --log-dir LOG_DIR\n                        specify the directory where the log file will be saved (default: logs/)\n  -v, --verbose         enable verbose logging\n  -s, --silent          disable all logging to stdout, except for critical errors\n```\n\n## 5. Defining Topologies\n\nMininet-YAML facilitates virtual network creation via YAML-defined topologies. This configuration allows specifying the high-level network structure, including routers, hosts, interfaces, and optionally, maximum transmission rates between network elements.\n\n### 5.1. Structure of the YAML file\n\nThe network topology in the YAML file comprises three main sections: `routers`, `hosts`, and `demands`, each detailed below.\n\nThis is an example of a valid YAML network configuration file:\n\n```yaml\nrouters:\n  r1:\n    eth0:\n      address: 192.168.0.1\n      mask: 255.255.255.0\n      cost: 10\n    eth1:\n      address: 10.0.1.5\n      mask: 255.255.255.240\n  r2:\n    eth1:\n     address: 10.0.1.1\n     mask: 255.255.255.240\n     cost: 15\nhosts:\n   h1:\n    eth0:\n        address: \n```\n\n#### 5.1.1. Routers\n\nEach router is defined by a name and includes one or more interfaces. Interfaces are detailed with IP addresses, subnet masks, and optionally, costs which influence routing decisions or traffic engineering.\n\n```yaml\nrouters:\n  router_name:\n    interface_name:\n      address: ipv4_address (i.e. 192.168.0.1)\n      mask: subnet_mask  (i.e. 255.255.255.0)\n      cost: cost_value  (unsigned integer) # Optional; default is 1\n```\n\n#### 5.1.2. Hosts\n\nSimilar to routers, each host is defined with a unique name and configured with one or more network interfaces:\n\n```yaml\nhosts:\n  host_name:\n    interface_name:\n      address: ipv4_address (i.e. 192.168.0.2)\n      mask: subnet_mask (i.e. 255.255.255.0)\n```\n\n#### 5.1.3. Demands (optional)\n\nIf your topology requires specific traffic **management**, the `demands` section allows you to define maximum transmission rate between couples of network nodes. This section triggers traffic engineering functionalities where the tool adjusts link capacities and routing configurations to meet these demands.\n\n```yaml\ndemands:\n    - source: source_element (router or host name, i.e. \"h1\")\n      destination: destination_element (router or host name, i.e. \"r1\") \n      rate: maximum_transmission_rate (in Mbps, i.e. 10)\n```\n\n### 5.2. Functionality of Interface Costs\n\nThe cost assigned to each interface serves different purposes in the tool, depending on the presence of the `demands` section in the YAML file:\n\n1. **Routing Algorithm**: The routing algorithm utilizes the cost to determine the optimal path between nodes. A lower cost generally makes a path more favorable.\n\n2. **Traffic Engineering**: When the `demands` section is included, the cost influences the adjustment of link capacities and routing tables to achieve the optimal effectiveness ratio, integrating a strategic layer to network management.\n\n\u003e **Note**: Absence of the `demands` section defaults the cost utility to only influence routing decisions.\n\n## 6. Examples\n\nIn the directory [`examples`](./examples), you can find some YAML files that define different network topologies. You can use them to test the tool and understand how to define your own network. In the following subsections, each example is presented with a graphical representation of the network topology and a brief explanation of the results.\n\n### 6.1. Example 1: Simple dumbbell network\n\nThis example defines a simple dumbbell network with two routers and six hosts. The routers are connected to each other, and each host is connected to a router via a switch. This is the topology built by *Mininet-YAML*:\n\n\u003cdiv style=\"width: 100%; display: block;\"\u003e\n    \u003cp align=\"center\"\u003e\n            \u003cimg alt=\"Example 1 - Network topology\" src=\"./docs/assets/examples_diagrams/example_1/example_1.svg\" /\u003e\n        \u003c/picture\u003e\n    \u003c/p\u003e\n\u003c/div\u003e\n\n\u003e YAML configuration file available in [`examples/dumbell-network-no-cost.yaml`](./examples/dumbell-network-no-cost.yaml)\n\n### 6.2. Example 2: Complex network with multiple routers and hosts\n\nThis example defines a more complex network with 3 routers, 4 hosts, and multiple links between them. Each router has 3 interfaces, in which some have a connection. The cost of each link is used by the tool to connect the elements together in the most efficient way, and also to route the traffic between them.\n\nThis is the resulting network topology:\n\n\u003cdiv style=\"width: 100%; display: block;\"\u003e\n    \u003cp align=\"center\"\u003e\n            \u003cimg alt=\"Example 2 - Network topology\" src=\"./docs/assets/examples_diagrams/example_2/example_2.svg\" /\u003e\n        \u003c/picture\u003e\n    \u003c/p\u003e\n\u003c/div\u003e\n\nFrom the diagram above, it is possible to see that the interface `eth1` of the router `r1` has been kept down as it is not connected to any other interface.\n\n\u003e YAML configuration file available in [`examples/complex-network-multilink-with-costs.yaml`](./examples/complex-network-multilink-with-costs.yaml)\n\n### 6.3. Example 3: Complex network with multiple routers, hosts and demands\n\nIn this example, we configure a network comprising 4 routers and 4 hosts, where two hosts are directly connected to the routers, and the remaining two are connected via a switch. We define 3 demands specifying maximum transmission rates between the hosts:\n\n- **Demand 1**: Maximum transmission rate of 10 Mbps between `h1` and `h4`.\n- **Demand 2**: Maximum transmission rate of 2 Mbps between `h4` and `h2`.\n- **Demand 3**: Maximum transmission rate of 15 Mbps between `h3` and `h4`.\n\nEach link in the topology also has a defined maximum bandwidth, crucial for traffic engineering optimization. Below is the network topology constructed by *Mininet-YAML*:\n\n\u003cdiv style=\"width: 100%; display: block;\"\u003e\n    \u003cp align=\"center\"\u003e\n        \u003cimg alt=\"Example 3 - Network topology\" src=\"./docs/assets/examples_diagrams/example_3/example_3_topo.svg\" /\u003e\n    \u003c/p\u003e\n\u003c/div\u003e\n\nThe tool adjusts link capacities and routing tables to meet the specified demands. It computes specific routes for each demand to achieve the desired goodput. In the following subsection is possible to view graphical representation of the optimal routes determined by the *MILP* model for each demand.\n\nGiven the constraints of the problem, it is not always feasible to perfectly satisfy all demands. However, the model aims to maximize the minimum effective goodput between the sources and destinations of each demand, ensuring optimal network performance.\n\nFurthermore, to manage this effectively without interfering with other network traffic, packets associated with a specific demand are tagged with a unique identifier. Routers along the path of the demand are equipped with custom routing table entries for these tagged packets, ensuring they are forwarded correctly to the next hop. Packets not associated with a demand follow the standard routing paths established by the tool. This allows to maintain the integrity of the network and prevent interference between different demands.\n\n#### Demand 1 - H1 to H4 \u003c!-- omit in toc --\u003e\n\n\u003cdiv style=\"width: 100%; display: block;\"\u003e\n    \u003cp align=\"center\"\u003e\n            \u003cimg alt=\"Example 3 - Demand 1\" src=\"./docs/assets/examples_diagrams/example_3/demand_1/example_3_demand_1.svg\" /\u003e\n        \u003c/picture\u003e\n    \u003c/p\u003e\n\u003c/div\u003e\n\nBy running `iperf` between `h1` and `h4`, has been possible to verify the goodput achieved by the tool. The following images show the goodput achieved by the tool for each demand:\n\n\u003c!-- Table with two images side by side --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003cimg alt=\"Demand 1 - Source\" src=\"./docs/assets/examples_diagrams/example_3/demand_3/demands-example-flow-bandwidth/demand_h1_h4/src.png\" /\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg alt=\"Demand 1 - Destination\" src=\"./docs/assets/examples_diagrams/example_3/demand_3/demands-example-flow-bandwidth/demand_h1_h4/dst.png\" /\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003eSource: h1\u003c/td\u003e\n    \u003ctd align=\"center\"\u003eDestination: h4\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\nThis path ensures that the goodput from `h1` to `h4` is 8 Mbps rather than the desired 10 (80% effectiveness ratio).\n\n#### Demand 2 - H4 to H2 \u003c!-- omit in toc --\u003e\n\n\u003cdiv style=\"width: 100%; display: block;\"\u003e\n    \u003cp align=\"center\"\u003e\n            \u003cimg alt=\"Example 3 - Demand 2\" src=\"./docs/assets/examples_diagrams/example_3/demand_2/example_3_demand_2.svg\" /\u003e\n        \u003c/picture\u003e\n    \u003c/p\u003e\n\u003c/div\u003e\n\nThis path ensures that the goodput from `h4` to `h2` is 2 Mbps. The desired goodput is achieved.\n\nThe following images show the goodput achieved by `iperf` for each demand:\n\n\u003c!-- Table with two images side by side --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003cimg alt=\"Demand 2 - Source\" src=\"./docs/assets/examples_diagrams/example_3/demand_3/demands-example-flow-bandwidth/demand_h4_h2/src.png\" /\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg alt=\"Demand 2 - Destination\" src=\"./docs/assets/examples_diagrams/example_3/demand_3/demands-example-flow-bandwidth/demand_h4_h2/dst.png\" /\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003eSource: h4\u003c/td\u003e\n    \u003ctd align=\"center\"\u003eDestination: h2\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\n#### Demand 3 - H3 to H4 \u003c!-- omit in toc --\u003e\n\n\u003cdiv style=\"width: 100%; display: block;\"\u003e\n    \u003cp align=\"center\"\u003e\n            \u003cimg alt=\"Example 3 - Demand 3\" src=\"./docs/assets/examples_diagrams/example_3/demand_3/example_3_demand_3.svg\" /\u003e\n        \u003c/picture\u003e\n    \u003c/p\u003e\n\u003c/div\u003e\n\nThis path ensures that the goodput from `h3` to `h4` is 10 Mbps rather than the desired 15 (66.67% effectiveness ratio).\n\nThe following images show the goodput achieved by `iperf` for each demand:\n\n\u003c!-- Table with two images side by side --\u003e\n\u003ctable\u003e\n  \u003ctr\u003e\n    \u003ctd\u003e\n      \u003cimg alt=\"Demand 3 - Source\" src=\"./docs/assets/examples_diagrams/example_3/demand_3/demands-example-flow-bandwidth/demand_h3_h4/src.png\" /\u003e\n    \u003c/td\u003e\n    \u003ctd\u003e\n      \u003cimg alt=\"Demand 3 - Destination\" src=\"./docs/assets/examples_diagrams/example_3/demand_3/demands-example-flow-bandwidth/demand_h3_h4/dst.png\" /\u003e\n    \u003c/td\u003e\n  \u003c/tr\u003e\n  \u003ctr\u003e\n    \u003ctd align=\"center\"\u003eSource: h4\u003c/td\u003e\n    \u003ctd align=\"center\"\u003eDestination: h2\u003c/td\u003e\n  \u003c/tr\u003e\n\u003c/table\u003e\n\nThe tool has been able to achieve the optimal goodput for this network topology, considering the constraints of the problem. The following table shows the results of the link capacities and the goodput achieved for each demand:\n\n| Demand | Source | Destination | Actual vs desired goodput (Mbps) | Demand Achieved (%) |\n| ------ | ------ | ----------- | -------------------------------- | ------------------- |\n| 1      | h1     | h4          | 8.0 / 10.0                       | 80.0                |\n| 2      | h4     | h2          | 2.0 / 2.0                        | 100.0               |\n| 3      | h3     | h4          | 10.0 / 15.0                      | 66.67               |\n\n\u003e YAML configuration file available in [`examples/network-with-demands.yaml`](./examples/network-with-demands.yaml)\n\n## 7. Development environment\n\nTo simplify the development process, this repository includes a preconfigured Devcontainer (available in directory [`.devcontainer`](./.devcontainer)) that includes all the necessary tools and dependencies to develop and test the tool.\n\nIt follows the open specification of development containers (refer to [Development Containers - Specification](https://containers.dev/implementors/spec/)), hence it is supported by Visual Studio Code and other IDEs that support this standard.\n\n\u003e [!WARNING]\n\u003e Unfortunately on MacOS *Open vSwitch* is not supported in Docker containers due to the lack of support for kernel modules. Therefore, to have a fully functional development environment, it is recommended to use Linux. To avoid setting up entire Linux VM from scratch by installing and compiling all the required tooling, it is always possible to use the devcontainer inside the VM. The configuation script will handle all the hard work!\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucadibello%2Fmininet-yaml","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flucadibello%2Fmininet-yaml","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flucadibello%2Fmininet-yaml/lists"}