Page History

Contents of this page are obsolete. Please refer to Getting Started with ONOS screencast and Building ONOS instead.

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.

...

• Use cell definitions to configure the ONOS build environment to customize the ONOS package
• Configure which modules the ONOS binary loads by default
• Install ONOS on a VM using the onos-install utility
• Access the CLI and monitor ONOS remotely

Conventions

Commands at the shell of the ONOS VM begin with $ (or sdn@onos-scratch:~$)  

...

build:~$ sudo -s
build:~#

1.

...

Prerequisites and Setup for the Tutorial

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.

...

• Install Oracle VirtualBox virtualization software
• Create a Virtual Machine 1 – onos-scratch VM - Ubuntu Server 14.04 TLS 64 bit
• Create a Virtual Machine 2 – Build VM running Ubuntu 14.04 TLS 64 bit desktop

1. Install and prepare VirtualBox

...

• click the green symbol with the + sign on the right to add host-only network
• click the blue tool icon on the right to edit host-only network and verify that dhcp is enabled.

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:

...

1. Select New
2. Name: onos-scratch, type: Linux
3. Hard disk: Create a virtual hard disk now; select the default VDI for disk type; dynamically allocated
4. 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.
    

    

...

• • • create a user named sdn, with password rocks, and confirm that you want to use this password. This will be the primary account used for this tutorial.
    • when prompted to encrypt the disk, select No
    • For partitioning the disk, select Guided - use entire disk and follow with the defaults provided.
    • For configuring proxy information, follow what best suits your environment.
    • when prompted to install additional software (Software Install) choose OpenSSH server.

Once the onos-scratch VM starts up:

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:

...

$ sudo ifconfig eth1 <IP address> up

Create a build VM

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

• • 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 - select at least 10 GB for the size of the virtual hard disk for the build VM
  • 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 onos-scratch 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

...

• Close the ssh connection to the onos-scratch VM by typing exit.

2. Install required software

On the build machine

Install Git:

build:~$ sudo apt-get install git-core

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/ 

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

...

Clone the ONOS source:

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.

On the onos-scratch VM

The VM only requires Java 8 - follow the instructions for Java 8 above performed on the build VM.

...

3. 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. 

...

sdn@build:~$ nano . ~/.bashrc

Add the line below at the end of the file:

...

Once you run the above command, you will see in the output of the env that  command 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:

...

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.

...

4. Create a custom cell definition

A quick intro to cells

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.

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

...

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

...

See vicell -h for the list of options.

...

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

This creates a tar archive in /tmp .

Deploying the package

We can now deploy it to our VM:

...

onos> apps -a -s
*  id=1, name= 6 org.onosproject.bgprouter, version=1.2.0 ...
  id=2, name=drivers              1.5.1.SNAPSHOT Default device drivers
*  35 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 ...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.

...

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.

...

/opt/onos/apache-karaf-$KARAF_VERSION/bin/karaf clean

What’s next?

• Now that you've got the basics of a development environment, try a hand at creating an application in the Template Application Tutorial.
• Learn more about the installation process in Installing and Running ONOS.
• Learn more about cells in Test Environment Setup.
  
  

...

Return To : Tutorials and Walkthroughs

...

...