From OpenNMS

This part of the tutorial assumes that you have already installed OpenNMS.

In this tutorial, when you see "$OPENNMS_HOME," that refers to the root directory of your OpenNMS installation, usually "/opt/opennms" on RPM-based systems, "/var/lib/opennms" on Debian-based systems, or "C:\Program Files\OpenNMS" on Windows.

Before you go any further, please start your OpenNMS installation by running the command:

 $OPENNMS_HOME/bin/opennms start

(or "$OPENNMS_HOME\bin\opennms.bat start" on Windows)

Introduction

OpenNMS has a very robust set of tools for scanning for the capability of devices on your network. Unlike some network management tools, detecting services, finding new devices, and provisioning devices from your asset management system are all separately configurable.

The first step after OpenNMS is started is to verify that discovery and capability scanning is working on your system. Now, we'll discuss basic capability scanning of a node.

Detecting Services on Devices

In order to detect services on devices, the Capsd daemon executes plugins to detect the presence of configured services. Once a service is detected, it is used by other daemons to monitor availability, or to collect data about it.

These services are configured in the capsd-configuration.xml file, which is pre-configured with a number of common services, like HTTP, SMTP, and so on. All Capsd needs to get started is an IP address that OpenNMS suspects may provide one or more of these services.

New Suspect Events

Capsd listens for "new suspect" events, which tell OpenNMS, "I suspect the IP address at <x> has services." These newSuspect events can come from a number of sources:

• an event sent from the command-line, using the send-event.pl script
• an event sent from a 3rd-party tool, talking on the OpenNMS event listener TCP port
• the Discovery daemon, which scans IP ranges for valid IP addresses (using ICMP "ping")
• the Trapd daemon, which listens for traps from SNMP-enabled devices
• the "Add Interface" page on the OpenNMS administrator web UI

 perl $OPENNMS_HOME/bin/send-event.pl \
   --interface YOUR-OPENNMS-IP \
   uei.opennms.org/internal/discovery/newSuspect

Scanning an Address

When Capsd receives a newSuspect event, it then executes the configured plugins to determine the availability of each service on the IP address provided by the event. It then creates a node and interface representing the IP address, and adds any services that it detects to that interface.

Note: detecting that a service exists is not necessarily the same as detecting that the service is functional and working properly. For example, an HTTP server responding with a 501 error is still detected as a valid HTTP service, even though it would be considered non-functional by a user.

After the scan is complete, the node, interfaces, and services are written to the database, and then OpenNMS events are sent to indicate that these new nodes, interfaces, and services exist.

SNMP Scanning

If the SNMP service was found, and is functioning correctly, then the SNMP agent is scanned for additional IP addresses, physical interfaces, and other information relating to the node. Each new IP address that's discovered is scanned for services, just like the one from the newSuspect event.

Configuring Access to SNMP Devices

By default, OpenNMS will scan a large variety of devices, using the default "public" SNMP community string. This is like a password, which allows access to SNMP on the device. In a secure environment, it is likely that your SNMP devices use a community string other than "public," and you will need to configure OpenNMS to know how to communicate with those devices. If the correct community name is not configured before the scan has started, the SNMP service will not be detected on your device, and additional SNMP scanning will not be performed.

 snmpwalk -v2c -c YOUR-COMMUNITY-STRING YOUR-OPENNMS-IP system

Adding a Custom Service

To add a custom service to Capsd, edit the capsd-configuration.xml file in $OPENNMS_HOME/etc. All Capsd plugins take the port, timeout, and retry parameters, but many can take additional parameters as well which allow you to tune a particular plugin's behavior.

Some example plugins are HttpPlugin for detecting web servers, TcpPlugin for detecting an open TCP port, and so on. All you really need to do to add a custom service is make a new <protocol-plugin ...> entry in the configuration file, with a unique "protocol" name defined.

   <protocol-plugin protocol="OpenNMS-WebUI"
      class-name="org.opennms.netmgt.capsd.plugins.HttpPlugin" scan="on">
      <property key="port" value="8980" />
      <property key="timeout" value="3000" />
      <property key="retry" value="1" />
    </protocol-plugin>

 $OPENNMS_HOME/bin/opennms restart

Re-Scanning a Device

By default, Capsd will re-scan all of your devices every 24 hours. If you wish to force it to schedule a rescan for your device immediately, it will do so when it receives the "forceRescan" event. A forceRescan event can be sent by:

• clicking the "Rescan" link on a node's page in the web UI
• sending an event with send-event.pl
• sending an event from a 3rd-party tool, talking on the OpenNMS event listener TCP port