Page History

Overview

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.

...

1. Install and prepare VirtualBox

...

Info
This link will guide you through installing VirtualBox if you do not have it installed: http://www.wikihow.com/Install-Ubuntu-on-VirtualBox

...

2. Prepare the Build VM and ONOS VM

...

Create onos-scratch VM

• Download Ubuntu Server 14.04 LTS 64-bit from Ubuntu.com
• Create an Ubuntu onos-scratch VM in VirtualBox using this image, with the following settings:

• • 2GB RAM
  • 2 processors
  • At least 5GB disk space
  • Two network interfaces, Adapter 1 attached to NAT, and Adapter 2 attached to host-only Adapter set to vboxnet0. Configure both to use DHCP.
  • This tutorial calls the VM onos-scratch.
• In VirtualBox:

...

1. Select New

...

1. Name: onos-scratch, type: Linux

...

1. Hard disk: Create a virtual hard disk now; select the default VDI for disk type; dynamically allocated

...

1. Add the second processor:

• Install Ubuntu

  • When the VM is created, attach the downloaded Ubuntu 14.04 LTS 64-bit ISO file to it: go to VM’s settings and click the “Storage” tab, add optical drive to the Controller: IDE by clicking the CD/DVD icon with the green plus sign.
    

    

• • Browse to the downloaded ISO file:
    
    

• • Click on the System tab. Choose boot order and keep CD/DVD on the top as first priority.

    

...

• Download Ubuntu 14.04 LTS 64-bit desktop from Ubuntu.com
• Create a new VM. In VirtualBox:

• • create a new VM: Name: build, type: Linux:
    • Select 2GB of RAM
    • Hard disk: take the defaults: 8 GB and Create a virtual hard disk now
    • Hard disk file type: VDI
    • Storage on physical hard disk: Dynamically allocated
    • File location and size: type build for the name
  • Click on settings for the build VM:
    • Storage: Controller IDE – click on the disk with a + sign symbol to add an optical drive. Choose disk: browse to the location of the downloaded iso file.
    • Add a 2nd network adapter for host-only network (see the screenshot in the section for Creating onos-scratch VM.)
    • System: Motherboard tab – uncheck floppy, move optical to the top in the Boot Order box.
  • Install Ubuntu (use the same credentials as for the first Ubuntu VM). When the installation completes, power the VM on and login.
    
    

• 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:

  Code Block
  language text
  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 VM using the IP address assigned to eth1:

  Code Block
  language text
  build:~$ ssh -l sdn 192.168.56.101

  If the ssh connection failed make sure that the openssh-server is installed by running:

  Code Block
  language text
  $ 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:

  Code Block
  language text
  sdn@build:~$ ping 192.168.56.101

...

• On the build machine

  • Install Git:

    Code Block
    language text
    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.

    Code Block
    language text
    build:~$ cd; mkdir Downloads Applications build:~$ cd Downloads build:~$ wget http://archive.apache.org/dist/karaf/3.0.5/apache-karaf-3.0.5.tar.gz build:~$ wget http://archive.apache.org/dist/maven/maven-3/3.3.9/binaries/apache-maven-3.3.9-bin.tar.gz build:~$ tar -zxvf apache-karaf-3.0.5.tar.gz -C ../Applications/ build:~$ tar -zxvf apache-maven-3.3.9-bin.tar.gz -C ../Applications/

  • Next, install Oracle Java 8:

    Code Block
    language text
    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. 

...

4. Set up your build environment

Environment variables

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

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 user's .profile (or just log out and log back in): or run this command:

sdn@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.

...

...

$ export ONOS_USER=<username>
$ export ONOS_GROUP=<groupname>

...

Building ONOS

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.

5. Create a custom cell definition

A quick intro to cells

Under ONOS terminology, a cell is a collection of environment variables that are used:

• by the utility scripts included with ONOS, including the ones that we are about to talk about
• for telling the packaging process how we want to customize our ONOS package

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.

Create a cell definition file

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:

• OC1 and OCI are set to the address of eth1 in our VM (onos-scratch VM)
• ONOS_APPS indicates the ONOS applications we want to activate, including OpenFlow protocol, reactive forwarding (fwd), proxy ARP, and mobility.

Applying a cell

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.

6. Package and deploy ONOS

Passwordless VM access

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

Creating the package

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.2.0.onosuser.tar.gz

This creates a tar archive in /tmp .

Deploying the package

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
  id=1, name=org.onosproject.bgprouter, version=1.2.0 ...
  id=2, name=org.onosproject.config, version=1.2.0 ...
  id=3, name=org.onosproject.demo, version=1.2.0 ...
* id=4, name=org.onosproject.drivers, version=1.2.0 ...
  id=5, name=org.onosproject.election, version=1.2.0 ...
* id=6, name=org.onosproject.fwd, version=1.2.0 ...
  id=7, name=org.onosproject.intentperf, version=1.2.0 ...
  id=8, name=org.onosproject.metrics, version=1.2.0 ...
* id=9, name=org.onosproject.mobility, version=1.2.0 ...
  id=10, name=org.onosproject.null, version=1.2.0 ...
* id=11, name=org.onosproject.openflow, version=1.2.0 ...
  id=12, name=org.onosproject.optical, version=1.2.0 ...
* id=13, name=org.onosproject.proxyarp, version=1.2.0 ...
  id=14, name=org.onosproject.routing, version=1.2.0 ...
  id=15, name=org.onosproject.sdnip, version=1.2.0 ...
  id=16, name=org.onosproject.segmentrouting, version=1.2.0 ...
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.

...

Deploy on Mac OS X

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

...