Overview

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

Setup

Passwordless Access Setup

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.

To configure passwordless CLI access, the operator must run onos-user-key tool as follows from each machine in the cluster:

# Usage is onos-user-key username key, e.g.

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

ONOS Username and Password change

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:

# Usage is onos-user-password username password

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

Configure ONOS instances IPs

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. Here’s an example of how to set the variable:

# The list of IP addresses is given as a space separated list

$ export ONOS_INSTANCES="10.192.19.111 10.192.19.112 10.192.19.113"

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)

Use

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 resulting /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...]

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 172.17.0.11 172.17.0.12 172.17.0.13