ComNetsEmu

A holistic testbed/emulator for the book: Computing in Communication Networks: From Theory to Practice

This project is currently under heavy development [beta].

This project is currently hosted both on Bitbucket and Comnets Gitlab (on the server of The Telekom Chair of Communication Networks). The master and dev branches are synchronized. The master branch contains latest stable sources, the dev branch is used as blessed branch for development.

Issues and pull requests can be created on both repositories. Please create an issues if there are any problems or feature requirement of the tested. It will be answered more quickly than Emails.

Table of Contents

TOC only supports Gitlab.

• Description
  • Main Features
• Installation
  • Option 1: Install in a Vagrant managed VM (Highly Recommended)
  • Option 2: Bare-mental Installation
  • Post-Installation
• Upgrade ComNetsEmu and Dependencies
• Run the Docker-in-Docker example
• File Catalog
• Development Guide and API Documentation
• FAQ
• Useful Links
• Contributing
• Contact

Description

ComNetsEmu is a tested and network emulator designed for the NFV/SDN teaching book "Computing in Communication Networks: From Theory to Practice". The design focus on emulating all examples and applications on a single computer, e.g. on a single laptop. ComNetsEmu extends the famous Mininet emulator to support better emulation of versatile NFV/SDN network applications. See the detailed comparison between upstream Mininet here.

Common facts about ComNetsEmu:

• Emulation performance is considered but not the main focus. All emulated nodes (processes) share the same underlying compute, storage and network resources when running it on a single system. ComNetsEmu is heavier than vanilla Mininet due to complete host isolation. Chose a reasonable performance limitation is recommended for better emulation results. For example, use e.g. 100ms as link delay instead of 1ms for large scale topology.

• ComNetsEmu is developed with Python3.6.

Main Features

• Use Docker hosts in Mininet topologies.

• Manage application Docker containers deployed INSIDE Docker hosts. "Docker-in-Docker"(sibling containers) is used by ComNetsEmu as an lightweight emulation for nested-virtualization. The Docker host with internal Docker containers deployed is used to mimic an actual physical host that runs Docker containers.

• A collection of application examples for "Computing In Communication Networks" with sample codes and detailed documentation. All examples can be easily reproduced and extended.

Installation

Supported/Tested distributions:

1. Ubuntu 18.04 LTS (Bionic Beaver): Used as base-box in the Vagrant VM.
2. GNU/Debian 10 (Buster)

For development and using it as a playground, it is recommended to run ComNetsEmu INSIDE a VM. Run ComNetsEmu/Mininet application requires root privilege, hacking it inside a VM is also safer. ComNetsEmu's installation script uses Mininet's install script to install Mininet natively from source. As described in Mininet's doc, the install script is a bit intrusive and may possible damage your OS and/or home directory. It is recommended to trying and installing ComNetsEmu in a VM. It runs smoothly in a VM with 2 vCPUs and 2GB RAM. (Host Physical CPU: Intel i7-7600U @ 2.80GHz). Some applications require more resources. For example, the object detection application requires minimal 4GB RAM.

Firstly, clone the repository with git. $TOP_DIR is the directory that you want to download the ComNetsEmu's source code. In Vagrant VM, TOP_DIR="$HOME". ComNetsEmu's installer (BASH scripts) assumes the name of the source directory is comnetsemu and will download external source dependencies in $TOP_DIR/comnetsemu_dependencies.

$ cd $TOP_DIR
$ git clone https://bitbucket.org/comnets/comnetsemu.git comnetsemu

ComNetsEmu's installer tries to install dependencies with package manager (apt, pip etc.) if they are available. Unavailable dependencies (e.g. latest stable Mininet) are installed from source code. The source codes are downloaded into "$TOP_DIR/comnetsemu_dependencies" directory by default (It does not use a subdirectory inside the ComNetsEmu's source due to a file-permission issue of Vagrant (v2.2.5)). The installer also checks the status of the dependency directory when upgrading is performed. The ComNetsEmu's installer script is designed mainly for easy/simple setup/upgrade of the Vagrant VM environment.

Here is a list of dependencies required by ComNetsEmu, these tools can be installed and updated by ComNetsEmu's installer.

Option 1: Install in a Vagrant managed VM (Highly Recommended)

The comfortable way to setup the test and development environment is to run a pre-configured VM managed by Vagrant. It supports different VM hypervisor and Virtualbox is used in project's Vagrantfile.

Recommended setup:

• Vagrant: v2.2.5 and beyond (Download Link)
• Virtualbox: v6.0 and beyond (Download Link)

In the directory of ComNetsEmu source code, you can create and manage the VM with:

# This will create the VM at the first time (takes around 20 minutes)
$ vagrant up comnetsemu

# SSH into the VM
$ vagrant ssh comnetsemu

# Poweroff the VM
$ vagrant halt comnetsemu

# Remove/Delete the VM
$ vagrant destory comnetsemu

A customization shell script (should be located in ./util/vm_customize.sh) is executed at the end of the provision process. This script is executed by the vagrant user which can run sudo commands without password. This script can be used to add your customized tools (e.g. ZSH, Desktop environment etc) and configuration to the ComNetsEmu VM. Since the vagrant VM uses Ubuntu LTS, apt should be used to manage the packages.

Example of vm_customize.sh:

sudo apt install -y zsh
# Install oh-my-zsh framework
sh -c "$(wget -O- https://raw.githubusercontent.com/robbyrussell/oh-my-zsh/master/tools/install.sh)"

The vagrant up should run correctly. If there are some "apt" or "dpkg" related error messages (like some packages can not be found or installed) during the vagrant up, it might due to the box you used to build the VM is outdated. It is configured in current ./Vagrantfile that the vagrant will check if there are any updates to the box used in the current environment. It can be checked manually with vagrant box update. You need to destroy the already built VM and recreate it to acquire the new updates in the box with:

$ vagrant box update
$ vagrant destory comnetsemu
# This will create the VM at the first time (takes around 15 minutes)
$ vagrant up comnetsemu

As configured in ./Vagrantfile, current source code folder on the host OS is synced to the /home/vagrant/comnetsemu folder in the VM. And the emulator's Python package is installed in development mode. So you can work on the emulator or application codes in your host OS and run/test them in the VM.

Option 2: Bare-mental Installation

• Install essential packages required by the installer from your package management systems:

$ sudo apt update
$ sudo apt upgrade
$ sudo apt install git make pkg-config sudo python3 libpython3-dev python3-dev python3-pip software-properties-common

• Install ComNetsEmu with all dependencies:

$ cd $TOP_DIR/comnetsemu/util
$ PYTHON=python3 bash ./install.sh -a

Post-Installation

MARK: ComNetsEmu is developed with Python3 (3.6). Please use python3 command to run examples or applications. Because the current master branch is still under heavy development, therefore this python3 package can be only installed from source using setuptools.

ComNetsEmu uses Docker containers to emulate network nodes. Some images are used to run hosts and app containers in examples and also applications. The Dockerfiles for external Docker hosts are located in ./test_containers.

Please build them after the installation and re-build them after updates by running the script:

$ cd ./test_containers
# This script removes all dangling images after build.
$ bash ./build.sh

Upgrade ComNetsEmu and Dependencies

The master branch contains stable/tested sources for ComNetsEmu's python package, utility scripts, examples and applications. It is recommended to upgraded to latest commit of the master branch.

The installer script has a function to ONLY upgrade ComNetsEmu's dependencies software automatically. This script ONLY works on supported distributions and has some default variables:

1. The ComNetsEmu's source files are located in "$TOP_DIR/comnetsemu"
2. The dependencies installed from source are located in "$TOP_DIR/comnetsemu_dependencies"

You can modify these variables in the installer script for your customized installation.

WARNING: The upgrade function does not re-install(upgrade) the Python package of ComNetsEmu. If the Vagrant VM is used, the develop mode and sync folder are used to apply changes automatically. Otherwise, the package should be re-installed manually.

Before running the upgrade function, the source code repository (by default, "$TOP_DIR/comnetsemu") should be updated to the latest commit in master branch via git (fix conflicts if required):

$ cd $TOP_DIR/comnetsemu
$ git checkout master
$ git pull origin master

Then run following commands to upgrade automatically (good luck ^_^):

$ cd $TOP_DIR/comnetsemu/util
$ PYTHON=python3 bash ./install.sh -u

Run the Docker-in-Docker example

$ cd $TOP_DIR/comnetsemu/examples/
$ sudo python3 .dockerindocker.py

See the README to get information about all built-in examples.

File Catalog

• app: All application programs are classified in this directory. Each subdirectory contains a brief introduction, source codes, Dockerfiles for internal containers and utility scripts of the application.

• comnetsemu: Source codes of ComNetsEmu's Python package.

• examples: Example programs for functionalities of the ComNetsEmu emulator.

• patch: Patches for external dependencies that are installed from source via installer.

• test_containers: Contains Dockerfiles and dependency files for external Docker containers (Docker host).

• utils: Utility and helper scripts.

• Vagrantfile: Vagrant file to setup development/experiment VM environment.

Development Guide and API Documentation

TODO: Add separate development guide

• Run unit tests with coverage report and minimal example tests:

$ sudo make coverage
$ sudo make test-examples

• Run static code checking(with pyflakes, pylint and pep8) and type hints checking (with google/pytype):

$ make codecheck
$ make typecheck

ComNetsEmu's development and API documentation is generated by Sphinx. Dependencies required to build documentation in HTML format are listed here. Please install these dependencies via pip install -r ./doc/requirements.txt. You can install dependencies and build documentation inside the Vagrant VM and view it on your host OS.

Run following commands to build documentation in HTML format and open it with Firefox.

$ make doc
$ firefox ./doc/build/html/index.html

FAQ

Useful Links

Contributing

This project exists thanks to all people who contribute. List of all contributors.

TODO: Add separate contributing guide

Contact

Project main maintainers:

• Zuo Xiang: zuo.xiang@tu-dresden.de