Table of Contents
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.
Code Block | ||||
---|---|---|---|---|
| ||||
$ 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
Code Block | ||||
---|---|---|---|---|
| ||||
$ 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
Code Block | ||||
---|---|---|---|---|
| ||||
$ 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:
Code Block | ||||
---|---|---|---|---|
| ||||
$ 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
Code Block | ||||
---|---|---|---|---|
| ||||
$ 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:
Code Block | ||||
---|---|---|---|---|
| ||||
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.
Code Block | ||||
---|---|---|---|---|
| ||||
$ 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.
Code Block | ||||
---|---|---|---|---|
| ||||
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.
Code Block | ||||
---|---|---|---|---|
| ||||
onos-diagnostics -u onos -p rules 172.17.0.11 172.17.0.12 172.17.0.13 |