Page History

...

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

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

  Code Block
  language text
  $ export JAVA_HOME=$(/usr/libexec/java_home -v 1.8)

  
  

• On Ubuntu: To verify the JAVA_HOME:
  

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

  Code Block
  language text
  $ export JAVA_HOME=/usr/lib/jvm/java-8-oracle

Installing ONOS

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:

...

Building ONOS 

Anchor
#build-onos #build-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: 

...

[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] ------------------------------------------------------------------------
$ 

Running

...

ONOS locally on development machine

ONOS may be run on the build machine directly, or packaged and launched on remote machines or VMs. This section describes both launching ONOS on the build machine ( locally), and packaging and deploying on a remote (target) machine. 

...

First, we need to copy several config files to the local karaf directory. This can be easily done by running the following command:

$ onos-setup-karaf clean <node-ip>

...

$ cp ${ONOS_ROOT}/tools/package/branding/target/onos-branding-1.2.0.jar ${KARAF_ROOT}/lib/

...

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.

...

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:

...

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

• The ONOS_FEATURESAPPS variable should be set to the list of modules Karaf should launch with ONOSONOS apps that should be auto-ignited:

  Code Block
  language text
  $ export ONOS_FEATURESAPPS="webconsole,onos-api,onos-core,onos-cli,onos-openflow,onos-app-fwd,onos-app-mobility,onos-guidrivers,openflow,proxyarp,mobility,fwd"

On the target VM:

• The Oracle Java 8 JRE and Maven are installed

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

  Tip
  To enable sudo without a password, edit the sudoers configuration. To do this, run sudo visudo within the VM, and add the following line: Code Block language text 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:

...

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

...

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

Deploying from onos.tar.gz only

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 For deployers who just want to install ONOS software from the distributable onos.tar.gz file, they can follow these simple steps to get ONOS up and running.

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

...

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 conf can be copied to the system /etc/init directory to use the Linux upstart deamon.

Forming ONOS cluster from individual ONOS instances

If you 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:

...

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.

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 8181 as in the following example:

...

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

...

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.

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.

Running in a VM

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

...