AlertToSnmp

Thu Dec 03 13:33:09 EST 2009

This handler forwards Augur alerts as SNMP events (either v.1 traps, or v.2c notifications). The following alert fields are encapsulated as SNMP varbinds:

TypeOIDValue
OctetString1.3.6.1.4.1.22765.1.1.1.8.1.1.2.0Gateway name
OctetString1.3.6.1.4.1.22765.1.1.1.8.1.1.3.0Element name
OctetString1.3.6.1.4.1.22765.1.1.1.8.1.1.4.0Rule node path name
OctetString1.3.6.1.4.1.22765.1.1.1.8.1.1.5.0Alert summary
Integer321.3.6.1.4.1.22765.1.1.1.8.1.1.6.0Alert priority number
Counter321.3.6.1.4.1.22765.1.1.1.8.1.1.7.0Alert count
Counter321.3.6.1.4.1.22765.1.1.1.8.1.1.8.0Alert initial event time (See notes below.)
Counter321.3.6.1.4.1.22765.1.1.1.8.1.1.9.0Alert validation time (See notes below.)
Counter321.3.6.1.4.1.22765.1.1.1.8.1.1.10.0Alert clear time (See notes below.)

The condition of the alert (new or cleared) is conveyed by the trap's specific number. A new alert is "6", and a cleared alert is "7". For version 1 traps, this number is passed as the trap's enterprise-specific field. For version 2 notifications, this number is passed in a varbind for the snmpTrapOID "1.3.6.1.6.3.1.1.4.1.0". The varbind's value is Augur's product OID, appended by the specific number; "1.3.6.1.4.1.22765.1.1.0.x", where 'x' is the specific trap number (6 or 7). This format is per the specification, RFC 1908.

Note that the sysUpTime value in the traps represents the time since the Augur server was started (in hundredths of seconds). It's probably of minimal use, but the RFP requires this field.

Also note that the time stamps in the last three varbinds represent the number of full seconds since the epoch (00:00:00 January 1, 1970 GMT). For most computing uses, you just have to convert the number to 64-bits, then multiply by 1000 to get milliseconds. (That order of operations is important to avoid overflow during the multiplication.)

Warning: Based on the varbind's 32-bit limitation (for SNMP v.1 compatibility), this value will roll over (starting back at zero) at 06:28:15 February 7, 2106 GMT. Be sure to roll your clocks forward on that day! (Just add 0x100000000 to the result.)

Due to the order of execution, the specific alert validation time and clear time are not available to the hander when the asoociated isValid and alertCompleted calls are made, so this handler assumes that the correct values are "now". This should be a very accurate assumption, although occassionally the trap data may differ from the Augur live data, but usually no more than a second. It is normal for the initial event time to be exactly the same as the validation time, if no validation delays (timers or threshold counters) are defined in the associated rule node.

Installation

An instance of this plug-in should be placed at the isValid and alertCompleted handler folders. If other handler(s) already exist in these folders, then this instance should be added at the end of an AND logic tree, so that this handler is only fired after all other handlers agree (return true).

Usually, you should use the gateway's scope (the gateway node's Handlers tab).

Samples

The following are examples of a v.1 trap and a v.2c notification, as converted to XML by the SnmpRx connector. Note that this event was a new alert, as indicated by the specific field value (6) in the v.1 version, and the last digit in the value of the second varbind for v.2c. 
<trapV1 peer="127.0.0.1" agent="192.168.2.1" enterprise="1.3.6.1.4.1.22765" generic="6" specific="6" ticks="736664">
  <varbindString oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.2.0" value="Test Gateway"/>
  <varbindString oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.3.0" value="Some Element Name"/>
  <varbindString oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.4.0" value="/MyRuleTree/Alerts/Pings/Availability/Down"/>
  <varbindString oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.5.0" value="Ping response test failed."/>
  <varbindInteger oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.6.0" value="1"/>
  <varbindCounter oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.7.0" value="1"/>
  <varbindCounter oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.8.0" value="1259088268"/>
  <varbindCounter oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.9.0" value="1259088268"/>
  <varbindCounter oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.10.0" value="0"/>
</trapV1>

<trapV2c peer="127.0.0.1">
  <varbindTicks oid="1.3.6.1.2.1.1.3.0" value="736664"/>
  <varbindOID oid="1.3.6.1.6.3.1.1.4.1.0" value="1.3.6.1.4.1.22765.1.1.0.6"/>
  <varbindString oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.2.0" value="Test Gateway"/>
  <varbindString oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.3.0" value="Some Element Name"/>
  <varbindString oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.4.0" value="/MyRuleTree/Alerts/Pings/Availability/Down"/>
  <varbindString oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.5.0" value="Ping response test failed."/>
  <varbindInteger oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.6.0" value="1"/>
  <varbindCounter oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.7.0" value="1"/>
  <varbindCounter oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.8.0" value="1259088268"/>
  <varbindCounter oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.9.0" value="1259088268"/>
  <varbindCounter oid="1.3.6.1.4.1.22765.1.1.1.8.1.1.10.0" value="0"/>
</trapV2c>