anchor.diff: +
   === SnmpMonitor
   
  -The SNMP monitor can perform 2 types of tests against SNMP MIB objects: .
  -. Test the value of a specific SNMP MIB object; 
  -. Test the value of all SNMP MIB objects within a MIB branch (_walk_ mode).
  +The SNMP monitor gives a generic possibility to monitor states and results from SNMP agents.
  +This monitors 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 `match-all` parameter is used.
  +By default the `match-all` is set to `false` which puts this monitor to test a scalar object ID.
  +
  +WARNING: This monitor can't be used on the OpenNMS Remote Poller.
  +It is currently not possible for the Remote Poller to have access to the SNMP configuration of a central OpenNMS.
  +
  +[options="autodwidth"]
  +|===
  +|
  +|===
   
   ==== Monitor facts
   
   [options="autowidth"]
   |===
   | Class Name     | `org.opennms.netmgt.poller.monitors.SnmpMonitor`
  -| Remote Enabled | true
  +| Remote Enabled | false
   |===
   
   ==== Configuration and Usage
  
positive.code: |===
  | 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.i                | optional | `false`
  | `match-all`       | Sets the monitor in _walk_ mode when set.
                        If set to _true_, specifies that the value of _every_ object encountered in the walk must
                        match the criteria specified by `operand` and `operator`.
                        If 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`.           | optional | `true`
  | `maximum`         | Valid only when `match-all` is set to _count_. 
                        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_. 
                        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,i
                        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.
  
negative.code:                             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:
                        `<` Less than. Both operand and observed object value must be numeric.
                        `>`  Greater than. Both operand and observed object value must be numeric.
                        `<=` Less than or equal to. Both operand and observed object value must be numeric.
                        `>=` 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) if you are editing the `poller-configuration.xml` file by hand.                      | 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'
  
  | `retry`           | Number of polls to attempt.                                                                      | optional | `from snmp-config.xml`
  | `retries`         | Deprecated.
                        Same as `retry`.
                        Parameter `retry` takes precedence if both are set.                                              | optional | `from snmp-config.xml`
  | `timeout`         | Timeout in milliseconds for retrieving the object's value.                                       | optional | `from snmp-config.xml`
  | `walk`            | If set to `true`, sets the monitor in _walk_ mode, and the monitor will perform _GET-NEXT_ or
                        _GET-BULK_ operations -effecting a "walk" to the end of the MIB branch specified by the
                        `oid` parameter- instead of the default _GET_ operation.
                        This parameter is typically used to monitor all instances of a tabular object.
                        When used alone, the service is considered available if the value of *any* object encountered
                        in the walk matches the criteria specified by operand and operator.
                        See also the `match-all`, `minimum`, and `maximum` parameters.                                   | optional | `false`
  |===
  
  ==== Example for monitoring scalar object
  As a working example we want to monitor the system fan status which is provided as a scalar object ID.
  The manufacturer MIB gives us the following information:
  
  .Description of the cpqHeThermalSystemFanStatus (.1.3.6.1.4.1.232.6.2.6.4.0) scalar object id from http://h18013.www1.hp.com/products/servers/management/hpsim/mibkit.html[CPQHLTH-MIB]
  [source, asn1]
  ----
  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."
  ----
  
  A test for the SNMP monitor can be configured as the following use case.
  Poll the fan status and test if the returned value is `ok(2)` and set it to _up_.
  Any other value indicates a service outage and marks the service _down_.
  
  The test monitoring the scalar object ID for the fan status can be configured as the following:
  
  .Example SnmpMonitor as HP InsightManager fan monitor in poller-configuration.xml
  [source, 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
  
  ==== Example test SNMP table with all matching values
  The second mode allows to monitor values of a whole SNMP table.
  As a practical use case the physical status of a set of physical drives is monitored.
  
  .Description of the cpqDaPhyDrvStatus (.1.3.6.1.4.1.232.3.2.5.1.1.6) table object id from http://h18013.www1.hp.com/products/servers/management/hpsim/mibkit.html[CPQIDA-MIB]
  [source, asn1]
  ----
  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.
  ----
  
  .Example SnmpMonitor as HP Insight physical dri
  ve monitor in poller-configuration.xml
  [source, 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
  
  ==== 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_ (1.3.6.1.2.1.4.21.1.9) from the http://www.ietf.org/rfc/rfc1213.txt[RFC1213-MIB2].
  The MIB description gives us the following information:
  
  [source, asn1]
  ----
  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.
  [source, xml]
  ----
  <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`
  