Containernet is a fork of the famous Mininet network emulator and allows to use Docker containers as hosts in emulated network topologies. This enables interesting functionalities to build networking/cloud emulators and testbeds. Containernet is actively used by the research community, focussing on experiments in the field of cloud computing, fog computing, network function virtualization (NFV) and multi-access edge computing (MEC). One example for this is the NFV multi-PoP infrastructure emulator which was created by the SONATA-NFV project and is now part of the OpenSource MANO (OSM) project.

Features

Installation

Containernet comes with two installation and deployment options.

Option 1: Bare-metal installation

This option is the most flexible. Your machine should run Ubuntu 20.04 LTS and Python3.

First install Ansible:

sudo apt-get install ansible

Then clone the repository:

git clone https://github.com/containernet/containernet.git

Finally run the Ansible playbook to install required dependencies:

sudo ansible-playbook -i "localhost," -c local containernet/ansible/install.yml

After the installation finishes, you should be able to get started.

Option 2: Nested Docker deployment

Containernet can be executed within a privileged Docker container (nested container deployment). There is also a pre-build Docker image available on Docker Hub.

Attention: Container resource limitations, e.g. CPU share limits, are not supported in the nested container deployment. Use bare-metal installations if you need those features.

You can build the container locally:

docker build -t containernet/containernet .

or alternatively pull the latest pre-build container:

docker pull containernet/containernet

You can then directly start the default containernet example:

docker run --name containernet -it --rm --privileged --pid='host' -v /var/run/docker.sock:/var/run/docker.sock containernet/containernet

or run an interactive container and drop to the shell:

docker run --name containernet -it --rm --privileged --pid='host' -v /var/run/docker.sock:/var/run/docker.sock containernet/containernet /bin/bash

Get started

Using Containernet is very similar to using Mininet.

Running a basic example

Make sure you are in the containernet directory. You can start an example topology with some empty Docker containers connected to the network:

sudo python3 examples/containernet_example.py

After launching the emulated network, you can interact with the involved containers through Mininet’s interactive CLI. You can for example:

You can exit the CLI using containernet> exit.

Running a client-server example

Let’s simulate a webserver and a client making requests. For that, we need a server and client image. First, change into the containernet/examples/basic_webserver directory.

Containernet already provides a simple Python server for testing purposes. To build the server image, just run

docker build -f Dockerfile.server -t test_server:latest .

If you have not added your user to the docker group as described here, you will need to prepend sudo.

We further need a basic client to make a CURL request. Containernet provides that as well. Please run

docker build -f Dockerfile.client -t test_client:latest .

Now that we have a server and client image, we can create hosts using them. You can either checkout the topology script demo.py first or run it directly:

sudo python3 demo.py

If everything worked, you should be able to see following output:

Execute: client.cmd("time curl 10.0.0.251")
Hello world.

Customizing topologies

You can also add hosts with resource restrictions or mounted volumes:

# ...

d1 = net.addDocker('d1', ip='10.0.0.251', dimage="ubuntu:trusty")
d2 = net.addDocker('d2', ip='10.0.0.252', dimage="ubuntu:trusty", cpu_period=50000, cpu_quota=25000)
d3 = net.addHost('d3', ip='11.0.0.253', cls=Docker, dimage="ubuntu:trusty", cpu_shares=20)
d4 = net.addDocker('d4', dimage="ubuntu:trusty", volumes=["/:/mnt/vol1:rw"])

# ...

Documentation

Containernet’s documentation can be found in the GitHub wiki. The documentation for the underlying Mininet project can be found on the Mininet website.

Research

Containernet has been used for a variety of research tasks and networking projects. If you use Containernet, let us know!

Cite this work

If you use Containernet for your work, please cite the following publication:

M. Peuster, H. Karl, and S. v. Rossem: MeDICINE: Rapid Prototyping of Production-Ready Network Services in Multi-PoP Environments. IEEE Conference on Network Function Virtualization and Software Defined Networks (NFV-SDN), Palo Alto, CA, USA, pp. 148-153. doi: 10.1109/NFV-SDN.2016.7919490. (2016)

Bibtex:

@inproceedings{peuster2016medicine,
    author={M. Peuster and H. Karl and S. van Rossem},
    booktitle={2016 IEEE Conference on Network Function Virtualization and Software Defined Networks (NFV-SDN)},
    title={MeDICINE: Rapid prototyping of production-ready network services in multi-PoP environments},
    year={2016},
    volume={},
    number={},
    pages={148-153},
    doi={10.1109/NFV-SDN.2016.7919490},
    month={Nov}
}

Publications

There is an extension of Containernet called vim-emu which is a full-featured multi-PoP emulation platform for NFV scenarios. Vim-emu was developed as part of the SONATA-NFV project and is now hosted by the OpenSource MANO project:

For running Mininet or Containernet distributed in a cluster, checkout Maxinet.

You can also find an alternative/teaching-focused approach for Container-based Network Emulation by TU Dresden in their repository.

Contact

Support

If you have any questions, please use GitHub’s issue system.

Contribute

Your contributions are very welcome! Please fork the GitHub repository and create a pull request.

Please make sure to test your code using

sudo make test

Lead developer

Manuel Peuster