== Description ==
This poller monitor's job is to monitor the running state of one or more processes. It does this via SNMP by inspecting the ''hrSwRunTable'' of the [http://www.ietf.org/rfc/rfc2790 HOST-RESOURCES-MIB], matching values of ''hrSwRunName'' against a configured string, and for rows that match comparing the value of ''hrSwRunState'' against an optional numeric value.

== Prerequisites ==
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. If OpenNMS is able to discover and collect data from the SNMP service on a given node, then that first requirement has almost certainly been met. 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.

==HostResourceSwRunMonitor Parameters ==

=== Monitor-specific required parameters ===
; service-name : The name of the process to be monitored. This parameter's value is case-sensitive.

=== Monitor-specific optional parameters ===
; 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''.
; 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}'''. Defaults to ''2'' ('''runnable''').
; service-name-oid : The numeric object identifier (OID) from which process names are queried. Defaults to ''hrSwRunName'' == '''.1.3.6.1.2.1.25.4.2.1.2''' and should never be changed under normal circumstances.
; service-status-oid : The numeric object identifier (OID) from which run status is queried. Defaults to ''hrSwRunStatus'' = '''.1.3.6.1.2.1.25.4.2.1.7''' and should never be changed under normal circumstances.

=== Parameters common to all monitors ===
; ds-name
; rrd-repository
; port
; timeout
; retry

== Example config ==
As an example, let's check for a process called ''httpd'' using this monitor.

=== capsd-configuration.xml ===

Currently the SnmpPlugin lacks a way to discover the presence of processes for polling with this monitor . It's possible, however, to use the LoopPlugin to force the appearance of such a service on one or more interfaces. For instance, to make the service described above appear on all interfaces with IP addresses in the range 192.168.42.50 through 192.168.42.69, and on 192.168.42.42:

<pre>
<protocol-plugin protocol="Process_httpd"
class-name="org.opennms.netmgt.capsd.LoopPlugin"
scan="off" user-defined="false">
<protocol-configuration scan="enable" user-defined="false">
<include-range begin="192.168.42.50" end="192.168.42.69" />
<specific>192.168.42.42</specific>
</protocol-configuration>
</protocol-plugin>
</pre>

As an alternative to Capsd, provisioning groups may be used. In this case the service will still need to be defined in '''capsd-configuration.xml''', but it need not be forced onto any interfaces.

=== poller-configuration.xml ===

To test that at least one process called ''httpd'' in a running or runnable state, the following service definition will work:

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


For a slightly more advanced example, let's test that at least one process called ''httpd'' exists, and that all processes with that name are in a valid state, i.e. have a run-level no higher than ''notRunnable(3)'':
<pre>
<service name="Process_httpd" interval="300000" user-defined="false" status="on">
<parameter key="retry" value="1"/>
<parameter key="timeout" value="3000"/>
<parameter key="service-name" value="httpd"/>
<parameter key="run-level" value="3"/>
<parameter key="match-all" value="true"/>
</service>
</pre>

Important Notes:

* The name attribute of the service in poller-configuration.xml needs to match the protocol attribute of the protocol-plugin in capsd-configuration.xml.
* You'll also need a line to map the new service to a monitor class (see at the end of the file):

<pre>
<monitor service="Process_httpd" class-name="org.opennms.netmgt.poller.monitors.HostResourcesSwRunMonitor"/>
</pre>


[[Category:Monitors]]
[[Category:Configuration]]
{{New Feature In|1.5.94}}