From OpenNMS
Jump to: navigation, search

Warning.png Consider SystemExecuteMonitor instead

The GpMonitor class is pretty hard to work with because it often requires extensive adaptations to your scripts' behavior to meet the interface contract. The SystemExecuteMonitor accomplishes exactly the same thing in a much more flexible way.

I know that this page is crappy, I threw it together in a terrible hurry

The General Purpose Poller Monitor (GpMonitor or just GP for short) allows polling to be delegated to an external script written in an arbitrary language.

In OpenNMS 1.12.2 the SystemExecuteMonitor is introduced to replace the GpMonitor, see SystemExecuteMonitor.

The following is ripped from

* This class is designed to be used by the service poller framework to test the
* availability of a generic service by calling an external script or program.
* The external script or program will be passed two options: --hostname, the IP
* address of the host to be polled, and --timeout, the timeout in seconds.
* Additional options or arguments can be specified in the poller configuration.

DEFAULT_TIMEOUT = 3000; // 3 second timeout

Script Interface Contract

Again ripped from

During the poll an attempt is made to call the specified external script or program. If the connection request is successful, the banner line returned as standard output by the script or program is parsed for a partial match with the banner string specified in the poller configuration. Provided that the script's response is valid we set the service status to SERVICE_AVAILABLE and return.

The timeout is handled by ExecRunner and is also passed as a parameter to the script or program being called.

From the Release notes

General Purpose Script Poller: Bill Ayres has written a poller that will execute a script, and based on the response from that script it will mark the service as being "up" or "down", called the "General Purpose" or "Gp" Poller. He has used it to monitor RADIUS servers, for example.

GpPlugin and GpMonitor work much like TcpPlugin and TcpMonitor in that you can use them to define as many custom services as you need, each with a unique service name.

GpPlugin and GpMonitor call an external script or program to test a particular service. The script will be passed the IP address of the interface OpenNMS is testing ( as --hostname [IP Address]), followed by the timeout (as --timeout [timeout]), followed by any optional arguments that may need to passed.

The script is expected to return a string as standard output which is then compared to the banner property or parameter to determine success or failure of the test.

The timeout is implemented in GpPlugin and GpMonitor. However, some scripts may want to know how long OpenNMS is going to wait for a reply, so the timeout value is passed to the script, and can be ignored by the script if it is not needed.

GpPlugin and GpMonitor also check the exit status of the script or program. If it is not zero, then the test fails. They will also gather and log any standard error output from the script, but the presence of error output does not prevent the test from succeeding if the banner matches the standard output.

Example poller parameters are shown below. All of these are optional except script, which is required, and will cause an exception to be logged if it is missing.

Example plugin properties are also shown below. All of these are optional except script, which is required, and will cause an exception to be logged if it is missing.

These programs use the exec method from Java's Runtime class. Exec is known to have pitfalls. (See When Runtime.exec() won't) Also, exec does not have a built-in timeout feature. In deciding what to do about these shortcomings, Bill discovered that Scott McCrory has already done it with his ExecRunner class. ExecRunner and StreamGobbler are at SourceForge as part of Spumoni.

One more word about the timeout. ExecRunner expects the timeout in integer seconds, not milliseconds, and a value of zero means wait indefinitely. To avoid confusion, Bill maintained the OpenNMS practice of specifying the timeout in milliseconds. Before passing it on to ExecRunner, it gets converted to seconds in the following manner: Zero remains zero, 1 thru 1999 gets converted to 1 second, 2000 thru 2999 -> 2 seconds, 3000 thru 3999 -> 3 seconds, etc..

Included in contrib is a simple perl test script,, that is handy for testing, since it is easy to edit and change its behaviour.

To implement Gp, add the following entries, substituting your information as needed.

For capsd configuration:

Attention: class-name is version dependent for both capsd and poller. Property key "script", parameter key "script" and parameter key "rrd-repository" must be consistent with your particular installation.

<protocol-plugin protocol="GPtest" class-name="org.opennms.netmgt.capsd.plugins.GpPlugin" scan="on" user-defined="true">
   <property key="script" value="/opt/OpenNMS/contrib/"/>
   <property key="banner" value="success"/>
   <property key="args" value="caps-arg1 caps-arg2"/>
   <property key="timeout" value="3000"/>
   <property key="retry" value="1"/>

And for poller configuration:

<service name="GPtest" interval="300000" user-defined="false" status="on">
   <parameter key="script" value="/opt/OpenNMS/contrib/"/>
   <parameter key="banner" value="successful"/>
   <parameter key="args" value="poll-arg1 poll-arg2"/>
   <parameter key="retry" value="1"/>
   <parameter key="timeout" value="2000"/>
   <parameter key="rrd-repository" value="/var/opennms/rrd/response"/>
   <parameter key="ds-name" value="GPtest"/>

and the monitor service entry:

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

A Real-World Example: SAV Scanning

This example sets up a GpPlugin / GpMonitor pair to test the response time of Symantec AntiVirus ICAP scanners using the ssecls utility, available from Symantec's Platinum Support Site. Note that you will need ssecls for the correct architecture.


    <protocol-plugin protocol="GPsav" class-name="org.opennms.netmgt.capsd.plugins.GpPlugin" scan="on" user-defined="true">
      <property key="script" value="/usr/local/bin/ssecls-gp-wrapper" />
      <property key="banner" value="SUCCESS" />
      <property key="timeout" value="3000" />
      <property key="retry" value="1" />


<poller-configuration ...>
    <package ...>
        <service name="GPsav" interval="300000" user-defined="false" status="on">
            <parameter key="script" value="/usr/local/bin/ssecls-gp-wrapper" />
            <parameter key="banner" value="SUCCESS" />
            <parameter key="retry" value="1" />
            <parameter key="timeout" value="3000" />
            <parameter key="rrd-repository" value="/opt/opennms/share/rrd/response" />
            <parameter key="ds-name" value="GPsav" />
    <monitor service="GPsav"    class-name="org.opennms.netmgt.poller.monitors.GpMonitor" />

#report keys, list ALL prefab reports here!
reports=icmp, avail, dhcp, dns, http, http-8000, http-8080, pop3, radius, smtp, ssh, jboss, snmp, gpsav

report.gpsav.command=--title="SAV Scan Time" \
 --vertical-label="Seconds" \
 DEF:rtMills={rrd1}:GPsav:AVERAGE \
 CDEF:rt=rtMills,1000,/ \
 LINE1:rt#0000ff:"Scan Time" \
 GPRINT:rt:AVERAGE:" Avg  \\: %8.2lf %s" \
 GPRINT:rt:MIN:"Min  \\: %8.2lf %s" \
 GPRINT:rt:MAX:"Max  \\: %8.2lf %s\\n"

Shell script ssecls-gp-wrapper:




while [ "$1" != "" ]; do
    if [ "$1" = "--hostname" ]; then

if [ "$HOSTNAME" = "" ]; then
    echo FAIL no host specified
    exit 1

echo $SSECLS_OUTPUT | /bin/grep 'Files Scanned = 1' 1>/dev/null 2>/dev/null
if [ $? = 0 ]; then
    echo SUCCESS
    exit 0
    echo FAIL
    echo Did not match expr 'Files Scanned = 1' 1>&2
    exit 1

See also

SystemExecuteMonitor GpMonitor