Installing and Running ONOS

This section covers the details involved in getting, installing, and running ONOS. Both single- and multi-instance cases are described. 

Prerequisites

ONOS and its test scripts are developed and tested on OS X (Mavericks and later) and Ubuntu (14.04 64-bit), with focus on the latter. 

We recommend the following if a VM is used for running ONOS:

• Ubuntu Server 14.04 LTS 64-bit
• 2GB or more RAM 
• 2 or more processors

In order to build and run ONOS the following are required:

• Java 8 JDK (Oracle Java recommended; OpenJDK is not as thoroughly tested)
• Apache Maven 3.3.9
• git
• bash (for packaging & testing)
• Apache Karaf 3.0.5

Finally, to take full advantage of the ONOS test suite and various developer conveniences, it is also recommended that developers have the following tools available on their machines:

• IDE (IntelliJ, Eclipse, etc.)
• VirtualBox (or other VM hosting software)

Installation - Java, Maven, and Karaf

The ONOS install process relies on the environment variable JAVA_HOME being properly set. In other words, both mvn --version and java -version should report the same Java version:

Maven and Karaf

The binaries for both Maven and Karaf can be downloaded as tar archives, where installation entails extracting them to the desired location. For example, if your archives were downloaded to ~/Downloads, and you wish to install Maven and Karaf into ~/Applications:

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.

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:

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.

You will have to accept the Oracle binary license terms  

For Debian, the following steps will upgrade the installation to Java 8: 

$ su -
$ echo "deb http://ppa.launchpad.net/webupd8team/java/ubuntu trusty main" | tee /etc/apt/sources.list.d/webupd8team-java.list
$ echo "deb-src http://ppa.launchpad.net/webupd8team/java/ubuntu trusty main" | tee -a /etc/apt/sources.list.d/webupd8team-java.list
$ apt-key adv --keyserver hkp://keyserver.ubuntu.com:80 --recv-keys EEA14886
$ apt-get update
$ apt-get install oracle-java8-installer oracle-java8-set-default -y
$ exit

You will have to accept the Oracle binary license terms

For OS X, the latest Oracle Java 8 SDK can be downloaded from Oracle. 

Setting JAVA_HOME 

If not set automatically during the Java 8 installation process, The JAVA_HOME environment variable should be set to the JRE installation location for Java 8. The process for verifying/setting the proper version varies with platform.

• On OS X: The current JAVA_HOME may be verified with:
  

  $ /usr/libexec/java_home
  /Library/Java/JavaVirtualMachines/jdk1.8.0_25.jdk/Contents/Home

  To set the version, either run or add the following to the shell profile:

  $ export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)

  
  

• On Ubuntu: To verify the JAVA_HOME:
  

  $ env | grep JAVA_HOME
  JAVA_HOME=/usr/lib/jvm/java-8-oracle

  If JAVA_HOME is not set or incorrect, either run or add the following to the shell profile:

  $ export JAVA_HOME=/usr/lib/jvm/java-8-oracle

Development Environment Setup

To get the most from the tools and instructions discussed in the following sections,  it is highly recommended that the ONOS_ROOT environment variable is exported in the shell profile (.bash_aliases, .profile, etc.) to refer to the top of the ONOS source tree. For example:

$ export ONOS_ROOT=~/onos
$ source $ONOS_ROOT/tools/dev/bash_profile

Building and packaging ONOS 

Build using Maven

ONOS uses Maven for managing the build process. To build the ONOS code-base from the top-most level, and from scratch, simply type the following: 

$ cd ~/onos
$ mvn clean install

This triggers a full build, complete with unit testing. This may take several minutes, depending on the compute resources of the machine used. ONOS developer tool-kit also includes onos-build command and alias ob, both of which build the entire code tree from any location.

When complete, there should be an output similar to the following:

[INFO] --- maven-bundle-plugin:2.5.3:install (default-install) @ onos-branding ---
[INFO] Installing org/onlab/onos/onos-branding/1.1.0-SNAPSHOT/onos-branding-1.1.0-SNAPSHOT.jar
[INFO] Writing OBR metadata
[INFO] ------------------------------------------------------------------------
[INFO] Reactor Summary:
[INFO] 
[INFO] onos-build-conf ................................... SUCCESS [0.697s]
[INFO] onos .............................................. SUCCESS [2.549s]
[INFO] onlab-utils ....................................... SUCCESS [1.521s]
[INFO] onlab-junit ....................................... SUCCESS [4.707s]
[INFO] onlab-misc ........................................ SUCCESS [8.002s]
[INFO] onlab-netty ....................................... SUCCESS [3.119s]
[INFO] onlab-nio ......................................... SUCCESS [2.048s]
[INFO] onlab-osgi ........................................ SUCCESS [0.635s]
[INFO] onlab-rest ........................................ SUCCESS [0.637s]
[INFO] onlab-thirdparty .................................. SUCCESS [2.212s]
[INFO] onos-core ......................................... SUCCESS [0.481s]
[INFO] onos-api .......................................... SUCCESS [6.186s]
[INFO] onos-core-store ................................... SUCCESS [0.641s]
[INFO] onos-core-trivial ................................. SUCCESS [3.002s]
[INFO] onos-core-net ..................................... SUCCESS [5.778s]
[INFO] onos-core-serializers ............................. SUCCESS [2.788s]
[INFO] onos-core-dist .................................... SUCCESS [8.149s]
[INFO] onos-json ......................................... SUCCESS [0.615s]
[INFO] onos-web .......................................... SUCCESS [0.533s]
[INFO] onos-gui .......................................... SUCCESS [0.888s]
[INFO] onos-rest ......................................... SUCCESS [1.886s]
[INFO] onos-cli .......................................... SUCCESS [1.163s]
[INFO] onos-of ........................................... SUCCESS [0.457s]
[INFO] onos-of-api ....................................... SUCCESS [8.798s]
[INFO] onos-providers .................................... SUCCESS [0.431s]
[INFO] onos-of-providers ................................. SUCCESS [0.473s]
[INFO] onos-of-provider-device ........................... SUCCESS [1.940s]
[INFO] onos-of-provider-link ............................. SUCCESS [2.042s]
[INFO] onos-of-provider-host ............................. SUCCESS [1.562s]
[INFO] onos-of-provider-packet ........................... SUCCESS [1.946s]
[INFO] onos-of-provider-flow ............................. SUCCESS [0.821s]
[INFO] onos-lldp-provider ................................ SUCCESS [1.824s]
[INFO] onos-host-provider ................................ SUCCESS [1.672s]
[INFO] onos-of-ctl ....................................... SUCCESS [2.213s]
[INFO] onos-of-drivers ................................... SUCCESS [0.560s]
[INFO] onos-apps ......................................... SUCCESS [0.436s]
[INFO] onos-app-tvue ..................................... SUCCESS [0.625s]
[INFO] onos-app-fwd ...................................... SUCCESS [0.618s]
[INFO] onos-app-ifwd ..................................... SUCCESS [0.592s]
[INFO] onos-app-foo ...................................... SUCCESS [0.814s]
[INFO] onos-app-mobility ................................. SUCCESS [0.611s]
[INFO] onos-app-proxyarp ................................. SUCCESS [0.579s]
[INFO] onos-app-config ................................... SUCCESS [0.626s]
[INFO] onos-app-sdnip .................................... SUCCESS [5.847s]
[INFO] onos-app-calendar ................................. SUCCESS [0.631s]
[INFO] onos-app-optical .................................. SUCCESS [0.732s]
[INFO] onos-app-metrics .................................. SUCCESS [0.435s]
[INFO] onos-app-metrics-intent ........................... SUCCESS [0.639s]
[INFO] onos-app-metrics-topology ......................... SUCCESS [0.681s]
[INFO] onos-app-oecfg .................................... SUCCESS [1.282s]
[INFO] onos-features ..................................... SUCCESS [0.442s]
[INFO] onos-branding ..................................... SUCCESS [0.486s]
[INFO] ------------------------------------------------------------------------
[INFO] BUILD SUCCESS
[INFO] ------------------------------------------------------------------------
[INFO] Total time: 1:40.113s
[INFO] Finished at: Sat Nov 08 13:49:43 PST 2014
[INFO] Final Memory: 120M/1453M
[INFO] ------------------------------------------------------------------------
$ 

Packaging ONOS tar.gz or zip distributions

Once the build has completed, we can use the onos-package shell tool to produce an installable compressed tar file, which contains ONOS artifacts as well as ONOS-branded distribution of Apache Karaf. If your development machine has the zip command available, the onos-package tool will also produce a ZIP file variant with the same contents as the tar file. As with onos-build, onos-package also has an alias called op. The following shows what one should expect to see when running onos-package command:

$ op
-rw-r--r--  1 tom  wheel  101196349 Apr 30 14:39 /tmp/onos-1.2.0.user.tar.gz
-rw-r--r--  1 tom  wheel  101763602 Apr 30 14:39 /tmp/onos-1.2.0.user.zip
$

Running ONOS locally on development machine

This section describes both launching ONOS on the build machine locally, which can be useful when developing functionality that does not require an ONOS cluster. To allow running ONOS directly on the development machine, ONOS toolbox comes with onos-karaf command, and corresponding ok alias, which makes sure that Apache Karaf is installed and properly configured to run ONOS before starting it.

Note: This tool is purposefully designed for development machines and is not intended to be used for production environments. It accepts the same arguments as does the original karaf command.

Selecting IP address

For the time-being, in order to run ONOS locally, we have to export ONOS_IP or ONOS_NIC environment variables with the IP address prefix to configure ONOS clustering component. This requirement will disappear before the Cardinal release however. For example:

$ export ONOS_IP=10.1.9.255

Selecting ONOS apps to activate

To configure ONOS with a set of applications that should be automatically activated on startup, use the ONOS_APPS environment variable as follows:

$ export ONOS_APPS=drivers,openflow,proxyarp,mobility,fwd

Starting ONOS

To pre-stage applications and appropriately configure ONOS, use the onos-karaf tool using the same arguments as would normally be used for the stock karaf command:

$ ok clean
Creating local cluster configs for IP 10.1.9.247...
Setting up hazelcast.xml for subnet 10.1.9.*...
Staging builtin apps...
Customizing apps to be auto-activated: drivers,openflow,proxyarp,mobility,fwd...
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>

At this point, typing help onos at the prompt should still bring up a list of available commands. Pressing Ctrl-D or logout will exit the CLI.

Upgrading ONOS

If a local install of ONOS is updated to a new version, the Karaf configuration files must be updated before it can be properly started:

$ onos-setup-karaf clean
$ ok clean

Deploying ONOS remotely using ONOS test tools

This section describes how to deploy and run ONOS using the various developer and test tools, specifically onos-package and onos-install available in the ONOS source tree.

Remote installations are useful when one wishes to run ONOS on a remote machine (or a VM), or run multiple ONOS instances in a cluster. This section demonstrates remote installation on a single remote machine.

Overview

The ONOS build process produces a number of OSGi bundles, which are essentially Java jar files.  These bundles can be deployed in any OSGi container, but this would require that such container be installed, properly configured, and that the bundles be collected and properly staged. The ONOS utility scripts, onos-package and onos-install, simplifies this task down to two steps:

• Running onos-package packages the ONOS binaries into a distributable compressed tar. Then,
  
• Running onos-install pushes the package created by onos-package onto the remote VM and ignites the ONOS service.
  

Setup

Some preparations are needed for using these scripts:

On the build machine:

• The Apache Karaf binaries (either .zip or .tar.gz format) are available in ~/Downloads
• The ONOS source has been built

• The ONOS_APPS variable should be set to the list of ONOS apps that should be auto-ignited:

  $ export ONOS_APPS="drivers,openflow,proxyarp,mobility,fwd"

On the target VM:

• The Oracle Java 8 JRE and Maven are installed

• A user named sdn with password-less sudo privilege, or, on the build machine, the ONOS_USER environment variable is set to the preferred user for the VM.

  To enable sudo without a password, edit the sudoers configuration. To do this, run sudo visudo within the VM, and add the following line:

  sdn ALL=(ALL) NOPASSWD:ALL

Additionally, onos-install relies on ssh to deploy the package to the target machine. To make the process easier, password-less (e.g. key-based) login to the VM is recommended. The onos-push-keys  utility can be used to transfer one's public keys to the VM:

$ onos-push-keys 192.168.56.10
sdn@192.168.56.10's password: 
sdn@192.168.56.10's password:

This requires that the keys have been generated prior to using the utility. As shown above, it will ask for the password twice.   

Deployment

1. Run onos-package to produce a self-contained tar archive:

   $ onos-package
   -rw-r--r-- 1 onosuser wheel 34187574 Nov 8 14:52 /tmp/onos-1.2.0.onosuser.tar.gz

   As seen above, the file has the naming convention "onos-1.2.0.<username>.tar.gz", and is created under the /tmp directory.
   
   

2. Deploy the binary by pointing onos-install to the remote target to run ONOS on (192.168.56.20 in this example):

   $ onos-install 192.168.56.20
   onos start/running, process 9513

   If ONOS has been previously installed on a remote machine, onos-install -f [target] will force a reinstall.

Once ONOS is running, the onos utility can be used to attach to the remote instance's CLI:

$ onos 192.168.56.20
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>

Alternatively, pointing a browser at http://<onos-ip>:8181/onos/ui will display the ONOS Web GUI.

Handling multiple remote targets

For deploying ONOS on multiple remote machines (i.e., as a cluster), the behavior of the ONOS utilities can be configured by employing test cells. Test cells are discussed under Test Environment Setup in the Developer's Guide.

Deploying ONOS using only the onos.tar.gz file

For deployers who just want to install ONOS software from the distributable onos.tar.gz file, without checking out the ONOS source code, they can follow these simple steps to get ONOS up and running.

First, untar the onos.tar.gz via the following command

tar zxf onos-1.2.0*.tar.gz

After that change to the newly created directory and configure the network interface that ONOS should use for clustering using the onos-config tool, for example:

bin/onos-config MyONOS 10.128.11.*

Note: If you are installing on multiple machines which you intend to cluster, make sure you use the same command to configure them.

At this point, you are ready to run the ONOS as a standalone instance. To do that, you can use the onos-service tool as follows.

bin/onos-service server &

Alternatively, you can integrate the onos-service into your Linux init daemon of choice. Note that etc/onos.conf can be copied to the system /etc/init directory to use the Linux upstart deamon.

Forming an ONOS cluster from individual ONOS instances

If you wish to form a cluster from individually installed ONOS instances, use the onos-form-cluster tool with the IP addresses of all the ONOS instances, as in the following example:

bin/onos-form-cluster 10.128.11.1 10.128.11.2 10.128.11.3

This tool generates a cluster configuration and uploads it to all the ONOS instances via ONOS REST API. Note that this request will trigger all ONOS instances to restart. When they finish the restart process, they will all be part of the same cluster.

You can check the status of the cluster through the REST API (Appendix B: REST API) or UI.

Attaching ONOS console

To attach a console to the local instance, you can use the bin/onos tool or you can remotely ssh on port 8101 as in the following example:

ssh -p 8101 karaf@10.128.11.1

To setup password-less login via SSH keys, please follow documentation on Apache Karaf 3.0.5 web pages.

If Things go Wrong

Maven and Karaf

Both Maven and Karaf rely on network access for some of their functionality. One of the first points to check if a build fails is to check for connectivity, and rebuild the project once it is restored.

In Karaf, connectivity issues may manifest as bundles not loading (e.g. not being able to use any ONOS-related commands, or help onos returning nothing). It may also take some time for ONOS to fully boot up, in which case some commands may not be available for the first minute or so.

Karaf System Console

ONOS by default activates the webconsole feature of Apache Karaf, so you can point your browser at http://<onos-ip>:8181/system/console to trouble-shoot features, bundles and component dependencies. At this time, the default username/password combination is karaf/karaf.

Running in a VM

Make sure that the primary user in the VM (sdn) has superuser privilege, or is part of sudoers.

Also be sure that there is a .m2 directory in the user's home directory. Running Maven at least once in the VM will generate the directory. 

Previous : Getting ONOS
Next : Interacting with ONOS