This is an archive of the ONOS 1.1 wiki. For the current ONOS wiki, look here.

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

 

This section assumes that the reader has already checked out the latest source by following Getting ONOS - ONOS Source Code.

If you are installing into an Ubuntu VM, make sure you have completed steps 2 and 3 from ONOS from Scratch to install Karaf, Maven, and Java 8.

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.0 and later)
  • git
  • bash (for packaging & testing)
  • Apache Karaf (3.0.2 and later) 

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:

The best way to prevent this version mismatch is to install Maven before Java 8.

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:

$ cd Downloads
$ tar -zxvf apache-karaf-3.0.2.tar.gz -C ../Applications/
$ tar -zxvf apache-maven-3.2.3-bin.tar.gz -C ../Applications/

 

Upgrading to Java 8

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

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

$ sudo apt-get install software-properties-common -y
$ sudo add-apt-repository ppa:webupd8team/java -y
$ sudo apt-get update
$ sudo apt-get install oracle-java8-installer oracle-java8-set-default -y

You will have to accept the Oracle binary license terms  

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


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

Adding Karaf related commands to PATH

To use karaf or onos command described in following sections, $KARAF_ROOT/bin needs be added to the PATH environment variable.

By default $ONOS_ROOT/tools/dev/bash_profile expects $KARAF_ROOT to be ~/Applications/apache-karaf-$KARAF_VERSION and add them to the PATH.

If you have installed Apache Karaf to a different path, define $KARAF_ROOT pointing to the correct path before including $ONOS_ROOT/tools/dev/bash_profile

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

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. 

Initial configuration

Karaf must first be configured to load the ONOS-related modules. Karaf's configuration file $KARAF_ROOT/etc/org.apache.karaf.features.cfg . Edit the file:

Append the following to featuresRepositories:

mvn:org.onosproject/onos-features/1.1.0/xml/features

Note: Above is an example when using ONOS version 1.1.0. When using snapshot version, etc. replace them with the version you intend to use e.g., 1.1.0-SNAPSHOT, etc.

Append the following to featuresBoot:

onos-api,onos-core-trivial,onos-cli,onos-openflow,onos-app-fwd,onos-app-mobility,onos-gui

 The above loads the trivial (single-instance) ONOS core, forwarding, and Web GUI applications.

Running locally on build machine

Out-Of-Date Content

Blackbird (1.1.0) requires extra config files to run locally. We wrote a script named 'onos-setup-karaf' to copy those config files to the correct location. However, this script is only in master branch for now. We will soon back port it to the 1.1 branch. Before that, you should use the method described in the section 'Running remotely with onos-package and onos-install' to run ONOS.

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

$ karaf clean
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. Ctrl-D or logout will exit the CLI.

Launching karaf may bring up the default karaf prompt, without the 'ONOS' ASCII art. This is purely cosmetic, and shouldn't affect functionality.

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.1.0.jar ${KARAF_ROOT}/lib/

And relaunch karaf.

Running remotely with onos-package and onos-install

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.

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_FEATURES variable should be set to the list of modules Karaf should launch with ONOS:

    $ export ONOS_FEATURES="webconsole,onos-api,onos-core,onos-cli,onos-openflow,onos-app-fwd,onos-app-mobility,onos-gui"

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.

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

    As seen above, the file has the naming convention "onos-1.1.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.

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.

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

 

 

  • No labels