This section covers the details involved in getting, installing, and running ONOS. Both single- and multi-instance cases are described.
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 for a VM used for running ONOS:
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:
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'.
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 |
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" |
To use karaf or onos command described in following sections, $KARAF_HOME/bin needs be added to the PATH environment variable. By default $ONOS_ROOT/tools/dev/bash_profile expects $KARAF_HOME 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_HOME pointing to the correct path before including $ONOS_ROOT/tools/dev/bash_profile |
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] ------------------------------------------------------------------------ $ |
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.
Karaf must first be configured to load the ONOS-related modules. In apache-karaf-3.0.2/etc/org.apache.karaf.features.cfg
.
Append the following to featuresRepositories:
mvn:org.onlab.onos/onos-features/1.0.0-SNAPSHOT/xml/features |
Append the following to featuresBoot:
onos-api,onos-core-trivial,onos-cli,onos-openflow,onos-app-fwd,onos-app-mobility,onos-app-tvue |
The above loads the trivial (single-instance) ONOS core, forwarding and topology viewer applications.
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 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> |
At this point, typing help onos
at the prompt should still bring up a list of available commands. Hitting <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:
And relaunch karaf. |
onos-package
and onos-install
Remote installations are useful when one wishes to 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. 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.
The prerequisites for using these scripts are:
Additionally, onos-install
relies on ssh
to deploy the package to the target machine. Therefore:
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. Additionally, the ONOS_FEATURES variable should be set to the list of modules Karaf should start up:
$ export ONOS_FEATURES="webconsole,onos-api,onos-core,onos-cli,onos-openflow,onos-app-fwd,onos-app-mobility,onos-app-tvue" |
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.20 onos 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 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> |
If ONOS has been previously installed on a remote machine, onos-install -f [target] will force a reinstall. |
For dealing with multiple remote machines, the behavior of the ONOS utilities can be streamlined by employing test cells. Test cells are discussed under Test Environment Setup in the Developer's Guide.
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.