
= HostResourceSwRunMonitor
:description: Learn about the HostResourceSwRunMonitor in OpenNMS {page-component-title} that tests the running state of one or more processes, via SNMP.

This monitor tests the running state of one or more processes.
It does this via SNMP by inspecting the http://www.ietf.org/rfc/rfc2790[HOST-RESOURCES-MIB] hrSwRunTable.
The test matches a given process as hrSwRunName against the numeric value of the hrSwRunState.

This monitor uses SNMP to accomplish its work.
Therefore, systems against which you use it 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 ship with Microsoft Windows, support this MIB.
Out-of-the-box support for HOST-RESOURCES-MIB among commercial Unix operating systems may be somewhat spotty.

== Monitor facts

[cols="1,7"]
|===
| Class Name
| `org.opennms.netmgt.poller.monitors.HostResourceSwRunMonitor`
|===

== Configuration and use

.Monitor-specific parameters for the HostResourceSwRunMonitor
[options="header"]
[cols="1,3,2"]
|===
| Parameter
| Description
| Default

3+| *Required*

| service-name
| The name of the process to be monitored.
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 it will be considered an exact match.
| n/a

3+|*Optional*

| port
| The port of the server's SNMP agent to test.
| from `snmp-config.xml`

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

| service-name-oid
| The numeric object identifier (OID) from which process names are queried.
Defaults to hrSwRunName.
You should never change it 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_.
| .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.
| .1.3.6.1.2.1.25.4.2.1.7

| min-services
| If `match-all` is `true`, the minimum number of services that need to match for the monitor to poll as up.
| n/a

| max-services
| If `match-all` is `true`, the maximum number of services that need to match for the monitor to poll as up.
| n/a
|===

This monitor implements the <<reference:service-assurance/introduction.adoc#ref-service-assurance-monitors-common-parameters, Common Configuration Parameters>>.

NOTE: For `min-services` and `max-services`, the poller service is up if `services_count >= min-services` and `services_count <= max-services`.
If either one is not defined, then only one has to pass.
If neither is defined, the monitor checks all instances to see if they are running.

== Examples

The following example shows how to monitor the `httpd` process running on a server using this monitor.

Note that you must include the `monitor` section for each service in your definition.

Define the configuration in `poller-configuration.xml` as follows:

[source, xml]
----
<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 if the process is in a valid state (in other words, 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.
