Due to a ransomware attack, the wiki was reverted to a July 2022 version. . We apologize for the lack of a more recent valid backup.
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!)
| Table of Contents |
|---|
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.
...
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.)
- Configure your VM with enough memory to run ONOS!
- ONOS
javaprocesses 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 runningtop- if you start using swap space, the performance of ONOS and Mininet will suffer greatly!
- ONOS
- You may find it more convenient to install a GUI in your VM if you haven't already.
- In Ubuntu, you can use the default Ubuntu Unity desktop or the lighter-weight LXDE.
- For VirtualBox, you may wish to set up networking so that you can connect from your host machine into your VM
- Usually this means adding a host-only interface to the VM, and making sure it's configured
- Make sure that interface has an IP address (you can check with
ifconfigorip addr) - You may need to run
dhclientmanually
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.
...
| Info | ||
|---|---|---|
| ||
Unfortunately the Linux 4.4 series kernel shipped in Ubuntu 16.04 (and later, possibly) has a kernel bug/regression which periodically breaks Mininet (and other container systems.) If you see a console (or |
Verifying Your Mininet Installation
Make sure you are running Mininet version 2.2.1 or later:
...
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.
...
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:
...
| Info | ||
|---|---|---|
| ||
If things don't start up correctly, look carefully at any error messages or exceptions which may have been generated - usually they give you important information which will enable you to figure out what is going wrong and to fix the issue. Also check out the troubleshooting section below. |
Questions and Answers
What do those mn command line options do?
--custom onos.py: uses onos.py to extend Mininet with new controller and switch types as well as a customized CLI
...
--topo torus,4,4: tells Mininet to use a 4x4 torus topology for the data network
What software switch does this use?
By default, it uses Open vSwitch. onos.py replaces Mininet's default switch with a new switch class called ONOSOVSSwitch or --switch onosovs. This switch class knows how to connect to an ONOS cluster with multiple IP addresses.
How can I use the user switch (or CPqD switch if I have it installed?)
In order to select the user switch (either Stanford reference switch or CPqD switch, depending on which one you have installed), you can use --switch onosuser.
How can I get more information on Mininet, the mn command, writing Mininet scripts, etc.?
There are lots of things you can do with Mininet, including customizing your data network topology, setting link parameters, etc..
For more information on Mininet, please check out http://docs.mininet.org
How can I specify the apps for ONOS to load?
For now, try using ONOS_APPS or connecting to the karaf console and using ONOS CLI commands. As root:
...
In the future, there should be an option to --controller onos and/or ONOSCluster().
How is the IP address range/subnet of the ONOS cluster specified?
--controller onos and ONOSCluster() take an ipBase option; the default is 192.168.123.0/24
...
sudo mn --custom onos.py --controller onos,3,ipBase=172.1.2.0/24 --topo tree,3,3
How can I connect to the ONOS console from the mininet-onos> prompt?
mininet-onos> onos
press control-D to return to the mininet-onos> prompt.
How can I run ONOS/karaf CLI commands from the mininet-onos> prompt?
There are several ways of doing it - you can use the one which works best for you. Here are four equivalent ways of invoking the onos:apps command:
...
The final method can be used to run client on a specific ONOS instance (and connect to that instance.)
How can I connect to the ONOS console from a shell/bash prompt?
Make sure karaf's bin/ directory is in your path, then:
client -h 192.168.123.1 # or the address of the ONOS node you wish to connect to
How can I connect to the karaf console using ssh?
ssh -p 8101 karaf@192.168.123.1
...
Note that this is using ssh inside the Mininet VM itself - from another machine, you should use the VM's IP address and the appropriate forwarded port as described below.
How can I connect to the ONOS GUI if ONOS is running in a Mininet host inside a VM?
One way is to run a browser inside the VM. Install a GUI in your VM if you haven't already (sudo apt-get install lxde and reboot), and then run a web browser pointed to the IP address of the ONOS node you want to talk to (for onos1, the default will be http://192.168.123.1:8181/onos/ui ). For the GUI to work well, you will want to make sure you've installed the appropriate VM support tools (such as virtualbox tools or VMware tools) for your virtualization platform.
...
If you are using VirtualBox, you will probably need to add a host-only interface to your VM and you may even need to run dhclient to make sure that that interface has an IP address. You can also set up port forwarding on a single interface - in this case you will want to make sure that it is set up for every port you wish to connect to (e.g. 8181 for the GUI on onos1.)
What are the default user name and password for the GUI?
Usually karaf/karaf (or sometimes onos/rocks)
onos.py should also respect the values of ONOS_WEB_USER and ONOS_WEB_PASS.
Can I use onos.py to control an external hardware (or virtual) network?
Yes you can! Simply use --topo none ; for example,
...
onos.py will forward the ports (e.g. 6653, 6654, 6655) appropriately as described above. Your Mininet VM or server will have to be reachable from the switches' management network, and you will need to configure your switches to connect to you ONOS nodes: the address of each node will be the VM's IP address, and the port will be the appropriate forwarded OpenFlow port.
Troubleshooting
onos.py doesn't work - what should I do?
Here are some things you can try:
- Make sure you've given your VM enough RAM - try using 2-4 GB for each ONOS node (so 6-12 GB for
--controller onos,3) - Make sure you are running the latest version of Mininet (see below)
- Look at the log file(s) and make sure no errors are occurring:
more /tmp/onos1/log; more /tmp/onos1/onos.log - Look at the output from running
mnoronos.pyand carefully examine and try to understand any error or exception messages - usually they will tell you what is going wrong - Reset your environment using:
sudo pkill -f karaf.jar; sudo mn -c - Make sure you have built onos:
cd ~/onos; buck build onos - Make sure you can run Mininet:
sudo mn --test pingall - Invoke Mininet in debug mode by adding the
-v debugflag to see what is going wrong or hanging:sudo mn --custom onos.py --controller onos,1 --topo tree,2,2 -v debug- You will want to pay careful attention to each operation as well as any error messages that are being displayed or exceptions that may be occurring.
Mininet doesn't work - what should I do?
First, make sure you are running Mininet 2.2.1 or later:
...
sudo mn --test pingall -v debug
Why can s1 ping onos1, but onos1 can't ping s1 (it just pings its own loopback interface?)
Currently, all of the switches are in the root namespace. If you wish to test connectivity from a switch to a controller, try pinging nat0 instead. In the future we may add support for a more complex control network with separate IP addresses for the switch management interfaces.
Why is ONOS startup so slow?
On my laptop, a 3-node ONOS cluster typically takes about a minute to start up, and a single-node ONOS cluster takes up to 20 seconds to start up.
...
You can also look at /tmp/onos1/log to see if exceptions are occurring.
Why can't I connect to the GUI that is running somewhere inside my VirtualBox VM?
First, make sure that you've configured your VM appropriately to enable connectivity:
...