Article Source

• Title: Basic ONOS Tutorial

---

Basic ONOS Tutorial

Introduction

Pre-requisites

You will need a computer with at least 2GB of RAM and at least 5GB of free hard disk space. A faster processor or solid-state drive will speed up the virtual machine boot time, and a larger screen will help to manage multiple terminal windows.

The computer can run Windows, Mac OS X, or Linux – all work fine with VirtualBox, the only software requirement.

To install VirtualBox, you will need administrative access to the machine.

The tutorial instructions require prior knowledge of SDN in general, and OpenFlow and Mininet in particular. So please first complete the OpenFlow tutorial and the Mininet walkthrough. Although not a requirement, completing the FlowVisor tutorial before starting this one is highly recommended. Also being familiar with Apache Karaf would be helpful although not entirely required.

Stuck? Found a bug? Questions?

Email us if you’re stuck, think you’ve found a bug, or just want to send some feedback. Please have a look at the guidelines to learn how to efficiently submit a bug report.

Set up your environment

Install required software

You will need to acquire two files: a VirtualBox installer and the Tutorial VM. 

After you have downloaded VirtualBox, install it, then go to the next section to verify that the VM is working on your system.

Create Virtual Machine

Double-click on the downloaded tutorial zipfile. This will give you an OVF file. Open the OVF file, this will open virtual box with an import dialog.

Click on import. When the import is finished start the VM and log in using:

USERNAME: tutorial1

PASSWORD: tutorial1

Important Command Prompt Notes

In this tutorial, commands are shown along with a command prompt to indicate the subsystem for which they are intended.

For example,

indicates that you are in the ONOS command line, whereas

indicates that you are in mininet.

 

Resetting

We have provided a simple mechanism which allows you to restart the tutorial from scratch. Simply, click on the 'Reset' icon on your desktop and this will reset ONOS to its initial state. It'll take a few seconds for ONOS to restart and during that time you may not be able to launch your ONOS cli. 

Start Mininet

We’ll be using the same physical topology for all exercises, so now is a good time to start Mininet. The network is a simple set of six switches where the outer switches are connected to two interconnection switches, which are connected together. The diagram below shows the topology.

Each of the outer switches has six hosts attached to it. To start mininet with this topology, simply double click on the Mininet icon on your desktop. To exit mininet, type CTRL-D or exit in the mininet prompt.

Start ONOS

Double-click the "Reset" icon on the desktop now. This will ensure the environment is clean and will start up ONOS.

Reactive Forwarding

Start by opening a console onto ONOS, you can do this by double clicking on the ONOS icon.

No pings? Why?

 In this exercise, we are going to run a sample app shipped with ONOS. Reactive Forwarding is a simple application which installs flows for every packet in that arrives at the controller. Go to your mininet prompt and do the following.

 

You will notice that the ping fails as shown below.

 

So why did the ping fail? Well we didn't load the reactive forwarding application. Indeed, if you list the loaded applications you will see the following:

As you can see above, there is no reactive forwarding application loaded. Let's see how we load it.

Make it so, Number one

In your ONOS window, do

 

Then, in a mininet window run the ping again, just this time don't limit the number of pings.

This time the ping is flowing:

Start stop start stop....

You have now seen that you can load applications into ONOS dynamically. Actually you can also interrupt applications while they are running so, for example, let's stop the reactive forwarding application.

Observe that the ping has now stopped. This is because when the reactive forwarding application is unloaded, it cleans up after itself by removing the rules that it has pushed. We'll talk more about this in the next section. For now, let's restart the reactive forwarding application.

...and the ping restarts  

ONOS CLI commands

ONOS has many CLI commands. In this section, we will go through some of the most useful commands. This section may also serve as a CLI reference for you during this tutorial. While we will explain some of the ONOS CLI commands here you can find an exhaustive list by running:

or more information about an individual command adding --help to any command. Also most commands have autocompletion to help you find the parameters quickly and easily.

Devices command

An SDN Controller would be nothing without devices to control. Luckily, ONOS has a convenient command to list the device currently known in the system. Running

will return the following information,

which consists of a device id, and a boolean value which indicates whether this devices is currently up. You also get the type of device and well as it's role relationship with this ONOS instance.

Links command

 The links command is used to list the links detected by ONOS. At the ONOS prompt run

and you should get the following output:

The output shows you the list of discovered links. Reported links are formatted by source device-port pair to destination device-port pair. The 'type' field indicates whether the link is a direct connection between two devices or not. 

Hosts command

A network without hosts is a little like a city without bars, it would be a ridiculously boring place. Fortunately, ONOS has the ability to list the hosts (as opposed to bars, although that would be a great feature) currently in the system.

with this output:

Which displays the hosts' id as well as its mac address and where in the network it is connected. The '-1' in the id field is used to display the vlan information, in this case there is no vlan .

Flows command

The flows command allows you to observe which flow entries are currently registered in the system. Flow entries may be in several states:

• PENDING_ADD - The flow has been submitted and forwarded to the switch.
• ADDED - The flow has been added to the switch.
• PENDING_REMOVE - The request to remove the flow has been submitted and forwarded to the switch.
• REMOVED - The rule has been removed.

So let's start some traffic but going to the mininet window and running

then in the ONOS window let's run the flows command

you should see the following output

As you can see from the above output, ONOS provides many details about he the flows at the switches. For example each flow entry defines a selector and treatment which is the set of traffic matched by the the flow entry and how this traffic should be handled. Notice as well that each flow entry it tagged by an appId (application id), this appId identifies which application installed this flow entry. This is a useful feature because it can help an admin identify which application may be misbehaving or consuming many resources.

Paths command

Given a network topology, ONOS computes all the shortest paths between any two nodes.  This is especially useful for your applications to obtain path information for either flow installation or some other use. The paths command takes two arguments, both of them are devices. To make things easy for you ONOS provides CLI autocompletion by simply hitting the <TAB> key.

ONOS lists device options for you, thereby making it easier to find the devices you would like. For example, the output of the command below shows two paths of equal costs.

Intent Command

The intent command allows one to see what intents are stored in the system. Intents can be in several states:

• SUBMITTED - The intent has been submitted and will be processed soon.
• COMPILING - The intent is being compiled. This is a transient state.
• INSTALLING - The intent is in the process of being installed. 
• INSTALLED - The intent has been installed.
• RECOMPILING - The intent is being recompiled after a failure.
• WITHDRAWING - The intent is being withdrawn.
• WITHDRAWN - The intent has been removed.
• FAILED - The intent is in a failed state because it cannot be satisfied.

For more information about Intents go here.

Note: You will not see any intents until some have been added. In the next section of the tutorial, you will load the intent reactive forwarding application, which automatically adds intents as needed.

The command can also tell you what type of sub-intents the intent has been compiled to:

For example, this host to host intent has been compiled to two path intents with the appropriate traffic selections and actions computed on your behalf.

Intent Reactive Forwarding

Another sample application in ONOS is the intent reactive forwarding application. Rather than pushing flow entries for each packet it sees, the intent reactive forwarding application provisions an intent. In particular, it provisions a host to host intent which is a simple connectivity intent which enables the connectivity between two hosts. 

Out with the old, In with the new

First let's start by removing the old reactive forwarding application and load the intent reactive forwarding application.

NB: Notice the different bundle names: onos-app-fwd vs. onos-app-ifwd (Hint: there is an extra 'i' )

Ok let's just make sure it is loaded correctly:

So we can see that the intent forwarding application is correctly active. The appId for the Reactive Forwarding application remains, so if you reload that application it will get the same appId it had previously.

Intentionally React

Alright so let's forward some traffic. 

 

So by using the flows command you can list the flows (by running the flows command) that the intent installed. So how is this different than the other application? Well the end result is the same but the process by which it was obtained it radically different. The intent reactive forwarding application has installed an intent between h21 and h31, as you can see by running the intents command:

 

So the intent forwarding app has pushed the intent you see above as evidenced by the appId field. The intent is a host to host intent which details the path along which the flows have been installed. If you would like to know more about intents or the intent framework in general have a look at this page.

Before we continue, let's remove the intent you just installed so that it doesn't get in the way of the intent gymnastics we are going to do in the next section.

The <tab> key will autocomplete the id that was associated the intent we just pushed. You should now see that there are no intents in the system.

This command will return nothing as there are no intents in the system.

State your intentions

One major advantage of using intents over simply using flow entries to program your network is that intents track the state of the network and reconfigure themselves in order to satisfy your intention. For example, if link were to go down the intent framework would reroute your intent (ie. your flows) onto an alternative path. But, what if there are no alternative path? Well, in this case the intent would enter the failed state and remain there until a path becomes available. Pretty cool, eh? Let's check this out in action.

Let's start by looking at the set of hosts know to ONOS. If you ran through this tutorial exactly there should be four hosts 

 

Pick any any of these two hosts and install a host to host intent for them. 

This command will provision a path between 10.0.0.1 (h11) and 10.0.0.19 (h41) and you can see that the intent is installed.

So now that the intent is installed let's have a look what path it is using. Be careful here as the output from the tutorial and what you see may vary slightly as all alternate paths here have equal cost and therefore ONOS is free to pick either one.

We can see that the traffic flows between dpid 00:00:00:00:00:00:00:01 (s1) and 00:00:00:00:00:00:00:0b (s11). If you have trouble seeing this, refer to the topology diagram in the beginning of this tutorial.

 

Ok so let's teardown the link between s1 and s11, you may have to teardown the link between s2 and s11 so pay attention to the flows command output. This can be done in mininet by running:

and let's have a look at the flows again.

Observe that the flows moved from  00:00:00:00:00:00:00:01 to  00:00:00:00:00:00:00:02 (s2) and the remaining flows remained untouched. How did this happen? Well when we tore down the link between s1 and s11, ONOS detected this change and informed all people interested by this event that the link went down. Therefore the intent service receives this information and realises that one of its intents is affected by this change and thus it recompiles the intent in light of this change which causes the intent to be installed on a different path.

This simple example shows that using intents is more powerful than simply installing flows. Intents maintain your intention (hence the name!) while retaining the ability to install them as is possible or most efficient. 

Up down up down

If you wish you can take down more links and see what happens. Obviously, if you partition the network then no flows will be installed, sadly ONOS doesn't grow links between switches yet. You can bring up links in mininet by:

Have fun!

ONOS Graphical User Interface

First , lets reload our reactive forwarding application.

 

ONOS comes with a GUI. The GUI allows you to manipulate your network in a simple way.

To open the UI simply click on the 'ONOS GUI' icon. Initially, when the UI loads up you will see your network's topology over a map of the US. You can remove the map by hitting 'b'. In fact, the UI has a cheat sheet which can be toggled by hitting '/' which is easy to remember because it's the question mark key except you don't need to hit shift. 

Ok let's make all the hosts appear in the UI, we can do this by making the hosts talk on the network. The best way to do this is to run the pingall command at mininet.

The hosts will not appear initially, simply type 'h' in your browser window and they will appear. At this point you should see something roughly similar to the image below. 

 

GUI Features

GUI Cheat Sheet

At anytime you can pull up the GUI's cheat sheet by typing '/' (which is '?' without the pesky shift ) and you will get a pane that looks like below.

Summary pane

The GUI comes with a very useful summary pane. It shows you a  summary of what is going on at this ONOS cluster.

Switch details

When you click on a switch a pane appears on the right hand side. This pane gives information about the switch as shown in the image below.

You my notice that the UI reports nine ports but you can only see eight, this is because OpenFlow switches have virtual ports that are hard to show on a UI. 

Shift click will unselect the switch and remove the pane

Instances

The GUI has the ability to show which ONOS instances are active. By hitting the 'i' key (it will be open by default) you will see a pane show up on the left hand side as shown below.

Notice that the glyphs for the switches changes color, this indicates which switches are controlled by which instance. This is useful to see at a glance which switches are controlled by which ONOS instance.

Install Intent

Ok let's install an intent using the UI. First select two hosts by clicking on one host then shift-click on another. Let's pick 10.0.0.20 and 10.0.0.9. Now a pane will appear on the right and side of the screen as here:

Now click on 'Create Host-to-host Flow', this actually provisions a host to host intent and lights up the path used by the intent. 

You can check that the intent was installed via the ONOS cli

Now let's send some traffic on that intent. This will animate the link to show traffic and display how much traffic (counter value) is flowing through that link

 

 

 

 

Show all traffic

Another thing you can do is activate the 'All Traffic' mode in the UI. This will show you any traffic that is running on the network. Activate this command by hitting 'a'.

Play on

Now you know the main features of the UI. We encourage you to play around with it to find out what other features you can use and who knows may find a few bugs.

Exploring Further

Here we just scratched the surface of what ONOS can do in terms of controlling a network. We highly encourage you to continue using ONOS and perhaps start developing your own applications. Find out how to get started in this tutorial.