Difference between revisions of "SNMP Agent XML Files"

From Control Solutions IoTServer Documentation
Jump to navigation Jump to search
 
(13 intermediate revisions by the same user not shown)
Line 1: Line 1:
 
== SNMP Agent XML Files ==
 
== SNMP Agent XML Files ==
<?xml version="1.0" encoding="ISO-8859-1" ?>
+
 
 +
'''Example XML File'''
 +
 
 +
&lt;?xml version="1.0" encoding="ISO-8859-1" ?&gt;<br>
 
&lt;!-- IoT Server SNMP Agent configuration file --&gt;
 
&lt;!-- IoT Server SNMP Agent configuration file --&gt;
  
 
&lt;configuration&gt;
 
&lt;configuration&gt;
  
&lt;mib_vars_int32&gt;
+
&lt;mib_vars_int32&gt;<br>
  &lt;var index="1" object="1"/&gt;
+
&lt;var index="1" object="1"/&gt;<br>
  &lt;var index="2" object="2"/&gt;
+
&lt;var index="2" object="2"/&gt;<br>
  &lt;var index="3" object="3"/&gt;
+
&lt;var index="3" object="3"/&gt;<br>
  &lt;var index="4" object="4" scale="10"/&gt;
+
&lt;var index="4" object="4" scale="10"/&gt;<br>
  &lt;var index="5" object="5" scale="100"/&gt;
+
&lt;var index="5" object="5" scale="100"/&gt;<br>
&lt;/mib_vars_int32&gt;
+
&lt;/mib_vars_int32&gt;<br>
  
&lt;mib_vars_uint64&gt;
+
&lt;mib_vars_uint64&gt;<br>
  &lt;var index="1" object="3"/&gt;
+
&lt;var index="1" object="3"/&gt;<br>
 
&lt;/mib_vars_uint64&gt;
 
&lt;/mib_vars_uint64&gt;
  
&lt;mib_vars_double&gt;
+
&lt;mib_vars_double&gt;<br>
  &lt;var index="1" object="4"/&gt;
+
&lt;var index="1" object="4"/&gt;<br>
  &lt;var index="2" object="5"/&gt;
+
&lt;var index="2" object="5"/&gt;<br>
 
&lt;/mib_vars_double&gt;
 
&lt;/mib_vars_double&gt;
  
&lt;mib_vars_charstr&gt;
+
&lt;mib_vars_charstr&gt;<br>
  &lt;var index="1" object="6"/&gt;
+
&lt;var index="1" object="6"/&gt;<br>
  &lt;var index="2" object="7"/&gt;
+
&lt;var index="2" object="7"/&gt;<br>
 
&lt;/mib_vars_charstr&gt;
 
&lt;/mib_vars_charstr&gt;
  
&lt;trap_devices&gt;
+
&lt;trap_devices&gt;<br>
  &lt;dev id="1" version="3"  secLevel="3" peername="192.168.1.109:162" name="Dell" devMask="1" username="jim" authType="MD5" authPhrase="jimsAuthPhrase" privType="DES" privPhrase="jimsPrivPhrase" engineId="0x80000ee7031803731a2386"/&gt;
+
&lt;dev id="1" version="3"  secLevel="3" peername="192.168.1.109:162" name="Dell" devMask="1" username="jim" authType="MD5" authPhrase="jimsAuthPhrase" privType="DES" privPhrase="jimsPrivPhrase" engineId="0x80000ee7031803731a2386"/&gt;<br>
 
&lt;/trap_devices&gt;
 
&lt;/trap_devices&gt;
  
&lt;trap_rules&gt;
+
&lt;trap_rules&gt;<br>
  &lt;rule branch="1" index="1" test="gt" condval="10" sendOnTrue="1" sendOnFalse="1" devMask="1" truemsg="Value is up" falsemsg="value is down"/&gt;
+
&lt;rule branch="1" index="1" test="gt" condval="10" sendOnTrue="1" sendOnFalse="1" devMask="1" truemsg="Value is up" falsemsg="value is down"/&gt;<br>
 
&lt;/trap_rules&gt;  
 
&lt;/trap_rules&gt;  
  
 
&lt;/configuration&gt;
 
&lt;/configuration&gt;
  
&lt;mib_vars_xxx&gt; section of XML or Json setMibVars:
+
== &lt;mib_vars_xxx&gt; section ==
  
 
There will be up to four &lt;mib_vars_xxx&gt; sections in the XML file referring to the branches of the MIB. The Json setMibVars API call specifies the branch by number in the call. The contents of each MIB var entry are as listed below - a simple mapping of object to MIB index.
 
There will be up to four &lt;mib_vars_xxx&gt; sections in the XML file referring to the branches of the MIB. The Json setMibVars API call specifies the branch by number in the call. The contents of each MIB var entry are as listed below - a simple mapping of object to MIB index.
  
index=”n” (Json “index”, integer) – Refers to the row number in the MIB table, ranging from 1 to maximum table size as set in the agent task configuration at startup.
+
'''index=”n”''' – Refers to the row number in the MIB table, ranging from 1 to maximum table size as set in the agent task configuration at startup.
  
object=”n” (Json “localObject”, integer) – Refers to the local object number mapped at this location (branch and index) in the MIB.
+
'''object=”n”''' – Refers to the local object number mapped at this location (branch and index) in the MIB.
  
scale=”n.nn” (Json “scale”, number) – Applies to integer branches only (disregarded otherwise), and provides the scale factor by which the local object value is multiplied when responding to an SNMP Get, or by which the incoming value from an SNMP Set is divided before placing it into the local object.  
+
'''scale=”n.nn”''' – Applies to integer branches only (disregarded otherwise), and provides the scale factor by which the local object value is multiplied when responding to an SNMP Get, or by which the incoming value from an SNMP Set is divided before placing it into the local object.  
  
&lt;trap_devices&gt; section of XML or Json updateDevices:
+
== &lt;trap_devices&gt; section ==
  
id=”n” (Json “devNumber”, integer) – A number ranging from 1 to device table size, and was historically referenced in read and write maps as the device to which the map applied. However, with the implementation of device mask in the SNMP agent, the mask is what actually determines which device(s) the trap is sent to, and the same trap may be sent to multiple devices with only one trap rule as a result of the mask implementation.  
+
'''id=”n”''' – A number ranging from 1 to device table size, and was historically referenced in read and write maps as the device to which the map applied. However, with the implementation of device mask in the SNMP agent, the mask is what actually determines which device(s) the trap is sent to, and the same trap may be sent to multiple devices with only one trap rule as a result of the mask implementation.  
  
peername=”xxxx” (Json “peername”, string) – Provides a definition of where on the network to find the device. The peername in simplest form will be an IP address as illustrated in the XML file example above. However, if the network has access to a DNS server and that server is configured in the network settings of the local device, then peername may be any name that can be found via DNS lookup.  
+
'''peername=”xxxx”''' – Provides a definition of where on the network to find the device. The peername in simplest form will be an IP address as illustrated in the XML file example above. However, if the network has access to a DNS server and that server is configured in the network settings of the local device, then peername may be any name that can be found via DNS lookup.  
  
version=”n” (Json “version”, integer) – Specifies what SNMP version should be used to send the trap, which in turn determines certain aspects of how the trap message is formatted. Version may be 1, 2, or 3 where 2 really means v2c.  
+
'''version=”n”''' – Specifies what SNMP version should be used to send the trap, which in turn determines certain aspects of how the trap message is formatted. Version may be 1, 2, or 3 where 2 really means v2c.  
  
devMask=”x” (Json “devMask”, integer) – A 32-bit bit mask that allows sending the same trap to multiple devices. Both the trap send rules and the trap devices have a “device mask” (devMask). This effectively creates device groups in a very simple manner. The bit mask found in the trap send rule is logically ANDed with the bit mask in the device table entry. If the result is non-zero, then the trap is sent to this device.  
+
'''devMask=”x”''' – A 32-bit bit mask that allows sending the same trap to multiple devices. Both the trap send rules and the trap devices have a “device mask” (devMask). This effectively creates device groups in a very simple manner. The bit mask found in the trap send rule is logically ANDed with the bit mask in the device table entry. If the result is non-zero, then the trap is sent to this device.  
  
community=”xxxx” (Json “community”, string) – Is the community string as defined for SNMP v1 and v2c.
+
'''community=”xxxx”''' – Is the community string as defined for SNMP v1 and v2c.
  
name=”xxxx” (Json “name”, string) – Simply a reference in the web UI for the user to identify this device.  
+
'''name=”xxxx”''' – Simply a reference in the web UI for the user to identify this device.  
  
secLevel=”n” (Json “secLevel”, integer) - Sets security level, 1=noAuthNoPriv, 2=authNoPriv, 3=authPriv. Those are the SNMP acronyms meaning (1) no authentication or privacy, (2) authentication required but privacy is not, (3) both authentication and privacy are required. The term “privacy” means encryption. (Used only for SNMPv3.)
+
'''secLevel=”n”''' - Sets security level, 1=noAuthNoPriv, 2=authNoPriv, 3=authPriv. Those are the SNMP acronyms meaning (1) no authentication or privacy, (2) authentication required but privacy is not, (3) both authentication and privacy are required. The term “privacy” means encryption. (Used only for SNMPv3.)
  
username=”xxxx” (Json “username”, string) - Sets the SNMP security name, analogous to username in SNMP terms. (Used only for SNMPv3.)
+
'''username=”xxxx”''' - Sets the SNMP security name, analogous to username in SNMP terms. (Used only for SNMPv3.)
  
authType=”xxx” (Json “authType”, string) - Sets the authentication type, may be “NOAUTH”, “MD5”, or “SHA”. It determines how the username (security name) is hashed when transmitted. (Used only for SNMPv3.)
+
'''authType=”xxx”''' - Sets the authentication type, may be “NOAUTH”, “MD5”, or “SHA”. It determines how the username (security name) is hashed when transmitted. (Used only for SNMPv3.)
  
authPhrase=”xxx” (Json “authPhrase”, string) - Sets the authentication phrase, analogous to an SNMP password. (Used only for SNMPv3.)
+
'''authPhrase=”xxx”''' - Sets the authentication phrase, analogous to an SNMP password. (Used only for SNMPv3.)
  
privType=”xxx” (Json “privType”, string) - Sets the privacy type, may be “NOPRIV”, “DES”, or “AES”. This determines which encryption algorithm will be used. (Used only for SNMPv3.)
+
'''privType=”xxx”''' - Sets the privacy type, may be “NOPRIV”, “DES”, or “AES”. This determines which encryption algorithm will be used. (Used only for SNMPv3.)
  
privPhrase=”xxx” (Json “privPhrase”, string) - Sets the privacy phrase which is used as the encryption key. (Used only for SNMPv3.)
+
'''privPhrase=”xxx”''' - Sets the privacy phrase which is used as the encryption key. (Used only for SNMPv3.)
  
engineId=”xxx” (Json “engineId”, string) - Sets the engine ID that will be sent with the trap message if SNMPv3. (Used only for SNMPv3.)
+
'''engineId=”xxx”''' - Sets the engine ID that will be sent with the trap message if SNMPv3. (Used only for SNMPv3.)
  
 
Note: The engine ID will be taken as a literal ASCII string (and probably not work) if it does not begin with “0x”. The recipient of an SNMPv3 trap will generally discard it if the engine ID does not match its own engine ID. It is necessary to know quite a bit about where you are sending traps with v3.  
 
Note: The engine ID will be taken as a literal ASCII string (and probably not work) if it does not begin with “0x”. The recipient of an SNMPv3 trap will generally discard it if the engine ID does not match its own engine ID. It is necessary to know quite a bit about where you are sending traps with v3.  
  
&lt;trap_rules&gt; section of XML or Json updateTrapSendRules:
+
== &lt;trap_rules&gt; section ==
  
ruleNumber implied by order in XML (Json “ruleNumber, integer) – Primarily used for database lookup of a specific rule. The rule number has functional significance in some applications, but not when it comes to trap send rules.  
+
'''branch=”n”''' – Specifies which branch in the MIB that this trap rule applies to, and primarily provides the means to look up the local object number that should be evaluated.  
  
branch=”n” (Json “branch”, integer) – Specifies which branch in the MIB that this trap rule applies to, and primarily provides the means to look up the local object number that should be evaluated.  
+
'''index=”n”''' – Specifies the index or row number in the given branch for looking up the local object nubmer.
  
index=”n” (Json “tableIndex”, integer) Specifies the index or row number in the given branch for looking up the local object nubmer.
+
'''condval=”n.nn”''' Provided no conditional object number is given, this becomes the threshold value for test purposes.
  
condval=”n.nn” (Json “condValue”, number) Provided no conditional object number is given, this becomes the threshold value for test purposes.
+
'''condobj=”n”''' Overrides the conditional value when given (non-zero), and provides the local object from which a test threshold should be retrieved.
  
condobj=”n” (Json “condObj”, integer) Overrides the conditional value when given (non-zero), and provides the local object from which a test threshold should be retrieved.
+
'''test=”xxx”''' Defines the test that should be performed to determine if the trap send rule state is true or false.
  
test=”xxx” (Json “testType”, integer) – Defines the test that should be performed to determine if the trap send rule state is true or false.
 
 
Test type is given as a character string in XML, but only with an integer code in Json.
 
 
 
XML value Json type code Test performed on object versus threshold
 
 
Trap state is considered “true” when this condition is met    
 
Trap state is considered “true” when this condition is met    
“none” 0 No trap sent    
+
{| class="wikitable"
“gt” 1 Object greater than threshold    
+
|-
“ge” 2 Object greater than or equal threshold    
+
! XML Label !! Test Code !! Rest performed on object versus threshold
“lt” 3 Object less than threshold    
+
|-
“le” 4 Object is less than or equal threshold    
+
| “none” || 0 || No trap sent    
“eq” 5 Object is equal threshold    
+
|-
“ne” 6 Object is not equal threshold    
+
| “gt” || 1 || Object greater than threshold    
“dev” 7 Object deviates from threshold by hysteresis amount    
+
|-
“delta” 8 Object has changed by threshold amount  
+
| “ge” || 2 || Object greater than or equal to threshold    
 
+
|-
 +
| “lt” || 3 || Object less than threshold    
 +
|-
 +
| “le” || 4 || Object is less than or equal to threshold    
 +
|-
 +
| “eq” || 5 || Object is equal to threshold    
 +
|-
 +
| “ne” || 6 || Object is not equal to threshold    
 +
|-
 +
| “dev” || 7 || Object deviates from threshold by hysteresis amount    
 +
|-
 +
| “delta” || 8 || Object has changed by threshold amount  
 +
|}
 
Threshold is either the fixed value given by “condval”, or the value found in the object given as “condobj”.  
 
Threshold is either the fixed value given by “condval”, or the value found in the object given as “condobj”.  
  
Line 112: Line 121:
 
Test type delta with threshold of zero is a special case within the special case. If the test type is delta and the threshold value is zero, then the trap will be sent any time the local object (found by looking it up in the MIB) has been updated or changed by some other action in the system, without any regard for what the actual value of the object is.
 
Test type delta with threshold of zero is a special case within the special case. If the test type is delta and the threshold value is zero, then the trap will be sent any time the local object (found by looking it up in the MIB) has been updated or changed by some other action in the system, without any regard for what the actual value of the object is.
  
hyst=”n.nn” (Json “hysteresis”, number) – Specifies the hysteresis value to be applied in the test process. Hysteresis is used to prevent a flood of trap messages when the object is hovering near the threshold but fluctuating frequently. For ‘greater than’ type tests, once the rule state becomes true, the object value must fall below the threshold by the hysteresis amount before the rule state will return to false. For ‘less than’ type tests, once the rule state becomes true, the object value must rise above the threshold by the hysteresis amount before the rule state will return to false. For example, if the rule threshold is 10, and the test is ‘greater than’, then the rule state will become true when the object value exceeds 10.  If the hysteresis value is 2, then the object value must now fall below 8 before the rule state will return to false.
+
'''hyst=”n.nn”''' – Specifies the hysteresis value to be applied in the test process. Hysteresis is used to prevent a flood of trap messages when the object is hovering near the threshold but fluctuating frequently. For ‘greater than’ type tests, once the rule state becomes true, the object value must fall below the threshold by the hysteresis amount before the rule state will return to false. For ‘less than’ type tests, once the rule state becomes true, the object value must rise above the threshold by the hysteresis amount before the rule state will return to false. For example, if the rule threshold is 10, and the test is ‘greater than’, then the rule state will become true when the object value exceeds 10.  If the hysteresis value is 2, then the object value must now fall below 8 before the rule state will return to false.
  
 
The hysteresis value takes on a special role when the test type is “deviates by”. The rule state will be true when the difference between object value and threshold exceeds the hysteresis amount in either direction, high or low.  
 
The hysteresis value takes on a special role when the test type is “deviates by”. The rule state will be true when the difference between object value and threshold exceeds the hysteresis amount in either direction, high or low.  
  
ontime=”n.nn” (Json “onTime”, real) – Specifies a minimum amount of time that the “true” state must exist before the trap state will be fully regarded as true and “true” trap sent. If the condition tests true, and within this time period returns to false, no “true” trap will be sent.  
+
'''ontime=”n.nn”''' – Specifies a minimum amount of time that the “true” state must exist before the trap state will be fully regarded as true and “true” trap sent. If the condition tests true, and within this time period returns to false, no “true” trap will be sent.  
  
offtime=”n.nn” (Json “offTime”, real) – Specifies the minimum amount of time that the “false” state must exist before the trap state will be fully regarded as false and the “false” trap sent. If the condition tests false, and within this time period returns to true, no “false” trap will be sent.  
+
'''offtime=”n.nn”''' – Specifies the minimum amount of time that the “false” state must exist before the trap state will be fully regarded as false and the “false” trap sent. If the condition tests false, and within this time period returns to true, no “false” trap will be sent.  
  
sendOnTrue=”x” (Json “sendOnTrue”, integer) – Expects a value of 0 to disable, or 1 to enable the sending of a trap when the condition specified by this rule tests “true”.  
+
'''sendOnTrue=”x”''' – Expects a value of 0 to disable, or 1 to enable the sending of a trap when the condition specified by this rule tests “true”.  
  
sendOnFalse=”x” (Json “sendOnFalse”, integer) – Expects a value of 0 to disable, or 1 to enable the sending of a trap when the condition specified by this rule tests “false”.  
+
'''sendOnFalse=”x”''' – Expects a value of 0 to disable, or 1 to enable the sending of a trap when the condition specified by this rule tests “false”.  
  
sendInform=”x” (Json “sendInform”, integer) – Expects a value of 0 to send the message as an SNMP Trap, or value of 1 to send the message as an SNMP Inform.  
+
'''sendInform=”x”''' – Expects a value of 0 to send the message as an SNMP Trap, or value of 1 to send the message as an SNMP Inform.  
  
devMask=”x” (Json “devMask”, integer) – A 32-bit bit mask that allows sending the same trap to multiple devices. Both the trap send rules and the trap devices have a “device mask” (devMask). This effectively creates device groups in a very simple manner. The bit mask found in the trap send rule is logically ANDed with the bit mask in the device table entry. If the result is non-zero, then the trap is sent to this device.  
+
'''devMask=”x”''' – A 32-bit bit mask that allows sending the same trap to multiple devices. Both the trap send rules and the trap devices have a “device mask” (devMask). This effectively creates device groups in a very simple manner. The bit mask found in the trap send rule is logically ANDed with the bit mask in the device table entry. If the result is non-zero, then the trap is sent to this device.  
  
repcounttrue=”n” (Json “repCountTrue”, integer) – Used only with SNMP v1 or v2, and generally only with Trap messages (not Inform messages) to repeat the trap this number of times when true. Traps are not acknowledged, so this provides a means of repeating the same Trap message to better ensure delivery.  
+
'''repcounttrue=”n”''' – Used to repeat the trap this number of times when true. Traps are not acknowledged, so this provides a means of repeating the same Trap message to better ensure delivery. Set to -1 to repeat indefinitely while condition tests true.
  
repcountfalse=”n” (Json “repCountFalse”, integer) – Used only with SNMP v1 or v2, and generally only with Trap messages (not Inform messages) to repeat the trap this number of times when false. Traps are not acknowledged, so this provides a means of repeating the same Trap message to better ensure delivery.  
+
'''repcountfalse=”n”''' – Used to repeat the trap this number of times when false. Traps are not acknowledged, so this provides a means of repeating the same Trap message to better ensure delivery. Set to -1 to repeat indefinitely while condition tests false.
  
reptime=”n.nn” (Json “repTime”, real) – Specifies the amount of time to wait in between repeated sending of the same Trap message as indicated by the repcount attributes above.  
+
'''reptime=”n.nn”''' – Specifies the amount of time to wait in between repeated sending of the same Trap message as indicated by the repcount attributes above.  
  
truemsg=”xxxx” (Json “trueMsg”, string) – Provides a user defined message that will be delivered as one of the varbinds in any “true” Trap or Inform message sent.
+
'''truemsg=”xxxx”''' – Provides a user defined message that will be delivered as one of the varbinds in any “true” Trap or Inform message sent.
  
falsemsg=”xxxx” (Json “falseMsg”, string) – Provides a user defined message that will be delivered as one of the varbinds in any “false” Trap or Inform message sent.
+
'''falsemsg=”xxxx”''' – Provides a user defined message that will be delivered as one of the varbinds in any “false” Trap or Inform message sent.

Latest revision as of 13:33, 21 May 2019

SNMP Agent XML Files

Example XML File

<?xml version="1.0" encoding="ISO-8859-1" ?>
<!-- IoT Server SNMP Agent configuration file -->

<configuration>

<mib_vars_int32>
<var index="1" object="1"/>
<var index="2" object="2"/>
<var index="3" object="3"/>
<var index="4" object="4" scale="10"/>
<var index="5" object="5" scale="100"/>
</mib_vars_int32>

<mib_vars_uint64>
<var index="1" object="3"/>
</mib_vars_uint64>

<mib_vars_double>
<var index="1" object="4"/>
<var index="2" object="5"/>
</mib_vars_double>

<mib_vars_charstr>
<var index="1" object="6"/>
<var index="2" object="7"/>
</mib_vars_charstr>

<trap_devices>
<dev id="1" version="3" secLevel="3" peername="192.168.1.109:162" name="Dell" devMask="1" username="jim" authType="MD5" authPhrase="jimsAuthPhrase" privType="DES" privPhrase="jimsPrivPhrase" engineId="0x80000ee7031803731a2386"/>
</trap_devices>

<trap_rules>
<rule branch="1" index="1" test="gt" condval="10" sendOnTrue="1" sendOnFalse="1" devMask="1" truemsg="Value is up" falsemsg="value is down"/>
</trap_rules>

</configuration>

<mib_vars_xxx> section

There will be up to four <mib_vars_xxx> sections in the XML file referring to the branches of the MIB. The Json setMibVars API call specifies the branch by number in the call. The contents of each MIB var entry are as listed below - a simple mapping of object to MIB index.

index=”n” – Refers to the row number in the MIB table, ranging from 1 to maximum table size as set in the agent task configuration at startup.

object=”n” – Refers to the local object number mapped at this location (branch and index) in the MIB.

scale=”n.nn” – Applies to integer branches only (disregarded otherwise), and provides the scale factor by which the local object value is multiplied when responding to an SNMP Get, or by which the incoming value from an SNMP Set is divided before placing it into the local object.

<trap_devices> section

id=”n” – A number ranging from 1 to device table size, and was historically referenced in read and write maps as the device to which the map applied. However, with the implementation of device mask in the SNMP agent, the mask is what actually determines which device(s) the trap is sent to, and the same trap may be sent to multiple devices with only one trap rule as a result of the mask implementation.

peername=”xxxx” – Provides a definition of where on the network to find the device. The peername in simplest form will be an IP address as illustrated in the XML file example above. However, if the network has access to a DNS server and that server is configured in the network settings of the local device, then peername may be any name that can be found via DNS lookup.

version=”n” – Specifies what SNMP version should be used to send the trap, which in turn determines certain aspects of how the trap message is formatted. Version may be 1, 2, or 3 where 2 really means v2c.

devMask=”x” – A 32-bit bit mask that allows sending the same trap to multiple devices. Both the trap send rules and the trap devices have a “device mask” (devMask). This effectively creates device groups in a very simple manner. The bit mask found in the trap send rule is logically ANDed with the bit mask in the device table entry. If the result is non-zero, then the trap is sent to this device.

community=”xxxx” – Is the community string as defined for SNMP v1 and v2c.

name=”xxxx” – Simply a reference in the web UI for the user to identify this device.

secLevel=”n” - Sets security level, 1=noAuthNoPriv, 2=authNoPriv, 3=authPriv. Those are the SNMP acronyms meaning (1) no authentication or privacy, (2) authentication required but privacy is not, (3) both authentication and privacy are required. The term “privacy” means encryption. (Used only for SNMPv3.)

username=”xxxx” - Sets the SNMP security name, analogous to username in SNMP terms. (Used only for SNMPv3.)

authType=”xxx” - Sets the authentication type, may be “NOAUTH”, “MD5”, or “SHA”. It determines how the username (security name) is hashed when transmitted. (Used only for SNMPv3.)

authPhrase=”xxx” - Sets the authentication phrase, analogous to an SNMP password. (Used only for SNMPv3.)

privType=”xxx” - Sets the privacy type, may be “NOPRIV”, “DES”, or “AES”. This determines which encryption algorithm will be used. (Used only for SNMPv3.)

privPhrase=”xxx” - Sets the privacy phrase which is used as the encryption key. (Used only for SNMPv3.)

engineId=”xxx” - Sets the engine ID that will be sent with the trap message if SNMPv3. (Used only for SNMPv3.)

Note: The engine ID will be taken as a literal ASCII string (and probably not work) if it does not begin with “0x”. The recipient of an SNMPv3 trap will generally discard it if the engine ID does not match its own engine ID. It is necessary to know quite a bit about where you are sending traps with v3.

<trap_rules> section

branch=”n” – Specifies which branch in the MIB that this trap rule applies to, and primarily provides the means to look up the local object number that should be evaluated.

index=”n” – Specifies the index or row number in the given branch for looking up the local object nubmer.

condval=”n.nn” – Provided no conditional object number is given, this becomes the threshold value for test purposes.

condobj=”n” – Overrides the conditional value when given (non-zero), and provides the local object from which a test threshold should be retrieved.

test=”xxx” – Defines the test that should be performed to determine if the trap send rule state is true or false.

Trap state is considered “true” when this condition is met

XML Label Test Code Rest performed on object versus threshold
“none” 0 No trap sent
“gt” 1 Object greater than threshold
“ge” 2 Object greater than or equal to threshold
“lt” 3 Object less than threshold
“le” 4 Object is less than or equal to threshold
“eq” 5 Object is equal to threshold
“ne” 6 Object is not equal to threshold
“dev” 7 Object deviates from threshold by hysteresis amount
“delta” 8 Object has changed by threshold amount

Threshold is either the fixed value given by “condval”, or the value found in the object given as “condobj”.

For most tests, the object is simply compared to the threshold value. The delta test is a special case. The threshold specifies an amount by which the local object needs to change before the rule test will be flagged as true. However, this “true” state is only temporary. Once the trap is sent, the new object value is now saved for subsequent tests of “changed by”. Every time the local object changes by the threshold amount, a new trap will be sent.

Test type delta with threshold of zero is a special case within the special case. If the test type is delta and the threshold value is zero, then the trap will be sent any time the local object (found by looking it up in the MIB) has been updated or changed by some other action in the system, without any regard for what the actual value of the object is.

hyst=”n.nn” – Specifies the hysteresis value to be applied in the test process. Hysteresis is used to prevent a flood of trap messages when the object is hovering near the threshold but fluctuating frequently. For ‘greater than’ type tests, once the rule state becomes true, the object value must fall below the threshold by the hysteresis amount before the rule state will return to false. For ‘less than’ type tests, once the rule state becomes true, the object value must rise above the threshold by the hysteresis amount before the rule state will return to false. For example, if the rule threshold is 10, and the test is ‘greater than’, then the rule state will become true when the object value exceeds 10. If the hysteresis value is 2, then the object value must now fall below 8 before the rule state will return to false.

The hysteresis value takes on a special role when the test type is “deviates by”. The rule state will be true when the difference between object value and threshold exceeds the hysteresis amount in either direction, high or low.

ontime=”n.nn” – Specifies a minimum amount of time that the “true” state must exist before the trap state will be fully regarded as true and “true” trap sent. If the condition tests true, and within this time period returns to false, no “true” trap will be sent.

offtime=”n.nn” – Specifies the minimum amount of time that the “false” state must exist before the trap state will be fully regarded as false and the “false” trap sent. If the condition tests false, and within this time period returns to true, no “false” trap will be sent.

sendOnTrue=”x” – Expects a value of 0 to disable, or 1 to enable the sending of a trap when the condition specified by this rule tests “true”.

sendOnFalse=”x” – Expects a value of 0 to disable, or 1 to enable the sending of a trap when the condition specified by this rule tests “false”.

sendInform=”x” – Expects a value of 0 to send the message as an SNMP Trap, or value of 1 to send the message as an SNMP Inform.

devMask=”x” – A 32-bit bit mask that allows sending the same trap to multiple devices. Both the trap send rules and the trap devices have a “device mask” (devMask). This effectively creates device groups in a very simple manner. The bit mask found in the trap send rule is logically ANDed with the bit mask in the device table entry. If the result is non-zero, then the trap is sent to this device.

repcounttrue=”n” – Used to repeat the trap this number of times when true. Traps are not acknowledged, so this provides a means of repeating the same Trap message to better ensure delivery. Set to -1 to repeat indefinitely while condition tests true.

repcountfalse=”n” – Used to repeat the trap this number of times when false. Traps are not acknowledged, so this provides a means of repeating the same Trap message to better ensure delivery. Set to -1 to repeat indefinitely while condition tests false.

reptime=”n.nn” – Specifies the amount of time to wait in between repeated sending of the same Trap message as indicated by the repcount attributes above.

truemsg=”xxxx” – Provides a user defined message that will be delivered as one of the varbinds in any “true” Trap or Inform message sent.

falsemsg=”xxxx” – Provides a user defined message that will be delivered as one of the varbinds in any “false” Trap or Inform message sent.