In order to make administration of an ONOS cluster easier, ONOS comes with a small set of tools that the administrator can use to interact with ONOS cluster from a remote platform, which can be either their laptop or some designated administration host.

Downloading & Installing Admin Tools

The admin tools are available for download as a compressed tar from Maven central or from Google drive. The onos-admin-<version>.tar.gz file can be unrolled at a desired location on the machine(s) from which the ONOS cluster will be remotely administered. The PATH environment variable should be set to include the ONOS admin tools directory, e.g:

# This is just an example; use actual path where you unpacked the tools
export PATH=$PATH:~/onos-admin-1.12.1-SNAPSHOT/

The admin tools primarily operate either using the ONOS CLI or ONOS REST API. The clients for these are the native ssh command and curl command, respectively. The ONOS CLI (ssh to port 8101) access is secured using the onos-user-key command, and the ONOS REST API (curl to port 8181) access is secured using onos-user-password command. Both of these commands are part of the standard ONOS distribution and are located under the top-level bin directory, e.g. /opt/onos/bin. See the following section on securing the ONOS cluster.

To simplify the remote administration it is recommended to capture the details about the ONOS cluster being managed by creating a file that will hold definitions of the ONOS cluster instances:

# IP addresses of the ONOS cluster nodes
export OC1=
export OC2=
export OC3=
export OC4=
export OC5=

# Provide a list of all ONOS instances using the above variables
export ONOS_INSTANCES=“$OC1 $OC2 $OC3 $OC4 $OC5"

# Optionally export ONOS web user/password if non-default ones are used
export ONOS_WEB_USER=onos
export ONOS_WEB_PASS=rocks

Save this file under a name that will make it easy to remember which ONOS deployment cluster it refers to.

Then to set the environment to point to that ONOS pod, simply source in the file, e.g.:

$ source ~/pod42 # source in pod42 from home directory

After this, and after exporting the PATH environment variable as indicated above, you should be able to type in the following commands to manage the cluster, e.g.:

$ onos # CLI to the first instance $OC1
$ onos 3 # CLI to the third instance $OC3
$ onos ipaddress # CLI to the ONOS at the given IP
$ onos 2 summary # execute “summary” CLI on 2nd instance $OC2
$ onos-diagnostics # collect ONOS diagnostics on the entire cluster

The above are just a few examples. Any of the ONOS admin commands that are intended to command a specific instance take the numeric argument or IP address as the first argument. These include onosonos-apponos-netcfg, etc.

Securing ONOS Cluster

To configure passwordless CLI access, the operator must run onos-user-key tool as follows from each machine in the cluster. This tool is available under the ONOS bin directory.

$ onos-user-key onos AAAAB3NzaC1yc2EAAAADAQABAAABAQC4pL/Jzlm/jq7ltDVIb4CEIUXxYEK...

Similarly, it is recommended to change the default username and password for the REST API using onos-user-password tool on each ONOS cluster node as follows:

$ onos-user-password onos superSecretPassword

By configuring the ONOS cluster in this manner, not only it will become more secure, it will also become more convenient to manage using automated tools without having to enter credentials each time.

Documentation & Example Usage

The following sections provides a quick overview of the individual administrative tools and their usage.


The onos-diagnostics tool collects various information from the running ONOS cluster and packages it into one, easy-to-share archive file. This tool is distributed as part of the ONOS software itself (under bin directory), but is also available as part of a small archive of remote tools to administer an ONOS cluster (onos-admin-*.tar.gz).

In order to run the onos-diagnostics tool, the machine/account from which the tool runs must be allowed to remotely connect to the ONOS CLI. This is accomplished by registering the user’s public RSA/DSA key with each ONOS instance. To make this easier another tool onos-user-key has been provided as part of the base ONOS distribution to modify the ONOS configuration appropriately to make this possible and, equally important, to make the ONOS deployment secure.

Since the tools contacts all ONOS node cluster instances, it needs to know the IP addresses of those machines. To avoid having to specify these IP addresses as part of the command, you can export the ONOS_INSTANCES environment variable to specify the addresses as a space-separated list. Here’s an example of how to set the variable:

$ export ONOS_INSTANCES=""

The tool also accesses the ONOS REST API to collect logs and for this it requires the REST API username and password credentials. These credentials can be provided either via ONOS_WEB_USER and ONOS_WEB_PASSWD environment variables or via command options (see usage below)

Once enabled, the onos-diagnostics tool can be run as follows:

$ onos-diagnostics

There is an option that allows for naming the resulting archive file for differentiation between different cluster instances, e.g.

# This will produce archive file /tmp/delta-pod-diags.tar.gz
$ onos-diagnostics -n delta-pod

The resuling /tmp/*-diags.tar.gz file will contain all relevant information about the ONOS cluster.

The following is the usage help for the onos-diagnostics tool:

usage: onos-diagnostics [-x] [-n name] [-u user] [-p password] [ip1 ip2...]
Environment Variables:
   ONOS_INSTANCES    IPs or hostnames of ONOS cluster machines
   ONOS_WEB_USER     username for REST API
   ONOS_WEB_PASS     password for REST API
Example Usages:
   # Collect compressed diagnostics for the cluster.
   # REST API user and password are drawn from environment variables.
   # Collection archive will be named /tmp/onos-diags.tar.gz
   # The cluster node IPs will be drawn from ONOS_INSTANCES variable.
   $ onos-diagnostics
   # Collect diagnostics for the cluster and leave them extracted.
   # Collection directory will be named /tmp/prague-diags/
   # Collection archive will be named /tmp/prague-diags.tar.gz.
   # REST API user name is 'onos' and password is 'rules'.
   # The cluster node IPs will be drawn from ONOS_INSTANCES variable.
   $ onos-diagnostics -x -n prague -u onos -p rules
   # Collect compressed diagnostics for a cluster.
   # REST API user name is 'onos' and password is 'rules'.
   # Collection archive will be named /tmp/onos-diags.tar.gz
   # The cluster node IPs are listed explicitly.
   $ onos-diagnostics -u onos -p rules


Since ONOS Apache Karaf log can be spread across multiple files, i.e. karaf.log, karaf.log.1, karaf.log.3, etc. and since each ONOS cluster node has its own set of such logs, it can be cumbersome to find relevant information in the logs purely manual means. The onos-log-query tool has been provided to make log stitching, filtering and collating much easier. The tool can operate on standalong log files, but it works well with information collected via the onos-diagnostics tool.

The tool is designed to splice together the different karaf.log* files and then to optionally to narrow them to include only the specified date/time interval. This is done using the -f and -t options. Since the splicing and filtering operation may take some time, the tool stores the processed output into a separate file, which by default is called query.log. This name can be changed using the -n option. This allows the user to keep results of multiple different queries and it also allows other types of processing to be applied on these files using other external tools without repeatedly incurring the cost of stitching and filtering a potentially very large data-sets.

The simplest way to run the tool is from the root of the directory produced by unrolling the ONOS diagnostics archive, which is where the node-level directories are. For example, to stitch and filter the logs to only focus on the specific duration of output, you could do the following:

$ onos-log-query -x -f "2018-04-25 13:04:30" -t "2018-04-25 13:10:00" -n anomaly

This will produce stitched and filtered versions of the log for each individual node, as well as a collated version containing merge of all node logs. These files will be called anomaly.log; there will be one for each of the nodes in the respective node directory and also the collated one at the top-level directory. 

The -f flag specifies the start of the time period (inclusive) and the -t flag specified the end of the tim period (also inclusive). If either is not specified, the logs will be included from the beginning or until the end. The -x option indicates that only timestamped log entries should be included, which means stack-traces and other multi-line log entries will be reduced to just the time-stamped line of the log. The -n option allows you to provide a custom name under which your results should be saved; if not specified, the logs will be stored in query.log files.


To facilitate remote management of ONOS applications the onos-app tool has been provided as a way to easily upload new application binaries via REST API. Of course, applications can also be listed, uninstalled, activated and deactivated using the CLI, but installation of apps via CLI only allows installing apps via a URL to application binaries located on a web-server elsewhere. The onos-app tools allows uploading application OAR file from the administration machine directly.

The following is the usage:

usage: onos-app [options] <node-ip> list
       onos-app [options] <node-ip> {install|install!} <app-file>
       onos-app [options] <node-ip> {reinstall|reinstall!} [<app-name>] <app-file>
       onos-app [options] <node-ip> {activate|deactivate|uninstall} <app-name>
options: [-P port] [-u user] [-p password] [-v]

For example, to upload a super duper ONOS app, whose binaries are located locally in a file ~/onos/apps/super-duper-6.28.oar file, to the ONOS cluster through one of its instances at, you would use the following command:

$ onos-app install! ~/onos/apps/super-duper-6.28.oar

The ! postfix in the  install! and reinstall! commands indicates that the application should also be activated immediately after the installation. Otherwise, the commands mean what their names clearly imply.


ONOS supports dynamic YANG compilation via GUI and via REST API. To make this even more convenient, the onos-compile-yang command has been provided. Internally, it uses the REST API, but should be far easier to use from the remote Unix shell.

usage: onos-compile-yang [-P port] [-u user] [-p password] [-v] \

The command allows uploading and compiling an individual .yang file, or a collection of yang files located in a given .zip file, .tar.gz file or even just a plain local directory. YANG compilation will result in generation of Java classes from the included YANG models, compilation of those classes into an ONOS application .oar bundle and automatic installation and activation of the application. The newly registered YANG models can be immediately listed via YANG REST API, GUI or CLI commands. The appllication will derive it's name and identifier from the name of the uploaded file or directory. It can be seen among the list of applications installed and active on the running ONOS cluster.

For example, to upload, compile and register some-funky-model.yang file, one could do the following:

$ onos-compile-yang ~/models/some-funky-model.yang

Notice that the ONOS cluster does not need to be rebuilt, stopped or reconfigured in any way. Once can simply dynamically add and remove YANG models at will.


The onos command is simply a convenience wrapper that allows the administrator to securely open the ssh session to any of the ONOS cluster nodes. As with all the admin commands, one can use either the DNS name, IP address or a numeric index of the ONOS node - provided the OC# environment variables have been properly setup. The following are examples of usage:

$ onos 1 summary		# Invoke summary command on the first ONOS instance
$ onos		# Open interactive CLI session on the ONOS instance at the specified IP
Welcome to Open Network Operating System (ONOS)!
     ____  _  ______  ____
    / __ \/ |/ / __ \/ __/
   / /_/ /    / /_/ /\ \

Mailing lists:

Come help out! Find out how at:

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.