π Create and manage virtual networks through simple YAML configuration files
- 1. Introduction
- 2. Key Features
- 3. Getting started
- 4. Tool usage
- 5. Defining Topologies
- 6. Examples
- 7. Development environment
Mininet-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 and Open vSwitch, it emulates network environments, offering granularity akin to physical hardware.
Additionally, 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, it ensures optimal network performance tailored to user specifications.
π Rapid Network Deployment:
- Quickly generate and deploy complex virtual network topologies from a simple YAML configuration file.
π Topology Visualization:
- Automatically generate a visual representation of your network in Graphviz format for easy analysis and sharing.
π Automated Network Configuration:
- Seamlessly configure routing tables and propagate them across the network to ensure all nodes can communicate effectively.
πΈ Advanced Traffic Engineering:
- 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.
π οΈ Enhanced Network Interaction:
- Interact with network elements through a robust CLI, execute custom scripts, and use network diagnostic tools like
ping
andwireshark
directly within virtual nodes.
π₯οΈ Extended Application Support:
- Support for GUI applications via X11 forwarding, allowing for graphical user interface operations on virtual hosts.
Please, refer to the Getting Started guide to learn how to install the tool and run your first virtual network.
Via 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:
usage: emulation.py [-h] [-d] [-l] [-p] [-ld LOG_DIR] [-v] [-s] definition
This 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.
positional arguments:
definition path to the YAML file containing the network definition
optional arguments:
-h, --help show this help message and exit
-d, --draw output to stdout the router topology as an undirected graph in Graphviz format
-l, --lp output to stdout the network engineering optimization problem in CPLEX format generated from the specified demands in the YAML file
-p, --print output to stdout the optimal goodput archievable for each of the flows listed in the demands in the YAML file (if any)
-ld LOG_DIR, --log-dir LOG_DIR
specify the directory where the log file will be saved (default: logs/)
-v, --verbose enable verbose logging
-s, --silent disable all logging to stdout, except for critical errors
Mininet-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.
The network topology in the YAML file comprises three main sections: routers
, hosts
, and demands
, each detailed below.
This is an example of a valid YAML network configuration file:
routers:
r1:
eth0:
address: 192.168.0.1
mask: 255.255.255.0
cost: 10
eth1:
address: 10.0.1.5
mask: 255.255.255.240
r2:
eth1:
address: 10.0.1.1
mask: 255.255.255.240
cost: 15
hosts:
h1:
eth0:
address:
Each 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.
routers:
router_name:
interface_name:
address: ipv4_address (i.e. 192.168.0.1)
mask: subnet_mask (i.e. 255.255.255.0)
cost: cost_value (unsigned integer) # Optional; default is 1
Similar to routers, each host is defined with a unique name and configured with one or more network interfaces:
hosts:
host_name:
interface_name:
address: ipv4_address (i.e. 192.168.0.2)
mask: subnet_mask (i.e. 255.255.255.0)
If 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.
demands:
- source: source_element (router or host name, i.e. "h1")
destination: destination_element (router or host name, i.e. "r1")
rate: maximum_transmission_rate (in Mbps, i.e. 10)
The cost assigned to each interface serves different purposes in the tool, depending on the presence of the demands
section in the YAML file:
-
Routing Algorithm: The routing algorithm utilizes the cost to determine the optimal path between nodes. A lower cost generally makes a path more favorable.
-
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.
Note: Absence of the
demands
section defaults the cost utility to only influence routing decisions.
In the directory 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.
This 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:
YAML configuration file available in
examples/dumbell-network-no-cost.yaml
This 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.
This is the resulting network topology:
From 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.
YAML configuration file available in
examples/complex-network-multilink-with-costs.yaml
In 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:
- Demand 1: Maximum transmission rate of 10 Mbps between
h1
andh4
. - Demand 2: Maximum transmission rate of 2 Mbps between
h4
andh2
. - Demand 3: Maximum transmission rate of 15 Mbps between
h3
andh4
.
Each link in the topology also has a defined maximum bandwidth, crucial for traffic engineering optimization. Below is the network topology constructed by Mininet-YAML:
The 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.
Given 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.
Furthermore, 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.
By 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:
Source: h1 | Destination: h4 |
This path ensures that the goodput from h1
to h4
is 8 Mbps rather than the desired 10 (80% effectiveness ratio).
This path ensures that the goodput from h4
to h2
is 2 Mbps. The desired goodput is achieved.
The following images show the goodput achieved by iperf
for each demand:
Source: h4 | Destination: h2 |
This path ensures that the goodput from h3
to h4
is 10 Mbps rather than the desired 15 (66.67% effectiveness ratio).
The following images show the goodput achieved by iperf
for each demand:
Source: h4 | Destination: h2 |
The 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:
Demand | Source | Destination | Actual vs desired goodput (Mbps) | Demand Achieved (%) |
---|---|---|---|---|
1 | h1 | h4 | 8.0 / 10.0 | 80.0 |
2 | h4 | h2 | 2.0 / 2.0 | 100.0 |
3 | h3 | h4 | 10.0 / 15.0 | 66.67 |
YAML configuration file available in
examples/network-with-demands.yaml
To simplify the development process, this repository includes a preconfigured Devcontainer (available in directory .devcontainer
) that includes all the necessary tools and dependencies to develop and test the tool.
It follows the open specification of development containers (refer to Development Containers - Specification), hence it is supported by Visual Studio Code and other IDEs that support this standard.
Warning
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!