Skip to content

Commit

Permalink
Revise README and tests, add LICENSE
Browse files Browse the repository at this point in the history
  • Loading branch information
@stevelorenz
stevelorenz committed Sep 23, 2019
1 parent 97c148c commit 96024e0
Show file tree
Hide file tree
Showing 18 changed files with 170 additions and 111 deletions.
21 changes: 21 additions & 0 deletions LICENSE
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
The MIT License

Copyright (c) 2019 The Deutsche Telekom Chair of Communication Networks. https://cn.ifn.et.tu-dresden.de

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
THE SOFTWARE.
20 changes: 8 additions & 12 deletions Makefile
View file
Original file line number Diff line number Diff line change
@@ -1,10 +1,10 @@
# vim:ft=make
#

COMNETSEMU = comnetsemu/*.py
CE_BIN = bin/ce
TEST = comnetsemu/test/*.py
UNITTESTS = comnetsemu/test/unit/*.py
EXAMPLES = examples/*.py
PYSRC = $(COMNETSEMU) $(EXAMPLES) $(CE_BIN) $(TEST)
PYSRC = $(COMNETSEMU) $(EXAMPLES) $(CE_BIN) $(UNITTESTS)
PYTHON ?= python3
PYTYPE = pytype
P8IGN = E251,E201,E302,E202,E126,E127,E203,E226
Expand Down Expand Up @@ -39,17 +39,13 @@ test-examples: $(COMNETSEMU) $(EXAMPLES)
test-examples-all: $(COMNETSEMU) $(EXAMPLES)
cd ./examples && bash ./run.sh -a

test: $(COMNETSEMU) $(TEST)
@echo "Running core tests of ComNetsEmu python module."
$(PYTHON) ./comnetsemu/test/test_comnetsemu.py

test-all: $(COMNETSEMU) $(TEST)
@echo "Running all tests of ComNetsEmu python module."
$(PYTHON) ./comnetsemu/test/runner.py -v
test: $(COMNETSEMU) $(UNITTESTS)
@echo "Running all unit tests of ComNetsEmu python package."
$(PYTHON) ./comnetsemu/test/unit/runner.py -v

coverage: $(COMNETSEMU) $(TEST)
coverage: $(COMNETSEMU) $(UNITTESTS)
@echo "Running coverage tests of ComNetsEmu core functions."
$(PYTHON) -m coverage run --source ./comnetsemu ./comnetsemu/test/test_comnetsemu.py
$(PYTHON) -m coverage run --source ./comnetsemu ./comnetsemu/test/unit/runner.py -v
$(PYTHON) -m coverage report -m

installercheck: ./util/install.sh
Expand Down
133 changes: 86 additions & 47 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,20 +6,41 @@ ComNetsEmu
**This project is currently under heavy development [beta]**.

This project is currently hosted both on [Bitbucket](https://bitbucket.org/comnets/comnetsemu/src/master/) and [Comnets
Gitlab](https://git.comnets.net/book/comnetsemu) (on the server of [The Telekom Chair of Communication
Networks](https://cn.ifn.et.tu-dresden.de/)). 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.
Gitlab](https://git.comnets.net/book/comnetsemu) (on the server of [The Telekom Chair of Communication Networks](https://cn.ifn.et.tu-dresden.de/)).
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

<!-- vim-markdown-toc GitLab -->

* [Description](#description)
* [Main Features](#main-features)
* [Installation](#installation)
* [Option 1: Install in a Vagrant managed VM (Highly Recommended)](#option-1-install-in-a-vagrant-managed-vm-highly-recommended)
* [Option 2: Bare-mental Installation](#option-2-bare-mental-installation)
* [Post-Installation](#post-installation)
* [Upgrade ComNetsEmu and Dependencies](#upgrade-comnetsemu-and-dependencies)
* [Run the Docker-in-Docker example](#run-the-docker-in-docker-example)
* [File Catalog](#file-catalog)
* [Development Guide and API Documentation](#development-guide-and-api-documentation)
* [Q&A](#qa)
* [Useful Links](#useful-links)
* [Contributing](#contributing)
* [Contact](#contact)

<!-- vim-markdown-toc -->

### 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](http://mininet.org/) emulator to support better emulation of
versatile NFV/SDN network **applications**.
See the comparison between upstream Mininet [here](./doc/comparison.md).
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](http://mininet.org/) emulator to support better emulation of versatile NFV/SDN network **applications**.
See the detailed comparison between upstream Mininet [here](./doc/comparison.md).

Common facts about ComNetsEmu:

Expand All @@ -38,6 +59,9 @@ Common facts about ComNetsEmu:
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**:
Expand All @@ -46,16 +70,18 @@ Common facts about ComNetsEmu:
1. 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 [install
script](./util/install.sh) 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. (Physical
CPU: Intel i7-7600U @ 2.80GHz).
application requires **root privilege**, hacking it inside a VM is also safer.
ComNetsEmu's [installation script](./util/install.sh) 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 also in $TOP_DIR.
external source dependencies in $TOP_DIR/comnetsemu_dependencies.

```bash
$ cd $TOP_DIR
Expand All @@ -65,25 +91,10 @@ $ git clone https://bitbucket.org/comnets/comnetsemu.git comnetsemu
ComNetsEmu's [installer](./util/install.sh) 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 limitation of Vagrant).
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**.

**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` module can be only
installed from source using setuptools. Pip package will be created for stable releases later.

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:

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

[Here](./doc/dependencies.md) is a list of dependencies required by ComNetsEmu, these tools can be installed and updated by
ComNetsEmu's [installer](./util/install.sh).

Expand All @@ -97,7 +108,7 @@ Recommended setup:
- Vagrant: v2.2.5 and beyond ([Download Link](https://www.vagrantup.com/downloads.html))
- Virtualbox: v6.0 and beyond ([Download Link](https://www.virtualbox.org/wiki/Downloads))

You can create and manage the VM with (cd to the same directory of the [Vagrantfile](./Vagrantfile)):
In the directory of ComNetsEmu source code, you can create and manage the VM with:

```bash
# This will create the VM at the first time (takes around 20 minutes)
Expand All @@ -112,10 +123,10 @@ $ 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 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.
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`:
```bash
Expand All @@ -138,7 +149,7 @@ $ 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 modules are installed in development mode. So you can work on the emulator
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
Expand All @@ -158,10 +169,28 @@ $ 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:

```bash
$ 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 module, utility scripts, examples and
applications. It is recommended to upgraded to latest commit of the master branch.
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](./util/install.sh) has a function to ONLY upgrade ComNetsEmu's dependencies software automatically.
This script **ONLY** works on supported distributions and has some default variables:
Expand All @@ -171,8 +200,8 @@ This script **ONLY** works on supported distributions and has some default varia

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

**WARNING**: The upgrade function does not re-install(upgrade) the Python module of ComNetsEmu. If the Vagrant VM is
used, the develop mode and sync folder are used to apply changes automatically. Otherwise, the module should be
**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
Expand Down Expand Up @@ -200,12 +229,12 @@ $ sudo python3 .dockerindocker.py

See the [README](./examples/README.md) to get information about all built-in examples.

### Catalog
### File Catalog

- [app](./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](./comnetsemu/): Source codes of ComNetsEmu's Python modules.
- [comnetsemu](./comnetsemu/): Source codes of ComNetsEmu's Python package.

- [examples](./examples/): Example programs for functionalities of the ComNetsEmu emulator.

Expand All @@ -219,6 +248,8 @@ See the [README](./examples/README.md) to get information about all built-in exa

### Development Guide and API Documentation

TODO: Add separate development guide

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

```bash
Expand Down Expand Up @@ -250,7 +281,15 @@ $ xdg-open ./doc/html/index.html

### [Useful Links](./doc/ref_links.md)

### Maintainers
### Contributing

This project exists thanks to all people who contribute.
[List](./CONTRIBUTORS) of all contributors.

TODO: Add separate contributing guide

### Contact

Project main maintainers:

- Zuo Xiang (zuo.xiang@tu-dresden.de)
- Carl Collmann (carl.collmann@mailbox.tu-dresden.de)
- Zuo Xiang: zuo.xiang@tu-dresden.de
8 changes: 4 additions & 4 deletions app/mec/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -21,7 +21,7 @@ BS_1 BS_2

This structure now needs to be translated into something that can be implemented in Mininet.
* Client -> Node / DockerHost, needs to execute an client application that sends requests
* Base Station -> OVSwitch, with custom Contoller to choose optimal Server in AS to process request
* Base Station -> OVSwitch, with custom Controller to choose optimal Server in AS to process request
* Autonomous System -> Fat Tree topology, end Nodes are the Servers, which are modeled as DockerHosts (it is assumed that every Server offers the Option to process the Client request), Nodes in-between are simple switches

````text
Expand Down Expand Up @@ -82,20 +82,20 @@ Before running, a dedicated docker image needs to be created with
sudo docker build -t mec_test -f ./Dockerfile.mec_test .
```

... ,where `mec_test` is the image name used in both, `mec` and `mec_only_forwarding` and `Dockerfile.mec_test` is the Dockerfile located in `/app/mec`.
... ,where `mec_test` is the image name used in both, `mec` and `edgecloud.py` and `Dockerfile.mec_test` is the Dockerfile located in `/app/mec`.

In the next step the Controllers need to be started

```sh
ryu-manager --verbose --log-file log.txt --ofp-tcp-listen-port 6633 ./controller.py
```

The `--log-file` option is optional, but `--ofp-tcp-listen-port` should match the one in `edgecloud.py` / `only_forwarding.py` (relevant when using multiple controllers).
The `--log-file` option is optional, but `--ofp-tcp-listen-port` should match the one in `edgecloud.py` (relevant when using multiple controllers).

To launch the emulation

```sh
sudo python3 ./edgecloud.py
sudo python3 ./edgelcoud/edgecloud.py
```

It is recommended to have a separate terminal session for each controller and the application.
Loading

0 comments on commit 96024e0

Please sign in to comment.