Overview

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. 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. Besides this, 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).


News and Releases

2020-10-04: Experimental support for Ubuntu 20.04 LTS

Added experimental support for Ubuntu 20.04 LTS to main branch. Credits go to Dimitrios (@digiou).

2019-12-19: Release: Containernet 3.1

This release changes the default installation environment of Containernet to be Python3. Credits for this go to Rafael Schellenberg.

2019-07-05: Release: Containernet 3.0

Besides an improved integration of Docker containers (port exposing, environment variables etc.), this release also adds an improved handling of container entrypoints and start commands, which was contributed by Erik Schilling. The release also merges the latest Mininet code (2.3.0d5) into Containernet which brings support for Python3. Credits for this goes to Zohar Lorberbaum.

2018-04-03: Release: Containernet 2.0

This release contained a lot of bug fixes and an experimental Libvirt integration which allows to use VMs within Containernet. However, this extension was later moved to a dedicated branch to keep the master slim and easy to use.

2017-09-04: Release: Containernet 1.0

First release that added the basic integration of Docker containers into Mininet.

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}
}

Get started

Using Containernet is very similar to using Mininet with custom topologies.

Create a custom topology

To start, a Python-based network topology description has to be created as shown in the following example:

"""
Example topology with two containers (d1, d2),
two switches, and one controller:

          - (c)-
         |      |
(d1) - (s1) - (s2) - (d2)
"""
from mininet.net import Containernet
from mininet.node import Controller
from mininet.cli import CLI
from mininet.link import TCLink
from mininet.log import info, setLogLevel
setLogLevel('info')

net = Containernet(controller=Controller)
info('*** Adding controller\n')
net.addController('c0')
info('*** Adding docker containers using ubuntu:trusty images\n')
d1 = net.addDocker('d1', ip='10.0.0.251', dimage="ubuntu:trusty")
d2 = net.addDocker('d2', ip='10.0.0.252', dimage="ubuntu:trusty")
info('*** Adding switches\n')
s1 = net.addSwitch('s1')
s2 = net.addSwitch('s2')
info('*** Creating links\n')
net.addLink(d1, s1)
net.addLink(s1, s2, cls=TCLink, delay='100ms', bw=1)
net.addLink(s2, d2)
info('*** Starting network\n')
net.start()
info('*** Testing connectivity\n')
net.ping([d1, d2])
info('*** Running CLI\n')
CLI(net)
info('*** Stopping network')
net.stop()

You can find this topology in containernet/examples/containernet_example.py.

Run emulation and interact with containers

Containernet requires root access to configure the emulated network described by the topology script:

sudo python3 containernet_example.py

After launching the emulated network, you can interact with the involved containers through Mininet’s interactive CLI as shown with the ping command in the following example:

containernet> d1 ping -c3 d2
PING 10.0.0.252 (10.0.0.252) 56(84) bytes of data.
64 bytes from 10.0.0.252: icmp_seq=1 ttl=64 time=200 ms
64 bytes from 10.0.0.252: icmp_seq=2 ttl=64 time=200 ms
64 bytes from 10.0.0.252: icmp_seq=3 ttl=64 time=200 ms

--- 10.0.0.252 ping statistics ---
3 packets transmitted, 3 received, 0% packet loss, time 2002ms
rtt min/avg/max/mdev = 200.162/200.316/200.621/0.424 ms
containernet>

To stop the emulation, do:

containernet> exit

Installation

Containernet comes with two installation and deployment options. You can find further documentation and help in the wiki.

Option 1: Bare-metal installation

Automatic installation is provided through an Ansible playbook. Requires Ubuntu 18.04 LTS and Python3.

$ sudo apt-get install ansible git aptitude
$ git clone https://github.com/containernet/containernet.git
$ cd containernet/ansible
$ sudo ansible-playbook -i "localhost," -c local install.yml
$ cd ..
$ sudo make develop

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 DockerHub.

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.

Build/Pull:

# build the container locally
$ docker build -t containernet/containernet .

# or pull the latest pre-build container
$ docker pull containernet/containernet

Run:

# run interactive container and directly start containernet example
$ docker run --name containernet -it --rm --privileged --pid='host' -v /var/run/docker.sock:/var/run/docker.sock containernet/containernet

# run interactive container and drop to shell
$ docker run --name containernet -it --rm --privileged --pid='host' -v /var/run/docker.sock:/var/run/docker.sock containernet/containernet /bin/bash

References

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

Publications

Containernet is part of the OpenSource MANO research ecosystem

Containernet is the basis of the vim-emu emulation platform for multi-PoP NFV scenarios.

Documentation

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

Libvirt Extension

Containernet 2.0 introduced an extension that added libvirt support which allows to connect and run arbitrary, fully-featured virtual machines (Qemu/KVM) as emulated hosts inside Containernet networks. However, this solution turned out to be to heavy and complicated to keep it in the master branch of Containernet. As a result, it was moved to n a dedicated branch on GitHub. More documentation about the libvirt integration is available on this wiki page. Note: The libvirt integration must be considered as experimental!

Contact

Support

If you have any questions, please use GitHub’s issue system to get in touch. You can find further documentation in the wiki.

Contribute

Your contributions are very welcome! Please fork the GitHub repository and create a pull request. We use Travis-CI to automatically test new commits.

Lead developer

Manuel Peuster