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 this Box location. 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=10.192.19.101 export OC2=10.192.19.102 export OC3=10.192.19.103 export OC4=10.192.19.104 export OC5=10.192.19.105 # 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 onos
, onos-app
, onos-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.
# Usage is onos-user-key username key, e.g. 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:
# 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.
Documentation & Example Usage
The following sections provides a quick overview of the individual administrative tools and their usage.
onos-diagnostics
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. 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)
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 172.17.0.11 172.17.0.12 172.17.0.13