Tutorial Capability Scanning

From OpenNMS
(Redirected from Capability Scanning)
Jump to: navigation, search

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, "/usr/share/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)


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 service detection is working on your system. Now, we'll discuss basic scanning of a node.

Detecting Services on Devices

In order to detect services on devices, the Provisiond daemon executes detectors 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 default foreign-source definition, which is pre-configured with a number of common services, like HTTP, SMTP, and so on. All Provisiond needs to get started is an IP address that OpenNMS suspects may provide one or more of these services.

New Suspect Events

Provisiond 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 "Add Interface" page on the OpenNMS administrator web UI

Note.png Try It! Scan Your First Device

Let's try having OpenNMS scan itself, using the send-event.pl script:

 perl $OPENNMS_HOME/bin/send-event.pl \
   --interface YOUR-OPENNMS-IP \

(don't forget to replace YOUR-OPENNMS-IP with the IP address of your OpenNMS server.)

Next, go to the event list page in your OpenNMS web UI. You should see the newSuspect event in the event browser, and will probably already see events related to scanning the node as well.

"newSuspect" Event

Scanning an Address

When Provisiond receives a newSuspect event, it executes the configured detectors to determine the presence 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.

Note.png Try It! Review Your First Scan

By now, the scan you initiated in the "new suspect events" section above should have completed, and you'll have a scanned node. Go to the node list page in your OpenNMS web UI and take a look at your node. It will probably look something like this:

Node Page After Scan

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.

Note.png Try It! Configure SNMP On Your Device

If the SNMP service was not discovered on your device, make sure an SNMP daemon is running on your OpenNMS system by running snmpwalk:


If you get the response, "Timeout: No Response from YOUR-OPENNMS-IP", then you will need to configure an SNMP daemon on your system. For most Linux distributions, you should be able to install the "net-snmp" or "snmpd" packages, and then run the "snmpconf" utility to configure your access and community strings.

Once SNMP is working, browse to the admin page in the OpenNMS web UI and then click "Configure SNMP Community Names by IP", under the "Operations" section. Enter your IP address in the first IP address box, and the community string, and click "Submit."

Now OpenNMS is configured with the community string for your server.

Adding a Custom Service

To add a custom service to Provisiond, log in to the web UI as an admin user. Go to Admin / Manage Provisioning Requisitions and click the Edit Default Foreign Source Definition button and add a detector for your custom service.

All Provisiond detectors 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. The available parameters for the chosen detector are enumerated in a drop-down list as you build the detector definition.

Some example detectors are HttpDetector for detecting web servers, TcpDetector for detecting an arbitrary open TCP port, and so on. All you really need to do to add a custom service is make a new detector entry in the default foreign-source definition, with a unique service name defined.

{{Try-It|title=Adding the OpenNMS Web Server|contents=As an example, let's make OpenNMS detect its web UI. The OpenNMS web UI is just an HTTP server, listening on port 8980, so we'll use the HttpDetector to detect it. Edit the default foreign-source definition and add the following to the end of the list of configured detectors:


Re-Scanning a Device

By default, Provisiond 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

Note.png Try It! Re-Scan Your Node

Now that we've done more configuration, let's tell OpenNMS to re-scan itself. The easiest way to do so is by clicking "Rescan" in the node's page in the web UI. Just navigate to the node list to find your node, and then in the node's page, click "Rescan" up at the top.

You should immediately see "A services scan has been forced on this node" in the "Recent Events" list on the node's page. If you wait a little bit and refresh the node page again, you should see more events, as well as the SNMP and OpenNMS-WebUI services in the "Availability" section.

New Services Found

Next-arrow.png Next Step: Notifications

Now that you know how to scan devices, let's configure notifications so that you can know when OpenNMS is doing things.