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. It is therefore recommended that one of these platforms be used. In the following examples, the build machine runs OS X. 

If using a VM, the following settings are recommended:

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

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:

Getting ONOS

The ONOS source can be checked out using git:

$ git clone ssh://<user>@gerrit.onlab.us:29418/onos-next ~/onos

This clones the repository to your home directory, under a directory named 'onos'.

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 your 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

If this is not done, at the very minimum, one should make sure to adjust their path as follows:

$ export PATH=”$PATH:~/onos/dev/bin:~/onos/tools/build:~/onos/tools/test/bin”

Building ONOS 

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. 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.0.0-SNAPSHOT/onos-branding-1.0.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] ------------------------------------------------------------------------
$ 

Running ONOS

ONOS may be run on the build machine directly, or packaged and launched on remote machines. 

Launching locally

After running maven as described in Building ONOS, karaf can be used to start ONOS and attach to its CLI:

$ karaf
Welcome to Open Networking 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>

Launching karaf may bring up the default karaf prompt, without the 'ONOS' ASCII art. This is purely cosmetic, and shouldn't affect functionality; typing help onos at the prompt should still bring up a list of available commands.

If the branding is desired, one can move the branding bundle created during the build process to karaf's lib directory:

$ cp ${ONOS_ROOT}/tools/package/branding/target/onos-branding-1.0.0-SNAPSHOT.jar /karaf-install-dir/apache-karaf-3.0.2/lib/

And relaunch karaf.

Deploying remotely with onos-package and onos-install

Remote installations are useful when one wishes to run multiple ONOS instances as a cluster.

The ONOS build process produces a number of OSGi bundles, which are essentially Java jar files.  One could simply deploy these bundles in any OSGi container to run ONOS, 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 by packaging the ONOS binaries into a distributable compressed tar. 

Setup

The prerequisites for using these scripts are:

Additionally, onos-install relies on ssh to deploy the package to the target machine. It is recommended that:

  1. Either the target machine have a user named 'sdn', or on the build machine, the ONOS_USER environment variable is exported with the username used in the target machine
  2. And password-less (e.g. key-based) login be enabled on the target. 

If 1 is met, the onos-push-keys  utility can be used to transfer one's public keys to targets. This requires that the keys have been generated prior to using the utility.

Deployment

Running onos-package produces a self-contained tar archive.

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

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

This file can be deployed by pointing onos-install to the remote target to run ONOS on (192.168.56.20 in this example):

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

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

$ onos 192.168.56.20

The same welcome banner and prompt as the local case should show up.

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