Mininet and onos.py workflow

This workflow is recommended for developers who want an easy end-to-end workflow that creates a single or multiple-node ONOS instance and a Mininet network, all in a single VM.

Mininet is a lightweight container orchestration system that is specialized for network emulation. With Mininet and onos.py, you can easily start up an ONOS cluster, and a modeled data network for any topology you might like, in a single VM or server. This is usually the most convenient way to create an ONOS development environment on your laptop, and you can be up and running in a matter of minutes (or seconds if you have already built ONOS and have already installed Mininet!)

Why use onos.py and Mininet?

If you are already running Mininet in a VM or on a physical server, it is easy to use onos.py to start up a complete emulated ONOS network in a single VM - including a ONOS cluster, modeled control network, and data network.

This simplifies development on a laptop, because you can run a single development VM (or no VM at all if you are running on a Linux machine!) Moreover, it is more efficient than a multi-VM setup because the entire emulated network lives in a single VM and shares a single Linux kernel.

Additionally, onos.py models the control network as well as the data network; you can easily change the number of nodes in your ONOS cluster, as well as things like the delay or bandwidth between nodes in the control network. It's even possible to change the control network topology as well as the data network topology. (We hope to make this more convenient and powerful in the future.)

onos.py provides a single, unified console via the mininet-onos> prompt, where you can enter both Mininet and ONOS commands - this can be very convenient! (We call this "One Console to Rule Them All.")

onos.py also automatically handles port forwarding, so you can easily connect to the GUI (or to karaf, or to the controllers' OpenFlow ports) by connecting to ports on the VM.

Chances are you're already using Mininet, so it's nice to be able to start an ONOS cluster using Mininet itself without installing or configuring additional software.

onos.py parametrizes both the control network (ONOS cluster) and the data network; so it's easy to iterate over multiple cluster sizes and network topologies.

We also hope that using onos.py will make ONOS development easier and more fun.

Configuring your development VM (or server)

This document assumes that you already have a VM or server  (we recommend Ubuntu 16 LTS) where you can compile ONOS, preferably using buck (or possibly with Maven - see below.)

1. Configure your VM with enough memory to run ONOS!
   1. ONOS java processes tend to consume a huge amount of memory. In order to run an ONOS cluster in a single VM, you should allocate a large amount of RAM to that VM. We recommend 2-4 GB (or more if you have it) for each ONOS node that you intend to run. You can see how much memory and CPU ONOS's java processes are using by running top - if you start using swap space, the performance of ONOS and Mininet will suffer greatly!
2. You may find it more convenient to install a GUI in your VM if you haven't already.
   1. In Ubuntu, you can use the default Ubuntu Unity desktop or the lighter-weight LXDE.
3. For VirtualBox, you may wish to set up networking so that you can connect from your host machine into your VM
   1. Usually this means adding a host-only interface to the VM, and making sure it's configured
   2. Make sure that interface has an IP address (you can check with ifconfig or ip addr)
   3. You may need to run dhclient manually

Getting Mininet

In order to use onos.py, you need Mininet, which is easy to install in a VM or server running a recent release of Ubuntu.

Option 1: If you are running Ubuntu 16.04, you can easily install Mininet 2.2 (and bridge-utils for LinuxBridge) using apt-get:

sudo apt-get install mininet bridge-utils

Option 2: It's also easy to install Mininet from source in an Ubuntu VM or server:

git clone http://github.com/mininet/mininet
mininet/util/install.sh -nvfw

(recommended options: -n: install core Mininet dependencies; -v: install Open vSwitch; -f: install legacy Stanford 1.0 user switch and controller; -w: install wireshark and improved OpenFlow wireshark dissector)

Option 3: You can also download a pre-built Mininet VM.

Verifying Your Mininet Installation

Make sure you are running Mininet version 2.2.1 or later:

mn --version

If not, try installing from the git repository as described above.

And make sure that Mininet works:

sudo mn --test pingall

If Mininet doesn't work, consult the troubleshooting section below.

Building ONOS

In order to run ONOS using onos.py, you will need a correctly built ONOS package in your VM.

We recommend building ONOS in your Mininet VM or server using buck:

cd ~/onos
buck build onos

Make sure that the build completes without errors - without a correctly built ONOS package, you will not be able to start ONOS.

You can also build elsewhere, copy onos.tar.gz into your development VM, and set ONOS_TAR to its full path. Since Java is platform independent, you can build on one OS (macOS, Windows) and run on another (Linux.)

It is also possible to share your ONOS source tree between a host system (e.g. Mac, Windows) and a VM (Linux) so that you can run your IDE on the host platform while using onos.py to run ONOS within the VM. (Todo: add more detailed instructions on how to do this!)

Starting up ONOS and your data network

Next, use Mininet and onos.py to start up a virtual ONOS cluster and data network:

cd ~/onos/tools/dev/mininet
sudo mn --custom onos.py --controller onos,1 --topo tree,2,2

(In this example, our "cluster" is a single node, but we will change that in a minute!)

You should see a bunch of output showing the startup of the control network and the data network.

After ONOS starts up and the switches connect, you should see the customized mininet CLI prompt:

mininet-onos>

At this point, you can enter mininet commands like pingall (all-to-all ping test) or help (to find out about Mininet CLI commands.)

You can also enter ONOS commands like onos:apps or onos:balance-masters and they should be invoked via karaf's client command on onos1.

You can also invoke the ONOS client using the onos command - press control-D to exit.

You can also connect to the ONOS GUI by following the instructions below.

To exit Mininet, use the exit command or press control-D.

Once you have verified that a single-node ONOS cluster and simple topology are working correctly, you can try a larger cluster (we recommend 3 nodes if you have configured your VM to use 6-12 GB of RAM) and a larger or more interesting topology (such as a 4x4 torus):

sudo mn --custom onos.py --controller onos,3 --topo torus,4,4