CorvilNet Monitoring User Guide

Overview

The CorvilNet integration enables Geneos to connect with the CorvilNet Engine (CNE). This integration makes available the network monitoring data from the CorvilNet Engine to Geneos. This integration is performed through the API plug-in.

When set up, the integration and its associated API plug-in comprise the CorvilNet plug-in (CNPI).

When you set up the CNPI for the first time, it produces three basic dataviews:

  • cnpiConfig — shows the general information and status of your CNPI.
  • qosAlerts — shows any outstanding quality-of-service alerts.
  • systemAlerts — shows any outstanding system alerts

The CorvilNet monitoring statistics views appear when you configure the respective configuration (.cfg) files on the API sampler. These views are the main feature of the CorvilNet monitoring integration, as these show the monitoring statistics coming from the CNE:

  • getSummary — shows a summary of the CorvilNet monitoring statistics.
  • getStats — shows historical statistics as monitored by the CNE.
  • getLiveStats — shows live statistics as monitored by the CNE.

If you are using the Latency Management Centre (LMC) to monitor your CNE, then your integration includes three additional views:

  • trapFODConfig — shows the configuration details of the trap fan-out daemon (trapFOD), including errors encountered when you run the trapFOD.
  • fodCNEStatus — shows the status of the trap-forwarding process with respect to each known CNE.
  • fodCNPIStatus — shows the status of the trap forwarding process with respect to each known CNPI instance.

The CNPI receives monitoring statistics from the CNE through the Corvil API. The CNE also sends system event information through the Simple Network Management Protocol (SNMP).

This guide discusses the steps to set up the CorvilNet plug-in from its source integration files. Once the integration is set up, the dataviews become available through the API plug-in.

Information related to setting up and administering to the CNE or LMC is out of scope of this guide.

Intended audience

This guide is directed towards experienced Geneos users who want to set up an integration between Geneos and the CorvilNet Engine (CNE). If the organisation uses the Corvil Latency Management Centre (LMC) to manage multiple instances of the CNE, then there are additional steps in the integration.

The CorvilNet monitoring integration requires a Linux machine. As a user, you should be familiar with general system administration on this platform.

Prerequisites

The following requirements must be met prior to the installation and setup of the template:

  • A Linux machine where the CNPI and, if applicable, the trapFOD can run.
  • The machine where the CNPI runs must be able to communicate with the CNE via HTTP or SNMP.
  • We recommend that you set up the integration on the same machine as the Netprobe. Otherwise, ensure that the machines can communicate via SNMP.
  • This requires an additional licence to use. Please contact your ITRS Account Manager for more information.

CorvilNet Engine credentials

When you configure the CorvilNet monitoring integration, you will need the following information from your CNE:

  • Address or hostname
  • Web services interface port number
  • Web services interface username and password

If you are using SNMP to connect the CNE to the CNPI, then you will need the following:

  • SNMP port number
  • SNMP community string

Connection structure

Depending on your organisation, your CorvilNet monitoring integration could look like one of the following:

Connecting to a CorvilNet Engine

Each instance of the CNPI communicates with a partner CNE. If you are monitoring multiple instances of the CNE, then you must set up a CNPI instance for each.

For each CNPI and partner CNE combination, you must configure the CNE with the network address or hostname of the machine where the CNPI is running, as well as the same port.

Connecting to a Latency Management Centre

If you are using the LMC, then the CNE and CNPI communicate through SNMP traps. In this integration, the SNMP traps are routed and forwarded by the trapFOD.

Each trapFOD communicates with an LMC. If you are monitoring multiple instances of the LMC, then you must set up a trapFOD instance for each.

Integration steps — CorvilNet Engine monitoring

The CorvilNet integration involves the following tasks:

  1. Download the integration files.
  2. Set up the API sampler.
  3. Associate the API plug-in with a managed entity.
  4. Set up the CorvilNet start-up script.
  5. Run the CorvilNet start-up script.

Download the integration files

  1. On the ITRS Downloads page, download the CorvilNet integration files (geneos-cnpi-1.3.2032.tar.gz).
  2. Save the files on the Linux machine where plan to run the CorvilNet integration.

The integration files include the following sub-folders:

  • examples — contains the configuration templates and start-up script you need to set up the integration.
  • Linux_x86_64 — contains the source files that run the CorvilNet integration.

Set up the API sampler

  1. On the Gateway Setup Editor, create a new sampler by right-clicking the Samplers folder.
  2. Enter a name for this sampler. As a default, enter the name CNE in the Name field.
  3. On the drop-down list under the Plugin field, select api.
  4. Click Save current document to apply your changes.

Associate the API plug-in with a managed entity

  1. On the Gateway Setup Editor, create a new managed entity by right-clicking the Managed entities folder.
  2. Enter a name for this managed entity. As a default, enter the name CN in the Name field.
  3. In the Options field, select the probe on which you want the sampler to run.
  4. Under the Sampler field, click Add new .
  5. In the text field under Ref, type the name of the API sampler you had created. By default, this is CNE.
  6. Click Save current document to apply your changes.

Set up the CorvilNet start-up script

  1. From the CorvilNet integration files you downloaded, go to the examples folder and locate the file named start_cnpi.
  2. Open start_cnpi in a text editor.
  3. Replace the values in brackets with the respective details from your system. For more information, see the CorvilNet plug-in start-up script variables.

Run the CorvilNet start-up script

  1. Open the Terminal.
  2. Enter the following command:
  3. bash$ chmod u+x start_cnpi

Success: After you run the integration script, the basic dataviews appear under the managed entity that you configured for CorvilNet. For more information on the basic dataviews, see the Default metrics and dataviews.

If you set the start script to have the --verbose setting, then you will see some initial information in the log file. Otherwise, the log file is empty.

Additional steps — Latency Management Centre

If you are using the CNE through the LMC, then there are additional steps for you to perform:

  1. Set up the trapFOD start-up script.
  2. Run the trapfod start-up script.
  3. Set the FOD parameters in the sampler.

Set up the trapFOD start-up script

  1. From the CorvilNet integration files you downloaded, go to the examples folder and locate the file named start_fod.
  2. Open start_fod in a text editor.
  3. Replace the values in brackets with the respective details from your system. For more information, see trapFOD start-up script variables.

Run the trapfod start-up script

  1. Open the Terminal.
  2. Enter the following command:

    bash$ chmod u+x fod_cnpi

  3. Success: After you run the integration script, the trapFOD dataviews appear under the managed entity that you configured for CorvilNet. For more information on the dataviews, see the trapfod metrics and dataviews.

    If you set the start script to have the --verbose setting, then you will see some initial information in the log file. Otherwise, the log file is empty.

Set the FOD parameters in the sampler

  1. On the Gateway Setup Editor, open the sampler you set up in Set up the API sampler.
  2. In the Basic tab, add the following parameters:
    • FOD_HOSTNAME — hostname of the trapFOD.
    • FOD_PORT — network port of the trapFOD.
  3. Success: After you set the FOD parameters, the API sampler begins to interact with the trapFOD.

Encryption utility

The encryption utility, cnpi_crypt, is included in the integration files. Run this utility to encrypt your CNE password:

  1. Open the Terminal.
  2. Navigate to the Linux_x86_64 folder from the CorvilNet integration files.
  3. Enter the following command:
  4. .\cnpi-crypt [your CNE password]

    Success: When you enter this command, the utility encrypts the password and displays its encrypted string on the Terminal.

  5. Copy the encrypted string and use this for the {EncryptedPassword} variable in the start-up script.

Shutdown script

If you want to shut down the CNPI, follow these steps:

  1. Locate the PID file in the {LogLocation} you specified in CorvilNet Monitoring User Guide .
  2. Open the Terminal.
  3. Enter the following command, specifying the {LogLocation} and the PID file on your system. For example:
  4. bash$ kill $(cat /home/user/log/geneos-cnpi.pid )

    Success: This command kills the process associated with the CNPI.

Further reading

The CorvilNet plug-in provides powerful customisable views on network monitoring statistics. After you have set up the integration, you can learn about its dataviews and plug-in configuration in the CorvilNet Monitoring Technical Reference.

Appendix

CorvilNet plug-in start-up script variables

The start_cnpi file is a default template for the start-up script, which sets up the CorvilNet integration. You need to replace the bracketed fields with the requisite CorvilNet Engine credentials.

Note: Remove the brackets ({}) when adding you system credentials into the start script.

#!/bin/bash
# Template start-up script for the Geneos CorvilNet plugin, geneos-cnpi.
# See the plug-in manual for a further explanation of this script.

# The location where the plug-in media was unpacked
export CNPI_UNPACK={UnpackLocation}

# The name of the subdirectory containing the executable and libraries appropriate to the host environment
# (eg Linux_x86_64, SunOS, etc)
export HOST_TYPE={HostType}

# The name of the directory in the unpack location containing the version of the plug-in to be used.
export CNPI_VERSION={PlugInVersion}

# The location to which the plug-in can write log files
export LOG_DIR={LogLocation}

# The relevant Geneos components
export MANAGED_ENTITY={ManagedEntity}
export NETPROBE_HOSTNAME={LocalHost}
export NETPROBE_PORT={Port}
export SAMPLER_NAME={SamplerName}

# The relevant Corvil components
export CNE_API_HOSTNAME={APIHostname}
export CNE_API_PORT={APIPort}
export CNE_USERNAME={Username}
export CNE_ENCRYPTED_PASSWORD={EncryptedPassword}
export CNE_SNMP_PORT={SNMPPort}
export CNE_COMMUNITY={CommunityString}

# The specification of how CNE traps will be received by geneos-cnpi
export TRAP_HOSTNAME={TrapHostname}
export TRAP_PORT={TrapPort}

# START THE PLUG-IN
export CNPI_DIR=$CNPI_UNPACK/$CNPI_VERSION/$HOST_TYPE
export LD_LIBRARY_PATH=$CNPI_DIR
$CNPI_DIR/geneos-cnpi $MANAGED_ENTITY $CNE_API_HOSTNAME \
--hostname=$NETPROBE_HOSTNAME \
--port=$NETPROBE_PORT \
--sampler=$SAMPLER_NAME \
--detach=$LOG_DIR \
--pid-file=$LOG_DIR/geneos-cnpi.pid \
--log-file=$LOG_DIR/geneos-cnpi.log \
--license=$CNPI_UNPACK/geneos-cnpi.lic \
--api-config=$CNPI_DIR/geneos-cnpi.cfg \
--cne-api-port=$CNE_API_PORT \
--cne-username=$CNE_USERNAME \
--cne-encrypted-password=$CNE_ENCRYPTED_PASSWORD \
--cne-snmp-port=$CNE_SNMP_PORT \
--cne-community="$CNE_COMMUNITY" \
--trap-hostname=$TRAP_HOSTNAME \
--trap-port=$TRAP_PORT \
--brief

# start_cnpi
Variable Example value Description
{UnpackLocation} /home/user/cnpi The directory where you unpacked the CorvilNet integration files downloaded from the ITRS Downloads page.
{HostType} Linux_x86_64

The subdirectory of the CorvilNet integration source files appropriate to the operating system in which the plug-in is being installed.

By default, this is Linux_x86_64.

{PlugInVersion} geneos-cnpi-1.3.2032

The subdirectory containing all the CorvilNet integration files.

By default, this is the top-level directory name of the unpacked files.

{LogLocation} /home/user/log

The directory where you want the CorvilNet plug-in to write its output files:

  • log files
  • process identifier (PID) files
{ManagedEntity} CN The name of the managed entity that you set up in Associate the API plug-in with a managed entity.
{LocalHost} localhost

The network address or hostname of the Netprobe you want to associate with the CorvilNet plug-in.

If the Netprobe is running on the same machine as the CorvilNet plug-in, then this is localhost.

{Port} 7036 The port number of the Netprobe you want to associate with the CorvilNet plug-in.
{SamplerName} CNE The name of the sampler that you set up in Set up the API sampler.
{APIHostName} 198.51.100.0 The network address or hostname of the CNE that you want to monitor.
{APIPort} 5101 The port number of the CNE that you want to monitor.
{Username} geneosuser The username you use to access the CNE you want to monitor.
{EncryptedPassword} encryptedpassword

The password associated with the username you use to access the CNE.

The password must be encrypted using the utility supplied with the CorvilNet Integration files. For more information, see Encryption utility.

{SNMPPort} 161 The SNMP port of the CNE you want to monitor.
{CommunityString} string The SNMP community string of the CNE you want to monitor.
{TrapHostname} 192.0.2.0 The network address or hostname of the network interface where the CNE can send SNMP traps. This should be on the same machine where the CNPI is running.
{TrapPort} 5555 The port of the network interface where the CNE can send SNMP traps. This should be on the same machine where the CNPI is running.

Note: In the start script, notice the line --brief near the end of the file. You may change this to --verbose or --debug. This setting determines whether the CNPI returns brief or verbose logs and error messages. For more information on commands available to the CNPI, see CNPI commands.

trapFOD start-up script variables

The start_fod file is a default template for the start script, which sets up the CorvilNet integration through the LMC. You need to replace the bracketed fields with the requisite CorvilNet Engine credentials.

Note: Remove the brackets ({}) when adding you system credentials into the start script.

#!/bin/bash
# Template start-up script for the Geneos CorvilNet plugin trap fan-out daemon, trapfod.
# See the plug-in manual for a further explanation of this script.

# The location where the plug-in media was unpacked
export FOD_UNPACK={UnpackLocation}

# The name of the subdirectory containing the executable and libraries appropriate to the host environment
# (eg Linux_x86_64, SunOS, etc)
export HOST_TYPE={HostType}

# The name of the directory in the unpack location containing the version of the plug-in to be used.
export CNPI_VERSION={PlugInVersion}

# The location to which the daemon should write log files
export LOG_DIR={LogLocation}

# The relevant Geneos components
export MANAGED_ENTITY={ManagedEntity}
export NETPROBE_HOSTNAME={LocalHost}
export NETPROBE_PORT={Port}
export SAMPLER_NAME={SamplerName}

# The specification of how CNE traps will be received by trapfod
export TRAP_HOSTNAME={TrapHostname}
export TRAP_PORT={TrapPort}

# START THE DAEMON
export FOD_DIR=$FOD_UNPACK/$CNPI_VERSION/$HOST_TYPE
export LD_LIBRARY_PATH=$FOD_DIR
$FOD_DIR/trapfod $MANAGED_ENTITY \
--hostname=$NETPROBE_HOSTNAME \
--port=$NETPROBE_PORT \
--sampler=$SAMPLER_NAME \
--detach=$LOG_DIR \
--pid-file=$LOG_DIR/trapfod.pid \
--log-file=$LOG_DIR/trapfod.log \
--license=$FOD_UNPACK/geneos-cnpi.lic \
--trap-hostname=$TRAP_HOSTNAME \
--trap-port=$TRAP_PORT \
--brief

# start_cnpi
Variable Example value Description
{UnpackLocation} /home/user/cnpi The directory where you unpacked the CorvilNet integration files downloaded from the ITRS Downloads page.
{HostType} Linux_x86_64

The subdirectory of the CorvilNet integration source files appropriate to the operating system in which the plug-in is being installed.

By default, this is Linux_x86_64.

{PlugInVersion} geneos-cnpi-1.3.2032

The subdirectory containing all the CorvilNet integration files.

By default, this is the top-level directory name of the unpacked files.

{LogLocation} /home/user/log

The directory where you want the CorvilNet plug-in to write its output files:

  • log files
  • process identifier (PID) files
{ManagedEntity} CN The name of the managed entity that you set up in Associate the API plug-in with a managed entity.
{LocalHost} localhost

The network address or hostname of the Netprobe you want to associate with the CorvilNet plug-in.

If the Netprobe is running on the same machine as the CorvilNet plug-in, then this is localhost.

{Port} 7036 The port number of the Netprobe you want to associate with the CorvilNet plug-in.
{SamplerName} CNE The name of the sampler that you set up in Set up the API sampler.
{TrapHostname} 192.0.2.0 The network address or hostname of the network interface where the CNE can send SNMP traps. This should be on the same machine where the CNPI is running.
{TrapPort} 5555 The port of the network interface where the CNE can send SNMP traps. This should be on the same machine where the CNPI is running.

Note: In the start script, notice the line --brief near the end of the file. You may change this to --verbose or --debug. This setting determines whether theCNPI returns brief or verbose logs and error messages. For more information on commands available to the trapFOD, see trapFOD commands.