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.

Monitor Facts

Class Name

org.opennms.netmgt.poller.monitors.SystemExecuteMonitor

Remote Enabled

true

Configuration and Use

Table 1. 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.

Providing always a script output with a more detailed test error makes it easier to diagnose the problem when the nodeLostDown event occurs.

This monitor implements the Common Configuration Parameters.

Table 2. 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.

${\nodeidl}

Nodeid of the node the monitor is associated to.

${nodelabel}

Nodelabel of the node the monitor is associated to.

Examples

Placeholder use

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

Exit status example

<service name="Script_Example" interval="300000" user-defined="true" status="on">
  <parameter key="script" value="/opt/opennms/contrib/Script_Example.sh"/>
  <parameter key="timeout" value="5000"/>
</service>

<monitor service="Script_Example" class-name="org.opennms.netmgt.poller.monitors.SystemExecuteMonitor"/>
#!/usr/bin/env bash

# ...some test logic

RESULT="TEST OK"

if [[ "TEST OK" == "${RESULT}" ]]; then
  echo "This test passed"
  exit 0
else
  echo "This test failed because of ..."
  exit 1
fi
<service name="Script_Example" interval="300000" user-defined="true" status="on">
  <parameter key="script" value="/opt/opennms/contrib/Script_Example.sh"/>
  <parameter key="banner" value="PASSED"/>
  <parameter key="timeout" value="5000"/>
</service>

<monitor service="Script_Example" class-name="org.opennms.netmgt.poller.monitors.SystemExecuteMonitor"/>
#!/usr/bin/env bash

# ...some test logic

RESULT="TEST OK"

if [[ "TEST OK" == "${RESULT}" ]]; then
  echo "PASSED"
else
  echo "FAILED"
fi

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.