1. Command Line

1.1. Karaf Shell

A number of Karaf Shell commands are made available to help administer and diagnose issues related to performance data collection.

To use the commands, log into the Karaf Shell on your system using:

ssh -p 8101 admin@localhost
The Karaf shell uses the same credential as the web interface. Users must be associated with the ADMIN role to access the shell.
In order to keep the session open while executing long-running tasks without any user input add -o ServerAliveInterval=10 to your ssh command.

1.1.1. Ad-hoc collection

The collection:collect Karaf Shell command can be used to trigger and perform a collection on any of the available collectors.

The results of the collection (also referred to as the "collection set") will be displayed in the console after a successful collection. The resulting collection set will not be persisted, nor will any thresholding be applied.

List all of the available collectors:

collection:list-collectors

Invoke the SnmpCollector against interface 127.0.0.1 on NODES:n1.

collection:collect -n NODES:n1 org.opennms.netmgt.collectd.SnmpCollector 127.0.0.1

Invoke the SnmpCollector against interface 127.0.0.1 on NODES:n1 via the MINION location.

collection:collect -l MINION -n NODES:n1 org.opennms.netmgt.collectd.SnmpCollector 127.0.0.1
Setting the location on the command line will override the node’s location.
If you see errors caused by RequestTimedOutException`s when invoking a collector at a remote location, consider increasing the time to live. By default, `collectd will use the service interval as the time to live.

Invoke the JdbcCollector against 127.0.0.1 while specifying some of the collector parameters.

collection:collect org.opennms.netmgt.collectd.JdbcCollector 127.0.0.1 collection=PostgreSQL driver=org.postgresql.Driver url=jdbc:postgresql://OPENNMS_JDBC_HOSTNAME/postgres user=postgres
Some collectors, such as the JdbcCollector, can be invoked without specifying a node.

Persist a collection :

collection:collect -l MINION -n NODES=n1 -p org.opennms.netmgt.collectd.SnmpCollector 127.0.0.1
-p/--persist option will persist collection set there by introducing an extra datapoint other than data collected during already configured collection interval.

A complete list of options is available using:

collection:collect --help

1.1.2. Interpreting the output

After a successful collection, the collection set will be displayed in the following format:

resource a
  group 1
    attribute
    attribute
  group 2
    attribute
resource b
  group 1
    attribute
...

The description of the resources, groups and attribute may differ between collectors. This output is independent of the persistence strategy that is being used.

1.2. Resource CLI

Sometimes a user want to list or manually delete collected data (resources) of an OpenNMS Horizon instance. When using RRDTool- or JRobin-based storage this can easily be achieved by traversing the share/rrd directory and its subdirectories. The several .rrd or .jrb files can be listed or deleted for individual nodes. When Newts-based storage is used the data is stored and indexed remotely on a Cassandra cluster. In this case the cluster must be queried for available resources. For the deletion of resources the data and all generated indexes must be gathered and removed. The resourcecli tool simplifies this process and works with Newts-based storage as well as with RRDTool and JRobin files.

1.2.1. Usage

The utility is installed by default and its wrapper script is located in the ${OPENNMS_HOME}/bin directory.

$ cd /path/to/opennms/bin
$ ./resourcecli
When invoked without parameters the usage and help information is printed.

The resourcecli tool uses sub-commands for the different tasks. Each of these sub-commands provide different options and parameters. The command line tool accepts the following sub-commands.

Sub-command Description

list

Queries an OpenNMS Horizon server for available resources.

show

Displays details for a given resource.

delete

Deletes a given resource and all of its child resources.

The following global options are available in each of the sub-commands of the tool:

Option/Argument Description Default

--help

Displays help and exit

false

--username VALUE

Username for connecting to OpenNMS Horizon

admin

--password VALUE

Password for connecting to OpenNMS Horizon

admin

--url VALUE

URL of the OpenNMS Horizon instance to connect to

http://localhost:8980/opennms

1.2.2. Sub-command: list

This sub-command is used to query an OpenNMS Horizon instance for its available resources. The following example queries the local OpenNMS Horizon instance with the credentials admin/secret.

$ ./resourcecli --username admin --password secret list
node[72]
  node[72].nodeSnmp[]
  node[72].responseTime[192.168.0.2]
node[70]
  node[70].nodeSnmp[]
  node[70].interfaceSnmp[bridge0]
  node[70].interfaceSnmp[bridge1]
  node[70].interfaceSnmp[vlan0-002500fe1bf3]
	node[70].responseTime[50.16.15.18]
  node[70].responseTime[192.168.0.1]

<output omitted>

1.2.3. Sub-command: show

This sub-command can be used to show details for a given resource. The following example display details for the resource identified by resourceId node[70].

$ ./resourcecli --username admin --password secret show node\[70\]
ID:         node[70]
Name:       70
Label:      MyRouter
Type:       Node
Link:       element/node.jsp?node=70
Parent ID:  null
Children:
  node[70].nodeSnmp[]
  node[70].interfaceSnmp[bridge0]
  node[70].interfaceSnmp[bridge1]
  node[70].interfaceSnmp[vlan0-002500fe1bf3]
	node[70].responseTime[50.16.15.18]
  node[70].responseTime[192.168.0.1]
Attributes:
  External:
  Graphs:
  Strings:

The following options are available for the show sub-command.

Option/Argument Description Default

<resource>

The resourceId of the resource to display.

 -

1.2.4. Sub-command: delete

This sub-command can be used to delete a given resource and its child resources. The following example deletes the resource identified by resourceId node[70]. When successful, this command does not generate any output.

$ ./resourcecli --username admin --password secret delete node\[70\]
$

The following options are available for the delete sub-command.

Option/Argument Description Default

<resource>

The resourceId of the resource to be deleted.

 -

1.3. Rrd/Jrb to Newts migration utility

This utility can be used to migrate existing RRDTool- or JRobin-based data to a Newts cluster. This will be achieved by traversing the share/rrd directory and its subdirectories, reading the data and properties files and persisting this data to Newts.

1.3.1. Migration

The following suggestions try to minimize the data collection gap that occur when reconfiguring OpenNMS Horizon for a different storage strategy. First, we determine the parameters needed for migration of the existing data. After that, we reconfigure OpenNMS Horizon to persists all new collected data to Newts storage. Finally, the Rrd- or JRobin-based data will be converted and persisted to Newts using the newts-repository-converter utility.

Prerequisites
  • Working OpenNMS Horizon installation with RRDTool- or JRobin-based storage strategy configured.

  • Installed and working Newts cluster reachable by the OpenNMS Horizon instance.

Migration plan
  1. Check and write down the values for the following options in your opennms.properties file. You will need these information later to invoke the newts-repository-converter utility.

    1. File etc/opennms.properties:

      • Check for the entry org.opennms.rrd.storeByGroup whether storeByGroup is enabled.

      • Check for the entry rrd.base.dir for the location where Rrd or Jrb files are stored.

      • Check for the entry rrd.binary for the location of the RRDTool binary.

    2. File etc/rrd-configuration.properties:

      • Check for the entry org.opennms.rrd.strategyClass whether JRobinRrdStrategy (JRobin) or JniRrdStrategy / MultithreadedJniRrdStrategy (RRDTool) is used.

  2. Stop your OpenNMS Horizon instance.

  3. Reconfigure OpenNMS Horizon to persist data to Newts - so, when correctly configured all new samples will be persisted into Newts after OpenNMS Horizon is started. Note, that the converter assumes storeByForeignSource to be enabled.

  4. Start your OpenNMS Horizon instance.

  5. Use the newts-repository-converter utility to convert the existing data to Newts by specifying the options that correspond to the information gathered during step #1.

This procedure will minimize the data collection gap to the time needed to reconfigure OpenNMS Horizon for Newts storage.

The newts_converter utility needs the path to the base directory of your OpenNMS Horizon instance for reading the configuration files. For instance the utility needs the datasource configuration during the migration process to query the database to lookup node data.

1.3.2. Usage

The utility is installed by default and its wrapper script is located in the ${OPENNMS_HOME}/bin directory.

$ cd /path/to/opennms/bin
$ ./newts-repository-converter
When invoked without parameters the usage and help information is printed.

The newts-repository-converter tool provide the following options and parameters:

Short-option Long-option Description Default

h

help

Prints help and usage information

false

o

onms-home

OpenNMS Horizon Home Directory

/opt/opennms

r

rrd-dir

The path to the RRD data

ONMS-HOME/share/rrd

t

rrd-tool

Whether to use rrdtool or JRobin

T

rrd-binary

The binary path to the rrdtool command (only used if rrd-tool is set)

/usr/bin/rrdtool

s

store-by-group

Whether store by group was enabled or not

n

threads

Number of conversion threads

defaults to number of CPUs

1.3.3. Example 1: convert Rrd-based data with storeByGroup enabled

The following example shows how to convert RRDTool-based data that was stored with storeByGroup enabled. The OpenNMS Horizon home is /opt/opennms, the data directory is /opt/opennms/share/rrd and the RRDTool binary located at /usr/local/bin/rrdtool. This program call will use 16 concurrent threads to convert the Rrd files.

$ ./newts-repository-converter -t true -s true -T /usr/local/bin/rrdtool -n 16
<output omitted>

1.3.4. Example 2: convert JRobin-based data with storeByGroup disabled

The following example shows how to convert JRobin-based data located in the directory /mnt/opennms/rrd that was collected with storeByGroup disabled. This program call will use 8 concurrent threads to convert the Jrb files.

$ ./newts-repository-converter -t false -s false -r /mnt/opennms/rrd -n 8
<output omitted>

1.3.5. Stress Testing

The metrics:stress Karaf Shell command can be used to simulate load on the active persistence strategy, whether it be RRDtool, JRobin, or Newts.

The tool works by generating collection sets, similar to those built when performing data collection, and sending these to the active persistence layer. By using the active persistence layer, we ensure that we use the same write path which is used by the actual data collection services.

Generate samples for 10 nodes every 15 seconds and printing the statistic report every 30 seconds:

metrics:stress -n 10 -i 15 -r 30

While active, the command will continue to generate and persist collection sets. During this time you can monitor the system I/O and other relevant statistics.

When your done, use CTRL+C to stop the stress tool.

A complete list of options is available using:

metrics:stress --help

1.3.6. Interpreting the output

The statistics output by the tool can be be interpreted as follows:

numeric-attributes-generated

The number of numeric attributes that were sent to the persistence layer. We have no guarantee as to whether or not these were actually persisted.

string-attributes-generated

The number of string attributes that were sent to the persistence layer. We have no guarantee as to whether or not these were actually persisted.

batches

The count is used to indicate how many batches of collection sets (one at every interval) were sent to the persistence layer. The timers show how much time was spent generating the batch, and sending the batch to the persistence layer.

2. Daemon Configuration Files

2.1. Eventd

Internal Daemon Name Reload Event

Eventd

uei.opennms.org/internal/reloadDaemonConfig -p 'daemonName Eventd'

Table 1. Eventd configuration file overview
File Restart Required Reload Event Description

eventd-configuration.xml

yes

no

Configure generic behavior of Eventd, i.e. TCP and UDP port numbers with IP addresses to listen for Events and socket timeouts.

eventconf.xml

no

yes

Main configuration file for Eventd.

events/*

no

yes

Out-of-the-box, all files in this folder are included via include directives in eventconf.xml.

2.2. Notifd

Internal Daemon Name Reload Event

Notifd

uei.opennms.org/internal/reloadDaemonConfig -p 'daemonName Notifd'

Table 2. Notifd configuration file overview
File Restart Required Reload Event Description

notifd-configuration.xml

no

yes

Describes auto-acknowledge prefix, e.g. prefix "RESOLVED: " for nodeUp/nodeDown events.

notificationCommands.xml

no

no

Configuration for notification media, e.g. scripts, XMPP or HTTP Post, immediately applied.

notifications.xml

no

no

Event notification definitions and changes are immediately applied.

destinationPaths.xml

no

no

Contains paths for notification targets, e.g. JavaMail, XMPP or external scripts.

users.xml

no

no

Contain pager and address information for notification destination paths.

groups.xml

no

no

Groups can be used as target for notifications.

javamail-configuration.properties

no

no

Configuration to send notification mails via specific mail servers.

2.3. Pollerd

Internal Daemon Name Reload Event

Pollerd

uei.opennms.org/internal/reloadDaemonConfig -p 'daemonName Pollerd'

Table 3. Pollerd configuration file overview
File Restart Required Reload Event Description

poller-configuration.xml

yes

yes

Restart is required in case new monitors are created or removed. Reload Event loads changed configuration parameters of existing monitors.

response-graph.properties

no

no

Graph definition for response time graphs from monitors

poll-outages.xml

no

yes

Can be reloaded with uei.opennms.org/internal/schedOutagesChanged

3. Event Sources

3.1. SNMP Traps

If SNMP-capable devices in the network are configured to send traps to OpenNMS Horizon, these traps are transformed into events according to pre-configured rules. The Trapd service daemon, which enables OpenNMS Horizon to receive SNMP traps, is enabled by default.

Disabling the Trapd service daemon will render OpenNMS Horizon incapable of receiving SNMP traps.

Event definitions are included with OpenNMS Horizon for traps from many vendors' equipment.

3.2. Syslog Messages

Syslog messages sent over the network to OpenNMS Horizon can be transformed into events according to pre-configured rules.

The Syslogd service daemon, which enables OpenNMS Horizon to receive syslog messages over the network, must be enabled for this functionality to work. This service daemon is disabled by default.

3.2.1. Parsers

Different parsers can be used to convert the syslog message fields into OpenNMS Horizon event fields.

Parser Description

org.opennms.netmgt.syslogd.CustomSyslogParser

Default parser that uses a regex statement to parse the syslog header.

org.opennms.netmgt.syslogd.RadixTreeSyslogParser

Parser that uses an internal list of grok-style statements to parse the syslog header.

org.opennms.netmgt.syslogd.SyslogNGParser

Parser that strictly parses messages in the default pattern of syslog-ng.

org.opennms.netmgt.syslogd.Rfc5424SyslogParser

Parser that strictly parses the RFC 5424 format for syslog messages.

RadixTreeSyslogParser

The RadixTreeSyslogParser normally uses a set of internally-defined patterns to parse multiple syslog message formats. If you wish to customize the set of patterns, you can put a new set of patterns into a syslog-grok-patterns.txt in the etc directory for OpenNMS Horizon.

The patterns are defined in grok-style statements where each token is defined by a %{PATTERN:semantic} clause. Whitespace in the pattern will match 0…​n whitespace characters and character literals in the pattern will match the corresponding characters. The '%' character literal must be escaped by using a backslash, ie. '\%'.

The RadixTreeSyslogParser’s grok implementation only supports a limited number of pattern types. However, these patterns should be sufficient to parse any syslog message format.

The patterns should be arranged in the file from most specific to least specific since the first pattern to successfully match the syslog message will be used to construct the OpenNMS Horizon event.

Pattern Description

INT

Positive integer.

MONTH

3-character English month abbreviation.

NOSPACE

String that contains no whitespace.

STRING

String. Because this matches any character, it must be followed by a delimiter in the pattern string.

Semantic Token Description

day

2-digit day of month (1-31).

facilityPriority

Facility-priority integer.

hostname

String hostname (unqualified or FQDN), IPv4 address, or IPv6 address.

hour

2-digit hour of day (0-23).

message

Remaining string message.

messageId

String message ID.

minute

2-digit minute (0-59).

month

2-digit month (1-12).

processId

String process ID.

processName

String process name.

second

2-digit second (0-59).

secondFraction

1- to 6-digit fractional second value as a string.

timezone

String timezone value.

version

Version.

year

4-digit year.

3.3. XML-TCP

Any application or script can create custom events in OpenNMS Horizon by sending properly-formatted XML data over a TCP socket.

3.4. IBM Tivoli EIF Events

OpenNMS can be configured to receive Events sent using the Tivoli Event Integration Facility(EIF). These EIF events are translated into OpenNMS events using preconfigured rules. The resulting UEI are anchored in the uei.opennms.org/vendor/IBM/EIF/ namespace, with the name of the EIF event class appended.

A sample event configuration for the OMEGAMON_BASE class is included with OpenNMS.

3.4.1. Configuring the EIF Adapter

Once OpenNMS is started and the Karaf shell is accessible, you can install the EIF Adapter feature and configure it to listen on a specific interface and port.

By default the EIF Adapter is configured to listen on TCP port 1828 on all interfaces.
OSGi login, installation, and configuration of the EIF Adapter
[root@localhost /root]# $ ssh -p 8101 admin@localhost
...
opennms> feature:install eif-adapter
opennms> config:edit org.opennms.features.eifadapter
opennms> config:property-set interface 0.0.0.0
opennms> config:property-set port 1828
opennms> config:update

You can check the routes status with the camel:* commands and/or inspect the log with log:tail for any obvious errors. The feature has a debug level logging that can be used to debug operations.

Documentation on using the OSGi console embedded in OpenNMS and the related camel commands.
Features installed through the Karaf shell persist only as long as the ${OPENNMS_HOME}/data directory remains intact. To enable the feature more permanently, add it to the featuresBoot list in ${OPENNMS_HOME}/etc/org.apache.karaf.features.cfg.

You should now be able to configure your EIF forwarders to send to this destination, and their events will be translated into OpenNMS Events and written to the event bus.

3.4.2. Troubleshooting

If events are not reaching OpenNMS, check whether the event source (EIF Forwarder) is correctly configured. Check your event destination configuration. In particular review the HOSTNAME and PORT parameters. Also check that your situations are configured to forward to that EIF destination.

If those appear to be correct verify that the EIF Forwarder can communicate with OpenNMS over the configured port (default 1828).

Review the OSGi log with log:tail or the camel:* commands.

3.5. TL1 Autonomous Messages

Autonomous messages can be retrieved from certain TL1-enabled equipment and transformed into events.

The Tl1d service daemon, which enables OpenNMS Horizon to receive TL1 autonomous messages, must be enabled for this functionality to work. This service daemon is disabled by default.

4. Service monitors

4.1. AvailabilityMonitor

This monitor tests reachability of a node by using the isReachable method of the InetAddress java class. The service is considered available if isReachable returns true. See Oracle’s documentation for more details.

This monitor is deprecated in favour of the IcmpMonitor monitor. You should only use this monitor on remote pollers running on unusual configurations (See below for more details).

4.1.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.AvailabilityMonitor

Remote Enabled

true

4.1.2. Configuration and Usage

This monitor implements the Common Configuration Parameters.

4.1.3. Examples

<service name="AVAIL" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="2"/>
  <parameter key="timeout" value="5000"/>
</service>

<monitor service="AVAIL" class-name="org.opennms.netmgt.poller.monitors.AvailabilityMonitor"/>

4.1.4. IcmpMonitor vs AvailabilityMonitor

This monitor has been developped in a time when the IcmpMonitor monitor wasn’t remote enabled, to circumvent this limitation. Now, with the JNA ICMP implementation, the IcmpMonitor monitor is remote enabled under most configurations and this monitor shouldn’t be needed -unless you’re running your remote poller on such an unusual configuration (See also issue NMS-6735 for more information)-.

4.2. BgpSessionMonitor

This monitor checks if a BGP-Session to a peering partner (peer-ip) is functional. To monitor the BGP-Session the RFC1269 SNMP MIB is used and test the status of the session using the following OIDs is used:

BGP_PEER_STATE_OID = .1.3.6.1.2.1.15.3.1.2.<peer-ip>
BGP_PEER_ADMIN_STATE_OID = .1.3.6.1.2.1.15.3.1.3.<peer-ip>
BGP_PEER_REMOTEAS_OID = .1.3.6.1.2.1.15.3.1.9.<peer-ip>
BGP_PEER_LAST_ERROR_OID = .1.3.6.1.2.1.15.3.1.14.<peer-ip>
BGP_PEER_FSM_EST_TIME_OID = .1.3.6.1.2.1.15.3.1.16.<peer-ip>

The <peer-ip> is the far end IP address of the BGP session end point.

A SNMP get request for BGP_PEER_STATE_OID returns a result between 1 to 6. The servicestates for OpenNMS Horizon are mapped as follows:

Result State description Monitor state in OpenNMS Horizon

1

Idle

DOWN

2

Connect

DOWN

3

Active

DOWN

4

OpenSent

DOWN

5

OpenConfirm

DOWN

6

Established

UP

4.2.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.BgpSessionMonitor

Remote Enabled

false

To define the mapping I used the description from RFC1771 BGP Finite State Machine.

4.2.2. Configuration and Usage

Parameter Description Required Default value

bgpPeerIp

IP address of the far end BGP peer session

required

-

This monitor implements the Common Configuration Parameters.

4.2.3. Examples

To monitor the session state Established it is necessary to add a service to your poller configuration in '$OPENNMS_HOME/etc/poller-configuration.xml', for example:

<!-- Example configuration poller-configuration.xml -->
<service name="BGP-Peer-99.99.99.99-AS65423" interval="300000"
         user-defined="false" status="on">
    <parameter key="retry" value="2" />
    <parameter key="timeout" value="3000" />
    <parameter key="port" value="161" />
    <parameter key="bgpPeerIp" value="99.99.99.99" />
</service>

<monitor service="BGP-Peer-99.99.99.99-AS65423" class-name="org.opennms.netmgt.poller.monitors.BgpSessionMonitor" />

4.2.4. Error code mapping

The BGP_PEER_LAST_ERROR_OID gives an error in HEX-code. To make it human readable a codemapping table is implemented:

Error code Error Message

0100

Message Header Error

0101

Message Header Error - Connection Not Synchronized

0102

Message Header Error - Bad Message Length

0103

Message Header Error - Bad Message Type

0200

OPEN Message Error

0201

OPEN Message Error - Unsupported Version Number

0202

OPEN Message Error - Bad Peer AS

0203

OPEN Message Error - Bad BGP Identifier

0204

OPEN Message Error - Unsupported Optional Parameter

0205

OPEN Message Error (deprecated)

0206

OPEN Message Error - Unacceptable Hold Time

0300

UPDATE Message Error

0301

UPDATE Message Error - Malformed Attribute List

0302

UPDATE Message Error - Unrecognized Well-known Attribute

0303

UPDATE Message Error - Missing Well-known Attribute

0304

UPDATE Message Error - Attribute Flags Error

0305

UPDATE Message Error - Attribute Length Error

0306

UPDATE Message Error - Invalid ORIGIN Attribute

0307

UPDATE Message Error (deprecated)

0308

UPDATE Message Error - Invalid NEXT_HOP Attribute

0309

UPDATE Message Error - Optional Attribute Error

030A

UPDATE Message Error - Invalid Network Field

030B

UPDATE Message Error - Malformed AS_PATH

0400

Hold Timer Expired

0500

Finite State Machine Error

0600

Cease

0601

Cease - Maximum Number of Prefixes Reached

0602

Cease - Administrative Shutdown

0603

Cease - Peer De-configured

0604

Cease - Administrative Reset

0605

Cease - Connection Rejected

0606

Cease - Other Configuration Change

0607

Cease - Connection Collision Resolution

0608

Cease - Out of Resources

Instead of HEX-Code the error message will be displayed in the service down logmessage. To give some additional informations the logmessage contains also

BGP-Peer Adminstate
BGP-Peer Remote AS
BGP-Peer established time in seconds

4.2.5. Debugging

If you have problems to detect or monitor the BGP Session you can use the following command to figure out where the problem come from.

snmpwalk -v 2c -c <myCommunity> <myRouter2Monitor> .1.3.6.1.2.1.15.3.1.2.99.99.99.99

Replace 99.99.99.99 with your BGP-Peer IP. The result should be an Integer between 1 and 6.

4.3. BSFMonitor

This monitor runs a Bean Scripting Framework BSF compatible script to determine the status of a service. Users can write scripts to perform highly custom service checks. This monitor is not optimised for scale. It’s intended for a small number of custom checks or prototyping of monitors.

4.3.1. BSFMonitor vs SystemExecuteMonitor

The BSFMonitor avoids the overhead of fork(2) that is used by the SystemExecuteMonitor. BSFMonitor also grants access to a selection of OpenNMS Horizon internal methods and classes that can be used in the script.

4.3.2. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.BSFMonitor

Remote Enabled

false

4.3.3. Configuration and Usage

Table 4. Monitor specific parameters for the BSFMonitor
Parameter Description Required Default value

file-name

Path to the script file.

required

-

bsf-engine

The BSF Engine to run the script in different languages like
Bean Shell: bsh.util.BeanShellBSFEngine
Groovy: org.codehaus.groovy.bsf.GroovyEngine
Jython: org.apache.bsf.engines.jython.JythonEngine

required

-

run-type

one of eval or exec

optional

eval

lang-class

The BSF language class, like groovy or beanshell.

optional

file-name extension is interpreted by default

file-extensions

comma-separated list

optional

-

This monitor implements the Common Configuration Parameters.

Table 5. Beans which can be used in the script
Variable Type Description

map

Map<String, Object>

The map contains all various parameters passed to the monitor from the service definition it the poller-configuration.xml file.

ip_addr

String

The IP address that is currently being polled.

node_id

int

The Node ID of the node the ip_addr belongs to.

node_label

String

The Node Label of the node the ip_addr and service belongs to.

svc_name

String

The name of the service that is being polled.

bsf_monitor

BSFMonitor

The instance of the BSFMonitor object calling the script. Useful for logging via its log(String sev, String fmt, Object... args) method.

results

HashMap<String, String>

The script is expected to put its results into this object. The status indication should be set into the entry with key status. If the status is not OK, a key reason should contain a description of the problem.

times

LinkedHashMap<String, Number>

The script is expected to put one or more response times into this object.

Additionally every parameter added to the service definition in poller-configuration.xml is available as a String object in the script. The key attribute of the parameter represents the name of the String object and the value attribute represents the value of the String object.

Please keep in mind, that these parameters are also accessible via the map bean.
Avoid non-character names for parameters to avoid problems in the script languages.

4.3.4. Response Codes

The script has to provide a status code that represents the status of the associated service. The following status codes are defined:

Table 6. Status codes
Code Description

OK

Service is available

UNK

Service status unknown

UNR

Service is unresponsive

NOK

Service is unavailable

4.3.5. Response time tracking

By default the BSFMonitor tracks the whole time the script file consumes as the response time. If the response time should be persisted the response time add the following parameters:

RRD response time tracking for this service in poller-configuration.xml
<!-- where in the filesystem response times are stored -->
<parameter key="rrd-repository" value="/opt/opennms/share/rrd/response" />

<!-- name of the rrd file -->
<parameter key="rrd-base-name" value="minimalbshbase" />

<!-- name of the data source in the rrd file -->
<!-- by default "response-time" is used as ds-name -->
<parameter key="ds-name" value="myResponseTime" />

It is also possible to return one or many response times directly from the script. To add custom response times or override the default one, add entries to the times object. The entries are keyed with a String that names the datasource and have as values a number that represents the response time. To override the default response time datasource add an entry into times named response-time.

4.3.6. Timeout and Retry

The BSFMonitor does not perform any timeout or retry processing on its own. If retry and or timeout behaviour is required, it has to be implemented in the script itself.

4.3.7. Requirements for the script (run-types)

Depending on the run-type the script has to provide its results in different ways. For minimal scripts with very simple logic run-type eval is the simple option. Scripts running in eval mode have to return a String matching one of the status codes.

If your script is more than a one-liner, run-type exec is essentially required. Scripts running in exec mode need not return anything, but they have to add a status entry with a status code to the results object. Additionally, the results object can also carry a "reason":"message" entry that is used in non OK states.

4.3.8. Commonly used language settings

The BSF supports many languages, the following table provides the required setup for commonly used languages.

Table 7. BSF language setups
Language lang-class bsf-engine required library

BeanShell

beanshell

bsh.util.BeanShellBSFEngine

supported by default

Groovy

groovy

org.codehaus.groovy.bsf.GroovyEngine

groovy-all-[version].jar

Jython

jython

org.apache.bsf.engines.jython.JythonEngine

jython-[version].jar

4.3.9. Example Bean Shell

BeanShell example poller-configuration.xml
<service name="MinimalBeanShell" interval="300000" user-defined="true" status="on">
  <parameter key="file-name"  value="/tmp/MinimalBeanShell.bsh"/>
  <parameter key="bsf-engine" value="bsh.util.BeanShellBSFEngine"/>
</service>

<monitor service="MinimalBeanShell" class-name="org.opennms.netmgt.poller.monitors.BSFMonitor" />
BeanShell example MinimalBeanShell.bsh script file
bsf_monitor.log("ERROR", "Starting MinimalBeanShell.bsf", null);
File testFile = new File("/tmp/TestFile");
if (testFile.exists()) {
  return "OK";
} else {
  results.put("reason", "file does not exist");
  return "NOK";
}

4.3.10. Example Groovy

To use the Groovy language an additional library is required. Copy a compatible groovy-all.jar into to opennms/lib folder and restart OpenNMS Horizon. That makes Groovy available for the BSFMonitor.

Groovy example poller-configuration.xml with default run-type set to eval
<service name="MinimalGroovy" interval="300000" user-defined="true" status="on">
  <parameter key="file-name"  value="/tmp/MinimalGroovy.groovy"/>
  <parameter key="bsf-engine" value="org.codehaus.groovy.bsf.GroovyEngine"/>
</service>

<monitor service="MinimalGroovy" class-name="org.opennms.netmgt.poller.monitors.BSFMonitor" />
Groovy example MinimalGroovy.groovy script file for run-type eval
bsf_monitor.log("ERROR", "Starting MinimalGroovy.groovy", null);
File testFile = new File("/tmp/TestFile");
if (testFile.exists()) {
  return "OK";
} else {
  results.put("reason", "file does not exist");
  return "NOK";
}
Groovy example poller-configuration.xml with run-type set to exec
<service name="MinimalGroovy" interval="300000" user-defined="true" status="on">
  <parameter key="file-name"  value="/tmp/MinimalGroovy.groovy"/>
  <parameter key="bsf-engine" value="org.codehaus.groovy.bsf.GroovyEngine"/>
  <parameter key="run-type" value="exec"/>
</service>

<monitor service="MinimalGroovy" class-name="org.opennms.netmgt.poller.monitors.BSFMonitor" />
Groovy example MinimalGroovy.groovy script file for run-type set to exec
bsf_monitor.log("ERROR", "Starting MinimalGroovy", null);
def testFile = new File("/tmp/TestFile");
if (testFile.exists()) {
  results.put("status", "OK")
} else {
  results.put("reason", "file does not exist");
  results.put("status", "NOK");
}

4.3.11. Example Jython

To use the Jython (Java implementation of Python) language an additional library is required. Copy a compatible jython-x.y.z.jar into the opennms/lib folder and restart OpenNMS Horizon. That makes Jython available for the BSFMonitor.

Jython example poller-configuration.xml with run-type exec
<service name="MinimalJython" interval="300000" user-defined="true" status="on">
  <parameter key="file-name"  value="/tmp/MinimalJython.py"/>
  <parameter key="bsf-engine" value="org.apache.bsf.engines.jython.JythonEngine"/>
  <parameter key="run-type" value="exec"/>
</service>

<monitor service="MinimalJython" class-name="org.opennms.netmgt.poller.monitors.BSFMonitor" />
Jython example MinimalJython.py script file for run-type set to exec
from java.io import File

bsf_monitor.log("ERROR", "Starting MinimalJython.py", None);
if (File("/tmp/TestFile").exists()):
        results.put("status", "OK")
else:
        results.put("reason", "file does not exist")
        results.put("status", "NOK")
We have to use run-type exec here because Jython chokes on the import keyword in eval mode.
As profit that this is really Python, notice the substitution of Python’s None value for Java’s null in the log call.

4.3.12. Advanced examples

The following example references all beans that are exposed to the script, including a custom parameter.

Groovy example poller-configuration.xml
<service name="MinimalGroovy" interval="30000" user-defined="true" status="on">
  <parameter key="file-name"  value="/tmp/MinimalGroovy.groovy"/>
  <parameter key="bsf-engine" value="org.codehaus.groovy.bsf.GroovyEngine"/>

  <!-- custom parameters (passed to the script) -->
  <parameter key="myParameter" value="Hello Groovy" />

  <!-- optional for response time tracking -->
  <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response" />
  <parameter key="rrd-base-name" value="minimalgroovybase" />
  <parameter key="ds-name" value="minimalgroovyds" />
</service>

<monitor service="MinimalGroovy" class-name="org.opennms.netmgt.poller.monitors.BSFMonitor" />
Groovy example Bean referencing script file
bsf_monitor.log("ERROR", "Starting MinimalGroovy", null);

//list of all available objects from the BSFMonitor
Map<String, Object> map = map;
bsf_monitor.log("ERROR", "---- map ----", null);
bsf_monitor.log("ERROR", map.toString(), null);

String ip_addr = ip_addr;
bsf_monitor.log("ERROR", "---- ip_addr ----", null);
bsf_monitor.log("ERROR", ip_addr, null);

int node_id = node_id;
bsf_monitor.log("ERROR", "---- node_id ----", null);
bsf_monitor.log("ERROR", node_id.toString(), null);

String node_label = node_label;
bsf_monitor.log("ERROR", "---- node_label ----", null);
bsf_monitor.log("ERROR", node_label, null);

String svc_name = svc_name;
bsf_monitor.log("ERROR", "---- svc_name ----", null);
bsf_monitor.log("ERROR", svc_name, null);

org.opennms.netmgt.poller.monitors.BSFMonitor bsf_monitor = bsf_monitor;
bsf_monitor.log("ERROR", "---- bsf_monitor ----", null);
bsf_monitor.log("ERROR", bsf_monitor.toString(), null);

HashMap<String, String> results = results;
bsf_monitor.log("ERROR", "---- results ----", null);
bsf_monitor.log("ERROR", results.toString(), null);

LinkedHashMap<String, Number> times = times;
bsf_monitor.log("ERROR", "---- times ----", null);
bsf_monitor.log("ERROR", times.toString(), null);

// reading a parameter from the service definition
String myParameter = myParameter;
bsf_monitor.log("ERROR", "---- myParameter ----", null);
bsf_monitor.log("ERROR", myParameter, null);

// minimal example
def testFile = new File("/tmp/TestFile");
if (testFile.exists()) {
  bsf_monitor.log("ERROR", "Done MinimalGroovy ---- OK ----", null);
  return "OK";
} else {

  results.put("reason", "file does not exist");
  bsf_monitor.log("ERROR", "Done MinimalGroovy ---- NOK ----", null);
  return "NOK";
}

4.4. CiscoIpSlaMonitor

This monitor can be used to monitor IP SLA configurations on your Cisco devices. This monitor supports the following SNMP OIDS from CISCO-RTT-MON-MIB:

RTT_ADMIN_TAG_OID = .1.3.6.1.4.1.9.9.42.1.2.1.1.3
RTT_OPER_STATE_OID = .1.3.6.1.4.1.9.9.42.1.2.9.1.10
RTT_LATEST_OPERSENSE_OID = .1.3.6.1.4.1.9.9.42.1.2.10.1.2
RTT_ADMIN_THRESH_OID = .1.3.6.1.4.1.9.9.42.1.2.1.1.5
RTT_ADMIN_TYPE_OID = .1.3.6.1.4.1.9.9.42.1.2.1.1.4
RTT_LATEST_OID = .1.3.6.1.4.1.9.9.42.1.2.10.1.1

The monitor can be run in two scenarios. The first one tests the RTT_LATEST_OPERSENSE which is a sense code for the completion status of the latest RTT operation. If the RTT_LATEST_OPERSENSE returns ok(1) the service is marked as up.

The second scenario is to monitor the configured threshold in the IP SLA config. If the RTT_LATEST_OPERSENSE returns with overThreshold(3) the service is marked down.

4.4.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.CiscoIpSlaMonitor

Remote Enabled

false

4.4.2. Configuration and Usage

Table 8. Monitor-specific parameters for the CiscoIpSlaMonitor
Parameter Description Required Default value

admin-tag

The tag attribute from your IP SLA configuration you want to monitor.

required

-

ignore-thresh

Boolean indicates if just the status or configured threshold should be monitored.

required

``

This monitor implements the Common Configuration Parameters.

4.4.3. Example for HTTP and ICMP echo reply

In this example we configure an IP SLA entry to monitor Google’s website with HTTP GET from the Cisco device. We use 8.8.8.8 as our DNS resolver. In our example our SLA says we should reach Google’s website within 200ms. To advise co-workers that this monitor entry is used for monitoring, I set the owner to OpenNMS. The tag is used to identify the entry later in the SNMP table for monitoring.

Cisco device configuration for IP SLA instance for HTTP GET
ip sla monitor 1
 type http operation get url http://www.google.de name-server 8.8.8.8
 timeout 3000
 threshold 200
 owner OpenNMS
 tag Google Website
ip sla monitor schedule 3 life forever start-time now

In the second example we configure a IP SLA to test if the IP address from www.opennms.org is reachable with ICMP from the perspective of the Cisco device. Like the example above we have a threshold and a timeout.

Cisco device configuration for IP SLA instance for ICMP monitoring.
ip sla 1
 icmp-echo 64.146.64.212
 timeout 3000
 threshold 150
 owner OpenNMS
 tag OpenNMS Host
ip sla schedule 1 life forever start-time now
It´s not possible to reconfigure an IP SLA entry. If you want to change parameters, you have to delete the whole configuration and reconfigure it with your new parameters. Backup your Cisco configuration manually or take a look at RANCID.

To monitor both of the entries the configuration in poller-configuration.xml requires two service definition entries:

<service name="IP-SLA-WEB-Google" interval="300000"
  user-defined="false" status="on">
    <parameter key="retry" value="2" />
    <parameter key="timeout" value="3000" />
    <parameter key="admin-tag" value="Google Website" />
    <parameter key="ignore-thresh" value="false" />(1)
</service>
<service name="IP-SLA-PING-OpenNMS" interval="300000"
  user-defined="false" status="on">
    <parameter key="retry" value="2" />
    <parameter key="timeout" value="3000" />
    <parameter key="admin-tag" value="OpenNMS Host" />
    <parameter key="ignore-thresh" value="true" />(2)
</service>

<monitor service="IP-SLA-WEB-Google" class-name="org.opennms.netmgt.poller.monitors.CiscoIpSlaMonitor" />
<monitor service="IP-SLA-PING-OpenNMS" class-name="org.opennms.netmgt.poller.monitors.CiscoIpSlaMonitor" />
1 Service is up if the IP SLA state is ok(1)
2 Service is down if the IP SLA state is overThreshold(3)

4.5. CiscoPingMibMonitor

This poller monitor’s purpose is to create conceptual rows (entries) in the ciscoPingTable on Cisco IOS devices that support the CISCO-PING-MIB. These entries direct the remote IOS device to ping an IPv4 or IPv6 address with a configurable set of parameters. After the IOS device has completed the requested ping operations, the poller monitor queries the IOS device to determine the results. If the results indicate success according to the configured parameters in the service configuration, then the monitored service is reported as available and the results are available for optional time-series (RRD) storage. If the results indicate failure, the monitored service is reported unavailable with a descriptive reason code. If something goes wrong during the setup of the entry or the subsequent querying of its status, the monitored service is reported to be in an unknown state.

Unlike most poller monitors, the CiscoPingMibMonitor does not interpret the timeout and retries parameters to determine when a poll attempt has timed out or whether it should be attempted again. The packet-count and packet-timeout parameters instead service this purpose from the perspective of the remote IOS device.
Supported MIB OIDs from CISCO_PING_MIB
 ciscoPingEntry             1.3.6.1.4.1.9.9.16.1.1.1
 ciscoPingSerialNumber      1.3.6.1.4.1.9.9.16.1.1.1.1
 ciscoPingProtocol          1.3.6.1.4.1.9.9.16.1.1.1.2
 ciscoPingAddress           1.3.6.1.4.1.9.9.16.1.1.1.3
 ciscoPingPacketCount       1.3.6.1.4.1.9.9.16.1.1.1.4
 ciscoPingPacketSize        1.3.6.1.4.1.9.9.16.1.1.1.5
 ciscoPingPacketTimeout     1.3.6.1.4.1.9.9.16.1.1.1.6
 ciscoPingDelay             1.3.6.1.4.1.9.9.16.1.1.1.7
 ciscoPingTrapOnCompletion  1.3.6.1.4.1.9.9.16.1.1.1.8
 ciscoPingSentPackets       1.3.6.1.4.1.9.9.16.1.1.1.9
 ciscoPingReceivedPackets   1.3.6.1.4.1.9.9.16.1.1.1.10
 ciscoPingMinRtt            1.3.6.1.4.1.9.9.16.1.1.1.11
 ciscoPingAvgRtt            1.3.6.1.4.1.9.9.16.1.1.1.12
 ciscoPingMaxRtt            1.3.6.1.4.1.9.9.16.1.1.1.13
 ciscoPingCompleted         1.3.6.1.4.1.9.9.16.1.1.1.14
 ciscoPingEntryOwner        1.3.6.1.4.1.9.9.16.1.1.1.15
 ciscoPingEntryStatus       1.3.6.1.4.1.9.9.16.1.1.1.16
 ciscoPingVrfName           1.3.6.1.4.1.9.9.16.1.1.1.17

4.5.1. Prerequisites

  • One or more Cisco devices running an IOS image of recent vintage; any 12.2 or later image is probably fine. Even very low-end devices appear to support the CISCO-PING-MIB.

  • The IOS devices that will perform the remote pings must be configured with an SNMP write community string whose source address access-list includes the address of the OpenNMS Horizon server and whose MIB view (if any) includes the OID of the ciscoPingTable.

  • The corresponding SNMP write community string must be specified in the write-community attribute of either the top-level <snmp-config> element of snmp-config.xml or a <definition> child element that applies to the SNMP-primary interface of the IOS device(s) that will perform the remote pings.

4.5.2. Scalability concerns

This monitor spends a fair amount of time sleeping while it waits for the remote IOS device to complete the requested ping operations. The monitor is pessimistic in calculating the delay between creation of the ciscoPingTable entry and its first attempt to retrieve the results of that entry’s ping operations — it will always wait at least (packet-count * (packet-timeout + packet-delay)) milliseconds before even checking whether the remote pings have completed. It’s therefore prone to hogging poller threads if used with large values for the packet-count, packet-timeout, and/or packet-delay parameters. Keep these values as small as practical to avoid tying up poller threads unnecessarily.

This monitor always uses the current time in whole seconds since the UNIX epoch as the instance identifier of the ciscoPingTable entries that it creates. The object that holds this identifier is a signed 32-bit integer type, precluding a finer resolution. It’s probably a good idea to mix in the least-significant byte of the millisecond-accurate time as a substitute for that of the whole-second-accurate value to avoid collisions. IOS seems to clean up entries in this table within a manner of minutes after their ping operations have completed.

4.5.3. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.CiscoPingMibMonitor

Remote Enabled

false

4.5.4. Configuration and Usage

Table 9. Monitor specific parameters for the CiscoPingMibMonitor
Parameter Description Required Default value

version

SNMP protocol version (1, 2c, or 3) to use for operations performed by this service monitor. Do not use with out a very good reason to do so.

optional

from snmp-config.xml

packet-count

Number of ping packets that the remote IOS device should send.

optional

5

packet-size

Size, in bytes, of each ping packet that the remote IOS device should send.

optional

100

packet-timeout

Timeout, in milliseconds, of each ping packet sent by the remote IOS device.

optional

2000

packet-delay

Delay, in milliseconds, between ping packets sent by the remote IOS device.

optional

0

entry-owner

String value to set as the value of ciscoPingEntryOwner of entries created for this service.

optional

OpenNMS CiscoPingMibMonitor

vrf-name

String value to set as the VRF (VLAN) name in whose context the remote IOS device should perform the pings for this service.

optional

empty String

proxy-node-id

Numeric database identifier of the node whose primary SNMP interface should be used as the proxy for this service. If specified along with the related proxy-node-foreign-source, proxy-node-foreign-id, and/or proxy-ip-addr, this parameter will be the effective one.

optional

-

proxy-node-foreign-source
proxy-node-foreign-id

foreign-source name and foreign-ID of the node whose primary SNMP interface should be used as the "proxy" for this service. These two parameters are corequisites. If they appear along with the related proxy-ip-addr, these parameters will be the effective ones.

optional

-

proxy-ip-addr

IP address of the interface that should be used as the proxy for this service. Effective only if none of proxy-node-id, proxy-node-foreign-source, nor proxy-node-foreign-id appears alongside this parameter. A value of ${ipaddr} will be substituted with the IP address of the interface on which the monitored service appears.

optional

-

target-ip-addr

IP address that the remote IOS device should ping. A value of ${ipaddr} will be substituted with the IP address of the interface on which the monitored service appears.

optional

-

success-percent

A whole-number percentage of pings that must succeed (from the perspective of the remote IOS device) in order for this service to be considered available. As an example, if packet-count is left at its default value of 5 but you wish the service to be considered available even if only one of those five pings is successful, then set this parameter’s value to 20.

optional

100

rrd-repository

Base directory of an RRD repository in which to store this service monitor’s response-time samples

optional

-

ds-name

Name of the RRD datasource (DS) name in which to store this service monitor’s response-time samples; rrd-base-name Base name of the RRD file (minus the .rrd or .jrb file extension) within the specified rrd-repository path in which this service monitor’s response-time samples will be persisted

optional

-

This monitor implements the Common Configuration Parameters.

This is optional just if you can use variables in the configuration.

Table 10. Variables which can be used in the configuration
Variable Description

${ipaddr}

This value will be substituted with the IP address of the interface on which the monitored service appears.

4.5.5. Example: Ping the same non-routable address from all routers of customer Foo

A service provider’s client, Foo Corporation, has network service at multiple locations. At each Foo location, a point-of-sale system is statically configured at IPv4 address 192.168.255.1. Foo wants to be notified any time a point-of-sale system becomes unreachable. Using an OpenNMS Horizon remote location monitor is not feasible. All of Foo Corporation’s CPE routers must be Cisco IOS devices in order to achieve full coverage in this scenario.

One approach to this requirement is to configure all of Foo Corporation’s premise routers to be in the surveillance categories Customer_Foo, CPE, and Routers, and to use a filter to create a poller package that applies only to those routers. We will use the special value ${ipaddr} for the proxy-ip-addr parameter so that the remote pings will be provisioned on each Foo CPE router. Since we want each Foo CPE router to ping the same IP address 192.168.255.1, we statically list that value for the target-ip-addr address.

<package name="ciscoping-foo-pos">
  <filter>catincCustomer_Foo & catincCPE & catincRouters & nodeSysOID LIKE '.1.3.6.1.4.1.9.%'</filter>
  <include-range begin="0.0.0.0" end="254.254.254.254" />
  <rrd step="300">
    <rra>RRA:AVERAGE:0.5:1:2016</rra>
    <rra>RRA:AVERAGE:0.5:12:1488</rra>
    <rra>RRA:AVERAGE:0.5:288:366</rra>
    <rra>RRA:MAX:0.5:288:366</rra>
    <rra>RRA:MIN:0.5:288:366</rra>
  </rrd>
  <service name="FooPOS" interval="300000" user-defined="false" status="on">
    <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response" />
    <parameter key="rrd-base-name" value="ciscoping" />
    <parameter key="ds-name" value="ciscoping" />
    <parameter key="proxy-ip-addr" value="${ipaddr}" />
    <parameter key="target-ip-addr" value="192.168.255.1" />
  </service>
  <downtime interval="30000" begin="0" end="300000" /><!-- 30s, 0, 5m -->
  <downtime interval="300000" begin="300000" end="43200000" /><!-- 5m, 5m, 12h -->
  <downtime interval="600000" begin="43200000" end="432000000" /><!-- 10m, 12h, 5d -->
  <downtime begin="432000000" delete="true" /><!-- anything after 5 days delete -->
</package>

<monitor service="FooPOS" class-name="org.opennms.netmgt.poller.monitors.CiscoPingMibMonitor" />

4.5.6. Example: Ping from a single IOS device routable address of each router of customer Bar

A service provider’s client, Bar Limited, has network service at multiple locations. While OpenNMS Horizon' world-class service assurance is generally sufficient, Bar also wants to be notified any time a premise router at one of their locations unreachable from the perspective of an IOS device in Bar’s main data center. Some or all of the Bar Limited CPE routers may be non-Cisco devices in this scenario.

To meet this requirement, our approach is to configure Bar Limited’s premise routers to be in the surveillance categories Customer_Bar, CPE, and Routers, and to use a filter to create a poller package that applies only to those routers. This time, though, we will use the special value ${ipaddr} not in the proxy-ip-addr parameter but in the target-ip-addr parameter so that the remote pings will be performed for each Bar CPE router. Since we want the same IOS device 20.11.5.11 to ping the CPE routers, we statically list that value for the proxy-ip-addr address. Example poller-configuration.xml additions

<package name="ciscoping-bar-cpe">
  <filter>catincCustomer_Bar & catincCPE & catincRouters</filter>
  <include-range begin="0.0.0.0" end="254.254.254.254" />
  <rrd step="300">
    <rra>RRA:AVERAGE:0.5:1:2016</rra>
    <rra>RRA:AVERAGE:0.5:12:1488</rra>
    <rra>RRA:AVERAGE:0.5:288:366</rra>
    <rra>RRA:MAX:0.5:288:366</rra>
    <rra>RRA:MIN:0.5:288:366</rra>
  </rrd>
  <service name="BarCentral" interval="300000" user-defined="false" status="on">
    <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response" />
    <parameter key="rrd-base-name" value="ciscoping" />
    <parameter key="ds-name" value="ciscoping" />
    <parameter key="proxy-ip-addr" value="20.11.5.11" />
    <parameter key="target-ip-addr" value="${ipaddr}" />
  </service>
  <downtime interval="30000" begin="0" end="300000" /><!-- 30s, 0, 5m -->
  <downtime interval="300000" begin="300000" end="43200000" /><!-- 5m, 5m, 12h -->
  <downtime interval="600000" begin="43200000" end="432000000" /><!-- 10m, 12h, 5d -->
  <downtime begin="432000000" delete="true" /><!-- anything after 5 days delete -->
</package>

<monitor service="BarCentral" class-name="org.opennms.netmgt.poller.monitors.CiscoPingMibMonitor" />

4.6. CitrixMonitor

This monitor is used to test if a Citrix® Server or XenApp Server® is providing the Independent Computing Architecture (ICA) protocol on TCP 1494. The monitor opens a TCP socket and tests the greeting banner returns with ICA, otherwise the service is unavailable.

4.6.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.CitrixMonitor

Remote Enabled

true

4.6.2. Configuration and Usage

Table 11. Monitor specific parameters for the CitrixMonitor
Parameter Description Required Default value

port

TCP port where the ICA protocol is listening.

optional

1494

This monitor implements the Common Configuration Parameters.

If you have configure the Metaframe Presentation Server Client using Session Reliability, the TCP port is 2598 instead of 1494. You can find additional information on CTX104147. It is not verified if the monitor works in this case.

4.6.3. Examples

The following example configures OpenNMS Horizon to monitor the ICA protocol on TCP 1494 with 2 retries and waiting 5 seconds for each retry.

<service name="Citrix-TCP-ICA" interval="300000" user-defined="false" status="on">
    <parameter key="retry" value="2" />
    <parameter key="timeout" value="5000" />
</service>

<monitor service="Citrix-TCP-ICA" class-name="org.opennms.netmgt.poller.monitors.CitrixMonitor" />

4.7. DhcpMonitor

This monitor is used to monitor the availability and functionality of DHCP servers. This monitor has two parts, the first one is the monitor class DhcpMonitor executed by Pollerd and the second part is a background daemon Dhcpd running inside the OpenNMS Horizon JVM and listening for DHCP responses. A DHCP server is tested by sending a DISCOVER message. If the DHCP server responds with an OFFER the service is marked as up. The Dhcpd background daemon is disabled by default and has to be activated in service-configuration.xml in OpenNMS Horizon by setting service enabled="true". The behavior for testing the DHCP server can be modified in the dhcp-configuration.xml configuration file.

It is required to install the opennms-plugin-protocol-dhcp before you can use this feature.
Installing the opennms-plugin-protocol-dhcp package
{apt-get,yum} install {opennms-package-base-name}-plugin-protocol-dhcp

If you try to start OpenNMS Horizon without the opennms-plugin-protocol-dhcp you will see the following error message in output.log:

An error occurred while attempting to start the "OpenNMS:Name=Dhcpd" service (class org.opennms.netmgt.dhcpd.jmx.Dhcpd).  Shutting down and exiting.
java.lang.ClassNotFoundException: org.opennms.netmgt.dhcpd.jmx.Dhcpd
Make sure no DHCP client is running on the OpenNMS Horizon server and using port UDP/68. If UDP/68 is already in use, you will find an error message in the manager.log. You can test if a process is listening on udp/68 with sudo ss -lnpu sport = :68.

4.7.1. Monitor facts

Class Name

org.opennms.protocols.dhcp.monitor.DhcpMonitor

Remote Enabled

false

Table 12. Service monitor parameters configured in poller-configuration.xml
Parameter Description Required Default value

retry

Number of retries before the service is marked as down

optional

0

rrd-repository

The location to write RRD data. Generally, you will not want to change this from default

optional

$OPENNMS_HOME/share/rrd/response

rrd-base-name

The name of the RRD file to write (minus the extension, .rrd or .jrb)

optional

dhcp

ds-name

This is the name as reference for this particular data source in the RRD file

optional

dhcp

This monitor implements the Common Configuration Parameters.

4.7.2. Dhcpd configuration

Table 13. Dhcpd parameters in dhcp-configuration.xml.

Parameter

Description

Required

Default value

port

Defines the port your dhcp server is using

required

5818

macAddress

The MAC address which OpenNMS Horizon uses for a dhcp request

required

00:06:0D:BE:9C:B2

myIpAddress

This parameter will usually be set to the IP address of the OpenNMS Horizon server, which puts the DHCP poller in relay mode as opposed to broadcast mode. In relay mode, the DHCP server being polled will unicast its responses directly back to the IP address specified by myIpAddress rather than broadcasting its responses. This allows DHCP servers to be polled even though they are not on the same subnet as the OpenNMS Horizon server, and without the aid of an external relay. Usage: myIpAddress="10.11.12.13" or myIpAddress="broadcast"

required

broadcast

extendedMode

When extendedMode is false, the DHCP poller will send a DISCOVER and expect an OFFER in return. When extendedMode is true, the DHCP poller will first send a DISCOVER. If no valid response is received it will send an INFORM. If no valid response is received it will then send a REQUEST. OFFER, ACK, and NAK are all considered valid responses in extendedMode. Usage: extendedMode="true" or extendedMode="false"

required

false

requestIpAddress

This parameter only applies to REQUEST queries sent to the DHCP server when extendedMode is true. If an IP address is specified, that IP address will be requested in the query. If targetHost is specified, the DHCP server’s own IP address will be requested. Since a well-managed server will probably not respond to a request for its own IP, this parameter can also be set to targetSubnet. This is similar to targetHost except the DHCP server’s IP address is incremented or decremented by 1 to obtain an ip address that is on the same subnet. (The resulting address will not be on the same subnet if the DHCP server’s subnet is a /32 or /31. Otherwise, the algorithm used should be reliable.) Usage: requestIpAddress="10.77.88.99" or requestIpAddress="targetHost" or requestIpAddress="targetSubnet"

required

false

01 dhcp monitor messages broadcast
Figure 1. Visualization of DHCP message flow in broadcast mode
02 dhcp monitor messages unicast
Figure 2. Visualization of DHCP message flow in relay mode

4.7.3. Example testing DHCP server in the same subnet

Example configuration how to configure the monitor in the poller-configuration.xml. The monitor will try to send in maximum 3 DISCOVER messages and waits 3 seconds for the DHCP server OFFER message.

Step 1: Configure a DHCP service in poller-configuration.xml
<service name="DHCP" interval="300000" user-defined="false" status="on">
 <parameter key="retry" value="2" />
 <parameter key="timeout" value="3000" />
 <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response" />
 <parameter key="rrd-base-name" value="dhcp" />
 <parameter key="ds-name" value="dhcp" />
</service>

<monitor service="DHCP" class-name="org.opennms.protocols.dhcp.monitor.DhcpMonitor"/>
Step 2: Enable the OpenNMS Horizon Dhcpd daemon in service-configuration.xml
<service enabled="true">
  <name>OpenNMS:Name=Dhcpd</name>
  <class-name>org.opennms.netmgt.dhcpd.jmx.Dhcpd</class-name>
  <invoke method="start" pass="1" at="start"/>
  <invoke method="status" pass="0" at="status"/>
  <invoke method="stop" pass="0" at="stop"/>
</service>
Step 3: Configure Dhcpd to test a DHCP server in the same subnet as the OpenNMS Horizon server.
<DhcpdConfiguration
       port="5818"
       macAddress="00:06:0D:BE:9C:B2"
       myIpAddress="broadcast
       extendedMode="false"
       requestIpAddress="127.0.0.1">
</DhcpdConfiguration>

4.7.4. Example testing DHCP server in a different subnet in extended mode

You can use the same monitor in poller-configuration.xml as in the example above.

Configure Dhcpd to test DHCP server in a different subnet. The OFFER from the DHCP server is sent to myIpAddress.
<DhcpdConfiguration
       port="5818"
       macAddress="00:06:0D:BE:9C:B2"
       myIpAddress="10.4.1.234"
       extendedMode="true"
       requestIpAddress="targetSubnet">
</DhcpdConfiguration>
If in extendedMode, the time required to complete the poll for an unresponsive node is increased by a factor of 3. Thus it is a good idea to limit the number of retries to a small number.

4.8. DiskUsageMonitor

The DiskUsageMonitor monitor can be used to test the amount of free space available on certain storages of a node. The monitor gets information about the available free storage spaces available by inspecting the hrStorageTable of the HOST-RESOURCES-MIB. A storage’s description (as found in the corresponding hrStorageDescr object) must match the criteria specified by the disk and match-type parameters to be monitored. A storage’s available free space is calculated using the corresponding hrStorageSize and hrStorageUsed objects.

The hrStorageUsed doesn’t account for filesystem reserved blocks (i.e. for the super-user), so DiskUsageMonitor will report the service as unavailable only when the amount of free disk space is actually lower than free minus the percentage of reserved filesystem blocks.

This monitor uses SNMP to accomplish its work. Therefore systems against which it is to be used must have an SNMP agent supporting the HOST-RESOURCES-MIB installed and configured. Most modern SNMP agents, including most distributions of the Net-SNMP agent and the SNMP service that ships with Microsoft Windows, support this MIB. Out-of-box support for HOST-RESOURCES-MIB among commercial Unix operating systems may be somewhat spotty.

4.8.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.DiskUsageMonitor

Remote Enabled

false, relies on SNMP configuration.

4.8.2. Configuration and Usage

Table 14. Monitor specific parameters for the DiskUsageMonitor
Parameter Description Required Default value

disk

A pattern that a storage’s description (hrStorageDescr) must match to be taken into account.

required

-

free

The minimum amount of free space that storages matching the criteria must have available. This parameter is evaluated as a percent of the storage’s reported maximum capacity.

optional

15

match-type

The way how the pattern specified by the disk parameter must be compared to storages description Must be one of the following symbolic operators:
endswith : The disk parameter’s value is evaluated as a string that storages' description must end with;
exact : The disk parameter’s value is evaluated as a string that storages" description must exactly match;
regex : The disk parameter’s value is evaluated as a regular expression that storages' description must match;
startswith : The disk parameter’s value is evaluated as a string that storages' description must start with.
Note: Comparisons are case-sensitive

optional

exact

port

Destination port where the SNMP requests shall be sent.

optional

from snmp-config.xml

retries

Deprecated. Same as retry. Parameter retry takes precedence when both are set.

optional

from snmp-config.xml

This monitor implements the Common Configuration Parameters.

4.8.3. Examples

<!-- Make sure there's at least 5% of free space available on storages ending with "/home" -->
<service name="DiskUsage-home" interval="300000" user-defined="false" status="on">
  <parameter key="timeout" value="3000" />
  <parameter key="retry" value="2" />
  <parameter key="disk" value="/home" />
  <parameter key="match-type" value="endsWith" />
  <parameter key="free" value="5" />
</service>
<monitor service="DiskUsage-home" class-name="org.opennms.netmgt.poller.monitors.DiskUsageMonitor" />

4.8.4. DiskUsageMonitor vs thresholds

Storages' available free space can also be monitored using thresholds if you are already collecting these data.

4.9. DnsMonitor

This monitor is build to test the availability of the DNS service on remote IP interfaces. The monitor tests the service availability by sending a DNS query for A resource record types against the DNS server to test.

The monitor is marked as up if the DNS Server is able to send a valid response to the monitor. For multiple records it is possible to test if the number of responses are within a given boundary.

The monitor can be simulated with the command line tool host:

~ % host -v -t a www.google.com 8.8.8.8
Trying "www.google.com"
Using domain server:
Name: 8.8.8.8
Address: 8.8.8.8#53
Aliases:

;; ->>HEADER<<- opcode: QUERY, status: NOERROR, id: 9324
;; flags: qr rd ra; QUERY: 1, ANSWER: 5, AUTHORITY: 0, ADDITIONAL: 0

;; QUESTION SECTION:
;www.google.com.			IN	A

;; ANSWER SECTION:
www.google.com.		283	IN	A	74.125.232.17
www.google.com.		283	IN	A	74.125.232.20
www.google.com.		283	IN	A	74.125.232.19
www.google.com.		283	IN	A	74.125.232.16
www.google.com.		283	IN	A	74.125.232.18

Received 112 bytes from 8.8.8.8#53 in 41 ms

TIP: This monitor is intended for testing the availability of a DNS service. If you want to monitor the DNS resolution of some of your nodes from a client’s perspective, please use the DNSResolutionMonitor.

4.9.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.DnsMonitor

Remote Enabled

true

4.9.2. Configuration and Usage

Table 15. Monitor specific parameters for the DnsMonitor
Parameter Description Required Default value

retry

Number of retries before the service is marked as down

optional

0

timeout

Time in milliseconds to wait for the A Record response from the server

optional

5000

port

UDP Port for the DNS server

optional

53

lookup

DNS A Record for lookup test

optional

localhost

fatal-response-codes

A comma-separated list of numeric DNS response codes that will be considered fatal if present in the server’s response. Default value is 2 corresponds to Server Failed. A list of codes and their meanings is found in RFC 2929

optional

2

min-answers

Minmal number of records in the DNS server respone for the given lookup

optional

-

max-answers

Maximal number of records in the DNS server respone for the given lookup

optional

-

This monitor implements the Common Configuration Parameters.

4.9.3. Examples

The given examples shows how to monitor if the IP interface from a given DNS server resolves a DNS request. This service should be bound to a DNS server which should be able to give a valid DNS respone for DNS request www.google.com. The service is up if the DNS server gives between 1 and 10 A record responses.

Example configuration monitoring DNS request for a given server for www.google.com
<service name="DNS-www.google.com" interval="300000" user-defined="false" status="on">
    <parameter key="lookup" value="www.google.com" />
    <parameter key="fatal-response-code" value="2" />
    <parameter key="min-answers" value="1" />
    <parameter key="max-answers" value="10" />
</service>

<monitor service="DNS-www.google.com" class-name="org.opennms.netmgt.poller.monitors.DnsMonitor" />

4.10. DNSResolutionMonitor

The DNS resolution monitor, tests if the node label of an OpenNMS Horizon node can be resolved. This monitor uses the name resolver configuration from the poller configuration or from the operating system where OpenNMS Horizon is running on. It can be used to test a client behavior for a given host name. For example: Create a node with the node label www.google.com and an IP interface. Assigning the DNS resolution monitor on the IP interface will test if www.google.com can be resolved using the DNS configuration defined by the poller. The response from the A record lookup can be any address, it is not verified with the IP address on the OpenNMS Horizon IP interface where the monitor is assigned to.

4.10.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.DNSResolutionMonitor

Remote Enabled

true

4.10.2. Configuration and Usage

Table 16. Monitor specific parameters for the DNSResolutionMonitor
Parameter Description Required Default value

resolution-type

Type of record for the node label test.
Allowed values
v4 for A records,
v6 for AAAA record,
both A and AAAA record must be available,
either A or AAAA record must be available.

optional

either

record-types

Alternate DNS record types to search for.
The comma separated list can contain A,
AAAA, CNAME, NS, MX, PTR, SOA,
SRV, or TXT.

optional

``

lookup

Alternate DNS record to lookup

optional

The node label.

nameserver

The DNS server to query for the records.
The string can be in the form of hostname,
hostname:port, or [ipv6address]:port.

optional

Use name server from host system running OpenNMS Horizon

This monitor implements the Common Configuration Parameters.

4.10.3. Examples

The following example shows the possibilities monitoring IPv4 and/or IPv6 for the service configuration:

<!-- Assigned service test if the node label is resolved for an A record -->
<service name="DNS-Resolution-v4" interval="300000" user-defined="false" status="on">
    <parameter key="retry" value="2"/>
    <parameter key="timeout" value="2000"/>
    <parameter key="resolution-type" value="v4"/>
    <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
    <parameter key="rrd-base-name" value="dns-res-v4"/>
    <parameter key="ds-name" value="dns-res-v4"/>
</service>

<!-- Assigned service test if www.google.com is resolved for an A record -->
<service name="DNS-Resolution-v4-lookup" interval="300000" user-defined="false" status="on">
    <parameter key="retry" value="2"/>
    <parameter key="timeout" value="2000"/>
    <parameter key="resolution-type" value="v4"/>
    <parameter key="lookup" value="www.google.com"/>
</service>

<!-- Assigned service test if the node label is resolved for an AAAA record using a specific DNS server -->
<service name="DNS-Resolution-v6" interval="300000" user-defined="false" status="on">
    <parameter key="retry" value="2"/>
    <parameter key="timeout" value="2000"/>
    <parameter key="resolution-type" value="v6"/>
    <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
    <parameter key="rrd-base-name" value="dns-res-v6"/>
    <parameter key="ds-name" value="dns-res-v6"/>
    <parameter key="nameserver" value="8.8.8.8"/>
</service>

<!-- Assigned service test if the node label is resolved for an AAAA record AND A record -->
<service name="DNS-Resolution-v4-and-v6" interval="300000" user-defined="false" status="on">
    <parameter key="retry" value="2"/>
    <parameter key="timeout" value="2000"/>
    <parameter key="resolution-type" value="both"/>
    <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
    <parameter key="rrd-base-name" value="dns-res-both"/>
    <parameter key="ds-name" value="dns-res-both"/>
</service>

<!-- Assigned service test if the node label is resolved for an AAAA record OR A record -->
<service name="DNS-Resolution-v4-or-v6" interval="300000" user-defined="false" status="on">
    <parameter key="retry" value="2"/>
    <parameter key="timeout" value="2000"/>
    <parameter key="resolution-type" value="either"/>
    <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
    <parameter key="rrd-base-name" value="dns-res-either"/>
    <parameter key="ds-name" value="dns-res-either"/>
</service>

<!-- Assigned service test if the node label is resolved for an CNAME record AND MX record -->
<service name="DNS-Resolution-CNAME-and-MX" interval="300000" user-defined="false" status="on">
    <parameter key="retry" value="2"/>
    <parameter key="timeout" value="2000"/>
    <parameter key="record-types" value="CNAME,MX"/>
    <parameter key="lookup" value="www.google.comm"/>
    <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
    <parameter key="rrd-base-name" value="dns-res-cname-mx"/>
    <parameter key="ds-name" value="dns-res-cname-mx"/>
</service>

<monitor service="DNS-Resolution-v4" class-name="org.opennms.netmgt.poller.monitors.DNSResolutionMonitor" />
<monitor service="DNS-Resolution-v4-lookup" class-name="org.opennms.netmgt.poller.monitors.DNSResolutionMonitor" />
<monitor service="DNS-Resolution-v6" class-name="org.opennms.netmgt.poller.monitors.DNSResolutionMonitor" />
<monitor service="DNS-Resolution-v4-and-v6" class-name="org.opennms.netmgt.poller.monitors.DNSResolutionMonitor" />
<monitor service="DNS-Resolution-v4-or-v6" class-name="org.opennms.netmgt.poller.monitors.DNSResolutionMonitor" />
<monitor service="DNS-Resolution-CNAME-and-MX" class-name="org.opennms.netmgt.poller.monitors.DNSResolutionMonitor" />

To have response time graphs for the name resolution you have to configure RRD graphs for the given ds-names (dns-res-v4, dns-res-v6, dns-res-both, dns-res-either, dns-res-cname-mx) in '$OPENNMS_HOME/etc/response-graph.properties'.

4.10.4. DNSResolutionMonitor vs DnsMonitor

The DNSResolutionMonitor is used to measure the availability and record outages of a name resolution from client perspective. The service is mainly used for websites or similar public available resources. It can be used in combination with the Page Sequence Monitor to give a hint if a website isn’t available for DNS reasons.

The DnsMonitor on the other hand is a test against a specific DNS server. In OpenNMS Horizon the DNS server is the node and the DnsMonitor will send a lookup request for a given A record to the DNS server IP address. The service goes down if the DNS server doesn’t have a valid A record in his zone database or as some other issues resolving A records.

4.11. FtpMonitor

The FtpMonitor is able to validate ftp connection dial-up processes. The monitor can test ftp server on multiple ports and specific login data.

The service using the FtpMonitor is up if the FTP server responds with return codes between 200 and 299. For special cases the service is also marked as up for 425 and 530.

4.11.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.FtpMonitor

Remote Enabled

true

4.11.2. Configuration and Usage

Table 17. Monitor specific parameters for the FtpMonitor.
Parameter Description Required Default value

retry

Number of attempts to get a valid FTP response/response-text

optional

0

port

A list of TCP ports to which connection shall be tried.

optional

20,21

password

This parameter is meant to be used together with the user parameter to perform basic authentication. This parameter specify to password to be used. The user and password parameters are ignored when the basic-authentication parameter is defined.

optional

empty string

userid

This parameter is meant to be used together with the password parameter to perform basic authentication. This parameter specify to user ID to be used. The userid and password parameters are ignored when the basic-authentication parameter is defined.

optional

-

This monitor implements the Common Configuration Parameters.

4.11.3. Examples

Some example configuration how to configure the monitor in the 'poller-configuration.xml'

<service name="FTP" interval="300000" user-defined="false" status="on">
 <parameter key="retry" value="1"/>
 <parameter key="timeout" value="3000"/>
 <parameter key="port" value="21"/>
 <parameter key="userid" value=""/>
 <parameter key="password" value=""/>
</service>

<service name="FTP-Customer" interval="300000" user-defined="false" status="on">
 <parameter key="retry" value="1"/>
 <parameter key="timeout" value="3000"/>
 <parameter key="port" value="21"/>
 <parameter key="userid" value="Customer"/>
 <parameter key="password" value="MySecretPassword"/>
</service>

<monitor service="FTP" class-name="org.opennms.netmgt.poller.monitors.FtpMonitor"/>
<monitor service="FTP-Customer" class-name="org.opennms.netmgt.poller.monitors.FtpMonitor"/>

4.11.4. Hint

Comment from FtpMonitor source

Also want to accept the following ERROR message generated by some FTP servers following a QUIT command without a previous successful login: "530 QUIT : User not logged in. Please login with USER and PASS first."

Also want to accept the following ERROR message generated by some FTP servers following a QUIT command without a previously successful login: "425 Session is disconnected."

4.12. HostResourceSwRunMonitor

This monitor test the running state of one or more processes. It does this via SNMP by inspecting the hrSwRunTable of the HOST-RESOURCES-MIB. The test is done by matching a given process as hrSwRunName against the numeric value of the hrSwRunState.

This monitor uses SNMP to accomplish its work. Therefore systems against which it is to be used must have an SNMP agent installed and configured. Furthermore, the SNMP agent on the system must support the HOST-RESOURCES-MIB. Most modern SNMP agents, including most distributions of the Net-SNMP agent and the SNMP service that ships with Microsoft Windows, support this MIB. Out-of-box support for HOST-RESOURCES-MIB among commercial Unix operating systems may be somewhat spotty.

4.12.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.HostResourceSwRunMonitor

Remote Enabled

false

4.12.2. Configuration and Usage

Table 18. Monitor specific parameters for the HostResourceSwRunMonitor
Parameter Description Required Default value

port

The port of the SNMP agent of the server to test.

optional

from snmp-config.xml

service-name

The name of the process to be monitored. This parameter’s value is case-sensitive and is evaluated as an exact match.

required

-

match-all

If the process name appears multiple times in the hrSwRunTable, and this parameter is set to true, then all instances of the named process must match the value specified for run-level.

optional

false

run-level

The maximum allowable value of hrSWRunStatus among
running(1),
runnable(2) = waiting for resource
notRunnable(3) = loaded but waiting for event
invalid(4) = not loaded

optional

2

service-name-oid

The numeric object identifier (OID) from which process names are queried. Defaults to hrSwRunName and should never be changed under normal circumstances. That said, changing it to hrSwRunParameters (.1.3.6.1.2.1.25.4.2.1.5) is often helpful when dealing with processes running under Java Virtual Machines which all have the same process name java.

optional

.1.3.6.1.2.1.25.4.2.1.2

service-status-oid

The numeric object identifier (OID) from which run status is queried. Defaults to hrSwRunStatus and should never be changed under normal circumstances.

optional

.1.3.6.1.2.1.25.4.2.1.7

This monitor implements the Common Configuration Parameters.

4.12.3. Examples

The following example shows how to monitor the process called httpd running on a server using this monitor. The configuration in poller-configuration.xml has to be defined as the following:

<service name="Process-httpd" interval="300000" user-defined="false" status="on">
    <parameter key="retry" value="3"/>
    <parameter key="timeout" value="3000"/>
    <parameter key="service-name" value="httpd"/>(1)
    <parameter key="run-level" value="3"/>(2)
    <parameter key="match-all" value="true"/>(3)
</service>

<monitor service="Process-httpd" class-name="org.opennms.netmgt.poller.monitors.HostResourceSwRunMonitor"/>
1 Name of the process on the system
2 Test the state if the process is in a valid state, i.e. have a run-level no higher than notRunnable(3)
3 If the httpd process runs multiple times the test is done for each instance of the process.

4.13. HttpMonitor

The HTTP monitor tests the response of an HTTP server on a specific HTTP 'GET' command. During the poll, an attempt is made to connect on the specified port(s). The monitor can test web server on multiple ports. By default the a test is made against port 80, 8080 and 8888. If the connection request is successful, an HTTP 'GET' command is sent to the interface. The response is parsed and a return code extracted and verified.

4.13.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.HttpMonitor

Remote Enabled

true

4.13.2. Configuration and Usage

Table 19. Monitor specific parameters for the HttpMonitor
Parameter Description Required Default value

basic-authentication

Authentication credentials to perform basic authentication.
Credentials should comply to RFC1945 section 11.1, without the Base64 encoding part. That’s: be a string made of the concatenation of:
1- the user ID;
2- a colon;
3- the password.
basic-authentication takes precedence over the user and password parameters.

optional

-

header[0-9]+

Additional headers to be sent along with the request.
Example of valid parameter’s names are
header0, header1 and header180. header is not a valid parameter name.

optional

-

host-name

Specify the Host header’s value.

optional

-

nodelabel-host-name

If the host-name parameter isn’t set and the resolve-ip parameter is set to false, then OpenNMS Horizon will use the node’s label to set the Host header’s value if this parameter is set to true. Otherwise, OpenNMS Horizon will fall back using the node interface’s IP address as Host header value.

optional

false

password

This parameter is meant to be used together with the user parameter to perform basic
authentication. This parameter specify to password to be used. The user and password
parameters are ignored when the basic-authentication parameter is defined.

optional

empty string

port

A list of TCP ports to which connection shall be tried.

optional

80,8080,8888

retry

Number of attempts to get a valid HTTP response/response-text

optional

0

resolve-ip

If the host-name parameter isn’t set and this parameter is set to true, OpenNMS Horizon will use DNS to resolve the node interface’s IP address, and use the result to set the Host header’s value. When set to false and the host-name parameter isn’t set, OpenNMS Horizon will try to use the nodelabel-host-name parameter to set the Host header’s value.

optional

false

response

A comma-separated list of acceptable HTTP response code ranges. Example: 200-202,299

optional

If the url parameter is set to /, the default
value for this parameter is 100-499, otherwise it’s 100-399.

response-text

Text to look for in the response body. This will be matched against every line, and it will be considered a success at the first match. If there is a ~ at the beginning of the parameter, the rest of the string will be used as a regular expression pattern match, otherwise the match will be a substring match. The regular expression match is anchored at the beginning and end of the line, so you will likely need to put a .* on both sides of your pattern unless you are going to be matching on the entire line.

optional

-

url

URL to be retrieved via the HTTP 'GET' command

optional

/

user

This parameter is meant to be used together with the password parameter to perform basic authentication. This parameter specify to user ID to be used. The user and password parameters are ignored when the basic-authentication parameter is defined.

optional

-

user-agent

Allows you to set the User-Agent HTTP header (see also RFC2616 section 14.43).

optional

OpenNMS HttpMonitor

verbose

When set to true, full communication between client and the webserver will be logged (with a log level of DEBUG).

optional

-

This monitor implements the Common Configuration Parameters.

4.13.3. Examples

<!-- Test HTTP service on port 80 only -->
<service name="HTTP" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="2"/>
  <parameter key="timeout" value="3000"/>
  <parameter key="port" value="80"/>
  <parameter key="url" value="/"/>
</service>

<!-- Test for virtual host opennms.com running -->
<service name="OpenNMSdotCom" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="1"/>
  <parameter key="timeout" value="3000"/>
  <parameter key="port" value="80"/>
  <parameter key="host-name" value="opennms.com"/>
  <parameter key="url" value="/solutions"/>
  <parameter key="response" value="200-202,299"/>
  <parameter key="response-text" value="~.*[Cc]onsulting.*"/>
</service>

<!-- Test for instance of OpenNMS 1.2.9 running -->
<service name="OpenNMS-129" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="1"/>
  <parameter key="timeout" value="3000"/>
  <parameter key="port" value="8080"/>
  <parameter key="url" value="/opennms/event/list"/>
  <parameter key="basic-authentication" value="admin:admin"/>
  <parameter key="response" value="200"/>
</service>

<monitor service="HTTP" class-name="org.opennms.netmgt.poller.monitors.HttpMonitor" />
<monitor service="OpenNMSdotCom" class-name="org.opennms.netmgt.poller.monitors.HttpMonitor" />
<monitor service="OpenNMS-129" class-name="org.opennms.netmgt.poller.monitors.HttpMonitor" />

4.13.4. Testing filtering proxies with HttpMonitor

In case a filtering proxy server is set up to allow retrieval of some URLs but deny others, the HttpMonitor can be used to verify this behavior.

As an example a proxy server is running on TCP port 3128, and serves http://www.opennms.org/ but never http://www.myspace.com/. To test this behaviour, the HttpMonitor can be configured as the following:

<service name="HTTP-Allow-opennms.org" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="1"/>
  <parameter key="timeout" value="3000"/>
  <parameter key="port" value="3128"/>
  <parameter key="url" value="http://www.opennms.org/"/>
  <parameter key="response" value="200-399"/>
</service>

<service name="HTTP-Block-myspace.com" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="1"/>
  <parameter key="timeout" value="3000"/>
  <parameter key="port" value="3128"/>
  <parameter key="url" value="http://www.myspace.com/"/>
  <parameter key="response" value="400-599"/>
</service>

<monitor service="HTTP-Allow-opennms.org" class-name="org.opennms.netmgt.poller.monitors.HttpMonitor"/>
<monitor service="HTTP-Block-myspace.com" class-name="org.opennms.netmgt.poller.monitors.HttpMonitor"/>

4.14. HttpPostMonitor

If it is required to HTTP POST any arbitrary content to a remote URI, the HttpPostMonitor can be used. A use case is to HTTP POST to a SOAP endpoint.

4.14.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.HttpPostMonitor

Remote Enabled

false

4.14.2. Configuration and Usage

Table 20. Monitor specific parameters for the HttpPostMonitor
Parameter Description Required Default value

payload

The body of the POST, for example properly escaped XML.

required

-

auth-password

The password to use for HTTP BASIC auth.

optional

-

auth-username

The username to use for HTTP BASIC auth.

optional

-

banner

A string that is matched against the response of the HTTP POST. If the output contains the banner, the service is determined as up. Specify a regex by starting with ~.

optional

-

charset

Set the character set for the POST.

optional

UTF-8

mimetype

Set the mimetype for the POST.

optional

text/xml

port

The port for the web server where the POST is send to.

optional

80

scheme

The connection scheme to use.

optional

http

usesslfilter

Enables or disables the SSL ceritificate validation. true - false

optional

false

uri

The uri to use during the POST.

optional

/

This monitor implements the Common Configuration Parameters.

4.14.3. Examples

The following example would create a POST that contains the payload Word.

<service name="MyServlet" interval="300000" user-defined="false" status="on">
  <parameter key="banner" value="Hello"/>
  <parameter key="port" value="8080"/>
  <parameter key="uri" value="/MyServlet">
  <parameter key="payload" value="World"/>
  <parameter key="retry" value="1"/>
  <parameter key="timeout" value="30000"/>
</service>
<monitor service="MyServlet" class-name="org.opennms.netmgt.poller.monitors.HttpPostMonitor"/>

The resulting POST looks like this:

POST /MyServlet HTTP/1.1
Content-Type: text/xml; charset=utf-8
Host: <ip_addr_of_interface>:8080
Connection: Keep-Alive

World

4.15. HttpsMonitor

The HTTPS monitor tests the response of an SSL-enabled HTTP server. The HTTPS monitor is an SSL-enabled extension of the HTTP monitor with a default TCP port value of 443. All HttpMonitor parameters apply, so please refer to HttpMonitor’s documentation for more information.

4.15.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.HttpsMonitor

Remote Enabled

true

4.15.2. Configuration and Usage

Table 21. Monitor specific parameters for the HttpsMonitor
Parameter Description Required Default value

port

A list of TCP ports to which connection shall be tried.

optional

443

4.15.3. Examples

<!-- Test HTTPS service on port 8443 -->
<service name="HTTPS" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="2"/>
  <parameter key="timeout" value="3000"/>
  <parameter key="port" value="8443"/>
  <parameter key="url" value="/"/>
</service>

<monitor service="HTTPS" class-name="org.opennms.netmgt.poller.monitors.HttpsMonitor" />

4.16. IcmpMonitor

The ICMP monitor tests for ICMP service availability by sending echo request ICMP messages. The service is considered available when the node sends back an echo reply ICMP message within the specified amount of time.

4.16.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.IcmpMonitor

Remote Enabled

true with some restrictions (see below)

4.16.2. Configuration and Usage

Table 22. Monitor specific parameters for the IcmpMonitor
Parameter Description Required Default value

timeout

Time in milliseconds to wait for a response.

optional

800

allow-fragmentation

Whether to set the "Don’t Fragment" bit on outgoing packets

optional

true

dscp

DSCP traffic-control value.

optional

0

packet-size

Number of bytes of the ICMP packet to send.

optional

64

thresholding-enabled

Enables ICMP thresholding.

optional

true

This monitor implements the Common Configuration Parameters.

4.16.3. Examples

<service name="ICMP" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="2"/>
  <parameter key="timeout" value="3000"/>
  <parameter key="rrd-repository" value="/var/lib/opennms/rrd/response"/>
  <parameter key="rrd-base-name" value="icmp"/>
  <parameter key="ds-name" value="icmp"/>
</service>
<monitor service="ICMP" class-name="org.opennms.netmgt.poller.monitors.IcmpMonitor"/>
<!-- Advanced example: set DSCP bits and send a large packet with allow-fragmentation=false -->
<service name="ICMP" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="2"/>
  <parameter key="timeout" value="3000"/>
  <parameter key="dscp" value="0x1C"/> <!-- AF32: Class 3, Medium drop probability -->
  <parameter key="allow-fragmentation" value="false"/>
  <parameter key="packet-size" value="2048"/>
  <parameter key="rrd-repository" value="/var/lib/opennms/rrd/response"/>
  <parameter key="rrd-base-name" value="icmp"/>
  <parameter key="ds-name" value="icmp"/>
</service>
<monitor service="ICMP" class-name="org.opennms.netmgt.poller.monitors.IcmpMonitor"/>

4.16.4. Note on Remote Poller

The IcmpMonitor needs the JNA ICMP implementation to function on remote poller. Though, corner cases exist where the IcmpMonitor monitor won’t work on remote poller. Examples of such corner cases are: Windows when the remote poller isn’t running has administrator, and Linux on ARM / Rasperry Pi. JNA is the default ICMP implementation used in the remote poller.

4.17. ImapMonitor

This monitor checks if an IMAP server is functional. The test is done by initializing a very simple IMAP conversation. The ImapMonitor establishes a TCP connection, sends a logout command and test the IMAP server responses.

The behavior can be simulated with telnet:

telnet mail.myserver.de 143
Trying 62.108.41.197...
Connected to mail.myserver.de.
Escape character is '^]'.
* OK [CAPABILITY IMAP4rev1 LITERAL+ SASL-IR LOGIN-REFERRALS ID ENABLE IDLE STARTTLS LOGINDISABLED] Dovecot ready. (1)
ONMSPOLLER LOGOUT (2)
* BYE Logging out (3)
ONMSPOLLER OK Logout completed.
Connection closed by foreign host.
1 Test IMAP server banner, it has to start * OK to be up
2 Sending a ONMSPOLLER LOGOUT
3 Test server responds with, it has to start with * BYE to be up

If one of the tests in the sample above fails the service is marked down.

4.17.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.ImapMonitor

Remote Enabled

false

4.17.2. Configuration and Usage

Table 23. Monitor specific parameters for the ImapMonitor
Parameter Description Required Default value

retry

Number of attempts to get a valid IMAP response

optional

0

port

The port of the IMAP server.

optional

143

This monitor implements the Common Configuration Parameters.

4.17.3. Examples

Some example configuration how to configure the monitor in the poller-configuration.xml

<!-- Test IMAP service on port 143 only -->
<service name="IMAP" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="1"/>
  <parameter key="port" value="143"/>
  <parameter key="timeout" value="3000"/>
</service>

<monitor service="IMAP" class-name="org.opennms.netmgt.poller.monitors.ImapMonitor" />

4.18. ImapsMonitor

The IMAPS monitor tests the response of an SSL-enabled IMAP server. The IMAPS monitor is an SSL-enabled extension of the IMAP monitor with a default TCP port value of 993. All ImapMonitor parameters apply, so please refer to ImapMonitor’s documentation for more information.

4.18.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.ImapsMonitor

Remote Enabled

true

4.18.2. Configuration and Usage

Table 24. Monitor specific parameters for the ImapsMonitor
Parameter Description Required Default value

port

The destination port where connections shall be attempted.

optional

993

This monitor implements the Common Configuration Parameters.

4.18.3. Examples

<!-- IMAPS service at OpenNMS.org is on port 9993 -->
<service name="IMAPS" interval="300000" user-defined="false" status="on">
  <parameter key="port" value="9993"/>
  <parameter key="version" value="3"/>
  <parameter key="retry" value="2"/>
  <parameter key="timeout" value="3000"/>
  <parameter key="rrd-repository" value="/var/lib/opennms/rrd/response"/>
  <parameter key="rrd-base-name" value="imaps"/>
  <parameter key="ds-name" value="imaps"/>
</service>

<monitor service="IMAPS" class-name="org.opennms.netmgt.poller.monitors.ImapsMonitor" />

4.19. JCifsMonitor

This monitor allows to test a file sharing service based on the CIFS/SMB protocol.

This monitor is not installed by default. You have to install opennmms-plugin-protocol-cifs from your OpenNMS Horizon installation repository.

With the JCIFS monitor you have different possibilities to test the availability of the JCIFS service:

With the JCifsMonitor it is possible to run tests for the following use cases:

  • share is available in the network

  • a given file exists in the share

  • a given folder exists in the share

  • a given folder should contain at least one (1) file

  • a given folder folder should contain no (0) files

  • by testing on files and folders, you can use a regular expression to ignore specific file and folder names from the test

A network resource in SMB like a file or folder is addressed as a UNC Path.

\\server\share\folder\file.txt

The Java implementation jCIFS, which implements the CIFS/SMB network protocol, uses SMB URLs to access the network resource. The same resource as in our example would look like this as an SMB URL:

smb://workgroup;user:password@server/share/folder/file.txt

The JCifsMonitor can not test:

  • file contains specific content

  • a specific number of files in a folder, for example folder should contain exactly / more or less than x files

  • Age or modification time stamps of files or folders

  • Permissions or other attributes of files or folders

4.19.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.JCifsMonitor

Remote Enabled

false

4.19.2. Configuration and Usage

Table 25. Monitor specific parameters for the JCifsMonitor
Parameter Description Required Default value

retry

Number of retries before the service is marked as down.

optional

0

domain

Windows domain where the user is located. You don’t have to use the domain parameter if you use local user accounts.

optional

empty String

username

Username to access the resource over a network

optional

empty String

password

Password for the user

optional

empty String

path

Path to the resource you want to test

required

empty String

mode

The test mode which has the following options
path_exist: Service is up if the resource is accessible
path_not_exist: Service is up if the resource is not accessible
folder_empty: Service is up if the folder is empty (0 files)
folder_not_empty: Service is up if the folder has at least one file

optional

path_exist

smbHost

Override the IP address of the SMB url to check shares on different file servers.

optional

empty String

folderIgnoreFiles

Ignore specific files in folder with regular expression. This parameter will just be applied on folder_empty and folder_not_empty, otherwise it will be ignored.

optional

-

This monitor implements the Common Configuration Parameters.

It makes little sense to have retries higher than 1. It is a waste of resources during the monitoring.
Please consider, if you are accessing shares with Mac OSX you have some side effects with the hidden file '.DS_Store.' It could give you false positives in monitoring, you can use then the folderIgnoreFiles parameter.

4.19.3. Example test existence of a file

This example shows how to configure the JCifsMonitor to test if a file share is available over a network. For this example we have access to a share for error logs and we want to get an outage if we have any error log files in our folder. The share is named log. The service should go back to normal if the error log file is deleted and the folder is empty.

JCifsMonitor configuration to test that a shared folder is empty
<service name="CIFS-ErrorLog" interval="30000" user-defined="true" status="on">
    <parameter key="retry" value="1" />
    <parameter key="timeout" value="3000" />
    <parameter key="domain" value="contoso" />(1)
    <parameter key="username" value="MonitoringUser" />(2)
    <parameter key="password" value="MonitoringPassword" />(3)
    <parameter key="path" value="/fileshare/log/" />(4)
    <parameter key="mode" value="folder_empty" />(5)
</service>

<monitor service="CIFS-ErrorLog" class-name="org.opennms.netmgt.poller.monitors.JCifsMonitor" />
1 Name of the SMB or Microsoft Windows Domain
2 User for accessing the share
3 Password for accessing the share
4 Path to the folder inside of the share as part of the SMB URL
5 Mode is set to folder_empty

4.20. JDBCMonitor

The JDBCMonitor checks that it is able to connect to a database and checks if it is able to get the database catalog from that database management system (DBMS). It is based on the JDBC technology to connect and communicate with the database.

4.20.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.JDBCMonitor

Remote Enabled

true

4.20.2. Configuration and Usage

Table 26. Monitor specific parameters for the JDBCMonitor
Parameter Description Required Default value

driver

JDBC driver class to use

required

org.postgresql.Driver

url

JDBC Url to connect to.

required

jdbc:postgresql://:OPENNMS_JDBC_HOSTNAME/opennms

user

Database user

required

postgres

password

Database password

required

empty string

retries

How many retries should be performed before failing the test

optional

0

The OPENNMS_JDBC_HOSTNAME is replaced in the url parameter with the IP or resolved hostname of the interface the monitored service is assigned to.

This monitor implements the Common Configuration Parameters.

4.20.3. Provide the database driver

The JDBCMonitor is based on JDBC and requires a JDBC driver to communicate with any database. Due to the fact that OpenNMS Horizon itself uses a PostgreSQL database, the PostgreSQL JDBC driver is available out of the box. For all other database systems a compatible JDBC driver has to be provided to OpenNMS Horizon as a jar-file. To provide a JDBC driver place the driver-jar in the opennms/lib folder of your OpenNMS Horizon. To use the JDBCMonitor from a remote poller, the driver-jar has to be provided to the Remote Poller too. This may be tricky or impossible when using the Java Webstart Remote Poller, because of code signing requirements.

4.20.4. Examples

The following example checks if the PostgreSQL database used by OpenNMS Horizon is available.

<service name="OpenNMS-DBMS" interval="30000" user-defined="true" status="on">
  <parameter key="driver" value="org.postgresql.Driver"/>
  <parameter key="url" value="jdbc:postgresql://OPENNMS_JDBC_HOSTNAME:5432/opennms"/>
  <parameter key="user" value="opennms"/>
  <parameter key="password" value="opennms"/>
</service>

<monitor service="OpenNMS-DBMS" class-name="org.opennms.netmgt.poller.monitors.JDBCMonitor" />

4.21. JDBCStoredProcedureMonitor

The JDBCStoredProcedureMonitor checks the result of a stored procedure in a remote database. The result of the stored procedure has to be a boolean value (representing true or false). The service associated with this monitor is marked as up if the stored procedure returns true and it is marked as down in all other cases. It is based on the JDBC technology to connect and communicate with the database.

4.21.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.JDBCStoredProcedureMonitor

Remote Enabled

false

4.21.2. Configuration and Usage

Table 27. Monitor specific parameters for the JDBCStoredProcedureMonitor
Parameter Description Required Default value

driver

JDBC driver class to use

required

org.postgresql.Driver

url

JDBC Url to connect to.

required

jdbc:postgresql://:OPENNMS_JDBC_HOSTNAME/opennms

user

Database user

required

postgres

password

Database password

required

empty string

retries

How many retries should be performed before failing the test

optional

0

stored-procedure

Name of the database stored procedure to call

required

-

schema

Name of the database schema in which the stored procedure is

optional

test

The OPENNMS_JDBC_HOSTNAME is replaced in the url parameter with the IP or resolved hostname of the interface the monitored service is assigned to.

This monitor implements the Common Configuration Parameters.

4.21.3. Provide the database driver

The JDBCStoredProcedureMonitor is based on JDBC and requires a JDBC driver to communicate with any database. Due to the fact that OpenNMS Horizon itself uses a PostgreSQL database, the PostgreSQL JDBC driver is available out of the box. For all other database systems a compatible JDBC driver has to be provided to OpenNMS Horizon as a jar-file. To provide a JDBC driver place the driver-jar in the opennms/lib folder of your OpenNMS Horizon. To use the JDBCStoredProcedureMonitor from a remote poller, the driver-jar has to be provided to the Remote Poller too. This may be tricky or impossible when using the Java Webstart Remote Poller, because of code signing requirements.

4.21.4. Examples

The following example checks a stored procedure added to the PostgreSQL database used by OpenNMS Horizon. The stored procedure returns true as long as less than 250000 events are in the events table of OpenNMS Horizon.

Stored procedure which is used in the monitor
CREATE OR REPLACE FUNCTION eventlimit_sp() RETURNS boolean AS
$BODY$DECLARE
num_events integer;
BEGIN
	SELECT COUNT(*) into num_events from events;
	RETURN num_events > 250000;
END;$BODY$
LANGUAGE plpgsql VOLATILE NOT LEAKPROOF
COST 100;
<service name="OpenNMS-DB-SP-Event-Limit" interval="300000" user-defined="true" status="on">
  <parameter key="driver" value="org.postgresql.Driver"/>
  <parameter key="url" value="jdbc:postgresql://OPENNMS_JDBC_HOSTNAME:5432/opennms"/>
  <parameter key="user" value="opennms"/>
  <parameter key="password" value="opennms"/>
  <parameter key="stored-procedure" value="eventlimit_sp"/>
  <parameter key="schema" value="public"/>
</service>

<monitor service="OpenNMS-DB-SP-Event-Limit" class-name="org.opennms.netmgt.poller.monitors.JDBCStoredProcedureMonitor"/>

4.22. JDBCQueryMonitor

The JDBCQueryMonitor runs an SQL query against a database and is able to verify the result of the query. A read-only connection is used to run the SQL query, so the data in the database is not altered. It is based on the JDBC technology to connect and communicate with the database.

4.22.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.JDBCQueryMonitor

Remote Enabled

false

4.22.2. Configuration and Usage

Table 28. Monitor specific parameters for the JDBCQueryMonitor
Parameter Description Required Default value

driver

JDBC driver class to use

required

org.postgresql.Driver

url

JDBC URL to connect to.

required

jdbc:postgresql://:OPENNMS_JDBC_HOSTNAME/opennms

user

Database user

required

postgres

password

Database password

required

empty string

query

The SQL query to run

required

-

action

What evaluation action to perform

required

row_count

column

The result column to evaluate against

required

-

operator

Operator to use for the evaluation

required

>=

operand

The operand to compare against the SQL query result

required

depends on the action

message

The message to use if the service is down. Both operands and the operator are added to the message too.

optional

generic message depending on the action

retries

How many retries should be performed before failing the test

optional

0

The OPENNMS_JDBC_HOSTNAME is replaced in the url parameter with the IP or resolved hostname of the interface the monitored service is assigned to.

This monitor implements the Common Configuration Parameters.

Table 29. Available action parameters and their default operand
Parameter Description Default operand

row_count

The number of returned rows is compared, not a value of the resulting rows

1

compare_string

Strings are always checked for equality with the operand

-

compare_int

An integer from a column of the first result row is compared

1

Table 30. Available operand parameters
Parameter XML entity to use in XML configs

=

=

<

&lt;

>

&gt;

!=

!=

&lt;=

>=

&gt;=

4.22.3. Evaluating the action - operator - operand

Only the first result row returned by the SQL query is evaluated. The evaluation can be against the value of one column or the number of rows returned by the SQL query.

4.22.4. Provide the database driver

The JDBCQueryMonitor is based on JDBC and requires a JDBC driver to communicate with any database. Due to the fact that OpenNMS Horizon itself uses a PostgreSQL database, the PostgreSQL JDBC driver is available out of the box. For all other database systems a compatible JDBC driver has to be provided to OpenNMS Horizon as a jar-file. To provide a JDBC driver place the driver-jar in the opennms/lib folder of your OpenNMS Horizon. To use the JDBCQueryMonitor from a remote poller, the driver-jar has to be provided to the Remote Poller too. This may be tricky or impossible when using the Java Webstart Remote Poller, because of code signing requirements.

4.22.5. Examples

The following example checks if the number of events in the OpenNMS Horizon database is fewer than 250000.

<service name="OpenNMS-DB-Event-Limit" interval="30000" user-defined="true" status="on">
  <parameter key="driver" value="org.postgresql.Driver"/>
  <parameter key="url" value="jdbc:postgresql://OPENNMS_JDBC_HOSTNAME:5432/opennms"/>
  <parameter key="user" value="opennms"/>
  <parameter key="password" value="opennms"/>
  <parameter key="query" value="select eventid from events" />
  <parameter key="action" value="row_count" />
  <parameter key="operand" value="250000" />
  <parameter key="operator" value="&lt;" />
  <parameter key="message" value="too many events in OpenNMS database" />
</service>

<monitor service="OpenNMS-DB-Event-Limit" class-name="org.opennms.netmgt.poller.monitors.JDBCQueryMonitor" />

4.23. JmxMonitor

The JMX monitor allows to test service availability of Java applications. The monitor offers the following functionalities:

  • test the application’s connectivity via JMX

  • existence of management beans

  • test the status of a single or multiple management beans and evaluate their value

4.23.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.Jsr160Monitor

Remote Enabled

true

4.23.2. Configuration and Usage

Table 31. Monitor specific parameters for the JmxMonitor
Parameter Description Required Default value

retry

Number of attempts to get a response

optional

3

timeout

Time in milliseconds to wait for a response

optional

?

port

Destination port where the JMX requests shall be sent

optional

from jmx-config.xml

factory              

Set this to PASSWORD-CLEAR if credentials are required  

optional

STANDARD

protocol            

Protocol used in the JMX connection string              

optional

rmi

urlPath              

Path used in JMX connection string                      

optional

/jmxrmi

rmiServerPort        

RMI port                                               

optional

45444

remoteJMX            

Use an alternative JMX URL scheme                        

optional

false

beans.<variable>

Defines a mbeans objectname to access. The ´<variable>´ name is arbitrary.

optional

-

tests.<variable>

Tests a mbeans attribute value. The ´<variable>´ name is arbitrary.

optional

-

4.23.3. Examples

Test if a JMX connection can be established
<service name="JMX-Connection-Test" interval="300000" user-defined="false" status="on">
    <parameter key="retry" value="3"/>
    <parameter key="timeout" value="3000"/>
    <parameter key="port" value="18980"/>
</service>
<monitor service="JMX-Connection-Test" class-name="org.opennms.netmgt.poller.monitors.JmxMonitor"/>
Test a specific management bean for a value
<service name="JMX-BeanValue-Test" interval="300000" user-defined="false" status="on">
    <parameter key="retry" value="3"/>
    <parameter key="timeout" value="3000"/>
    <parameter key="port" value="18980"/>
    <parameter key="beans.connected" value="org.opennms.workflow:name=client.onms.connected"/>
    <parameter key="tests.isConnected" value="connected.get(&quot;Value&quot;) == true"/>
</service>
<monitor service="JMX-BeanValue-Test" class-name="org.opennms.netmgt.poller.monitors.Jsr160Monitor"/>
Reserved XML characters like >, <, " need to be escaped.

4.24. JolokiaBeanMonitor

The JolokiaBeanMonitor is a JMX monitor specialized for the use with the Jolokia framework. If it is required to execute a method via JMX or poll an attribute via JMX, the JolokiaBeanMonitor can be used. It requires a fully installed and configured Jolokia agent to be deployed in the JVM container. If required it allows attribute names, paths, and method parameters to be provided additional arguments to the call. To determine the status of the service the JolokiaBeanMonitor relies on the output to be matched against a banner. If the banner is part of the output the status is interpreted as up. If the banner is not available in the output the status is determined as down. Banner matching supports regular expression and substring match.

4.24.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.JolokiaBeanMonitor

Remote Enabled

false

4.24.2. Configuration and Usage

Table 32. Monitor specific parameters for the JolokiaBeanMonitor
Parameter Description Required Default value

beanname

The bean name to query against.

required

-

attrname

The name of the JMX attribute to scrape.

optional (attrname or methodname must be set)

-

attrpath

The attribute path.

optional

-

auth-username

The username to use for HTTP BASIC auth.

optional

-

auth-password

The password to use for HTTP BASIC auth.

optional

-

banner

A string that is match against the output of the system-call. If the output contains the banner, the service is determined as up. Specify a regex by starting with ~.

optional

-

input1

Method input

optional

-

input2

Method input

optional

-

methodname

The name of the bean method to execute, output will be compared to banner.

optional (attrname or methodname must be set)

-

port

The port of the jolokia agent.

optional

8080

url

The jolokia agent url. Defaults to "http://<ipaddr>:<port>/jolokia"

optional

-

This monitor implements the Common Configuration Parameters.

Table 33. Variables which can be used in the configuration
Variable Description

${ipaddr}

IP-address of the interface the service is bound to.

${port}

Port the service it bound to.

4.24.3. Examples

Some example configuration how to configure the monitor in the poller-configuration.xml

<parameter key="url" value="http://${ipaddr}:${port}/jolokia"/>
<parameter key="url" value="https://${ipaddr}:${port}/jolokia"/>

4.24.4. AttrName vs MethodName

The JolokiaBeanMonitor has two modes of operation. It can either scrape an attribute from a bean, or execute a method and compare output to a banner. The method execute is useful when your application has it’s own test methods that you would like to trigger via OpenNMS Horizon.

The args to execute a test method called "superTest" that take in a string as input would look like this:

<parameter key="beanname" value="MyBean" />
<parameter key="methodname" value="superTest" />
<parameter key="input1" value="someString"/>

The args to scrape an attribute from the same bean would look like this:

<parameter key="beanname" value="MyBean" />
<parameter key="attrname" value="upTime" />

4.25. LdapMonitor

The LDAP monitor tests for LDAP service availability. The LDAP monitor first tries to establish a TCP connection on the specified port. Then, if it succeeds, it will attempt to establish an LDAP connection and do a simple search. If the search returns a result within the specified timeout and attempts, the service will be considered available. The scope of the LDAP search is limited to the immediate subordinates of the base object. The LDAP search is anonymous by default. The LDAP monitor makes use of the com.novell.ldap.LDAPConnection class.

4.25.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.LdapMonitor

Remote Enabled

true

4.25.2. Configuration and Usage

Table 34. Monitor specific parameters for the LdapMonitor
Parameter Description Required Default value

dn

The distinguished name to use if authenticated search is needed.

optional

-

password

The password to use if authenticated search is needed.

optional

-

port

The destination port where connection shall be attempted.

optional

389

retry

Number of attempts to get a search result.

optional

1

searchbase

The base distinguished name to search from.

optional

base

searchfilter

The LDAP search’s filter.

optional

(objectclass=*)

version

The version of the LDAP protocol to use, specified as an integer. Note: Only LDAPv3 is supported at the moment.

optional

3

This monitor implements the Common Configuration Parameters.

4.25.3. Examples

<!-- OpenNMS.org -->
<service name="LDAP" interval="300000" user-defined="false" status="on">
  <parameter key="port" value="389"/>
  <parameter key="version" value="3"/>
  <parameter key="searchbase" value="dc=opennms,dc=org"/>
  <parameter key="searchfilter" value="uid=ulf"/>
  <parameter key="retry" value="2"/>
  <parameter key="timeout" value="3000"/>
  <parameter key="rrd-repository" value="/var/lib/opennms/rrd/response"/>
  <parameter key="rrd-base-name" value="ldap"/>
  <parameter key="ds-name" value="ldap"/>
</service>
<monitor service="LDAP" class-name="org.opennms.netmgt.poller.monitors.LdapMonitor"/>

4.26. LdapsMonitor

The LDAPS monitor tests the response of an SSL-enabled LDAP server. The LDAPS monitor is an SSL-enabled extension of the LDAP monitor with a default TCP port value of 636. All LdapMonitor parameters apply, so please refer to LdapMonitor’s documentation for more information.

4.26.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.LdapsMonitor

Remote Enabled

true

4.26.2. Configuration and Usage

Table 35. Monitor specific parameters for the LdapsMonitor
Parameter Description Required Default value

port

The destination port where connections shall be attempted.

optional

636

This monitor implements the Common Configuration Parameters.

4.26.3. Examples

<!-- LDAPS service at OpenNMS.org is on port 6636 -->
<service name="LDAPS" interval="300000" user-defined="false" status="on">
  <parameter key="port" value="6636"/>
  <parameter key="version" value="3"/>
  <parameter key="searchbase" value="dc=opennms,dc=org"/>
  <parameter key="searchfilter" value="uid=ulf"/>
  <parameter key="retry" value="2"/>
  <parameter key="timeout" value="3000"/>
  <parameter key="rrd-repository" value="/var/lib/opennms/rrd/response"/>
  <parameter key="rrd-base-name" value="ldaps"/>
  <parameter key="ds-name" value="ldaps"/>
</service>

<monitor service="LDAPS" class-name="org.opennms.netmgt.poller.monitors.LdapsMonitor" />

4.27. MemcachedMonitor

This monitor allows to monitor Memcached, a distributed memory object caching system. To monitor the service availability the monitor tests if the Memcached statistics can be requested. The statistics are processed and stored in RRD files. The following metrics are collected:

Table 36. Collected metrics using the MemcachedMonitor
Metric Description

uptime

Seconds the Memcached server has been running since last restart.

rusageuser

User time seconds for the server process.

rusagesystem

System time seconds for the server process.

curritems

Number of items in this servers cache.

totalitems

Number of items stored on this server.

bytes

Number of bytes currently used for caching items.

limitmaxbytes

Maximum configured cache size.

currconnections

Number of open connections to this Memcached.

totalconnections

Number of successful connect attempts to this server since start.

connectionstructure

Number of internal connection handles currently held by the server.

cmdget

Number of GET commands received since server startup.

cmdset

Number of SET commands received since server startup.

gethits

Number of successful GET commands (cache hits) since startup.

getmisses

Number of failed GET requests, because nothing was cached.

evictions

Number of objects removed from the cache to free up memory.

bytesread

Number of bytes received from the network.

byteswritten

Number of bytes send to the network.

threads

Number of threads used by this server.

4.27.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.MemcachedMonitor

Remote Enabled

true

4.27.2. Configuration and Usage

Table 37. Monitor specific parameters for the MemcachedMonitor
Parameter Description Required Default value

retry

Number of attempts to establish the Memcached connnection.

optional

0

port

TCP port connecting to Memcached.

optional

11211

This monitor implements the Common Configuration Parameters.

4.27.3. Examples

The following example shows a configuration in the poller-configuration.xml.

<service name="Memcached" interval="300000" user-defined="false" status="on">
  <parameter key="port" value="11211" />
  <parameter key="retry" value="2" />
  <parameter key="timeout" value="3000" />
  <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response" />
  <parameter key="ds-name" value="memcached" />
  <parameter key="rrd-base-name" value="memcached" />
</service>

<monitor service="Memcached" class-name="org.opennms.netmgt.poller.monitors.MemcachedMonitor" />

4.28. NetScalerGroupHealthMonitor

This monitor is designed for Citrix® NetScaler® loadbalancing checks. It checks if more than x percent of the servers assigned to a specific group on a loadbalanced service are active. The required data is gathered via SNMP from the NetScaler®. The status of the servers is determined by the NetScaler®. The provided service it self is not part of the check. The basis of this monitor is the SnmpMonitorStrategy. A valid SNMP configuration in OpenNMS Horizon for the NetScaler® is required.

A NetScaler® can manage several groups of servers per application. This monitor just covers one group at a time. If there are multiple groups to check, define one monitor per group.
This monitor is not checking the loadbalanced service it self.

4.28.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.NetScalerGroupHealthMonitor

Remote Enabled

false

4.28.2. Configuration and Usage

Table 38. Monitor specific parameters for the NetScalerGroupHealthMonitor
Parameter Description Required Default value

group-name

The name of the server group to check

required

-

group-health

The percentage of active servers vs total server of the group as an integer

optional

60

This monitor implements the Common Configuration Parameters.

4.28.3. Examples

The following example checks a server group called central_webfront_http. If at least 70% of the servers are active, the service is up. If less then 70% of the servers are active the service is down. A configuration like the following can be used for the example in the poller-configuration.xml.

<service name="NetScaler_Health" interval="300000" user-defined="false" status="on">
   <parameter key="group-name" value="central_webfront_http" />
   <parameter key="group-health" value="70" />
</service>

<monitor service="NetScaler_Health" class-name="org.opennms.netmgt.poller.monitors.NetScalerGroupHealthMonitor” />

4.28.4. Details about the used SNMP checks

The monitor checks the status of the server group based on the NS-ROOT-MIB using the svcGrpMemberState. svcGrpMemberState is part of the serviceGroupMemberTable. The serviceGroupMemberTable is indexed by svcGrpMemberGroupName and svcGrpMemberName. A initial lookup for the group-name is performed. Based on the lookup the serviceGroupMemberTable is walked with the numeric representation of the server group. The monitor interprets just the server status code 7-up as active server. Other status codes like 2-unknown or 3-busy are counted for total amount of servers.

4.29. NrpeMonitor

This monitor allows to test plugins and checks running on the Nagios Remote Plugin Executor (NRPE) framework. The monitor allows to test the status output of any available check command executed by NRPE. Between OpenNMS Horizon and Nagios are some conceptional differences. In OpenNMS Horizon a service can only be available or not available and the response time for the service is measured. Nagios on the other hand combines service availability, performance data collection and thresholding in one check command. For this reason a Nagios check command can have more states then OK and CRITICAL. Using the NrpeMonitor marks all check command results other than OK as down. The full output of the check command output message is passed into the service down event in OpenNMS Horizon.

NRPE configuration on the server is required and the check command has to be configured, e.g. command[check_apt]=/usr/lib/nagios/plugins/check_apt
OpenNMS Horizon executes every NRPE check in a Java thread without fork() a process and it is more resource friendly. Nevertheless it is possible to run NRPE plugins which combine a lot of external programs like sed, awk or cut. Be aware, each command end up in forking additional processes.

4.29.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.NrpeMonitor

Remote Enabled

false

4.29.2. Configuration and Usage

Table 39. Monitor specific parameters for the NrpeMonitor
Parameter Description Required Default value

retry

Number of retries before the service is marked as down.

optional

0

command

The {check_name} of the command configured as `command[{check_name}]="/path/to/plugin/check-script"

required

empty

port

Port to access NRPE on the remote server.

optional

5666

padding

Padding for sending the command to the NRPE agent.

optional

2

usessl

Enable encryption of network communication. NRPE uses SSL with anonymous DH and the following cipher suite TLS_DH_anon_WITH_AES_128_CBC_SHA

optional

true

This monitor implements the Common Configuration Parameters.

4.29.3. Example: Using check_apt with NRPE

This examples shows how to configure the NrpeMonitor running the check_apt command on a configured NRPE.

Configuration of the NRPE check command on the agent in 'nrpe.cfg'
command[check_apt]=/usr/lib/nagios/plugins/check_apt
Configuration to test the NRPE plugin with the NrpeMonitor
<service name="NRPE-Check-APT" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="3" />
  <parameter key="timeout" value="3000" />
  <parameter key="port" value="5666" />
  <parameter key="command" value="check_apt" />
  <parameter key="padding" value="2" />
</service>

<monitor service="NRPE-Check-APT" class-name="org.opennms.netmgt.poller.monitors.NrpeMonitor" />

4.30. NtpMonitor

The NTP monitor tests for NTP service availability. During the poll an NTP request query packet is generated. If a response is received, it is parsed and validated. If the response is a valid NTP response, the service is considered available.

4.30.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.NtpMonitor

Remote Enabled

true

4.30.2. Configuration and Usage

Table 40. Monitor specific parameters for the NtpMonitor
Parameter Description Required Default value

port

The destination port where the NTP request shall be sent.

optional

123

retry

Number of attempts to get a response.

optional

0

timeout

Time in milliseconds to wait for a response.

optional

5000

This monitor implements the Common Configuration Parameters.

4.30.3. Examples

<!-- Fast NTP server -->
<service name="NTP" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="2"/>
  <parameter key="timeout" value="1000"/>
  <parameter key="rrd-repository" value="/var/lib/opennms/rrd/response"/>
  <parameter key="rrd-base-name" value="ntp"/>
  <parameter key="ds-name" value="ntp"/>
</service>
<monitor service="NTP" class-name="org.opennms.netmgt.poller.monitors.NtpMonitor"/>

4.31. OmsaStorageMonitor

With OmsaStorageMonitor you are able to monitor your Dell OpenManaged servers RAID array status. The following OIDs from the STORAGEMANAGEMENT-MIB are supported by this monitor:

virtualDiskRollUpStatus                     .1.3.6.1.4.1.674.10893.1.20.140.1.1.19
arrayDiskLogicalConnectionVirtualDiskNumber .1.3.6.1.4.1.674.10893.1.20.140.3.1.5
arrayDiskNexusID                            .1.3.6.1.4.1.674.10893.1.20.130.4.1.26
arrayDiskLogicalConnectionArrayDiskNumber   .1.3.6.1.4.1.674.10893.1.20.140.3.1.3
arrayDiskState                              .1.3.6.1.4.1.674.10893.1.20.130.4.1.4

To test the status of the disk array the virtualDiskRollUpStatus is used. If the result of the virtualDiskRollUpStatus is not 3 the monitors is marked as down.

Table 41. Possible result of virtual disk rollup status
Result State description Monitor state in OpenNMS Horizon

1

other

DOWN

2

unknown

DOWN

3

ok

UP

4

non-critical

DOWN

5

critical

DOWN

6

non-recoverable

DOWN

You’ll need to know the maximum number of possible logical disks you have in your environment. For example: If you have 3 RAID arrays, you need for each logical disk array a service poller.

To give more detailed information in case of an disk array error, the monitor tries to identify the problem using the other OIDs. This values are used to enrich the error reason in the service down event. The disk array state is resolved to a human readable value by the following status table.

Table 42. Possible array disk state errors
Value Status

1

Ready

2

Failed

3

Online

4

Offline

6

Degraded

7

Recovering

11

Removed

15

Resynching

24

Rebuilding

25

noMedia

26

Formating

28

Running Diagnostics

35

Initializing

4.31.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.OmsaStorageMonitor

Remote Enabled

false

4.31.2. Configuration and Usage

Table 43. Monitor specific parameters for the OmsaStorageMonitor
Parameter Description Required Default value

virtualDiskNumber

The disk index of your RAID array

optional

1

port

The TCP port OpenManage is listening

optional

from snmp-config.xml

This monitor implements the Common Configuration Parameters.

4.31.3. Examples

Some example configuration how to configure the monitor in the poller-configuration.xml. The RAID array monitor for your first array is configured with virtualDiskNumber = 1 and can look like this:

<service name="OMSA-Disk-Array-1" interval="300000" user-defined="false" status="on">
 <parameter key="retry" value="3"/>
 <parameter key="timeout" value="6000"/>
 <parameter key="virtualDiskNumber" value="1"/>
</service>

<monitor service="OMSA-Disk-Array-1" class-name="org.opennms.netmgt.poller.monitors.OmsaStorageMonitor"/>

If there is more than one RAID array to monitor you need an additional configuration. In this case virtualDiskNumber = 2.

<service name="OMSA-Disk-Array-2" interval="300000" user-defined="false" status="on">
 <parameter key="retry" value="3"/>
 <parameter key="timeout" value="6000"/>
 <parameter key="virtualDiskNumber" value="2"/>
</service>

<monitor service="OMSA-Disk-Array-2" class-name="org.opennms.netmgt.poller.monitors.OmsaStorageMonitor"/>

4.32. OpenManageChassisMonitor

The OpenManageChassis monitor tests the status of a Dell chassis by querying its SNMP agent. The monitor polls the value of the node’s SNMP OID .1.3.6.1.4.1.674.10892.1.300.10.1.4.1 (MIB-Dell-10892::chassisStatus). If the value is OK (3), the service is considered available.

As this monitor uses SNMP, the queried nodes must have proper SNMP configuration in snmp-config.xml.

4.32.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.OpenManageChassisMonitor

Remote Enabled

false

4.32.2. Configuration and Usage

Table 44. Monitor specific parameters for the OpenManageChassisMonitor
Parameter Description Required Default value

port

The port to which connection shall be tried.

optional

from snmp-config.xml

This monitor implements the Common Configuration Parameters.

4.32.3. Examples

<!-- Overriding default SNMP config -->
<service name="OMA-Chassis" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="3"/>
  <parameter key="timeout" value="5000"/>
</service>

<monitor service="OMA-Chassis" class-name="org.opennms.netmgt.poller.monitors.OpenManageChassisMonitor" />

4.32.4. Dell MIBs

Dell MIBs can be found here. Download the DCMIB<version>.zip or DCMIB<version>.exe file corresponding to the version of your OpenManage agents. The latest one should be good enough for all previous version though.

4.33. PageSequenceMonitor

The PageSequenceMonitor (PSM) allows OpenNMS to monitor web applications. This monitor has several configuration options regarding IPv4, IPv6 and how to deal with name resolution. To add flexibility, the node label and IP address can be passed as variable into the monitor. This allows running the monitor with node dependent configuration. Beyond testing a web application with a single URL it can also test a path through a web application. A test path through an web application can look like this:

  1. login to a certain web application

  2. Execute an action while being logged in

  3. Log off

The service is considered as up if all this is working ok. If there’s an error somewhere, your application will need attention and the service changes the state to down.

4.33.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.PageSequenceMonitor

Remote Enabled

true

4.33.2. Configuration and Usage

The configuration for this monitor consists of several parts. First is the overall configuration for retries and timeouts. These parameters are global for the whole path through the web application.

01 page sequence monitor config
Figure 3. Configuration overview of the PSM

The overall layout of the monitor configuration is more complex. Additionally, it is possible to configure a page sequence containing a path through a web application.

Table 45. Monitor parameters for the PageSequenceMonitor
Parameter Description Required Default value

retry

The number of retries per page.

optional

0

strict-timeout

Defines a timer to wait before a retry attempt is made. It is only used if at least one (1) retry is configured. If retry >= 1 and strict-timeout is true the next attempt is delayed and the Poller Daemon waits NOW - InitialAttempt ms + Timeout ms. With strict-timout = false the next attempt is started right after a failure.

optional

false

page-sequence

Definition of the page-sequence to execute, see table with Page Sequence Parameter

required

-

sequence-retry

The retry parameter for the entire page sequence.

optional

0

This monitor implements the Common Configuration Parameters.

Table 46. Page Sequence Parameter
Parameter Description Required Default

name

The name of the page-sequence. (Is this relevant/used?)

optional

-

method

HTTP method for example GET or POST

-

-

http-version

HTTP protocol version number, 0.9, 1.0 or 1.1

optional

HTTP/1.1

user-agent

Set the user agent field in HTTP header to identify the OpenNMS monitor

optional

OpenNMS PageSequenceMonitor (Service name: "${SERVICE NAME}")

virtual-host

Set the virtual host field in HTTP header. In case of an HTTPS request, this is also the virtual domain to send as part of the TLS negotiation, known as server name indication (SNI) (See: RFC3546 section 3.1)

-

-

path

The relative URL to call in the request.

required

-

scheme

Define the URL scheme as http or https

optional

http

user-info

Set user info field in the HTTP header

-

-

host

Set host field in HTTP header

optional

IP interface address of the service

requireIPv6

Communication requires a connection to an IPv6 address. (true or false)

-

-

requireIPv4

Communication requires a connection to an IPv4 address. (true or false)

-

-

disable-ssl-verification

Enable or disable SSL certificate verification for HTTPS tests. Please use this option carefully, for self-signed certificates import the CA certificate in the JVM and don’t just disable it.

optional

false

port

Port of the web server connecting to

optional

80

query

??

-

-

failureMatch

Text to look for in the response body. This is a Regular Expression matched against every line, and it will be considered a failure at the first match and sets the service with this monitor Down.

-

-

failureMessage

The failure message is used to construct the reason code. ${n} values may be used to pull information from matching groups in the failureMatch regular expression.

-

-

successMatch

Text to look for in the response body. This is a Regular Expression matched against every line, and it will be considered a success at the first match and sets the service with this monitor Up.

optional

-

locationMatch

The relative URL which must be loaded for the request to be considered successful.

optional

-

response-range

Range for allowed HTTP error codes from the response.

-

-

session-variable

Assign the value of a regex match group to a session variable with a user-defined name. The match group is identified by number and must be zero or greater.

-

-

response-range

A comma-separated list of acceptable HTTP response code ranges (200-202,299).

optional

100-399

If you set requireIPv4 and requireIPv6 false, the host IP for connection will be resolved from system name resolver and the associated IP address from the IP interface is ignored.
Table 47. Variables which can be passed in the configuration
Variable Description

${nodelabel}

Nodelabel of the node the monitor is associated to.

4.33.3. Session variables

It is possible to assign strings from a retrieved page to variables that can be used in page parameters later in the same sequence. First, specify one or more capturing groups in the successMatch expression (see Java Class Pattern for more information on regular expressions in Java). The captured values can then be assigned to variable names by using the session-variable parameter, and used in a later page load.

4.33.4. Per-page response times

It is possible to collect response times for individual pages in a sequence. To use this functionality, a ds-name attribute must be added to each page whose load time should be tracked. The response time for each page will be stored in the same RRD file specified for the service via the rrd-base-name parameter under the specified datasource name.

You will need to delete existing RRD files and let them be recreated with the new list of datasources when you add a ds-name attribute to a page in a sequence that is already storing response time data.

4.33.5. Examples

The following example shows how to monitor the OpenNMS web application using several mechanisms. It first does an HTTP GET of ${ipaddr}/opennms (following redirects as a browser would) and then checks to ensure that the resulting page has the phrase Password on it. Next, a login is attempted using HTTP POST to the relative URL for submitting form data (usually, the URL which the form action points to). The parameters (j_username and j_password) indicate the form’s data and values to be submitted. After getting the resulting page, first the expression specified in the page’s failureMatch attribute is verified, which when found anywhere on the page indicates that the page has failed. If the failureMatch expression is not found in the resulting page, then the expression specified in the page’s successMatch attribute is checked to ensure it matches the resulting page. If the successMatch expression is not found on the page, then the page fails. If the monitor was able to successfully login, then the next page is processed. In the example, the monitor navigates to the Event page, to ensure that the text Event Queries is found on the page. Finally, the monitor calls the URL of the logout page to close the session. By using the locationMatch parameter, it is verified that the logout was successful and a redirect was triggered.

Each page is checked to ensure its HTTP response code fits into the response-range, before the failureMatch, successMatch, and locationMatch expressions are evaluated.
Configuration to test the login to the OpenNMS Web application
<service name="OpenNMS-Web-Login" interval="30000" user-defined="true" status="on">
  <parameter key="retry" value="1"/>
  <parameter key="timeout" value="5000"/>
  <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
  <parameter key="ds-name" value="opennmslogin"/>
  <parameter key="page-sequence">
    <page-sequence>
      <page path="/opennms/login.jsp"
            port="8980"
            successMatch="Password" />
      <page path="/opennms/j_spring_security_check"
            port="8980"
            method="POST">
        <parameter key="j_username" value="admin"/>
        <parameter key="j_password" value="admin"/>
      </page>
      <page path="/opennms/index.jsp"
            port="8980"
            successMatch="Log Out" />
      <page path="/opennms/event/index"
            port="8980" successMatch="Event Queries" />
      <page path="/opennms/j_spring_security_logout"
            port="8980"
            method="POST"
            response-range="300-399"
            locationMatch="/opennms" />
    </page-sequence>
  </parameter>
</service>

<monitor service="OpenNMS-Web-Login" class-name="org.opennms.netmgt.poller.monitors.PageSequenceMonitor"/>
Test with mixing HTTP and HTTPS in a page sequence
<service name="OpenNMS-Web-Login" interval="30000" user-defined="true" status="on">
  <parameter key="retry" value="1"/>
  <parameter key="timeout" value="5000"/>
  <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
  <parameter key="ds-name" value="opennmslogin"/>
  <parameter key="page-sequence">
    <page-sequence>
      <page scheme="http"
            host="ecomm.example.com"
            port="80"
            path="/ecomm/jsp/Login.jsp"
            virtual-host="ecomm.example.com"
            successMatch="eComm Login"
            timeout="10000"
            http-version="1.1"/>
      <page scheme="https"
            method="POST"
            host="ecomm.example.com" port="443"
            path="/ecomm/controller"
            virtual-host="ecomm.example.com"
            successMatch="requesttab_select.gif"
            failureMessage="Login failed: ${1}"
            timeout="10000"
            http-version="1.1">
        <parameter key="action_name" value="XbtnLogin"/>
        <parameter key="session_timeout" value=""/>
        <parameter key="userid" value="EXAMPLE"/>
        <parameter key="password" value="econ"/>
      </page>
      <page scheme="http"
            host="ecomm.example.com" port="80"
            path="/econsult/controller"
            virtual-host="ecomm.example.com"
            successMatch="You have successfully logged out of eComm"
            timeout="10000" http-version="1.1">
        <parameter key="action_name" value="XbtnLogout"/>
      </page>
    </page-sequence>
  </parameter>
</service>

<monitor service="OpenNMS-Web-Login" class-name="org.opennms.netmgt.poller.monitors.PageSequenceMonitor"/>
Test login with dynamic credentials using session variables
<service name="OpenNMS-Web-Login" interval="30000" user-defined="true" status="on">
  <parameter key="retry" value="1"/>
  <parameter key="timeout" value="5000"/>
  <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
  <parameter key="ds-name" value="opennmslogin"/>
  <parameter key="page-sequence">
    <page-sequence name="opennms-login-seq-dynamic-credentials">
      <page path="/opennms"
            port="80"
            virtual-host="demo.opennms.org"
            successMatch="(?s)User:.*<strong>(.*?)</strong>.*?Password:.*?<strong>(.*?)</strong>">
        <session-variable name="username" match-group="1" />
        <session-variable name="password" match-group="2" />
      </page>
      <page path="/opennms/j_acegi_security_check"
            port="80"
            virtual-host="demo.opennms.org"
            method="POST"
            failureMatch="(?s)Your log-in attempt failed.*Reason: ([^<]*)"
            failureMessage="Login Failed: ${1}"
            successMatch="Log out">"
        <parameter key="j_username" value="${username}" />
        <parameter key="j_password" value="${password}" />
      </page>
      <page path="/opennms/event/index.jsp"
            port="80"
            virtual-host="demo.opennms.org"
            successMatch="Event Queries" />
      <page path="/opennms/j_acegi_logout"
            port="80"
            virtual-host="demo.opennms.org"
            successMatch="logged off" />
    </page-sequence>
  </parameter>
</service>

<monitor service="OpenNMS-Web-Login" class-name="org.opennms.netmgt.poller.monitors.PageSequenceMonitor"/>
Log in to demo.opennms.org without knowing username and password
<service name="OpenNMS-Demo-Login" interval="300000" user-defined="true" status="on">
  <parameter key="page-sequence">
    <page-sequence>
      <page path="/opennms"
            port="80"
            virtual-host="demo.opennms.org"
            successMatch="(?s)User:.*<strong>(.*?)</strong>.*?Password:.*?<strong>(.*?)</strong>">
        <session-variable name="username" match-group="1" />
        <session-variable name="password" match-group="2" />
      </page>
      <page path="/opennms/j_acegi_security_check"
            port="80"
            virtual-host="demo.opennms.org"
            method="POST"
            successMatch="Log out">"
        <parameter key="j_username" value="${username}" />
        <parameter key="j_password" value="${password}" />
      </page>
      <page path="/opennms/j_acegi_logout"
            port="80"
            virtual-host="demo.opennms.org"
            successMatch="logged off" />
    </page-sequence>
  </parameter>
</service>

<monitor service="OpenNMS-Demo-Login" class-name="org.opennms.netmgt.poller.monitors.PageSequenceMonitor"/>
Example with per-page response times
<service name="OpenNMS-Login" interval="300000" user-defined="false" status="on">
  <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
  <parameter key="rrd-base-name" value="opennmslogin"/>
  <parameter key="ds-name" value="overall"/>
  <parameter key="page-sequence">
    <page-sequence>
      <page path="/opennms/acegilogin.jsp"
            port="8980"
            ds-name="login-page"/>
      <page path="/opennms/event/index.jsp"
            port="8980"
            ds-name="event-page"/>
    </page-sequence>
  </parameter>
</service>

<monitor service="OpenNMS-Login" class-name="org.opennms.netmgt.poller.monitors.PageSequenceMonitor"/>

4.34. PercMonitor

This monitor tests the status of a PERC RAID array.

The monitor first polls the RAID-Adapter-MIB::logicaldriveTable (1.3.6.1.4.1.3582.1.1.2) to retrieve the status of the RAID array you want to monitor. If the value of the status object of the corresponding logicaldriveEntry is not 2, the array is degraded and the monitor further polls the RAID-Adapter-MIB::physicaldriveTable (1.3.6.1.4.1.3582.1.1.3) to detect the failed drive(s).

This monitor requires the outdated persnmpd software to be installed on the polled nodes. Please prefer using OmsaStorageMonitor monitor where possible.

4.34.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.PercMonitor

Remote Enabled

false (relies on SNMP configuration)

4.34.2. Configuration and Usage

Table 48. Monitor specific parameters for the PercMonitor
Parameter Description Required Default value

array

The RAID array you want to monitor.

optional

0.0

port

The UDP port to connect to

optional

from snmp-config.xml

This monitor implements the Common Configuration Parameters.

4.34.3. Examples

<!-- Monitor 1st RAID arrays using configuration from snmp-config.xml -->
<service name="PERC" interval="300000" user-defined="false" status="on" />

<monitor service="PERC" class-name="org.opennms.netmgt.poller.monitors.PercMonitor" />

4.35. Pop3Monitor

The POP3 monitor tests for POP3 service availability on a node. The monitor first tries to establish a TCP connection on the specified port. If a connection is established, a service banner should have been received. The monitor makes sure the service banner is a valid POP3 banner (ie: starts with +OK). If the banner is valid, the monitor sends a QUIT POP3 command and makes sure the service answers with a valid response (ie: a response that starts with +OK). The service is considered available if the service’s answer to the QUIT command is valid.

The behaviour can be simulated with telnet:

$ telnet mail.opennms.org 110
Trying 192.168.0.100
Connected to mail.opennms.org.
Escape character is '^]'.
+OK <21860.1076718099@mail.opennms.org>
quit
+OK
Connection closed by foreign host.

4.35.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.Pop3Monitor

Remote Enabled

true

4.35.2. Configuration and Usage

Table 49. Monitor specific parameters for the Pop3Monitor
Parameter Description Required Default value

port

TCP port to connect to.

optional

110

retry

Number of attempts to find the service available.

optional

0

strict-timeout

If set to true, makes sure that at least timeout milliseconds are elapsed between attempts.

optional

false

This monitor implements the Common Configuration Parameters.

4.35.3. Examples

<service name="POP3" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="2"/>
  <parameter key="timeout" value="3000"/>
  <parameter key="rrd-repository" value="/var/lib/opennms/rrd/response"/>
  <parameter key="rrd-base-name" value="pop3"/>
  <parameter key="ds-name" value="pop3"/>
</service>
<monitor service="POP3" class-name="org.opennms.netmgt.poller.monitors.Pop3Monitor"/>

4.36. PrTableMonitor

The PrTableMonitor monitor tests the prTable of a Net-SNMP agent.

prTable definition

A table containing information on running programs/daemons configured for monitoring in the snmpd.conf file of the agent. Processes violating the number of running processes required by the agent’s configuration file are flagged with numerical and textual errors.

— UCD-SNMP-MIB

The monitor looks up the prErrorFlag entries of this table. If the value of a prErrorFlag entry in this table is set to "1" the service is considered unavailable.

prErrorFlag definition

An Error flag to indicate trouble with a process. It goes to 1 if there is an error, 0 if no error.

— UCD-SNMP-MIB

4.36.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.PrTableMonitor

Remote Enabled

false

4.36.2. Configuration and Usage

Table 50. Monitor specific parameters for the PrTableMonitor
Parameter Description Required Default value

port

The port to which connection shall be tried.

optional

from snmp-config.xml

retries

Deprecated. Same as retry. Parameter retry takes precedence if both are set.

optional

from snmp-config.xml

This monitor implements the Common Configuration Parameters.

4.36.3. Examples

<!-- Overriding default SNMP config -->
<service name="Process-Table" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="3"/>
  <parameter key="timeout" value="5000"/>
</service>

<monitor service="Process-Table" class-name="org.opennms.netmgt.poller.monitors.PrTableMonitor" />

4.36.4. UCD-SNMP-MIB

The UCD-SNMP-MIB may be found here.

4.37. RadiusAuthMonitor

This monitor allows to test the functionality of the RADIUS authentication system. The availability is tested by sending an AUTH packet to the RADIUS server. If a valid ACCEPT response is received, the RADIUS service is up and considered as available.

To use this monitor it is required to install the RADIUS protocol for OpenNMS Horizon.
{apt-get,yum} install {opennms-package-base-name}-plugin-protocol-radius

The test is similar to test the behavior of a RADIUS server by evaluating the result with the command line tool radtest.

root@vagrant:~# radtest "John Doe" hello 127.0.0.1 1812 radiuspassword
Sending Access-Request of id 49 to 127.0.0.1 port 1812
	User-Name = "John Doe"
	User-Password = "hello"
	NAS-IP-Address = 127.0.0.1
	NAS-Port = 1812
	Message-Authenticator = 0x00000000000000000000000000000000
rad_recv: Access-Accept packet from host 127.0.0.1 port 1812, id=49, length=37 (1)
	Reply-Message = "Hello, John Doe"
1 The Access-Accept message which is evaluated by the monitor.

4.37.1. Monitor facts

Class Name

org.opennms.protocols.radius.monitor.RadiusAuthMonitor

Remote Enabled

false

4.37.2. Configuration and Usage

Table 51. Monitor specific parameters for the RadiusAuthMonitor
Parameter Description Required Default value

timeout

Time in milliseconds to wait for the RADIUS service.

optional

5000

retry

This is a placeholder for the second optional monitor parameter description.

optional

0

authport

RADIUS authentication port.

optional

1812

acctport

RADIUS accounting port.

optional

1813

user

Username to test the authentication

optional

OpenNMS

password

Password to test the authentication

optional

OpenNMS

secret

The RADIUS shared secret used for communication between the client/NAS and the RADIUS server.

optional

secret

authtype

RADIUS authentication type. The following authentication types are supported: chap, pap, mschapv1, mschapv2, eapmd5, eapmschapv2, eapttls

optional

pap

nasid

The Network Access Server identifier originating the Access-Request.

optional

opennms

inner-protocol

When using EAP-TTLS authentication, this property indicates the tunnelled authentication type. Only pap is currently supported.

optional

pap

inner-user

Username for the tunnelled pap authentication when using EAP-TTLS.

optional

Inner-OpenNMS

This monitor implements the Common Configuration Parameters.

4.37.3. Examples

Example configuration how to configure the monitor in the poller-configuration.xml.

<service name="Radius-Authentication" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="3" />
  <parameter key="timeout" value="3000" />
  <parameter key="user" value="John Doe" />
  <parameter key="password" value="hello" />
  <parameter key="secret" value="radiuspassword" />
  <parameter key="rrd-repository" value="/var/lib/opennms/rrd/response" />
  <parameter key="ds-name" value="radiusauth" />
</service>

<monitor service="Radius-Authentication" class-name="org.opennms.protocols.radius.monitor.RadiusAuthMonitor" />

4.38. SmbMonitor

This monitor is used to test the NetBIOS over TCP/IP name resolution in Microsoft Windows environments. The monitor tries to retrieve a NetBIOS name for the IP address of the interface. Name services for NetBIOS in Microsoft Windows are provided on port 137/UDP or 137/TCP.

The service uses the IP address of the interface, where the monitor is assigned to. The service is up if for the given IP address a NetBIOS name is registered and can be resolved.

For troubleshooting see the usage of the Microsoft Windows command line tool nbtstat or on Linux nmblookup.

Microsoft deprecated the usage of NetBIOS. Since Windows Server 2000 DNS is used as the default name resolution.

4.38.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.SmbMonitor

Remote Enabled

false

4.38.2. Configuration and Usage

Table 52. Monitor specific parameters for the SmbMonitor
Parameter Description Required Default value

do-node-status

Try to get the NetBIOS node status type for the given address

optional

true

This monitor implements the Common Configuration Parameters.

4.38.3. Examples

Some example configuration how to configure the monitor in the poller-configuration.xml.

<service name="SMB" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="1"/>
  <parameter key="timeout" value="3000"/>
</service>

<monitor service="SMB" class-name="org.opennms.netmgt.poller.monitors.SmbMonitor"/>

4.39. SnmpMonitor

The SNMP monitor gives a generic possibility to monitor states and results from SNMP agents. This monitor has two basic operation modes:

  • Test the response value of one specific OID (scalar object identifier);

  • Test multiple values in a whole table.

To decide which mode should be used, the walk and match-all parameters are used.

See the Operating mode selection'' and Monitor specific parameters for the SnmpMonitor'' tables below for more information about these operation modes.

Table 53. Operating mode selection
walk match-all Operating mode

true

true

tabular, all values must match

false

tabular, any value must match

count

specifies that the value of at least minimum and at most maximum objects encountered in

false

true

scalar

false

scalar

count

tabular, between minimum and maximum values must match

This monitor can’t be used on the OpenNMS Horizon Remote Poller. It is currently not possible for the Remote Poller to have access to the SNMP configuration of a central OpenNMS Horizon.

4.39.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.SnmpMonitor

Remote Enabled

false

When the monitor is configured to persist the response time, it will count the total amount of time spent until a successful response is obtained, including the retries. It won’t store the time spent during the last successful attempt.

4.39.2. Configuration and Usage

Table 54. Monitor specific parameters for the SnmpMonitor
Parameter Description Required Default value

hex

Specifies that the value monitored should be compared against its hexadecimal representation. Useful when the monitored value is a string containing non-printable characters.

optional

false

match-all

Can be set to:
count: specifies that the value of at least minimum and at most maximum objects encountered in the walk must match the criteria specified by operand and operator.
true and walk is set to true: specifies that the value of every object encountered in the walk must match the criteria specified by the operand and operator parameters.
false and walk is set to true: specifies that the value of any object encountered in the walk must match the criteria specified by the operand and operator parameters.

optional

true

maximum

Valid only when match-all is set to count, otherwise ignored. Should be used in conjunction with the minimum parameter. Specifies that the value of at most maximum objects encountered in the walk must meet the criteria specified by the operand and operator parameters.

optional

0

minimum

Valid only when match-all is set to count, otherwise ignored. Should be used in conjunction with the maximum parameter. Specifies that the value of at least minimum objects encountered in the walk must meet the criteria specified by the operand and operator parameters.

optional

0

oid

The object identifier of the MIB object to monitor. If no other parameters are present, the monitor asserts that the agent’s response for this object must include a valid value (as opposed to an error, no-such-name, or end-of-view condition) that is non-null.

optional

.1.3.6.1.2.1.1.2.0 (SNMPv2-MIB::SysObjectID)

operand

The value to be compared against the observed value of the monitored object. Note: Comparison will always succeed if either the operand or operator parameter isn’t set and the monitored value is non-null.

optional

-

operator

The operator to be used for comparing the monitored object against the operand parameter. Must be one of the following symbolic operators:
&lt; (<): Less than. Both operand and observed object value must be numeric.
&gt; (>): Greater than. Both operand and observed object value must be numeric.
&lt;= (⇐): Less than or equal to. Both operand and observed object value must be numeric.
&gt;= (>=): Greater than or equal to. Both operand and observed object value must be numeric.
=: Equal to. Applied in numeric context if both operand and observed object value are numeric, otherwise in string context as a case-sensitive exact match.
!=: Not equal to. Applied in numeric context if both operand and observed object value are numeric, otherwise in string context as a case-sensitive exact match.
~: Regular expression match. Always applied in string context.
Note: Comparison will always succeed if either the operand or operator parameter isn’t set and the monitored value is non-null. Keep in mind that you need to escape all < and > characters as XML entities (&lt; and &gt; respectively)

optional

-

port

Destination port where the SNMP requests shall be sent.

optional

from snmp-config.xml

reason-template

A user-provided template used for the monitor’s reason code if the service is unvailable. Defaults to a reasonable value if unset. See below for an explanation of the possible template parameters.

optional

depends on operation mode

retries

Deprecated Same as retry. Parameter retry takes precedence if both are set.

optional

from snmp-config.xml

walk

false: Sets the monitor to poll for a scalar object unless if the match-all parameter is set to count, in which case the match-all parameter takes precedence.
true: Sets the monitor to poll for a tabular object where the match-all parameter defines how the tabular object’s values must match the criteria defined by the operator and operand parameters. See also the match-all, minimum, and maximum parameters.

optional

false

This monitor implements the Common Configuration Parameters.

Table 55. Variables which can be used in the reason-template parameter
Variable Description

${hex}

Value of the hex parameter.

${ipaddr}

IP address polled.

${matchAll}

Value of the match-all parameter.

${matchCount}

When match-all is set to count, contains the number of matching instances encountered.

${maximum}

Value of the maximum parameter.

${minimum}

Value of the minimum paramater.

${observedValue}

Polled value that made the monitor succeed or fail.

${oid}

Value of the oid parameter.

${operand}

Value of the operand parameter.

${operator}

Value of the operator parameter.

${port}

Value of the port parameter.

${retry}

Value of the retry parameter.

${timeout}

Value of the timeout parameter.

${walk}

Value of the walk parameter.

4.39.3. Example for monitoring scalar object

As a working example we want to monitor the thermal system fan status which is provided as a scalar object ID.

cpqHeThermalSystemFanStatus .1.3.6.1.4.1.232.6.2.6.4.0

The manufacturer MIB gives the following information:

Description of the cpqHeThermalSystemFanStatus from CPQHLTH-MIB
SYNTAX 	INTEGER  {
    other    (1),
    ok       (2),
    degraded (3),
    failed   (4)
}
ACCESS 	read-only
DESCRIPTION
"The status of the fan(s) in the system.

This value will be one of the following:
other(1)
Fan status detection is not supported by this system or driver.

ok(2)
All fans are operating properly.

degraded(3)
A non-required fan is not operating properly.

failed(4)
A required fan is not operating properly.

If the cpqHeThermalDegradedAction is set to shutdown(3) the
system will be shutdown if the failed(4) condition occurs."

The SnmpMonitor is configured to test if the fan status returns ok(2). If so, the service is marked as up. Any other value indicates a problem with the thermal fan status and marks the service down.

Example SnmpMonitor as HP InsightManager fan monitor in poller-configuration.xml
<service name="HP-Insight-Fan-System" interval="300000" user-defined="false" status="on">
    <parameter key="oid" value=".1.3.6.1.4.1.232.6.2.6.4.0"/>(1)
    <parameter key="operator" value="="/>(2)
    <parameter key="operand" value="2"/>(3)
    <parameter key="reason-template" value="System fan status is not ok. The state should be ok(${operand}) the observed value is ${observedValue}. Please check your HP Insight Manager. Syntax: other(1), ok(2), degraded(3), failed(4)"/>(4)
</service>

<monitor service="HP-Insight-Fan-System" class-name="org.opennms.netmgt.poller.monitors.SnmpMonitor" />
1 Scalar object ID to test
2 Operator for testing the response value
3 Integer 2 as operand for the test
4 Encode MIB status in the reason code to give more detailed information if the service goes down

4.39.4. Example test SNMP table with all matching values

The second mode shows how to monitor values of a whole SNMP table. As a practical use case the status of a set of physical drives is monitored. This example configuration shows the status monitoring from the CPQIDA-MIB.

We use as a scalar object id the physical drive status given by the following tabular OID:

cpqDaPhyDrvStatus .1.3.6.1.4.1.232.3.2.5.1.1.6
Description of the cpqDaPhyDrvStatus object id from CPQIDA-MIB
SYNTAX 	INTEGER  {
    other             (1),
    ok                (2),
    failed            (3),
    predictiveFailure (4)
}
ACCESS 	read-only
DESCRIPTION
Physical Drive Status.
This shows the status of the physical drive.
The following values are valid for the physical drive status:

other (1)
 Indicates that the instrument agent does not recognize
 the drive.  You may need to upgrade your instrument agent
 and/or driver software.

ok (2)
 Indicates the drive is functioning properly.

failed (3)
 Indicates that the drive is no longer operating and
 should be replaced.

predictiveFailure(4)
 Indicates that the drive has a predictive failure error and
 should be replaced.

The configuration in our monitor will test all physical drives for status ok(2).

Example SnmpMonitor as HP Insight physical drive monitor in poller-configuration.xml
<service name="HP-Insight-Drive-Physical" interval="300000" user-defined="false" status="on">
    <parameter key="oid" value=".1.3.6.1.4.1.232.3.2.5.1.1.6"/>(1)
    <parameter key="walk" value="true"/>(2)
    <parameter key="operator" value="="/>(3)
    <parameter key="operand" value="2"/>(4)
    <parameter key="match-all" value="true"/>(5)
    <parameter key="reason-template" value="One or more physical drives are not ok. The state should be ok(${operand}) the observed value is ${observedValue}. Please check your HP Insight Manager. Syntax: other(1), ok(2), failed(3), predictiveFailure(4), erasing(5), eraseDone(6), eraseQueued(7)"/>(6)
</service>

<monitor service="HP-Insight-Drive-Physical" class-name="org.opennms.netmgt.poller.monitors.SnmpMonitor" />
1 OID for SNMP table with all physical drive states
2 Enable walk mode to test every entry in the table against the test criteria
3 Test operator for integer
4 Integer 2 as operand for the test
5 Test in walk mode has to be passed for every entry in the table
6 Encode MIB status in the reason code to give more detailed information if the service goes down

4.39.5. Example test SNMP table with all matching values

This example shows how to use the SnmpMonitor to test if the number of static routes are within a given boundary. The service is marked as up if at least 3 and at maxium 10 static routes are set on a network device. This status can be monitored by polling the table ipRouteProto from the RFC1213-MIB2.

ipRouteProto 1.3.6.1.2.1.4.21.1.9

The MIB description gives us the following information:

SYNTAX 	INTEGER  {
    other(1),
    local(2),
    netmgmt(3),
    icmp(4),
    egp(5),
    ggp(6),
    hello(7),
    rip(8),
    is-is(9),
    es-is(10),
    ciscoIgrp(11),
    bbnSpfIgp(12),
    ospf(13),
    bgp(14)}
}
ACCESS 	read-only
DESCRIPTION
"The routing mechanism via which this route was learned.
Inclusion of values for gateway routing protocols is not
intended to imply that hosts should support those protocols."

To monitor only local routes, the test should be applied only on entries in the ipRouteProto table with value 2. The number of entries in the whole ipRouteProto table has to be counted and the boundaries on the number has to be applied.

Example SnmpMonitor used to test if the number of local static route entries are between 3 or 10.
<service name="All-Static-Routes" interval="300000" user-defined="false" status="on">
 <parameter key="oid" value=".1.3.6.1.2.1.4.21.1.9" />(1)
 <parameter key="walk" value="true" />(2)
 <parameter key="operator" value="=" />(3)
 <parameter key="operand" value="2" />(4)
 <parameter key="match-all" value="count" />(5)
 <parameter key="minimum" value="3" />(6)
 <parameter key="maximum" value="10" />(7)
</service>

<monitor service="All-Static-Routes" class-name="org.opennms.netmgt.poller.monitors.SnmpMonitor" />
1 OID for SNMP table ipRouteProto
2 Enable walk mode to test every entry in the table against the test criteria
3 Test operator for integer
4 Integer 2 as operand for testing local route entries
5 Test in walk mode has is set to count to get the number of entries in the table regarding operator and operand
6 Lower count boundary set to 3
7 High count boundary is set to 10

4.40. SshMonitor

The SshMonitor tests the availability of a SSH service. During the poll an attempt is made to connect on the specified port. If the connection request is successful, then the service is considered up. Optionaly, the banner line generated by the service may be parsed and compared against a pattern before the service is considered up.

4.40.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.SshMonitor

Remote Enabled

true

4.40.2. Configuration and Usage

Table 56. Monitor specific parameters for the SshMonitor
Parameter Description Required Default value

banner

Regular expression to be matched against the service’s banner.

optional

-

client-banner

The client banner that OpenNMS Horizon will use to identify itself on the service.

optional

SSH-1.99-OpenNMS_1.5

match

Regular expression to be matched against the service’s banner.
Deprecated, please use the banner parameter instead.
Note that this parameter takes precedence over the banner parameter, though.

optional

-

port

TCP port to which SSH connection shall be tried.

optional

22

retry

Number of attempts to establish the SSH connnection.

optional

0

This monitor implements the Common Configuration Parameters.

4.40.3. Examples

<service name="SSH" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="1"/>
  <parameter key="banner" value="SSH"/>
  <parameter key="client-banner" value="OpenNMS poller"/>
  <parameter key="timeout" value="5000"/>
  <parameter key="rrd-repository" value="/var/lib/opennms/rrd/response"/>
  <parameter key="rrd-base-name" value="ssh"/>
  <parameter key="ds-name" value="ssh"/>
</service>
<monitor service="SSH" class-name="org.opennms.netmgt.poller.monitors.SshMonitor"/>

4.41. SSLCertMonitor

This monitor is used to test if a SSL certificate presented by a remote network server are valid. A certificate is invalid if its initial time is prior to the current time, or if the current time is prior to 7 days (configurable) before the expiration time. The monitor only supports SSL on the socket and does not support a higher level protocol above it.

You can simulate the behavior by running a command like this:

echo | openssl s_client -connect <site>:<port> 2>/dev/null | openssl x509 -noout -dates

The output shows you the time range a certificate is valid:

notBefore=Dec 24 14:11:34 2013 GMT
notAfter=Dec 25 10:37:40 2014 GMT

You can configure a threshold in days applied on the notAfter date.

4.41.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.SSLCertMonitor

Remote Enabled

true

4.41.2. Configuration and Usage

Table 57. Monitor specific parameters for the SSLCertMonitor
Parameter Description Required Default value

port

TCP port for the service with SSL certificate.

required

-1

retry

Number of attempts to get the certificate state

optional

0

days

Number of days before the certificate expires that we mark the service as failed.

optional

7

server-name

This is the DNS hostname to send as part of the TLS negotiation, known as server name indication (SNI) (See: RFC3546 section 3.1)

optional

-

This monitor implements the Common Configuration Parameters.

Table 58. Variables which can be passed in the configuration for server-name
Variable Description

${ipaddr}

The node’s IP-Address

${nodeid}

The node ID

${nodelabel}

Label of the node the monitor is associated to.

${svcname}

The service name

The monitor has no support for communicating on other protocol layers above the SSL session layer. It is not able to send a Host header for HTTPS, or issue a STARTTLS command for IMAP, POP3, SMTP, FTP, XMPP, LDAP, or NNTP.

4.41.3. Examples

The following example shows how to monitor SSL certificates on services like IMAPS, SMTPS and HTTPS. If the certificates expire within 30 days the service goes down and indicates this issue in the reason of the monitor. In this example the monitoring interval is reduced to test the certificate every 2 hours (7,200,000 ms). Configuration in poller-configuration.xml is as the following:

<service name="SSL-Cert-IMAPS-993" interval="7200000" user-defined="false" status="on">
    <parameter key="retry" value="2"/>
    <parameter key="timeout" value="2000"/>
    <parameter key="port" value="993"/>
    <parameter key="days" value="30"/>
</service>
<service name="SSL-Cert-SMTPS-465" interval="7200000" user-defined="false" status="on">
    <parameter key="retry" value="2"/>
    <parameter key="timeout" value="2000"/>
    <parameter key="port" value="465"/>
    <parameter key="days" value="30"/>
</service>
<service name="SSL-Cert-HTTPS-443" interval="7200000" user-defined="false" status="on">
    <parameter key="retry" value="2"/>
    <parameter key="timeout" value="3000"/>
    <parameter key="port" value="443"/>
    <parameter key="days" value="30"/>
    <parameter key="server-name" value="${nodelabel}.example.com"/>
</service>

<monitor service="SSL-Cert-IMAPS-993" class-name="org.opennms.netmgt.poller.monitors.SSLCertMonitor" />
<monitor service="SSL-Cert-SMTPS-465" class-name="org.opennms.netmgt.poller.monitors.SSLCertMonitor" />
<monitor service="SSL-Cert-HTTPS-443" class-name="org.opennms.netmgt.poller.monitors.SSLCertMonitor" />

4.42. StrafePingMonitor

This monitor is used to monitor packet delay variation to a specific endpoint using ICMP. The main use case is to monitor a WAN end point and visualize packet loss and ICMP packet round trip time deviation. The StrafePingMonitor performs multiple ICMP echo requests (ping) and stores the response-time of each as well as the packet loss, in a RRD file. Credit is due to Tobias Oetiker, as this graphing feature is an adaptation of the SmokePing tool that he developed.

01 strafeping
Figure 4. Visualization of a graph from the StrafePingMonitor

4.42.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.StrafePingMonitor

Remote Enabled

false

4.42.2. Configuration and Usage

Monitor specific parameters for the StrafePingMonitor

Parameter Description Required Default value

timeout

Time in milliseconds to wait before assuming that a packet has not responded

optional

800

retry

The number of retries to attempt when a packet fails to respond in the given timeout

optional

2

ping-count

The number of pings to attempt each interval

required

20

failure-ping-count

The number of pings that need to fail for the service to be considered down

required

20

allow-fragmentation

Whether to set the "Don’t Fragment" bit on outgoing packets

optional

true

dscp

DSCP traffic-control value.

optional

0

packet-size

Number of bytes of the ICMP packet to send.

optional

64

wait-interval

Time in milliseconds to wait between each ICMP echo-request packet

required

50

rrd-repository

The location to write RRD data. Generally, you will not want to change this from default

required

$OPENNMS_HOME/share/rrd/response

rrd-base-name

The name of the RRD file to write (minus the extension, .rrd or .jrb)

required

strafeping

This monitor implements the Common Configuration Parameters.

4.42.3. Examples

The StrafePingMonitor is typically used on WAN connections and not activated for every ICMP enabled device in your network. Further this monitor is much I/O heavier than just a simple RRD graph with a single ICMP response time measurement. By default you can find a separate poller package in the 'poller-configuration.xml' called strafer. Configure the include-range or a filter to enable monitoring for devices with the service StrafePing.

Don’t forget to assign the service StrafePing on the IP interface to be activated.

The following example enables the monitoring for the service StrafePing on IP interfaces in the range 10.0.0.1 until 10.0.0.20. Additionally the Nodes have to be in a surveillance category named Latency.

<package name="strafer" >
   <filter>categoryName == 'Latency'</filter>
   <include-range begin="10.0.0.1" end="10.0.0.20"/>
   <rrd step="300">
     <rra>RRA:AVERAGE:0.5:1:2016</rra>
     <rra>RRA:AVERAGE:0.5:12:1488</rra>
     <rra>RRA:AVERAGE:0.5:288:366</rra>
     <rra>RRA:MAX:0.5:288:366</rra>
     <rra>RRA:MIN:0.5:288:366</rra>
   </rrd>
   <service name="StrafePing" interval="300000" user-defined="false" status="on">
     <parameter key="retry" value="0"/>
     <parameter key="timeout" value="3000"/>
     <parameter key="ping-count" value="20"/>
     <parameter key="failure-ping-count" value="20"/>
     <parameter key="wait-interval" value="50"/>
     <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
     <parameter key="rrd-base-name" value="strafeping"/>
   </service>
   <downtime interval="30000" begin="0" end="300000"/>
   <downtime interval="300000" begin="300000" end="43200000"/>
   <downtime interval="600000" begin="43200000" end="432000000"/>
   <downtime begin="432000000" delete="true"/>
 </package>
 <monitor service="StrafePing" class-name="org.opennms.netmgt.poller.monitors.StrafePingMonitor"/>

4.43. TcpMonitor

This monitor is used to test IP Layer 4 connectivity using TCP. The monitor establishes an TCP connection to a specific port. To test the availability of the service, the greetings banner of the application is evaluated. The behavior is similar to a simple test using the telnet command as shown in the example.

Simulating behavior of the monitor with telnet
root@vagrant:~# telnet 127.0.0.1 22
Trying 127.0.0.1...
Connected to 127.0.0.1.
Escape character is '^]'.
SSH-2.0-OpenSSH_6.6.1p1 Ubuntu-2ubuntu2 (1)
1 Service greeting banner

4.43.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.TcpMonitor

Remote Enabled

true

4.43.2. Configuration and Usage

Table 59. Monitor specific parameters for the TcpMonitor
Parameter Description Required Default value

port

TCP port of the application.

required

-1

retry

Number of retries before the service is marked as down.

optional

0

banner

Evaluation of the service connection banner with regular expression. By default any banner result is valid.

optional

*

This monitor implements the Common Configuration Parameters.

4.43.3. Examples

This example shows to test if the ICA service is available on TCP port 1494. The test evaluates the connection banner starting with ICA.

<service name="TCP-Citrix-ICA" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="0" />
  <parameter key="banner" value="ICA" />
  <parameter key="port" value="1494" />
  <parameter key="timeout" value="3000" />
  <parameter key="rrd-repository" value="/var/lib/opennms/rrd/response" />
  <parameter key="rrd-base-name" value="tcpCitrixIca" />
  <parameter key="ds-name" value="tcpCitrixIca" />
</service>

<monitor service="TCP-Citrix-ICA" class-name="org.opennms.netmgt.poller.monitors.TcpMonitor" />

4.44. SystemExecuteMonitor

If it is required to execute a system call or run a script to determine a service status, the SystemExecuteMonitor can be used. It is calling a script or system command, if required it provides additional arguments to the call. To determine the status of the service the SystemExecuteMonitor can rely on 0 or a non-0 exit code of system call. As an alternative, the output of the system call can be matched against a banner. If the banner is part of the output the status is interpreted as up. If the banner is not available in the output the status is determined as down.

4.44.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.SystemExecuteMonitor

Remote Enabled

true

4.44.2. Configuration and Usage

Table 60. Monitor specific parameters for the SystemExecuteMonitor
Parameter Description Required Default value

script

The system-call to execute.

required

-

args

The arguments to hand over to the system-call. It supports variable replacement, see below.

optional

-

banner

A string that is match against the output of the system-call. If the output contains the banner, the service is determined as UP.

optional

-

The parameter args supports variable replacement for the following set of variables.

This monitor implements the Common Configuration Parameters.

Table 61. Variables which can be used in the configuration
Variable Description

${timeout}

Timeout in milliseconds, based on config of the service.

${timeoutsec}

Timeout in seconds, based on config of the service.

${retry}

Amount of retries based on config of the service.

${svcname}

Service name based on the config of the service.

${ipaddr}

IP-address of the interface the service is bound to.

${nodeid}

Nodeid of the node the monitor is associated to.

${nodelabel}

Nodelabel of the node the monitor is associated to.

4.44.3. Examples

<parameter key="args" value="-i ${ipaddr} -t ${timeout}"/>
<parameter key="args" value="http://${nodelabel}/${svcname}/static"/>

4.44.4. SystemExecuteMonitor vs GpMonitor

The SystemExecuteMonitor is the successor of the GpMonitor. The main differences are:

  • Variable replacement for the parameter args

  • There are no fixed arguments handed to the system-call

  • The SystemExecuteMonitor supports RemotePoller deployment

To migrate services from the GpMonitor to the SystemExecuteMonitor it is required to alter the parameter args. To match the arguments called hoption for the hostAddress and toption for the timeoutInSeconds. The args string that matches the GpMonitor call looks like this:

<parameter key="args" value="--hostname ${ipaddr} --timeout ${timeoutsec}" />

To migrate the GpMonitor parameters hoption and toption just replace the --hostname and --timeout directly in the args key.

4.45. VmwareCimMonitor

This monitor is part of the VMware integration provided in Provisiond. The monitor is specialized to test the health status provided from all Host System (host) sensor data.

This monitor is only executed if the host is in power state on.
This monitor requires to import hosts with Provisiond and the VMware import. OpenNMS Horizon requires network access to VMware vCenter and the hosts. To get the sensor data the credentials from vmware-config.xml for the responsible vCenter is used. The following asset fields are filled from Provisiond and is provided by VMware import feature: VMware Management Server, VMware Managed Entity Type and the foreignId which contains an internal VMware vCenter Identifier.

The global health status is evaluated by testing all available host sensors and evaluating the state of each sensor. A sensor state could be represented as the following:

  • Unknown(0)

  • OK(5)

  • Degraded/Warning(10)

  • Minor failure(15)

  • Major failure(20)

  • Critical failure(25)

  • Non-recoverable error(30)

The service is up if all sensors have the status OK(5). If any sensor gives another status then OK(5) the service is marked as down. The monitor error reason contains a list of all sensors which not returned status OK(5).

In case of using Distributed Power Management the standBy state forces a service down. The health status is gathrered with a direct connection to the host and in stand by this connection is unavailable and the service is down. To deal with stand by states, the configuration ignoreStandBy can be used. In case of a stand by state, the service is considered as up.

state can be changed see the ignoreStandBy configuration parameter.

4.45.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.VmwareCimMonitor

Remote Enabled

false

4.45.2. Configuration and Usage

Table 62. Monitor specific parameters for the VmwareCimMonitor
Parameter Description Required Default value

retry

Number of retries before the service is marked as down.

optional

0

ignoreStandBy

Treat power state standBy as up.

optional

false

This monitor implements the Common Configuration Parameters.

4.45.3. Examples

Some example configuration how to configure the monitor in the poller-configuration.xml.

<service name="VMwareCim-HostSystem" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="2"/>
  <parameter key="timeout" value="3000"/>
</service>

<monitor service="VMwareCim-HostSystem" class-name="org.opennms.netmgt.poller.monitors.VmwareCimMonitor"/>

4.46. VmwareMonitor

This monitor is part of the VMware integration provided in Provisiond and test the power state of a virtual machine (VM) or a host system (host). If the power state of a VM or host is poweredOn the service is up. The state off the service on the VM or Host is marked as down. By default standBy is also considered as down. In case of using Distributed Power Management the standBy state can be changed see the ignoreStandBy configuration parameter.

The information for the status of a virtual machine is collected from the responsible VMware vCenter using the credentials from the vmware-config.xml. It is also required to get specific asset fields assigned to an imported virtual machine and host system. The following asset fields are required, which are populated by the VMware integration in Provisiond: VMware Management Server, VMware Managed Entity Type and the foreignId which contains an internal VMware vCenter Identifier.

4.46.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.VmwareMonitor

Remote Enabled

false

4.46.2. Configuration and Usage

Table 63. Monitor specific parameters for the VmwareMonitor
Parameter Description Required Default value

retry

Number of retries before the service is marked as down.

optional

0

ignoreStandBy

Treat power state standBy as up.

optional

false

This monitor implements the Common Configuration Parameters.

4.46.3. Examples

Some example configuration how to configure the monitor in the poller-configuration.xml.

<service name="VMware-ManagedEntity" interval="300000" user-defined="false" status="on">
  <parameter key="retry" value="2"/>
  <parameter key="timeout" value="3000"/>
</service>

<monitor service="VMware-ManagedEntity" class-name="org.opennms.netmgt.poller.monitors.VmwareMonitor"/>

4.47. Win32ServiceMonitor

The Win32ServiceMonitor enables OpenNMS Horizon to monitor the running state of any Windows service. The service status is monitored using the Microsoft Windows® provided SNMP agent providing the LAN Manager MIB-II. For this reason it is required the SNMP agent and OpenNMS Horizon is correctly configured to allow queries against part of the MIB tree. The status of the service is monitored by polling the

svSvcOperatingState = 1.3.6.1.4.1.77.1.2.3.1.3

of a given service by the display name.

4.47.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.Win32ServiceMonitor

Remote Enabled

false

4.47.2. Configuration and Usage

Table 64. Monitor specific parameters for the Win32ServiceMonitor
Parameter Description Required Default value

service-name

The name of the service, this should be the exact name of the Windows service to monitor as it appears in the Services MSC snap-in. Short names such as you might use with net start will not work here.

required

Server

This monitor implements the Common Configuration Parameters.

Non-English Windows The service-name is sometime encoded in languages other than English. Like in French, the Task Scheduler service is Planificateur de tâche. Because of the "â" (non-English character), the OID value is encoded in hexa (0x50 6C 61 6E 69 66 69 63 61 74 65 75 72 20 64 65 20 74 C3 A2 63 68 65 73).

4.47.3. Troubleshooting

If you’ve created a Win32ServiceMonitor poller and are having difficulties with it not being monitored properly on your hosts, chances are there is a difference in the name of the service you’ve created, and the actual name in the registry.

For example, I need to monitor a process called Example Service on one of our production servers. I retrieve the Display name from looking at the service in service manager, and create an entry in the poller-configuration.xml files using the exact name in the Display name field.

However, what I don’t see is the errant space at the end of the service display name that is revealed when doing the following:

snmpwalk -v 2c -c <communitystring> <hostname> .1.3.6.1.4.1.77.1.2.3.1.1

This provides the critical piece of information I am missing:

iso.3.6.1.4.1.77.1.2.3.1.1.31.83.116.97.102.102.119.97.114.101.32.83.84.65.70.70.86.73.69.87.32.66.97.99.107.103.114.111.117.110.100.32 = STRING: "Example Service "
Note the extra space before the close quote.

The extra space at the end of the name was difficult to notice in the service manager GUI, but is easily visible in the snmpwalk output. The right way to fix this would be to correct the service Display name field on the server, however, the intent of this procedure is to recommend verifying the true name using snmpwalk as opposed to relying on the service manager GUI.

4.47.4. Examples

Monitoring the service running state of the Task Scheduler on an English local Microsoft Windows® Server requires at minimum the following entry in the poller-configuration.xml.

<service name="Windows-Task-Scheduler" interval="300000" user-defined="false" status="on">
    <parameter key="service-name" value="Task Scheduler"/>
</service>

<monitor service="Windows-Task-Scheduler" class-name="org.opennms.netmgt.poller.monitors.Win32ServiceMonitor"/>

4.48. WsManMonitor

This monitor can be used to issue a WS-Man Get command and validate the results using a SPEL expression.

4.48.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.WsManMonitor

Remote Enabled

false

4.48.2. Configuration and Usage

Table 65. Monitor specific parameters for the WsManMonitor
Parameter Description Required Default value

resource-uri

Resource URI

required

-

rule

SPEL expression applied against the result of the Get

required

-

selector.

Used to filter the result set. All selectors must prefixed with selector.

optional

(None)

This monitor implements the Common Configuration Parameters.

4.48.3. Examples

The following monitor will issue a Get against the configured resource and verify that the correct service tag is returned:

<service name="WsMan-ServiceTag-Check" interval="300000" user-defined="false" status="on">
  <parameter key="resource-uri" value="http://schemas.dell.com/wbem/wscim/1/cim-schema/2/root/dcim/DCIM_ComputerSystem"/>
  <parameter key="selector.CreationClassName" value="DCIM_ComputerSystem"/>
  <parameter key="selector.Name" value="srv:system"/>
  <parameter key="rule" value="#IdentifyingDescriptions matches '.*ServiceTag' and #OtherIdentifyingInfo matches 'C7BBBP1'"/>
</service>

<monitor service="WsMan-ServiceTag-Check" class-name="org.opennms.netmgt.poller.monitors.WsManMonitor/>

4.49. XmpMonitor

The XMP monitor tests for XMP service/agent availability by establishing an XMP session and querying the target agent’s sysObjectID variable contained in the Core MIB. The service is considered available when the session attempt succeeds and the agent returns its sysObjectID without error.

4.49.1. Monitor facts

Class Name

org.opennms.netmgt.poller.monitors.XmpMonitor

Remote Enabled

false

4.49.2. Configuration and Usage

These parameters can be set in the XMP service entry in collectd-configuration.xml and will override settings from xmp-config.xml. Also, don’t forget to add an entry in response-graph.properties so that response values will be graphed.

Table 66. Monitor specific parameters for the XmpMonitor
Parameter Description Required Default value

timeout

Time in milliseconds to wait for a successful session.

optional

5000

authenUser

The authenUser parameter for use with the XMP session.

optional

xmpUser

port

TCP port to connect to for XMP session establishment

optional

5270

mib

Name of MIB to query

optional

core

object

Name of MIB object to query

optional

sysObjectID

This monitor implements the Common Configuration Parameters.

4.49.3. Examples

Adding entry in collectd-configuration.xml
<service name="XMP" interval="300000" user-defined="false" status="on">
  <parameter key="timeout" value="3000"/>
  <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response"/>
  <parameter key="rrd-base-name" value="xmp"/>
  <parameter key="ds-name" value="xmp"/>
</service>
<monitor service="XMP" class-name="org.opennms.netmgt.poller.monitors.XmpMonitor"/>
Add entry in response-graph.properties
reports=icmp, \
xmp, \ . . . .

report.xmp.name=XMP
report.xmp.columns=xmp
report.xmp.type=responseTime
report.xmp.command=--title="XMP Response Time" \
 --vertical-label="Seconds" \
 DEF:rtMills={rrd1}:xmp:AVERAGE \
 DEF:minRtMills={rrd1}:xmp:MIN \
 DEF:maxRtMills={rrd1}:xmp:MAX \
 CDEF:rt=rtMills,1000,/ \
 CDEF:minRt=minRtMills,1000,/ \
 CDEF:maxRt=maxRtMills,1000,/ \
 LINE1:rt#0000ff:"Response Time" \
 GPRINT:rt:AVERAGE:" Avg  \\: %8.2lf %s" \
 GPRINT:rt:MIN:"Min  \\: %8.2lf %s" \
 GPRINT:rt:MAX:"Max  \\: %8.2lf %s\\n"

5. Data Collectors

5.1. SnmpCollector

The SnmpCollector is used to collect performance data through the SNMP protocol. Access to the SNMP Agent is configured through the SNMP configuration in the Web User Interface.

5.1.1. Collector Facts

Class Name

org.opennms.netmgt.collectd.SnmpCollector

Package

core

Supported on Minion

Yes (via the SNMP proxy)

5.1.2. Collector Parameters

Table 67. Collector specific parameters for the SnmpCollector
Parameter Description Required Default value

collection

The name of the SNMP Collection to use.

required

default

thresholding-enabled

Whether collected performance data shall be tested against thresholds.

optional

true

timeout

Timeout in milliseconds to wait for SNMP responses.

optional

SNMP configuration

5.1.3. SNMP Collection Configuration

SNMP Collection are defined in the etc/datacollection-config.xml and etc/datacollection.d/*.xml files.

<?xml version="1.0"?>
<datacollection-config rrd-repository="/var/lib/opennms/rrd/snmp/">(1)
    <snmp-collection name="default"(2)
                     snmpStorageFlag="select">(3)
        <rrd step="300">(4)
            <rra>RRA:AVERAGE:0.5:1:2016</rra>
            <rra>RRA:AVERAGE:0.5:12:1488</rra>
            <rra>RRA:AVERAGE:0.5:288:366</rra>
            <rra>RRA:MAX:0.5:288:366</rra>
            <rra>RRA:MIN:0.5:288:366</rra>
        </rrd>

        <include-collection dataCollectionGroup="MIB2"/>(5)
        <include-collection dataCollectionGroup="3Com"/>
        ...
        <include-collection dataCollectionGroup="VMware-Cim"/>
    </snmp-collection>
</datacollection-config>
1 Directory where to persist RRD files on the file system, ignored if NewTS is used as time series storage.
2 Name of the SNMP data collection referenced in the Collection Package in collectd-configuration.xml.
3 Configure SNMP MIB-II interface metric collection behavior: all means collect metrics from all interfaces, primary only from interface provisioned as primary interface, select only from manualy selected interfaces from the Web UI.
4 RRD archive configuration for this set of performance metrics, ignored when NewTS is used as time series storage.
5 Include device or application specific performance metric OIDS to collect.
01 snmp collector
Figure 5. Configuration overview for SNMP data collection

5.2. WsManCollector

The WsManCollector collects peformance metrics using the Web Services-Management (WS-Management) protocol.

Web Services-Management (WS-Management) is a DMTF open standard defining a SOAP-based protocol for the management of servers, devices, applications and various Web services. Windows Remote Management (WinRM) is the Microsoft implementation of WS-Management Protocol.

5.2.1. Collector Facts

Class Name

org.opennms.netmgt.collectd.WsManCollector

Package

core

Supported on Minion

Yes

5.2.2. Collector Parameters

Table 68. Collector specific parameters for the WsManCollector
Parameter Description Required Default value

collection

The name of the WS-Man Collection to use

required

5.2.3. WS-Management Setup

Before setting up OpenNMS Horizon to communicate with a WS-Management agent, you should confirm that it is properly configured and reachable from the OpenNMS Horizon system. If you need help enabling the WS-Management agent, consult the documentation from the manufacturer. Here are some link resources that could help:

We suggest using the Openwsman command line client for validating authentication and connectivity. Packages are available for most distributions under wsmancli.

For example:

wsman identify -h localhost -P 5985 -u wsman -p secret

Once validated, add the agent specific details to the OpenNMS Horizon configuration, defined in the next section.

Troubleshooting and Commands

For troubleshooting there is a set of commands you can use in Powershell verified on Microsoft Windows Server 2012.

Enable WinRM in PowerShell
Enable-PSRemoting
Setup Firewall for WinRM over HTTP
netsh advfirewall firewall add rule name="WinRM-HTTP" dir=in localport=5985 protocol=TCP action=allow
Setup Firewall for WinRM over HTTPS
netsh advfirewall firewall add rule name="WinRM-HTTPS" dir=in localport=5986 protocol=TCP action=allow
Test WinRM on local Windows Server
winrm id
Show WinRM configuration on Windows Server
winrm get winrm/config
Show listener for configuration on Windows Server
winrm e winrm/config/listener
Test connectivity from a Linux system
nc -z -w1 <windows-server-ip-or-host> 5985;echo $?
Use BasicAuthentication just with WinRM over HTTPS with verifiable certificates in production environment.
Enable BasicAuthentication
winrm set winrm/config/client/auth '@{Basic="true"}'
winrm set winrm/config/service/auth '@{Basic="true"}'
winrm set winrm/config/service '@{AllowUnencrypted="true"}'

5.2.4. WS-Management Agent Configuration

The agent specific configuration details are maintained in etc/wsman-config.xml. This file has a similar structure as etc/snmp-config.xml, which the reader may already be familiar with.

This file is consulted when a connection to a WS-Man Agent is made. If the IP address of the agent is matched by the range, specific or ip-match elements of a definition, then the attributes on that definition are used to connect to the agent. Otherwise, the attributes on the outer wsman-config definition are used.

This etc/wsman-config.xml files is automatically reloaded when modified.

Here is an example with several definitions:

<?xml version="1.0"?>
<wsman-config retry="3" timeout="1500" ssl="true" strict-ssl="false" path="/wsman">
    <definition ssl="true" strict-ssl="false" path="/wsman" username="root" password="calvin" product-vendor="Dell" product-version="iDRAC 6">
        <range begin="192.168.1.1" end="192.168.1.10"/>
    </definition>
    <definition ssl="false" port="5985" path="/wsman" username="Administrator" password="P@ssword">
        <ip-match>172.23.1-4.1-255</ip-match>
        <specific>172.23.1.105</specific>
    </definition>
</wsman-config>
Table 69. Collector configuration attributes
Attribute Description Default

timeout

HTTP Connection and response timeout in milliseconds.

HTTP client default

retry

Number of retries on connection failure.

0

username

Username for basic authentication.

none

password

Password used for basic authentication.

none

port

HTTP/S port

Default for protocol

max-elements

Maximum number of elements to retrieve in a single request.

no limit

ssl

Enable SSL

False

strict-ssl

Enforce SSL certificate verification.

True

path

Path in the URL to the WS-Management service.

/

product-vendor

Used to overwrite the detected product vendor.

none

product-version

Used to overwrite the detected product version.

none

gss-auth

Enables GSS authentication. When enabled a reverse lookup is performed on the target IP address in order to determine the canonical host name.

False

If you try to connect against Microsoft Windows Server make sure to set specific ports for WinRM connections. By default Microsoft Windows Server uses port TCP/5985 for plain text and port TCP/5986 for SSL connections.

5.2.5. WS-Management Collection Configuration

Configuration for the WS-Management collector is stored in etc/wsman-datacollection-config.xml and etc/wsman-datacollection.d/*.xml.

The contents of these files are automatically merged and reloaded when changed. The default WS-Management collection looks as follows:
<?xml version="1.0"?>
<wsman-datacollection-config rrd-repository="${install.share.dir}/rrd/snmp/">
    <collection name="default">
        <rrd step="300">
            <rra>RRA:AVERAGE:0.5:1:2016</rra>
            <rra>RRA:AVERAGE:0.5:12:1488</rra>
            <rra>RRA:AVERAGE:0.5:288:366</rra>
            <rra>RRA:MAX:0.5:288:366</rra>
            <rra>RRA:MIN:0.5:288:366</rra>
        </rrd>

        <!--
             Include all of the available system definitions
         -->
        <include-all-system-definitions/>
    </collection>
</wsman-datacollection-config>

The magic happens with the <include-all-system-definitions/> element which automatically includes all of the system definitions into the collection group.

If required, you can include a specific system-definition with <include-system-definition>sys-def-name</include-system-definition>.

System definitions and related groups can be defined in the root etc/wsman-datacollection-config.xml file, but it is preferred that be added to a device specific configuration files in etc/wsman-datacollection-config.d/*.xml.

Avoid modifying any of the distribution configuration files and create new ones to store you specific details instead.

Here is an example configuration file for a Dell iDRAC:

<?xml version="1.0"?>
<wsman-datacollection-config>
    <group name="drac-system"
           resource-uri="http://schemas.dell.com/wbem/wscim/1/cim-schema/2/root/dcim/DCIM_ComputerSystem"
           resource-type="node">
        <attrib name="OtherIdentifyingInfo" index-of="#IdentifyingDescriptions matches '.*ServiceTag'" alias="serviceTag" type="String"/>
    </group>

    <group name="drac-power-supply"
           resource-uri="http://schemas.dmtf.org/wbem/wscim/1/*"
           dialect="http://schemas.microsoft.com/wbem/wsman/1/WQL"
           filter="select InputVoltage,InstanceID,PrimaryStatus,SerialNumber,TotalOutputPower from DCIM_PowerSupplyView where DetailedState != 'Absent'"
           resource-type="dracPowerSupplyIndex">
        <attrib name="InputVoltage" alias="inputVoltage" type="Gauge"/>
        <attrib name="InstanceID" alias="instanceId" type="String"/>
        <attrib name="PrimaryStatus" alias="primaryStatus" type="Gauge"/>
        <attrib name="SerialNumber" alias="serialNumber" type="String"/>
        <attrib name="TotalOutputPower" alias="totalOutputPower" type="Gauge"/>
    </group>

    <system-definition name="Dell iDRAC (All Version)">
        <rule>#productVendor matches '^Dell.*' and #productVersion matches '.*iDRAC.*'</rule>
        <include-group>drac-system</include-group>
        <include-group>drac-power-supply</include-group>
    </system-definition>
</wsman-datacollection-config>
System Definitions

Rules in the system definition are written using SpEL expressions.

The expression has access to the following variables in it`s evaluation context:

Name Type

(root)

org.opennms.netmgt.model.OnmsNode

agent

org.opennms.netmgt.collection.api.CollectionAgent

productVendor

java.lang.String

productVersion

java.lang.String

If a particular agent is matched by any of the rules, then the collector will attempt to collect the referenced groups from the agent.

Group Definitions

Groups are retrieved by issuing an Enumerate command against a particular Resource URI and parsing the results. The Enumerate commands can include an optional filter in order to filter the records and attributes that are returned.

When configuring a filter, you must also specify the dialect.

The resource type used by the group must of be of type node or a generic resource type. Interface level resources are not supported.

When using a generic resource type, the IndexStorageStrategy cannot be used since records have no implicit index. Instead, you must use an alternative such as the SiblingColumnStorageStrategy.

If a record includes a multi-valued key, you can collect the value at a specific index with an index-of expression. This is best demonstrated with an example. Let`s assume we wanted to collect the ServiceTag from the following record:

<IdentifyingDescriptions>CIM:GUID</IdentifyingDescriptions>
<IdentifyingDescriptions>CIM:Tag</IdentifyingDescriptions>
<IdentifyingDescriptions>DCIM:ServiceTag</IdentifyingDescriptions>
<OtherIdentifyingInfo>45454C4C-3700-104A-8052-C3C01BB25031</OtherIdentifyingInfo>
<OtherIdentifyingInfo>mainsystemchassis</OtherIdentifyingInfo>
<OtherIdentifyingInfo>C8BBBP1</OtherIdentifyingInfo>

Specifying, the attribute name OtherIdentifyingInfo would not be sufficient, since there are multiple values for that key. Instead, we want to retrieve the value for the OtherIdentifyingInfo key at the same index where IdentifyingDescriptions is set to DCIM:ServiceTag.

This can be achieved using the following attribute definition:

<attrib name="OtherIdentifyingInfo" index-of="#IdentifyingDescriptions matches '.*ServiceTag'" alias="serviceTag" type="String"/>

5.3. JmxCollector

The JmxCollector is used to collect performance data via JMX. Attributes are extracted from the available MBeans.

5.3.1. Collector Facts

Class Name

org.opennms.netmgt.collectd.Jsr160Collector

Package

core

Supported on Minion

Yes

5.3.2. Collector Parameters

Table 70. Collector specific parameters for the Jsr160Collector
Parameter Description Required Default value

collection

The name of the JMX Collection to use

required

(none)

thresholding-enabled

Whether collected performance data shall be tested against thresholds

optional

true

retry

Number of retries

optional

3

friendlyName

Name of the path in which the metrics should be stored

optional

Value of the port, or 'jsr160' if no port is set.

factory

The password strategy to use. Supported values are: STANDARD (for authentication), PASSWORD_CLEAR (same as STANDARD) and SASL (if secure connection is required)

optional

STANDARD

url

The connection url, e.g. service:jmx:rmi:localhost:18980. The ip address can be substituted. Use ${ipaddr} in that case, e.g.: service:jmx:rmi:${ipaddr}:18980

optional

(none)

username

The username if authentication is required.

optional

(none)

password

The password if authentication is required.

optional

(none)

port

Deprecated. JMX port.

optional

1099

protocol

Deprecated. Protocol used in the JMX connection string.

optional

rmi

urlPath

Deprecated. Path used in JMX connection string.

optional

/jmxrmi

rmiServerPort

Deprecated. RMI port.

optional

45444

remoteJMX

Deprecated. Use an alternative JMX URL scheme.

optional

false

The parameters port, protocol, urlPath, rmiServerPort and remoteJMX are deprecated and should be replaced with the url parameter. If url is not defined the collector falls back to Legacy Mode and the deprecated parameters are used instead to build the connection url.
If a service requires different configuration it can be overwritten with an entry in $OPENNMS_HOME/etc/jmx-config.xml.

5.3.3. JMX Collection Configuration

JMX Collections are defined in the etc/jmx-datacollection-config.xml and etc/jmx-datacollection-config.d/.

Here is a snippet providing a collection definition named opennms-poller:

<jmx-collection name="opennms-poller">
    <rrd step="300">
        <rra>RRA:AVERAGE:0.5:1:2016</rra>
        <rra>RRA:AVERAGE:0.5:12:1488</rra>
        <rra>RRA:AVERAGE:0.5:288:366</rra>
        <rra>RRA:MAX:0.5:288:366</rra>
        <rra>RRA:MIN:0.5:288:366</rra>
    </rrd>
    <mbeans>
        <mbean name="OpenNMS Pollerd" objectname="OpenNMS:Name=Pollerd">
            <attrib name="NumPolls" alias="ONMSPollCount" type="counter"/>
        </mbean>
    </mbeans>
</jmx-collection>

Once added to etc/jmx-datacollection-config.xml you can test it using the collect command available in the Karaf Shell:

collection:collect org.opennms.netmgt.collectd.Jsr160Collector 127.0.0.1 collection=opennms-poller port=18980

5.3.4. Generic Resource Type

In order to support wildcard (*) in objectname, JMX collector supports generic resource types. Two changes needed to jmx configuration for this to work.

  • Create a custom resource type in etc/resource-types.d/ for ex: there is already a definition in jmx-resource.xml which defines a custom resource for kafka lag

<resource-types>
    <resourceType name="kafkaLag" label="Kafka Lag"
                  resourceLabel="${index}">
      <persistenceSelectorStrategy class="org.opennms.netmgt.collection.support.PersistAllSelectorStrategy"/>
      <storageStrategy class="org.opennms.netmgt.dao.support.SiblingColumnStorageStrategy">
		   <parameter key="sibling-column-name" value="name" />
      </storageStrategy>
    </resourceType>
</resource-types>
  • Match the resourceType name as resource-type in mbean definition

<mbean name="org.opennms.core.ipc.sink.kafka.heartbeat" resource-type="kafkaLag" objectname="org.opennms.core.ipc.sink.kafka:name=OpenNMS.Sink.*.Lag">
   <attrib name="Value" alias="Lag" type="gauge"/>
</mbean>
Resource definition

JMX objectname is the full name of Mbean in form of ( domain:key=value, key=value, ..). Wildcard (*) can exist anywhere in the objectname.

Depending on wildcard definition, use SiblingColumnStorageStrategy to extract resource label. If wildcard exists in the value ( usual case), use corresponding key as the sibling-column-name parameter. for ex: org.apache.activemq:BrokerName=*,Type=Queue,Destination=com.mycompany.myqueue

Here BrokerName can be defined as parameter for SiblingColumnStorageStrategy

   <parameter key="sibling-column-name" value="BrokerName" />

The extracted BrokerNames from the wildcard will be the resource folders in the form of nodeId/resourceTypeName/{resource-label}

Wildcard may exist in domain as well, for ex: org.apache.*:BrokerName=trap, Type=Queue. Then domain can be defined as the sibling-column-name parameter.

  <parameter key="sibling-column-name" value="domain" />

The objectname itself can be used as resource label, simply use IndexStorageStrategy as storageStrategy in resource-type definition.

5.3.5. 3rd Party JMX Services

Some java applications provide their own JMX implementation and require certain libraries to be present on the classpath, e.g. the java application server Wildfly. In order to successfully collect data the following steps may be required:

  • Place the jmx client lib to the $OPENNMS_HOME/lib folder (e.g. jboss-cli-client.jar)

  • Configure the JMX-Collector accordingly (see below)

  • Configure the collection accordingly (see above)

Example
<service name="JMX-WILDFLY" interval="300000" user-defined="false" status="on">
    <parameter key="url" value="service:jmx:http-remoting-jmx://${ipaddr}:9990"/>
    <parameter key="retry" value="2"/>
    <parameter key="timeout" value="3000"/>
    <parameter key="factory" value="PASSWORD-CLEAR"/>
    <parameter key="username" value="admin"/>
    <parameter key="password" value="admin"/>
    <parameter key="rrd-base-name" value="java"/>
    <parameter key="collection" value="jsr160"/>
    <parameter key="thresholding-enabled" value="true"/>
    <parameter key="ds-name" value="jmx-wildfly"/>
    <parameter key="friendly-name" value="jmx-wildfly"/>
</service>
<collector service="JMX-WILDFLY" class-name="org.opennms.netmgt.collectd.Jsr160Collector"/>

5.4. VmwareCimCollector

The VmwareCimCollector collects ESXi host and sensor metrics from vCenter.

5.4.1. Collector Facts

Class Name

org.opennms.netmgt.collectd.VmwareCimCollector

Package

core

Supported on Minion

Yes

5.4.2. Collector Parameters

Table 71. Collector specific parameters for the VmwareCimCollector
Parameter Description Required Default value

collection

The name of the VMWare CIM Collection to use

required

timeout

Connection timeout in milliseconds

optional

5.5. VmwareCollector

The VmwareCollector collects peformance metrics for managed entities from vCenter.

5.5.1. Collector Facts

Class Name

org.opennms.netmgt.collectd.VmwareCollector

Package

core

Supported on Minion

Yes

5.5.2. Collector Parameters

Table 72. Collector specific parameters for the VmwareCollector
Parameter Description Required Default value

collection

The name of the VMWare Collection to use

required

timeout

Connection timeout in milliseconds

optional

5.6. WmiCollector

The WmiCollector collects peformance metrics from Windows systems using Windows Management Instrumentation (WMI).

5.6.1. Collector Facts

Class Name

org.opennms.netmgt.collectd.WmiCollector

Package

core

Supported on Minion

Yes

5.6.2. Collector Parameters

Table 73. Collector specific parameters for the WmiCollector
Parameter Description Required Default value

collection

The name of the WMI Collection to use

required

5.7. XmlCollector

The XmlCollector is used to collect and extract metrics from a XML and JSON documents.

5.7.1. Collector Facts

Class Name

org.opennms.protocols.xml.collector.XmlCollector

Package

core

Supported on Minion

Yes (see limitations)

Limitations on Minion

The following handlers are not currently supported on Minion:

  • DefaultJsonCollectionHandler

  • Sftp3gppXmlCollectionHandler

  • Sftp3gppVTDXmlCollectionHandler

5.7.2. Collector Parameters

Table 74. Collector specific parameters for the XmlCollector
Parameter Description Required Default value

collection

The name of the XML Collection to use

required

-

handler-class

Class used to perform the collection

optional

org.opennms.protocols.xml.collector.DefaultXmlCollectionHandler

The available handlers include:

  • org.opennms.protocols.xml.collector.DefaultXmlCollectionHandler

  • org.opennms.protocols.xml.collector.Sftp3gppXmlCollectionHandler

  • org.opennms.protocols.xml.vtdxml.DefaultVTDXmlCollectionHandler

  • org.opennms.protocols.xml.vtdxml.Sftp3gppVTDXmlCollectionHandler

  • org.opennms.protocols.json.collector.DefaultJsonCollectionHandler

  • org.opennms.protocols.http.collector.HttpCollectionHandler

5.7.3. XML Collection Configuration

XML Collections are defined in the etc/xml-datacollection-config.xml and etc/xml-datacollection/.

Here is a snippet providing a collection definition named xml-opennms-nodes:

<xml-collection name="xml-opennms-nodes">
  <rrd step="300">
    <rra>RRA:AVERAGE:0.5:1:2016</rra>
    <rra>RRA:AVERAGE:0.5:12:1488</rra>
    <rra>RRA:AVERAGE:0.5:288:366</rra>
    <rra>RRA:MAX:0.5:288:366</rra>
    <rra>RRA:MIN:0.5:288:366</rra>
  </rrd>
  <xml-source url="http://admin:admin@{ipaddr}:8980/opennms/rest/nodes">
    <import-groups>xml-datacollection/opennms-nodes.xml</import-groups>
  </xml-source>
</xml-collection

The referenced opennms-nodes.xml file contains:

<xml-groups>
    <xml-group name="nodes" resource-type="node" resource-xpath="/nodes">
        <xml-object name="totalCount" type="GAUGE" xpath="@totalCount"/>
    </xml-group>
</xml-groups>

With the configuration in place, you can test it using the collect command available in the Karaf Shell:

collection:collect -n 1 org.opennms.protocols.xml.collector.XmlCollector 127.0.0.1 collection=xml-opennms-nodes

5.7.4. Caveats

The org.opennms.protocols.json.collector.DefaultJsonCollectionHandler requires the fetched document to be single element of type object to make xpath query work. If the root element is an array, it will be wrapped in an object whereas the original array is accessible as /elements.

5.8. HttpCollector

The HttpCollector is used to collect performance data via HTTP and HTTPS. Attributes are extracted from the HTTP responses using a regular expression.

5.8.1. Collector Facts

Class Name

org.opennms.netmgt.collectd.HttpCollector

Package

core

Supported on Minion

Yes

5.8.2. Collector Parameters

Table 75. Collector specific parameters for the HttpCollector
Parameter Description Required Default value

collection

The name of the HTTP Collection to use.

required

(none)

thresholding-enabled

Whether collected performance data shall be tested against thresholds.

optional

true

port

Override the default port in the all of the URIs

optional

80

timeout

Connection and socket timeout in milliseconds

optional

3000

retry

Number of retries

optional

2

5.8.3. HTTP Collection Configuration

HTTP Collections are defined in the etc/http-datacollection-config.xml.

Here is a snippet providing a collection definition named opennms-copyright:

<http-collection name="opennms-copyright">
  <rrd step="300">
    <rra>RRA:AVERAGE:0.5:1:2016</rra>
    <rra>RRA:AVERAGE:0.5:12:1488</rra>
    <rra>RRA:AVERAGE:0.5:288:366</rra>
    <rra>RRA:MAX:0.5:288:366</rra>
    <rra>RRA:MIN:0.5:288:366</rra>
  </rrd>
  <uris>
    <uri name="login-page">
      <url path="/opennms/login.jsp"
           matches=".*2002\-([0-9]+).*" response-range="100-399" dotall="true" >
      </url>
      <attributes>
        <attrib alias="copyrightYear" match-group="1" type="gauge"/>
      </attributes>
    </uri>
  </uris>
</http-collection>

Once added to etc/http-datacollection-config.xml you can test it using the collect command available in the Karaf Shell:

collection:collect org.opennms.netmgt.collectd.HttpCollector 127.0.0.1 collection=opennms-copyright port=8980

5.9. JdbcCollector

The JdbcCollector is used to collect performance data via JDBC drivers. Attributes are retrieved using SQL queries.

5.9.1. Collector Facts

Class Name

org.opennms.netmgt.collectd.JdbcCollector

Package

core

Supported on Minion

Yes (see limitations)

Limitations on Minion

When running on Minion the data sources in opennms-datasources.xml cannot be referenced. Instead, the JDBC connection settings need be set using the service parameters instead.

Also, the JDBC driver must be properly loaded in the Minion container. By default, only the JDBC driver for PostgreSQL is available.

5.9.2. Collector Parameters

Table 76. Collector specific parameters for the JdbcCollector
Parameter Description Required Default value

collection

The name of the JDBC Collection to use

required

(empty)

data-source

Use an existing datasource defined in opennms-datasources.xml

optional

NO_DATASOURCE_FOUND

driver

Driver class name

optional

org.postgresql.Driver

url

JDBC URL

optional

jdbc:postgresql://:OPENNMS_JDBC_HOSTNAME/opennms

user

JDBC username

optional

postgres

password

JDBC password

optional

(empty string)

5.9.3. JDBC Collection Configuration

JDBC Collections are defined in the etc/jdbc-datacollection-config.xml.

Here is a snippet providing a collection definition named opennms-stats:

<jdbc-collection name="opennms-stats">
  <rrd step="300">
    <rra>RRA:AVERAGE:0.5:1:2016</rra>
    <rra>RRA:AVERAGE:0.5:12:1488</rra>
    <rra>RRA:AVERAGE:0.5:288:366</rra>
    <rra>RRA:MAX:0.5:288:366</rra>
    <rra>RRA:MIN:0.5:288:366</rra>
  </rrd>
  <queries>
    <query name="opennmsQuery" ifType="ignore">
      <statement data-source="opennms">
        <queryString>select count(*) as event_count from events;</queryString>
      </statement>
      <columns>
        <column name="event_count" data-source-name="event_count" alias="event_count" type="GAUGE"/>
      </columns>
    </query>
  </queries>
</jdbc-collection>

Once added to etc/jdbc-datacollection-config.xml you can test it using the collect command available in the Karaf Shell:

collection:collect org.opennms.netmgt.collectd.JdbcCollector 127.0.0.1 collection=opennms-stats data-source=opennms

To test this same collection on Minion you must specify the JDBC settings as service attributes, for example:

collection:collect -l MINION org.opennms.netmgt.collectd.JdbcCollector 127.0.0.1 collection=opennms-stats driver=org.postgresql.Driver url=jdbc:postgresql://localhost:5432/opennms user=opennms password=opennms

5.10. NSClientCollector

The NSClientCollector is used to collect performance data over HTTP from NSClient++.

5.10.1. Collector Facts

Class Name

org.opennms.protocols.nsclient.collector.NSClientCollector `

Package

opennms-plugin-protocol-nsclient

Supported on Minion

Yes

5.10.2. Collector Parameters

Table 77. Collector specific parameters for the NSClientCollector
Parameter Description Required Default value

collection

The name of the NSClient Collection to use

optional

default

5.11. TcaCollector

The TcaCollector is used to collect special SNMP data from Juniper TCA Devices.

5.11.1. Collector Facts

Class Name

org.opennms.netmgt.collectd.tca.TcaCollector

Package

opennms-plugin-collector-juniper-tca

Supported on Minion

Yes

5.11.2. Collector Parameters

Table 78. Collector specific parameters for the TcaCollector
Parameter Description Required Default value

collection

The name of the TCA Collection to use

required

5.12. XmpCollector

The XmpCollector collects peformance metrics via the X/Open Management Protocol API (XMP) protocol.

5.12.1. Collector Facts

Class Name

org.opennms.netmgt.protocols.xmp.collector.XmpCollector

Package

opennms-plugin-protocol-xmp

Supported on Minion

No

5.12.2. Collector Parameters

Table 79. Collector specific parameters for the XmpCollector
Parameter Description Required Default value

collection

The name of the XMP Collection to use

required

port

The TCP port on which the agent communicates

required

authenUser

The username used for authenticating to the agent

optional

(none)

timeout

The timeout used when communicating with the agent

optional

3000

retry

The number of retries permitted when timeout expires

optional

0

6. Notification Strategies

6.1. Mattermost

If your organization uses the Mattermost team communications platform, you can configure OpenNMS Horizon to send notices to any Mattermost channel via an incoming webhook. You must configure an incoming webhook in your Mattermost team and do a bit of manual configuration to your OpenNMS Horizon instance.

First, add the following bit of XML to the notificationCommands.xml configuration file (no customization should be needed):

<command binary="false">
  <name>mattermost</name>
  <execute>org.opennms.netmgt.notifd.MattermostNotificationStrategy</execute>
  <comment>class for sending messages to a Mattermost team channel for notifications</comment>
  <argument streamed="false">
    <switch>-subject</switch>
  </argument>
  <argument streamed="false">
    <switch>-tm</switch>
  </argument>
</command>

Then create a new file called mattermost.properties in the opennms.properties.d directory with the following contents (customizing values as appropriate):

org.opennms.netmgt.notifd.mattermost.webhookURL=https://mattermost.example.com/hooks/bf980352b5f7232efe721dbf0626bee1

Restart OpenNMS so that the mattermost.properties file will be loaded. Your new mattermost notification command is now available for use in a destination path.

Additional Options

The following table lists optional properties that you may use in mattermost.properties to customize your Mattermost notifications.

To improve the layout, the property names have been shortened to their final component; you must prepend org.opennms.netmgt.notifd.mattermost. when using them.
Table 80. Additional available parameters for the Mattermost notification strategy
Parameter Description Required Default value Example

channel

Specify a channel or private group other than the one targeted by the webhook

optional

Webhook default

NetOps

username

The username to associate with the notification posts

optional

None

OpenNMS_Bot

iconEmoji

An emoji sequence to use as the icon for the notification posts

optional

No icon

:metal:

iconURL

The URL of an image to use as the icon for the notification posts

optional

No icon

https://example.org/assets/icon.png

Some of the optional configuration parameters are incompatible with some versions of Mattermost. For instance, the channel option is known not to work with Mattermost 3.7.0.

For more information on incoming webhooks in Mattermost, see Mattermost Integration Guide.

6.2. Slack Notifications

If your organization uses the Slack team communications platform, you can configure OpenNMS Horizon to send notices to any Slack channel via an incoming webhook. You must configure an incoming webhook in your Slack team and do a bit of manual configuration to your OpenNMS Horizon instance.

First, add the following bit of XML to the notificationCommands.xml configuration file (no customization should be needed):

<command binary="false">
  <name>slack</name>
  <execute>org.opennms.netmgt.notifd.SlackNotificationStrategy</execute>
  <comment>class for sending messages to a Slack team channel for notifications</comment>
  <argument streamed="false">
    <switch>-subject</switch>
  </argument>
  <argument streamed="false">
    <switch>-tm</switch>
  </argument>
</command>

Then create a new file called slack.properties in the opennms.properties.d directory with the following contents (customizing values as appropriate):

org.opennms.netmgt.notifd.slack.webhookURL=https://hooks.slack.com/services/AEJ7IIYAI/XOOTH3EOD/c3fc4a662c8e07fe072aeeec

Restart OpenNMS so that the slack.properties file will be loaded. Your new slack notification command is now available for use in a destination path.

Additional Options

The following table lists optional properties that you may use in slack.properties to customize your Slack notifications.

To improve the layout, the property names have been shortened to their final component; you must prepend org.opennms.netmgt.notifd.slack. when using them.
Table 81. Additional parameters for the Slack notification strategy
Parameter Description Required Default value Example

channel

Specify a channel or private group other than the one targeted by the webhook

optional

Webhook default

NetOps

username

The username to associate with the notification posts

optional

None

OpenNMS_Bot

iconEmoji

An emoji sequence to use as the icon for the notification posts

optional

No icon

:metal:

iconURL

The URL of an image to use as the icon for the notification posts

optional

No icon

https://example.org/assets/icon.png

For more information on incoming webhooks in Slack, see Slack API.

7. Provisioning

7.1. Service Detectors

7.1.1. SNMP Detector

This detector is used to find and assigns services based on SNMP. The detector binds a service with a given Service Name when a particular SNMP OID as scalar or table matches a given criteria.

Detector facts

Implementation

org.opennms.netmgt.provision.detector.snmp.SnmpDetector

Configuration and Usage
Table 82. Parameters for the SNMP detector
Parameter Description Required Default value

oid

SNMP OID for scalar or table to detect the service.

required

.1.3.6.1.2.1.1.2.0

retry

Number of retries to detect the service.

optional

agent config

timeout

Timeout in milliseconds to wait for a response from the SNMP agent.

optional

agent config

vbvalue

expected return value to detect the service; if not specified the service is detected if the SNMP OID returned any kind of valid value. The vbvalue is evaluated as Java Regular Expression.

optional

-

hex

Set true if the data is from type HEX-String.

optional

false

isTable

Set true if detector should evaluate SNMP tables.

optional

false

matchType

Set match type to evaluate the expected value in the SNMP table.
EXIST: the expected vbalue is ignored, service detected if the given table under OID exist
ALL: all values in the table must match against expected vbalue to detect service
ANY: at least one value in the table must match against expected vbalue to detect service
NONE: None of the values should match against expected value to detect service

optional

EXIST

Example for SNMP scalar value

We have Dell server farm and want to monitor the global server status provided by the OpenManage Server Administrator. Global status is provided by a scalar OID .1.3.6.1.4.1.674.10892.1.200.10.1.2.1. The service should be automatically detected if the server supports this OID.

For provisioning we have a requisition named Server which contains all server of our data center. A Detector with the name Dell-OMSA-Global-State for this requisition is created with the following parameter:

Table 83. Parameters for the SNMP detector
Parameter Value

Name

Dell-OMSA-Global-State

oid

.1.3.6.1.4.1.674.10892.1.200.10.1.2.1

When the requisition Server is synchronized the service Dell-OMSA-Global-State will be detected in case they support the given SNMP OID.

Example using SNMP tables

We have a HP server farm and want to monitor the status of logical drives over SNMP provided from HP Insight Manager. The status for logical drives is provided in a SNMP Table under .1.3.6.1.4.1.232.3.2.3.1.1.4. The service should be automatically assigned to all servers exposing the given SNMP OID.

For provisioning we have a requisition named Server which contains all server of our data center. A Detector with the name HP-Insight-Drive-Logical for this requisition is created with the following parameter:

Table 84. Parameters for the SNMP detector
Parameter Value

Name

HP-Insight-Drive-Logical

oid

.1.3.6.1.4.1.232.3.2.3.1.1.4

isTable

true

When the requisition Server is synchronized the service HP-Insight-Drive-Logical will be detected in case they support the given SNMP OID table.

7.1.2. WS-Man Detector

The WS-Management detector attempts to connect to the agent defined in wsman-config.xml and issues an Identify command. If the Identify command is successful, the service is marked as detected and the product details returned by the command are optionally stored in the asset fields (see details bellow.)

Detector facts

Implementation

org.opennms.netmgt.provision.detector.wsman.WsManDetector

Configuration and Usage
Table 85. Parameters for the <DETECTOR-NAME-HERE>
Parameter Description Required Default value

updateAssets

Stores the product vendor and product version in the vendor and modelNumber asset fields

false

true

Examples

If a valid response to the Identify command is received, the product vendor and product version are stored in the vendor and modelNumber fields of the associated node`s assets table.

For example, a Windows Server 2008 machine returns:

Product Vendor

Microsoft Corporation

Product Version

OS: 6.1.7601 SP: 1.0 Stack: 2.0

If these assets field are being used for another purpose, this behavior can be disabled by settings the updateAssets parameters to false in the detector configuration of the appropriate foreign source.

Some agents may respond to the Identify command with generic identities such as Openwsman 2.0.0. These values can be overridden by specifying the product-vendor and product-version attributes in wsman-config.xml.

Example detector configuration:

<detector name="WS-Man" class="org.opennms.netmgt.provision.detector.wsman.WsManDetector">
    <parameter key="updateAssets" value="true"/>
</detector>

The response is logged as DEBUG information in provisiond.log and looks like the following:

ID: 3
Response-Code: 200
309Encoding: UTF-8
Content-Type: application/soap+xml;charset=UTF-8
Headers: {Content-Length=[787], content-type=[application/soap+xml;charset=UTF-8], Date=[Mon, 08 Feb 2016 14:21:20 GMT], Server=[Microsoft-HTTPAPI/2.0]}
Payload:
<s:Envelope xmlns:s="http://www.w3.org/2003/05/soap-envelope" xml:lang="en-US">
  <s:Header/>
  <s:Body>
    <wsmid:IdentifyResponse xmlns:wsmid="http://schemas.dmtf.org/wbem/wsman/identity/1/wsmanidentity.xsd">
    <wsmid:ProtocolVersion>http://schemas.dmtf.org/wbem/wsman/1/wsman.xsd</wsmid:ProtocolVersion>
    <wsmid:ProductVendor>Microsoft Corporation</wsmid:ProductVendor>(1)
    <wsmid:ProductVersion>OS: 6.2.9200 SP: 0.0 Stack: 3.0</wsmid:ProductVersion>(2)
    <wsmid:SecurityProfiles>
      <wsmid:SecurityProfileName>http://schemas.dmtf.org/wbem/wsman/1/wsman/secprofile/http/basic</wsmid:SecurityProfileName>
      <wsmid:SecurityProfileName>http://schemas.dmtf.org/wbem/wsman/1/wsman/secprofile/http/spnego-kerberos</wsmid:SecurityProfileName>
    </wsmid:SecurityProfiles>
    </wsmid:IdentifyResponse>
  </s:Body>
</s:Envelope>
1 ProductVendor: Stored to the asset field vendor
2 ProductVersion: Stored in the asset field modelNumber
The information of the asset fields are used in the System Definition Rule to decide which performance metrics will be gathered from Collectd.

7.2. Adapters

7.2.1. DDNS Adapter

The Opposite end of Provisiond integration from the DNS Requisition Import, is the DDNS adapter. This adapter uses the dynamic DNS protocol to update a DNS system as nodes are provisioned into OpenNMS Horizon. To configure this adapter, edit the opennms.properties file and set the importer.adapter.dns.server property:

importer.adapter.dns.server=192.168.1.1

8. Topology Provider

8.1. GraphML Asset Topology Provider

OpenNMS Horizon has introduced the ability for users to define arbitrarily complex layered topologies using GraphML (see http://graphml.graphdrawing.org/). The details of how OpenNMS Horizon interprets GraphML are given in the GraphML section of the OpenNMS Horizon developers guide. The ability to display complex layered topologies is a great feature but creating a usable GraphML topology for a large network can be a complex task for a user.

The Asset Topology Provider avoids the need for users to work directly with GraphML by directly generating a layered GraphML topology based upon node parameters and the contents of the Node Asset table. The Asset Topology Provider greatly simplifies the task for many use cases by allowing users to define fields in the Node Asset table which will enable nodes to be positioned correctly in a complex topology. This allows a physical and logical ordering of nodes which makes it easier for users to represent and navigate their infrastructure.

The structure of the generated topology is determined by the assetLayers configuration constant which can be set by a user. To illustrate how this works, we will consider the following configuration:

assetLayers=asset-region,asset-building

The OpenNMS Horizon Asset table is parsed to generate nested layers in the order of the comma separated keys in the assetLayers property. Each layer is a graph which is named after the key. Graph nodes in each layer reference related Graph nodes in the underlying layer. The lowest layer contains Graph nodes which are directly linked to monitored OpenNMS Horizon nodes which have entries in the Asset table.

The following diagram shows the structure of a topology generated by the above assetLayers property

Illustrating how node asset entries are interpreted as layers

In this example the region asset fields for node 1,2,3,4 are set to north. All of these nodes are in the same north region. The building asset fields for Node 1 and Node 2 are set to 21 (both nodes are in building 21) while the building asset fields for Node 3 and Node 4 are set to 22 (both nodes are in building 22).

The Asset Topology Provider generates four linked graphs for this configuration. The layer 0 graph is called asset-region, the layer 1 graph is called asset-building and the layer 2 graph is called nodes.

Conceptually we can see that the topology is rendered as concentric sets. The Asset Topology Provider first searches all of the nodes with regions defined and creates a new level 0 graph node representing each region found. The Asset Topology Provider then searches within each region to find the building entries and creates a corresponding level 1 graph node for each building name found. Finally the Asset Topology Provider creates layer 2 nodes corresponding to each OpenNMS Horizon monitored node and places each in the correct building.

If however OpenNMS Horizon monitored nodes are found which have either the region or building asset fields empty they cannot be placed correctly in this topology. These nodes as shown in the diagram as unallocated nodes. Finally, only building and region nodes are generated which can be linked to OpenNMS Horizon nodes in the topology. The Asset Topology Provider does not generate spurious graph nodes in upper layers which are not directly and completely referenced by OpenNMS Horizon nodes in the lowest layer.

Example screenshots of a topology containing regions, buildings, racks and nodes are shown below

Screenshot of Regions Layer
Screenshot of Buildings Layer
Screenshot of Nodes Layer

8.1.1. Asset layers

The entries for assetLayers can be any node or asset entry from the following list (defined in class NodeParamLabels). Keys beginning with node- come from the node table. Keys beginning with parent- come from the node table entry of the designated parent node (If defined). Keys beginning with asset- come from the corresponding asset table entry for the given node (If defined).

node-nodelabel

node-nodeid

node-foreignsource

node-foreignid

node-nodesysname

node-nodesyslocation

node-operatingsystem

node-categories

parent-nodelabel

parent-nodeid

parent-foreignsource

parent-foreignid

asset-address1

asset-address2

asset-city

asset-zip

asset-state

asset-latitude

asset-longitude

asset-region

asset-division

asset-department

asset-building

asset-floor

asset-room

asset-rack

asset-slot

asset-port

asset-circuitid

asset-category

asset-displaycategory

asset-notifycategory

asset-pollercategory

asset-thresholdcategory

asset-managedobjecttype

asset-managedobjectinstance

asset-manufacturer

asset-vendor

asset-modelnumber

asset-description

asset-operatingsystem

asset-country

This allows arbitrary topologies to be generated including physical fields (room, rack etc.) and logical fields such as asset node categories. Please note you should not put any spaces in the comma separated assetLayers list. If the assetLayers property is defined as empty then a single graph layer will be generated containing all opennms nodes.

8.1.2. Node filtering

In many cases it is desirable to control which nodes are included or excluded from a topology. For instance it is useful to be able to generate customised topologies for specific customers which include only regions/buildings etc relevant to their filtered node set. To this end it is possible to define a node filter which chooses which nodes are included in a generated topology.

Filters are defined using the same asset table keys which are available for the assetLayers field.

Operation Definition Example

OR

key1=value1,value2 alternatively key1=value1;key1=value2

asset-region=north,south

AND

key1=val1;key2=val2

asset-region=north;asset-building=23

NOT

key1=!val1

asset-building=!23

Thus the following configuration means include only nodes with region north or south but exclude all nodes with building 23.

filter=asset-region=north,south;asset-building=!23

The filters are designed to treat all selected text key entries as comma separated values (csv). This allows OpenNMS node-categories which are many to many entries to be dealt with as a comma separated list of values; routers,servers,web etc. Thus we can select based on multiple separate node categories. The following configuration means show routers and servers on all buildings except building 23.

filter=node-categories=routers,servers;asset-building=!23

The filters treat all asset table entries as comma separated variables (csv). This also means that, for instance asset-displaycategory could also contain several values separated by commas. e.g. customer1,customer2,customer3 etc.

You should make sure asset addresses and other free format asset text fields do not contain commas if you want an exact match on the whole field

Regular expressions are also allowed. Regular expressions start with the ~ character. You can also negate a regular expression by preceding it with !~.

The following example will match against regions 'Stuttgart' and 'Isengard' and any building name which ends in 4

filter=asset-region=~.*gar(t|d);asset-building=~.*4

8.1.3. Configuration

The Asset Topology Provider persists both the asset topology graph definitions and the generated GraphML graphs. The persisted definitions mean that is is possible to regenerate graphs if the asset table is changed without reentering the configuration.

The Asset Topology Provider persists GraphML graphs along side any other GraphML graphs in the directory;

<opennms home>/etc/graphml

Please note that if you are using ReST or any other means to generate other GraphML graphs, you should ensure that the providerIds and labels are distinct from those used by the Asset Topology Provider

The asset graph definitions for the Asset Topology Provider are persisted to the following xml configuration file:

<opennms home>/etc/org.opennms.features.topology.plugins.topo.asset.xml

Normally you should not edit this file directly but use the karaf consol or events to define new graphs.

The config file will contain each of the graph definitions as properties in the form

<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<configs>
    <config>
        <label>Asset Topology Provider</label>
        <breadcrumb-strategy>SHORTEST_PATH_TO_ROOT</breadcrumb-strategy>
        <provider-id>asset</provider-id>
        <preferred-layout>Grid Layout</preferred-layout>
        <filters>
            <filter>asset-region=South</filter>
        </filters>
        <layers>
            <layer>asset-region</layer>
            <layer>asset-building</layer>
            <layer>asset-rack</layer>
        </layers>
    </config>
</configs>

The individual definition parameters are described in the following table

Parameter Description

providerId

The unique name of the provider - used as handle to install and remove the topology

label

The name which shows up on the topology menu (must be unique)

assetLayers

List of asset layers (in order). See separate description.

filters

List of filters to be applied. Filters determine which nodes are included in graph. See separate description.

preferredLayout

Preferred layout of the nodes in generated graphs.

breadcrumbStrategy

Breadcrumb strategy used to display breadcrumbs above each graph

8.1.4. Creating Asset Based Topologies From Karaf Consol

The OpenNMS Horizon Karaf Consol can be used to control topology generation. To login use admin password.

ssh admin@localhost -p 8101

The following commands are available

Command Description Options

asset-topology:create

Creates Asset Topology.

(The default settings are used if a particular setting is not included in the command)

-l, --label : Asset Topology label (shows in topology menu) (Default: asset)

-i, --providerId : Unique providerId of asset topology (Default: 'Asset Topology Provider')

-f, --filter : Optional node filter (Default: empty filter i.e. allow all nodes)

-a, --assetLayers : Comma separated list of asset layers (Default: asset-region,asset-building,asset-rack)

-p, --preferredLayout : Preferred Layout (Default: 'Grid Layout')

-b, --breadcrumbStrategy : Bread Crumb Strategy (Default: SHORTEST_PATH_TO_ROOT)

If you simply type asset-topology:create a default topology with providerId asset will be created.

asset-topology:remove

Removes Asset Topology.

-i, --providerId : Unique providerId of asset topology (Default: asset)

asset-topology:list

Lists all Asset Topologies installed.

all : display detailed view including --uriParams string

asset-topology:regenerate

Regenerates the graphs for the given Asset Topology definition.

-i, --providerId : Unique providerId of asset topology to regenerate (Default: asset)

asset-topology:regenerateall

Best Effort regeneration of all asset topologies. (If one graph fails, the command will try to complete the rest of the definitions definition)

8.1.5. Creating Asset Based Topologies Using OpenNMS Horizon events

The Asset Topology Provider listens for events which trigger the generation and installation or removal of topologies. The Asset Topology Provider events are defined in the file

<opennms home>/etc/events/GraphMLAssetPluginEvents.xml

These events will use the default parameters if parameters are not supplied

To create a new topology from the current OpenNMS inventory use

(for default topology)
sudo ./send-event.pl  uei.opennms.plugins/assettopology/create localhost

(or with parameters)
sudo ./send-event.pl  uei.opennms.plugins/assettopology/create localhost  -p 'providerId test' -p 'label test' -p 'assetLayers asset-country,asset-city,asset-building'-->

other example possible parameters are
-p 'filters asset-displaycategory=!testDisplayCategory'
-p 'preferredLayout Grid Layout'
-p 'breadcrumbStrategy SHORTEST_PATH_TO_ROOT'

To uninstall an asset topology use

(for default topology providerId)
sudo ./send-event.pl  uei.opennms.plugins/assettopology/remove localhost

(or with specific providerId)
sudo ./send-event.pl  uei.opennms.plugins/assettopology/remove localhost -p 'providerId test'

To regenerate an existing asset topology use

(for default topology providerId)
sudo ./send-event.pl  uei.opennms.plugins/assettopology/regenerate localhost

(or with specific providerId)
sudo ./send-event.pl  uei.opennms.plugins/assettopology/regenerate localhost-p 'providerId test'

To regenerate all existing asset topologies use

sudo ./send-event.pl  uei.opennms.plugins/assettopology/regenerateall localhost

8.1.6. Viewing the topology

If all goes well, having installed the topology, upon refreshing your screen, you should see a new topology display option in the OpenNMS Horizon topology page. The displayed name of this topology is given by the label field

The label field need not be the same as the providerId which is used by the ReST api for the installation or removal of a topology. However the label field must be unique across all installed topologies.

It is possible to have several topologies installed which have been generated using different configurations. You simply need to ensure that the providerId and label field used for each installation command is different.

8.1.7. Additional notes

Please note you MUST first uninstall an OpenNMS Horizon graphml topology before installing a new one. You will also have to log out and log back into the UI in order to see the new topology file. If you uninstall a topology while viewing it, the UI will throw an error and you will also have to log out and back in to see the remaining topologies.

9. Ticketing Adapaters

9.1. JIRA Ticketing Plugin

The JIRA Ticketing Plugin is used to create JIRA Issues in response to OpenNMS Horizon alarms.

9.1.1. Setup

First, you’ll need to install the opennms-plugin-ticketer-jira package for your system. The JIRA ticketing plugin and it’s dependencies are not part of the core packages.

Now, in order to enable the plugin start by setting following property in ${OPENNMS_HOME}/etc/opennms.properties:

opennms.ticketer.plugin=org.opennms.netmgt.ticketd.OSGiBasedTicketerPlugin

Configure the plugin options by setting the following properties in ${OPENNMS_HOME}/etc/jira.properties:

Name Description

jira.host

JIRA Server Url

jira.username

Username

jira.password

Password

jira.project

The key of the project to use. Use jira:list-projects command to determine the project key.

jira.type

The Issue Type Id to use when opening new issues. Use jira:list-issue-types command to determine the issue type id.

jira.resolve

Name of the transition to use when resolving issues

jira.reopen

Name of the transition to use when re-opening issues

jira.status.open

Comma-separated list of JIRA status names for which the ticket should be considered 'Open'

jira.status.closed

Comma-separated list of JIRA status names for which the ticket should be considered 'Closed'

jira.status.cancelled

Comma-separated list of JIRA status names for which the ticket should be considered 'Cancelled'

jira.cache.reloadTime

The time in milliseconds it takes to reload the fields cache. This is required to prevent the plugin to read the issue type’s meta data every time an issue is created. A value of 0 disables the cache. Default value is 300000 (5 minutes).

The transition names for resolve and reopen are typically found on buttons when looking at the ticket in JIRA
Either use jira:list-issue-types OSGI Command or https://confluence.atlassian.com/display/JIRA050/Finding+the+Id+for+Issue+Types for determining the appropriate issue type id.

Next, add jira-troubleticketer to the featuresBoot property in the ${OPENNMS_HOME}/etc/org.apache.karaf.features.cfg

Restart OpenNMS Horizon.

When OpenNMS Horizon has started again, login to the Karaf Shell and install the feature:

feature:install jira-troubleticketer

The plugin should be ready to use.

9.1.2. Jira Commands

The JIRA Ticketing Plugin provides various OSGI Commands which can be used on the Karaf Shell to help set up the plugin.

There are OSGI Commands to list all available projects, versions, components, groups, issue types and even more.

To list all available commands simply type help | grep jira in the Karaf Shell.

Afterwards you can type for example jira:list-projects --help to determine the usage of a command.

9.1.3. Custom fields

The OpenNMS Horizon Ticketer model is limited to the most common fields provided by all ticketing systems.

Besides the common fields creator, create date, description or subject, ticket system proprietary fields usually need to be set.

In some cases, even additional - so called - custom fields are defined.

In order to set these fields, the JIRA Ticketing Plugin provides the possibility to define those in the OpenNMS Ticket attributes which can be overwritten with the Usage of Drools.

To enable the Drools Ticketing integration, the following property in ${OPENNMS_HOME}/etc/opennms.properties must be set:

opennms.ticketer.servicelayer=org.opennms.netmgt.ticketd.DroolsTicketerServiceLayer

In addition the property in ${OPENNMS_HOME/etc/drools-ticketer.properties must point to a drools-ticketer-rules.drl file:

drools-ticketer.rules-file=${OPENNMS_HOME/etc/drools-ticketer-rules.drl

Finally a Drools Rule file named drools-ticketer-rules.drl must be placed in ${OPENNMS_HOME}/etc.

The following drools example snippet defines attributes to set custom fields:

// Set ticket defaults
rule "TicketDefaults"
salience 100
 when
  $alarm : OnmsAlarm()
 then
  ticket.setSummary($alarm.logMsg);
  ticket.setDetails($alarm.description);
  ticket.addAttribute("customfield_10111", "custom-value");
  ticket.addAttribute("customfield_10112", "my-location");
  ticket.addAttribute("customfield_10113", "some classification");
end

Fields must be referenced by their id. To identify the id of a field, the jira:list-fields command can be used. By default only custom fields are shown. The -s options allows to show all fields. This may be necessary if JIRA default values need to be set as well, e.g. the Component, the Reporter, the Asignee, etc. Even the project key or issue type can be defined differently than originally in the jira.properties.

The OpenNMS Ticketer Attribute model only allows to set a String value. However the JIRA model is slightly different. Therefore each String value must be converted to a JIRA field type. The following table describes valid values for an OpenNMS attribute.

Type Description

any

Any string.

date

Any date in the format of YYYY-MM-DD.

datetime

Any datetime in ISO 8601 format: YYYY-MM-DDThh:mm:ss.sTZD.

group

The name of the group.

user

The name of the user.

project

The key of the project (e.g. NMS)

version

The name of the version. To list all available versions, use jira:list-versions.

string

Any string.

option

The name of the option.

issuetype

The name of the issuetpye, e.g. Bug. To list all issue types, use jira:list-issue-types.

priority

The name of the priority, e.g. Major. To list all priorites, use jira:list-priorities.

option-with-child

Either the name of the option, or a comma separated list (e.g. parent,child).

number

Any valid number (e.g. 1000)

array

If the type is array the value must be of the containing type. E.g. to set a custom field which defines multiple groups, the value jira-users,jira-administrators is mapped properly. The same is valid for versions: 18.0.3,19.0.0.

As described above the values are usually identified by their name instead of their id (projects are identified by their key). This is easier to read, but may break the mapping code, if for example the name of a component changes in the future. To change the mapping from name (or key) to id an entry in jira.properties must be made:

jira.attributes.customfield_10113.resolution=id

To learn more about the Jira REST API please consult the following pages:

The following jira (custom) fields have been tested with jira version 6.3.15:

  • Checkboxes

  • Date Picker

  • Date Time Picker

  • Group Picker (multiple groups)

  • Group Picker (single group)

  • Labels

  • Number Field

  • Project Picker (single project)

  • Radio Buttons

  • Select List (cascading)

  • Select List (multiple choices)

  • Select List (single choice)

  • Text Field (multi-line)

  • Text Field (read only)

  • Text Field (single line)

  • URL Field

  • User Picker (multiple user)

  • User Picker (single user)

  • Version Picker (multiple versions)

  • Version Picker (single version)

All other field types are mapped as is and therefore may not work.
Examples

The following output is the result of the command jira:list-fields -h http://localhost:8080 -u admin -p testtest -k DUM -i Bug -s and lists all available fields for project with key DUM and issue type Bug:

Name                           Id                   Custom     Type
Affects Version/s              versions             false      array
Assignee                       assignee             false      user
Attachment                     attachment           false      array
Component/s                    components           false      array  (1)
Description                    description          false      string
Environment                    environment          false      string
Epic Link                      customfield_10002    true       any
Fix Version/s                  fixVersions          false      array (2)
Issue Type                     issuetype            false      issuetype (3)
Labels                         labels               false      array
Linked Issues                  issuelinks           false      array
Priority                       priority             false      priority (4)
Project                        project              false      project (5)
Reporter                       reporter             false      user
Sprint                         customfield_10001    true       array
Summary                        summary              false      string
custom checkbox                customfield_10100    true       array (6)
custom datepicker              customfield_10101    true       date
1 Defined Components are core, service, web
2 Defined versions are 1.0.0 and 1.0.1
3 Defined issue types are Bug and Task
4 Defined priorities are Major and Minor
5 Defined projects are NMS and HZN
6 Defined options are yes, no and sometimes

The following snipped shows how to set the various custom fields:

ticket.addAttribute("components", "core,web"); (1)
ticket.addAttribute("assignee", "ulf"); (2)
ticket.addAttribute("fixVersions", "1.0.1"); (3)
ticket.addAttribte("issueType", "Task"); (4)
ticket.addAttribute("priority", "Minor"); (5)
ticket.addAttribute("project", "HZN"); (6)
ticket.addAttribute("summary", "Custom Summary"); (7)
ticket.addAttribute("customfield_10100", "yes,no"); (8)
ticket.addAttribute("customfield_10101", "2016-12-06"); (9)
1 Sets the components of the created issue to core and web.
2 Sets the Asignee of the issue to the user with login ulf.
3 Sets the fix version of the issue to 1.0.1
4 Sets the issue type to Task, overwriting the value of jira.type.
5 Sets the priority of the created issue to Minor.
6 Sets the project to HZN, overwriting the value of jira.project.
7 Sets the summary to Custom Summary, overwriting any previous summary.
8 Checks the checkboxes yes and no.
9 Sets the value to 2016-12-06.

9.1.4. Troubleshooting

When troubleshooting, consult the following log files:

  • ${OPENNMS_HOME}/data/log/karaf.log

  • ${OPENNMS_HOME}/logs/trouble-ticketer.log

You can also try the jira:verify OSGI Command to help identifying problems in your configuration.

9.2. Remedy Ticketing Plugin

The Remedy Ticketing Plugin is used to create requests in the BMC Remedy ARS Help Desk Module in response to OpenNMS Horizon alarms.

9.2.1. Remedy Product Overview

It’s important to be specific when discussing Remedy, because BMC Remedy is a suite of products. The OpenNMS Horizon Remedy Ticketing Plugin requires the core Remedy ARS and the Help Desk Module. The Help Desk Module contains a Help Desk Interface Web Service, which serves as the endpoint for creating, updating, and fetching tickets.

The Help Desk Interface (HDI) Web Service requires extensive configuration for its basic operation, and may need additional customization to interoperate with the OpenNMS Horizon Remedy Ticketing Plugin. Contact your Remedy administrator for help with required configuration tasks.

9.2.2. Supported Remedy Product Versions

Currently supported Remedy product versions are listed below:

Product Version

Remedy ARS

7.6.04 Service Pack 2

Help Desk Module

7.6.04 Service Pack 1

HDI Web Service

Same as Help Desk Module

9.2.3. Setup

The Remedy Ticketing Plugin and its dependencies are part of the OpenNMS Horizon core packages.

Start by enabling the plugin and the ticket controls in the OpenNMS Horizon web interface, by setting the following properties in ${OPENNMS_HOME}/etc/opennms.properties:

opennms.ticketer.plugin=org.opennms.netmgt.ticketer.remedy.RemedyTicketerPlugin
opennms.alarmTroubleTicketEnabled = true

In the same file, set the property opennms.alarmTroubleTicketLinkTemplate to a value appropriate for constructing a link to tickets in the Remedy web interface. A sample value is provided but must be customized for your site; the token ${id} will be replaced with the Remedy ticket ID when the link is rendered.

Now configure the plugin itself by setting the following properties in ${OPENNMS_HOME}/etc/remedy.properties:

Name Required Description

remedy.username

required

Username for authenticating to Remedy

remedy.password

required

Password for authenticating to Remedy

remedy.authentication

optional

Authentication style to use

remedy.locale

optional

Locale for text when creating and updating tickets

remedy.timezone

optional

Timezone for interaction with Remedy

remedy.endpoint

required

The endpoint URL of the HPD web service

remedy.portname

required

The Port name of the HPD web service

remedy.createendpoint

required

The endpoint location of the Create-HPD web service

remedy.createportname

required

The Port name of the Create-HPD web service

remedy.targetgroups

optional

Colon-separated list of Remedy groups to which created tickets may be assigned ({group} below refers to values from this list)

remedy.assignedgroup.{group}

optional

Assigned group for the target group {group}

remedy.assignedsupportcompany.{group}

optional

Assigned support company for the target group {group}

remedy.assignedsupportorganization.{group}

optional

Assigned support organization for the target group {group}

remedy.assignedgroup

required

Default group to assign the ticket in case the ticket itself lacks information about a target assigned group

remedy.firstname

required

First name for ticket creation and updating. Must exist in Remedy.

remedy.lastname

required

Last name for ticket creation and updating. Must exist in Remedy.

remedy.serviceCI

required

A valid Remedy Service CI for ticket creation

remedy.serviceCIReconID

required

A valid Remedy Service CI Reconciliation ID for ticket creation

remedy.assignedsupportcompany

required

A valid default assigned support company for ticket creation

remedy.assignedsupportorganization

required

A valid default assigned support organization for ticket creation

remedy.categorizationtier1

required

A valid categorization tier (primary) for ticket creation

remedy.categorizationtier2

required

A valid categorization tier (secondary) for ticket creation

remedy.categorizationtier3

required

A valid categorization tier (tertiary) for ticket creation

remedy.serviceType

required

A valid service type for ticket creation

remedy.reportedSource

required

A valid Reported Source for ticket creation

remedy.impact

required

A valid value for Impact, used in ticket creation

remedy.urgency

required

A valid value for Urgency, used in ticket creation

remedy.reason.reopen

required

The reason code set in Remedy when the ticket is reopened in OpenNMS Horizon

remedy.resolution

required

The reason code set in Remedy when the ticket is closed in OpenNMS Horizon

remedy.reason.cancelled

required

The reason code set in Remedy when the ticket is cancelled in OpenNMS Horizon

The values for many of the required properties are site-specific; contact your Remedy administrator for assistance.

Restart OpenNMS Horizon.

The plugin should be ready to use. When troubleshooting, consult the following log files:

  • ${OPENNMS_HOME}/logs/trouble-ticketer.log

9.3. TSRM Ticketing Plugin

The TSRM Ticketing Plugin is used to create TSRM incidents in response to OpenNMS Horizon alarms.

9.3.1. Setup

In order to enable the plugin start by setting following property in ${OPENNMS_HOME}/etc/opennms.properties:

opennms.ticketer.plugin=org.opennms.netmgt.ticketd.OSGiBasedTicketerPlugin

Configure the plugin options by setting the following properties in ${OPENNMS_HOME}/etc/tsrm.properties:

Name Description

tsrm.url

TSRM Endpoint URL

tsrm.ssl.strict

Strict SSL Check (true/false)

tsrm.status.open

TSRM status for open ticket

tsrm.status.close

TSRM status for close ticket

Next, add tsrm-troubleticketer to the featuresBoot property in the ${OPENNMS_HOME}/etc/org.apache.karaf.features.cfg

Restart OpenNMS.

When OpenNMS has started again, login to the Karaf Shell and install the feature:

feature:install tsrm-troubleticketer

The plugin should be ready to use. When troubleshooting, consult the following log files:

  • ${OPENNMS_HOME}/data/log/karaf.log

  • ${OPENNMS_HOME}/logs/trouble-ticketer.log

9.3.2. Mapping OpenNMS Ticket with TSRM Incident

Following tables shows mapping between OpenNMS ticket and TSRM Incident

Ticket Field TSRM Incident Field

id

TICKETID

state

STATUS

summary

DESCRIPTION

details

DESCRIPTIONLONGDESCRIPTION

user

REPORTEDBY

Below fields are not part of Ticket, they have to be added as attributes.

Ticket Field TSRM Incident Field

affectedPerson

AFFECTEDPERSON

assetNum

ASSETNUM

classId

CLASS

classStructureId

CLASSSTRUCTUREID

commodity

COMMODITY

location

LOCATION

ownerGroup

OWNERGROUP

shsCallerType

SHSCALLERTYPE

shsReasonForOutage

SHSREASONFOROUTAGE

shsResolution

SHSRESOLUTION

shsRoomNumber

SHSROOMNUMBER

siteId

SITEID

source

source

statusIface

STATUSIFACE

10. Telemetryd

10.1. Listener

10.1.1. UDP Listener

The UDP listener can be used to open a simple UDP socket and build messages from the received packets.

Facts

Class Name

org.opennms.netmgt.telemetry.listeners.udp.UdpListener

Supported on Minion

Yes

Parameters
Table 86. Listener specific parameters for the UdpListener
Parameter Description Required Default value

host

IP address on which to bind the UDP port

optional

0.0.0.0

port

UDP port number on which to listen

optional

50000

maxPacketSize

Maximum packet size in bytes (anything greater will be truncated)

optional

8096

10.1.2. Netflow v9 UDP Listener

This UDP based listener can be used to open a UDP socket to deal with incoming Netflow v9 packets.

Facts

Class Name

org.opennms.netmgt.telemetry.listeners.flow.netflow9.UdpListener

Supported on Minion

Yes

Parameters
Table 87. Listener specific parameters for the Netflow v9 UDP listener
Parameter Description Required Default value

host

IP address on which to bind the UDP socket

optional

0.0.0.0

port

UDP port number on which to listen

optional

4738

maxPacketSize

Maximum packet size in bytes (anything greater will be truncated)

optional

8096

templateTimeout

Number of milliseconds after which templates timeout

optional

1800000 (30 minutes)

10.1.3. sFlow UDP Listener

This UDP based listener can be used to open a UDP socket to deal with incoming sFlow packets.

Facts

Class Name

org.opennms.netmgt.telemetry.listeners.sflow.Listener

Supported on Minion

Yes

Parameters
Table 88. Listener specific parameters for the sFlow UDP listener
Parameter Description Required Default value

host

IP address on which to bind the UDP socket

optional

0.0.0.0

port

UDP port number on which to listen

optional

6343

maxPacketSize

Maximum packet size in bytes (anything greater will be truncated)

optional

8096

10.1.4. IPFIX UDP Listener

This UDP based listener can be used to open a UDP socket to deal with incoming IPFIX packets.

Facts

Class Name

org.opennms.netmgt.telemetry.listeners.flow.ipfix.UdpListener

Supported on Minion

Yes

Parameters
Table 89. Listener specific parameters for the IPFIX UDP listener
Parameter Description Required Default value

host

IP address on which to bind the UDP socket

optional

0.0.0.0

port

UDP port number on which to listen

optional

4738

maxPacketSize

Maximum packet size in bytes (anything greater will be truncated)

optional

8096

templateTimeout

Number of milliseconds after which templates timeout

optional

1800000 (30 minutes)

10.1.5. IPFIX TCP Listener

This TCP based listener can be used to open a TCP socket to deal with IPFIX sessions.

Facts

Class Name

org.opennms.netmgt.telemetry.listeners.flow.ipfix.TcpListener

Supported on Minion

Yes

Parameters
Table 90. Listener specific parameters for the IPFIX TCP listener
Parameter Description Required Default value

host

IP address on which to bind the TCP socket

optional

0.0.0.0

port

TCP port number on which to listen

optional

4739

10.2. Protocols

10.2.1. IPFIX Adapter

The IPFIX adapter is used to handle IPFIX payloads generated by either of the UDP or TCP based IPFIX listeners. Flows are decoded from the messages into the canonical flow format and are published to the flow repository

Facts

Class Name

org.opennms.netmgt.telemetry.adapters.netflow.ipfix.IpfixAdapter

Parameters

This adapter does not currently have any configurable parameters.

10.2.2. Junos Telemetry Interface

The Junos Telemetry Interface (JTI) allows to push operational statistics asynchronously to OpenNMS Horizon. OpenNMS Horizon sends a request to stream periodic updates once to the device. Data is generated as Google protocol buffers (gpb) structured messages over UDP. Detailed information about JTI can be found in Juniper Documentation.

To enable support for Junos Telemetry Interface (JTI), edit ${OPENNMS_HOME}/etc/telemetryd-configuration.xml set enabled=true for JTI protocol.

Enable JTI protocol in telemetryd-configuration.xml
<protocol name="JTI" description="Junos Telemetry Interface (JTI)" enabled="true">

Apply the changes without restarting by sending a reloadDaemonConfig event in the CLI or the WebUI:

Send a reloadDaemonConfig event through CLI
${OPENNMS_HOME}bin/send-event.pl -p 'daemonName Telemetryd' uei.opennms.org/internal/reloadDaemonConfig

By default, this will open a UDP socket bound to 0.0.0.0:50000 to which JTI messages can be forwarded.

Configure JTI Listener on a Minion

To enable and configure an UDP Listener for JTI on Minion, connect to the Karaf Console and set the following properties:

$ ssh -p 8201 admin@localhost
...
admin@minion()> config:edit org.opennms.features.telemetry.listeners-udp-50000
admin@minion()> config:property-set name JTI
admin@minion()> config:property-set class-name org.opennms.netmgt.telemetry.listeners.udp.UdpListener
admin@minion()> config:property-set listener.port 50000
admin@minion()> config:update
The protocol must also be enabled on OpenNMS Horizon for the messages to be processed.

10.2.3. JTI Adapter

The JTI adapter is used to handle Junos Telemetry Interface payloads. Messages are decoded using the published protobuf specifications and forwarded to a JSR-223 compatible script (i.e. Beanshell or Groovy) for further processing. Using the script extension you can extract the desired metrics from the JTI messages and persist the results as time series data.

Facts

Class Name

org.opennms.netmgt.telemetry.adapters.jti.JtiGpbAdapter

Parameters
Table 91. Adapter specific parameters for the JtiGpbAdapter
Parameter Description Required Default value

script

Full path to the script used to handle the JTI messages

required

(none)

Scripting

The script will be invoked for every JTI message that is received and succesfully decoded.

The following globals will be passed to the script:

Table 92. Globals passed to the script
Parameter Description Type

agent

The agent (node) against which the metrics will be associated

org.opennms.netmgt.collection.api.CollectionAgent

builder

Builder in which the resources and metrics should be added

org.opennms.netmgt.collection.support.builder.CollectionSetBuilder

msg

Decoded JTI message from which the metrics should be extracted

org.opennms.netmgt.telemetry.adapters.jti.proto.TelemetryTop

NetFlow v5 Adapter

The NetFlow v5 adapter is used to handle NetFlow v5 payloads.

Facts

Class Name

org.opennms.netmgt.telemetry.adapters.netflow.Netflow5Adapter

Parameters

This adapter does not currently have any configurable parameters.

Netflow v9 Adapter

The Netflow v9 adapter is used to handle Netflow v9 payloads generated by the Netflov9 UDP listener. Flows are decoded from the messages into the canonical flow format and are published to the flow repository

Facts

Class Name

org.opennms.netmgt.telemetry.adapters.netflow.v9.Netflow9Adapter

Parameters

This adapter does not currently have any configurable parameters.

10.2.4. Cisco NX-OS Telemetry

The Cisco NX-OS Telemetry allows to push operational statistics asynchronously to OpenNMS Horizon. OpenNMS Horizon sends a request to stream periodic updates once to the device. Data is generated as Google protocol buffers (gpb) structured messages over UDP. Detailed information about NX-OS can be found in NXOS Documentation.

To enable support for NX-OS Telemetry, edit ${OPENNMS_HOME}/etc/telemetryd-configuration.xml set enabled=true for NXOS protocol.

Enable NX-OS protocol in telemetryd-configuration.xml
<protocol name="NXOS" description="Cisco NX-OS Telemetry" enabled="true">

Apply the changes without restarting by sending a reloadDaemonConfig event in the CLI or the WebUI:

Send a reloadDaemonConfig event through CLI
${OPENNMS_HOME}bin/send-event.pl -p 'daemonName Telemetryd' uei.opennms.org/internal/reloadDaemonConfig

By default, this will open a UDP socket bound to 0.0.0.0:50001 to which NXOS messages can be forwarded.

Configure NX-OS Listener on a Minion

To enable and configure an UDP Listener for NX-OS on Minion, connect to the Karaf Console and set the following properties:

$ ssh -p 8201 admin@localhost
...
admin@minion()> config:edit org.opennms.features.telemetry.listeners-udp-50000
admin@minion()> config:property-set name NXOS
admin@minion()> config:property-set class-name org.opennms.netmgt.telemetry.listeners.udp.UdpListener
admin@minion()> config:property-set listener.port 50001
admin@minion()> config:update
The protocol must also be enabled on OpenNMS Horizon for the messages to be processed.

10.2.5. Cisco NX-OS Adapter

The NX-OS adapter is used to handle Cisco NX-OS Telemetry payloads. Messages are decoded using the published protobuf (proto3) specifications and forwarded to a JSR-223 compatible script (i.e. Beanshell or Groovy) for further processing. Using the script extension you can extract the desired metrics from the NX-OS messages and persist the results as time series data.

Facts

Class Name

org.opennms.netmgt.telemetry.adapters.nxos.NxosGpbAdapter

Parameters
Table 93. Adapter specific parameters for the NxosGpbAdapter
Parameter Description Required Default value

script

Full path to the script used to handle the NXOS messages

required

(none)

Scripting

The script will be invoked for every NX-OS message that is received and succesfully decoded.

The following globals will be passed to the script:

Table 94. Globals passed to the script
Parameter Description Type

agent

The agent (node) against which the metrics will be associated

org.opennms.netmgt.collection.api.CollectionAgent

builder

Builder in which the resources and metrics should be added

org.opennms.netmgt.collection.support.builder.CollectionSetBuilder

msg

Decoded NX-OS message from which the metrics should be extracted

org.opennms.netmgt.telemetry.adapters.nxos.proto.TelemetryBis

10.2.6. sFlow Adapter

The sFlow adapter is used to handle sFlow payloads generated by the sFlow listener. Flows are decoded from the messages into the canonical flow format and are published to the flow repository.

Facts

Class Name

org.opennms.netmgt.telemetry.adapters.netflow.sflow.SFlowAdapter

Parameters

This adapter does not currently have any configurable parameters.

11. Plugins

11.1. Alarm Change Notifier Plugin

The Alarm Change Notifier Plugin generates new OpenNMS events corresponding to changes in alarms The new events are defined in the <opennms home>/etc/events/AlarmChangeNotifierEvents.xml file

These events contain a json copy of the database table before changes in %parm[oldalarmvalues]% and after changes in %parm[newalarmvalues]%. (New Alarm events do not contain %parm[oldalarmvalues] and Alarm Deleted events do not contain %parm[newalarmvalues]%)

%parm[alarmid]% contains the alarmid of the alarm which has changed

The generated event itself references copies of the nodeid, interface and service contained in the original alarm. This way the alarm change events are associated with the original source of the alarm.

Alarm change events have a severity of normal since they only reflect changes to the alarm.

Events from the alarm-change-notifier are also used by the opennms-es-rest plugin to send alarm history to Elasticsearch

The table below lists the parameters included with each type of Alarm Change Event. Parameters are listed in the %parm[xxx]% format which is used to reference them in AlarmChangeNotifierEvents.xml

To simplify searching and visualisation, specific parameter values are also added for each alarm change event type. These additional values are described in the table below.

Alarm Change Event Type UEI Additional Parameters

New Alarm Created

uei.opennms.org/plugin/AlarmChangeNotificationEvent/NewAlarmCreated

%parm[alarmid]% %parm[newalarmvalues]%

Alarm Severity Changed

uei.opennms.org/plugin/AlarmChangeNotificationEvent/AlarmSeverityChanged

%parm[alarmid]% %parm[oldalarmvalues]% %parm[newalarmvalues]% %parm[severity]% %parm[oldseverity]%

Alarm Cleared

uei.opennms.org/plugin/AlarmChangeNotificationEvent/AlarmCleared

%parm[alarmid]% %parm[oldalarmvalues]% %parm[newalarmvalues]%

Alarm Deleted

uei.opennms.org/plugin/AlarmChangeNotificationEvent/AlarmDeleted

%parm[alarmid]% %parm[oldalarmvalues]%

Alarm Changed

uei.opennms.org/plugin/AlarmChangeNotificationEvent/AlarmChanged

%parm[alarmid]% %parm[oldalarmvalues]% %parm[newalarmvalues]%

Alarm Acknowledged

uei.opennms.org/plugin/AlarmChangeNotificationEvent/AlarmAcknowledged

%parm[alarmid]% %parm[oldalarmvalues]% %parm[newalarmvalues]% %parm[alarmid]% %parm[alarmacktime]% %parm[alarmackuser]%

Alarm UnAcknowledged

uei.opennms.org/plugin/AlarmChangeNotificationEvent/AlarmUnAcknowledged

%parm[alarmid]% %parm[oldalarmvalues]% %parm[newalarmvalues]%

Alarm Suppressed

uei.opennms.org/plugin/AlarmChangeNotificationEvent/AlarmSuppressed

%parm[alarmid]% %parm[oldalarmvalues]% %parm[newalarmvalues]% %parm[suppressedtime]% %parm[suppresseduntil]% %parm[suppresseduser]%

Alarm UnSuppressed

uei.opennms.org/plugin/AlarmChangeNotificationEvent/AlarmUnSuppressed

%parm[alarmid]% %parm[oldalarmvalues]% %parm[newalarmvalues]%

TroubleTicketStateChange

uei.opennms.org/plugin/AlarmChangeNotificationEvent/TroubleTicketStateChange

%parm[alarmid]% %parm[oldalarmvalues]% %parm[newalarmvalues]% %parm[tticketid]% %parm[tticketstate]%

Sticky Memo Added

uei.opennms.org/plugin/AlarmChangeNotificationEvent/StickyMemoAdded

%parm[alarmid]% %parm[oldalarmvalues]% %parm[newalarmvalues]% %parm[stickymemo]%

Sticky Memo Update

uei.opennms.org/plugin/AlarmChangeNotificationEvent/StickyMemoUpdate

%parm[alarmid]% %parm[oldalarmvalues]% %parm[newalarmvalues]% %parm[oldalarmvalues]% %parm[stickymemo]% %parm[author]% %parm[body]% %parm[memovalues]%

Journal Memo Update

uei.opennms.org/plugin/AlarmChangeNotificationEvent/JournalMemoUpdate

%parm[alarmid]% %parm[newalarmvalues]% %parm[oldalarmvalues]% %parm[author]% %parm[body]% %parm[reductionkey]% %parm[memovalues]%