If you have come across Installing and Running ONOS, you'll notice that there are several ways to install and run ONOS. This tutorial takes the aforementioned page, and focuses on showing you one useful deployment method - ONOS packaged from source, and deployed in an Ubuntu VM or on OS X.
By completing this tutorial, you will understand how to:
Commands at the shell of the VM begin with
$ sudo -s #
And commands at the build machine shell begin with
build:~$ sudo -s build:~#
You need a build machine for packaging ONOS and for running your VM. The build machine should be running a UNIX-like OS. This tutorial assumes that your build machine is running Ubuntu 14.04, 64-bit.
You should have some kind of VM hosting software, such as VirtualBox, installed on your build machine. This tutorial assumes you are using VirtualBox.
Finally, you should generate a SSH public key on your build machine if you hadn't done so in the past:
build:~$ ssh-keygen -t rsa
The default options and no password are fine for this tutorial.
Download Ubuntu Server 14.04 LTS 64-bit. Create a VM using this image, with the following settings:
This tutorial calls the VM onos-scratch.
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 and eth1:
$ ifconfig 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)
From the build machine you should be able to SSH to the 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
build:~$ sudo apt-get install git-core
Create two directories called ~/Downloads and ~/Applications. Download the Karaf 3.0.2 and Maven 3.2.3 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.
build:~$ cd; mkdir Downloads Applications build:~$ cd Downloads build:~$ wget http://download.nextag.com/apache/karaf/3.0.2/apache-karaf-3.0.2.tar.gz build:~$ wget https://archive.apache.org/dist/maven/maven-3/3.2.3/binaries/apache-maven-3.2.3-bin.tar.gz build:~$ tar -zxvf apache-karaf-3.0.2.tar.gz -C ../Applications/ build:~$ tar -zxvf apache-maven-3.2.3-bin.tar.gz -C ../Applications/
Next, install Oracle Java 8:
build:~$ sudo apt-get install software-properties-common -y build:~$ sudo add-apt-repository ppa:webupd8team/java -y build:~$ sudo apt-get update build:~$ sudo apt-get install oracle-java8-installer oracle-java8-set-default -y
It will ask you to acknowledge the license; do so when prompted.
|The second step above may prompt for the installation of python-software-properties. If prompted, do so.|
Finally, clone the ONOS source to sdn's home directory:
build:~$ git clone https://gerrit.onosproject.org/onos -b onos-1.1
This will create a directory called onos, with the source code in it.
The VM only requires karaf, Maven and Java 8 - follow the instructions for karaf, Maven and Java 8 above.
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 user build machine's ~/.profile by adding the following line to it at the end:
Once the line is added, source the user's .profile (or just log out and log back in):
build:~$ . ~/.profile
Once you run the above command, you will see in the output of
env 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.)
~/Applications/apache-karaf-3.0.2/etc/org.apache.karaf.features.cfg by appending the following line to featuresRepositories:
mvn:org.onosproject/onos-features/1.1.0-SNAPSHOT/xml/features # (see note below to get proper version number)
Note: You you clone the current code of branch onos-1.1, the onos version may differ from "1.1.0-SNAPSHOT" (may be "1.1.1-SNAPSHOT" or larger number). Please find the corrent version number of "onos" in the file ~/onos/pom.xml and replace the most current version string.
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/tools/test/cells/ :
# 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_FEATURES="onos-api,onos-core-trivial,onos-cli,onos-openflow,onos-app-ifwd" # 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.*"
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_FEATURES 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. Which brings us to:
For convenience, before we can deploy anything to our VM, we will configure paswordless login to the VM from our build machine with
build:~$ onos-push-keys 192.168.56.101 email@example.com's password: firstname.lastname@example.org's password:
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.
To create a ONOS binary, run
op, for short):
build:~$ onos-package -rw-rw-r-- 1 onosuser onosuser 33395409 Dec 4 16:12 /tmp/onos-1.1.0.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
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)! ____ _ ______ ____ / __ \/ |/ / __ \/ __/ / /_/ / / /_/ /\ \ \____/_/|_/\____/___/ 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>
If the onos cli does not appear, make sure the KARAF_ROOT was set in the vm's env. This can be done by typing:
sdn:~$ export KARAF_ROOT=~/Application/apache-karaf-3.0.2
We are now actually logged into the ONOS CLI of the instance that we have deployed on the VM. Use
list to see that the correct modules that we have configured are loaded:
onos> list START LEVEL 100 , List Threshold: 50 ID | State | Lvl | Version | Name ------------------------------------------------------------------------------- 40 | Active | 80 | 2.6 | Commons Lang 41 | Active | 80 | 3.3.2 | Apache Commons Lang ... 72 | Active | 80 | 1.1.0.SNAPSHOT | onos-api 73 | Active | 80 | 1.1.0.SNAPSHOT | onos-cli ... 86 | Active | 80 | 1.1.0.SNAPSHOT | onos-of-provider-device 87 | Active | 80 | 1.1.0.SNAPSHOT | onos-of-provider-packet 88 | Active | 80 | 1.1.0.SNAPSHOT | onos-of-provider-flow 98 | Active | 80 | 1.1.0.SNAPSHOT | onos-core-net 99 | Active | 80 | 1.1.0.SNAPSHOT | onos-core-trivial <--single-instance core 112 | Active | 80 | 1.1.0.SNAPSHOT | onos-app-ifwd <--intent forwarding 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.
OS X manages daemons using
and start ONOS manually using
Return To : Tutorials and Walkthroughs