Contents of this page are obsolete. Please refer to Getting Started with ONOS screencast and Building ONOS instead.
If you have come across Installing and Running ONOS, you'll notice that there are several ways to install and run ONOS. This tutorial focuses on showing you one of several useful deployment methods - ONOS packaged from source, and deployed in an Ubuntu VirtualBox VM using Windows, Linux or Mac OS X as an operation system on your computer.
By completing this tutorial, in addition to learning how to create your ONOS lab environment you will understand how to:
Commands at the shell of the ONOS VM begin with $ (or sdn@onos-scratch:~$)
$ sudo -s # |
The commands at the build machine shell begin with build:~$: (or sdn@build:~$)
build:~$ sudo -s build:~# |
You need a build machine for packaging ONOS and for running your Ubuntu Server ONOS VM. The build machine should be running a UNIX-like OS. In this tutorial you will create a build VM in VirtualBox named Build that is running Ubuntu 14.04, 64-bit Desktop.
You can create the two virtual machines using the virtualization software of your choice, but in this case we use VirtualBox. This tutorial assumes you are using VirtualBox (free open source virtualiztion software).
Setup needed:
This link will guide you through installing VirtualBox if you do not have it installed: http://www.wikihow.com/Install-Ubuntu-on-VirtualBox |
Add Host-only Networks vboxnet0 adapter in VirtualBox if it doesn’t have it:
Go to VirtualBox Preferences > Network, select Host-only Networks tab, and:
Click on the System tab. Choose boot order and keep CD/DVD on the top as first priority.
Log into your new VM as sdn and give the user passwordless sudo privileges. Run sudo visudo, and add the following line to the end of the file:
sdn ALL=(ALL) NOPASSWD:ALL |
Then, update the package repository:
$ sudo apt-get update |
You should also be able to verify that it has two network interfaces, eth0, eth1 and lo:
$ ifconfig -a
eth0 Link encap:Ethernet HWaddr 08:00:27:15:7e:e1
inet addr:10.0.2.15 Bcast:10.0.2.255 Mask:255.255.255.0
inet6 addr: fe80::a00:27ff:fe15:7ee1/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:35 errors:0 dropped:0 overruns:0 frame:0
TX packets:43 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:3535 (3.5 KB) TX bytes:3749 (3.7 KB)
eth1 Link encap:Ethernet HWaddr 08:00:27:b7:18:47
inet addr:192.168.56.101 Bcast:192.168.56.255 Mask:255.255.255.0
inet6 addr: fe80::a00:27ff:feb7:1847/64 Scope:Link
UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
RX packets:157 errors:0 dropped:0 overruns:0 frame:0
TX packets:48 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:1000
RX bytes:19323 (19.3 KB) TX bytes:7379 (7.3 KB)
lo Link encap:Local Loopback
inet addr:127.0.0.1 Mask:255.0.0.0
inet6 addr: ::1/128 Scope:Host
UP LOOPBACK RUNNING MTU:65536 Metric:1
RX packets:0 errors:0 dropped:0 overruns:0 frame:0
TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
collisions:0 txqueuelen:0
RX bytes:0 (0.0 B) TX bytes:0 (0.0 B)
|
If eth1 doesn't have UP as an attribute, manually run DHCP client (this should also bring the interface up):
$ sudo dhclient eth1 |
Or manually assign IP and bring the interface up:
$ sudo ifconfig eth1 <IP address> up |
Generate a SSH public key on your build machine if you hadn't done so in the past.
Login to the build machine and run the following command:
build:~$ ssh-keygen -t rsa |
The default options and no password are fine for this tutorial.
Verify connectivity. From the build machine you should be able to SSH to the onos-scratch VM using the IP address assigned to eth1:
build:~$ ssh -l sdn 192.168.56.101 |
If the ssh connection failed make sure that the openssh-server is installed by running:
$ sudo apt-get install openssh-server |
Check that you can ping the onos-scratch VM by IP from the build machine and reverse, for example:
sdn@build:~$ ping 192.168.56.101 |
Close the ssh connection to the onos-scratch VM by typing exit.
build:~$ sudo apt-get install git-core |
Install Karaf, Maven:Create two directories called ~/Downloads and ~/Applications. Download the Karaf 3.0.5 and Maven 3.3.9 binaries (the tar.gz versions of both) into ~/Downloads and extract it to ~/Applications. Keep the tar archives in ~/Downloads; we'll need that later.
Next, install Oracle Java 8:
It will ask you to acknowledge the license; do so when prompted. |
Now let’s copy a repository into a new onos directory under the home directory on the build machine.
navigate to the home directory by issuing this command:
build:~$ cd ~ build:~$ git clone https://gerrit.onosproject.org/onos |
This will create a directory called onos, with the source code in it.
The VM only requires Java 8 - follow the instructions for Java 8 above performed on the build VM.
First off, you will need to export several environment variables. The ONOS source comes with a sample bash_profile that can set these variables for you.
This file can be sourced from the interactive portion of .bashrc, or .bash_aliases (or .profile if /bin/sh is bash) of user sdn, by adding the following line to it at the end:
. ~/onos/tools/dev/bash_profile |
Warning: technically any bash-specific code should not go in .profile. If you have a Debian-based system (e.g. Raspbian) where .profile may be executed by a shell that is not bash (e.g. /bin/sh is |
Here is how:
On the build VM, Edit the .bashrc file (by typing the command below)
sdn@build:~$ nano ~/.bashrc |
Add the line below at the end of the file:
. ~/onos/tools/dev/bash_profile |
Press Ctrl-X to exit and Yes to save changes.
Once the line is added, source the file you just modified (or just log out and log back in): or run this command:
sdn@build:~$ . ~/.bashrc |
Once you run the above command, you will see in the output of the env command that several new variables, such as ONOS_ROOT, OCI, and KARAF_ROOT, have been set.
Make sure you also setup ONOS_USER If you used a user name other than "sdn" during the Ubuntu installation. You can also customize the ONOS_GROUP (typically, the user name and group name will be identical.)
|
Edit ~/Applications/apache-karaf-3.0.5/etc/org.apache.karaf.features.cfg file by appending the following line to featuresRepositories:
build:~$ nano ~/Applications/apache-karaf-3.0.5/etc/org.apache.karaf.features.cfg |
locate the featuresRepositories and append this line (will need a comma before appending the text to separate from the previous value)
mvn:org.onosproject/onos-features/1.5.0-SNAPSHOT/xml/features |
Save and close the file. Now we are ready to build ONOS with Maven:
build:~$ cd ~/onos build:~$ mvn clean install # or use the alias 'mci' |
Now we are ready to start customizing, creating, and installing ONOS packages.
If previous version of ONOS is running, the service should be stopped (sudo service onos stop) before building with mvn. Otherwise, the test on onlab.nio package would fail with "address already in use" error.
Under ONOS terminology, a cell is a collection of environment variables that are used:
Cells make it easy to use the utility scripts to package, configure, install, and run ONOS. Here we will create an ONOS package that, when installed and launched, starts up a single-instance (non-clustering) ONOS instance that uses the intent-based forwarding application.
A cell is defined in a cell definition file. We will create the following cell definition file called tutorial in ${ONOS_ROOT}/tools/test/cells/ :
sdn@build:~$ nano onos/tools/test/cells/tutorial |
# ONOS from Scratch tutorial cell # the address of the VM to install the package onto export OC1="192.168.56.101" # the default address used by ONOS utilities when none are supplied export OCI="192.168.56.101" # the ONOS apps to load at startup export ONOS_APPS="drivers,openflow,fwd,proxyarp,mobility" # the Mininet VM (if you have one) export OCN="192.168.56.102" # pattern to specify which address to use for inter-ONOS node communication (not used with single-instance core) export ONOS_NIC="192.168.56.*" |
Note that:
This cell can be applied to your build environment with the cell command:
build:~$ cell tutorial |
Now any ONOS package you will build will take up the ONOS_APPS setting. Additionally, if you need to create packages with other configurations (i.e. different applications or install targets), all you need to do is to apply a different cell definition to your environment before package creation and deployment.
If you want to work with multiple terminals on the build machine, you should apply the cell to each new terminal you have, if you want the onos-* scripts (from the Create and Deploy the package sections below) to work from all of them.
You can also use the vicell utility to create and edit your cell file. For example, to create a new cell file:
$ vicell -c -a mycell |
the above command opens a new file named "mycell" in ${ONOS_ROOT}/tools/test/cells/ either in the editor specified by the EDITOR env variable, or vi otherwise. When you exit out of the editor, the cell is automatically created and then applied to your session.
See vicell -h for the list of options.
For convenience, before we can deploy anything to our VM, we will configure paswordless login to the VM from our build machine with onos-push-keys:
build:~$ onos-push-keys 192.168.56.101 sdn@192.168.56.101's password: |
Older versions of the utility will ask you to authenticate multiple times; newer versions will require you to enter the password just once.
This tutorial deals with only 1 VM, but if you want to create a cluster of ONOS, cloning the 1st VM, onos-patch-vm script can be used to set the hostname, etc. to the cloned VM.
build:~$ onos-patch-vm $OC2 onos-scratch2 192.168.56.102: onos-scratch2 |
To create an ONOS binary, run onos-package (or op, for short):
build:~$ onos-package -rw-rw-r-- 1 onosuser onosuser 33395409 Dec 4 16:12 /tmp/onos-1.5.1.onosuser.tar.gz |
This creates a tar archive in /tmp .
We can now deploy it to our VM:
build:~$ onos-install -f $OC1 onos start/running, process 2028 |
Once onos-install returns with the last message in the code block above, we can try logging on from our build machine:
build:~$ onos $OC1
Logging in as karaf
Welcome to Open Network Operating System (ONOS)!
____ _ ______ ____
/ __ \/ |/ / __ \/ __/
/ /_/ / / /_/ /\ \
\____/_/|_/\____/___/
Documentation: wiki.onosproject.org
Tutorials: tutorials.onosproject.org
Mailing lists: lists.onosproject.org
Come help out! Find out how at: contribute.onosproject.org
Hit '<tab>' for a list of available commands
and '[cmd] --help' for help on a specific command.
Hit '<ctrl-d>' or type 'system:shutdown' or 'logout' to shutdown ONOS.
onos> |
We are now actually logged into the ONOS CLI of the instance that we have deployed on the VM.
Use apps to list all installed applications. The one with asterisk sign indicates that it is activated (running).
onos> apps -a -s * 6 org.onosproject.drivers 1.5.1.SNAPSHOT Default device drivers * 35 org.onosproject.hostprovider 1.5.1.SNAPSHOT ONOS host location provider. * 50 org.onosproject.sdnip 1.5.1.SNAPSHOT SDN-IP peering application * 56 org.onosproject.lldpprovider 1.5.1.SNAPSHOT ONOS LLDP link provider. * 78 org.onosproject.openflow-base 1.5.1.SNAPSHOT OpenFlow protocol southbound providers * 82 org.onosproject.openflow 1.5.1.SNAPSHOT OpenFlow southbound meta application * 94 org.onosproject.proxyarp 1.5.1.SNAPSHOT Proxy ARP/NDP application. onos> |
Note that there will be many more modules than you have configured - these are part of the ONOS OpenFlow and core components. Refer to Appendix C : Source Tree Organization to see descriptions of the modules.
You can log out (detach) from the CLI with logout, or Ctrl-D.
The argument $OC1 can be replaced with $OCI, or even omitted; when omitted, the scripts will fall back to using the value stored in OCI.
On Ubuntu, onos-install uses the upstart/initctl system to start and stop onos semi-automatically.
OS X manages daemons using launchd/launchctl, which onos-install doesn't currently support, so we need to specify "nostart" (-n):
onos-install -fn $OC1 |
and start ONOS manually using
/opt/onos/apache-karaf-$KARAF_VERSION/bin/karaf clean |
Return To : Tutorials and Walkthroughs