Difference between revisions of "SNMP Agent CSV Files"

From Control Solutions IoTServer Documentation
Jump to navigation Jump to search
 
(7 intermediate revisions by the same user not shown)
Line 23: Line 23:
  
 
Functions may be any of the following (with this listed expanded from time to time):<br>
 
Functions may be any of the following (with this listed expanded from time to time):<br>
LOCALDATA<br>
+
* LOCALDATA
MODBUS<br>
+
* MODBUS
SNMP
+
* SNMP
  
 
Sub-functions:<br>
 
Sub-functions:<br>
SNMP (client)<br>
+
SNMP (client)
&nbsp;&nbsp;&nbsp;DEVICES<br>
+
* DEVICES
READMAPS<br>
+
* READMAPS
WRITEMAPS<br>
+
* WRITEMAPS
WALKRULES<br>
+
* WALKRULES
SNMP (agent)<br>
+
SNMP (agent)
MIBVARS<br>
+
* MIBVARS
DEVICES<br>
+
* DEVICES
TRAPSENDRULES<br>
+
* TRAPSENDRULES
SNMP (trap receiver)<br>
+
SNMP (trap receiver)
TRAPRECVRULES
+
* TRAPRECVRULES
  
 
NOTE: The same SNMP CSV file may NOT contain both client and server sections as DEVICES becomes ambiguous. SNMP requires different applications for different purposes (csiSnmpClient, csiSnmpAgent, csiSnmpTrapRecv). A fourth application, csiTrapHandler, is also associated with csiSnmpAgent.
 
NOTE: The same SNMP CSV file may NOT contain both client and server sections as DEVICES becomes ambiguous. SNMP requires different applications for different purposes (csiSnmpClient, csiSnmpAgent, csiSnmpTrapRecv). A fourth application, csiTrapHandler, is also associated with csiSnmpAgent.
 +
 +
== SNMP Agent (Server) Example ==
 +
 +
BEGIN,SNMP,MIBVARS<br>
 +
BRANCH,INDEX,OBJECT,SCALE<br>
 +
1,1,1,0.000000<br>
 +
1,2,2,0.000000<br>
 +
1,3,3,0.000000<br>
 +
1,4,4,10.000000<br>
 +
1,5,5,100.000000<br>
 +
2,1,3,0.000000<br>
 +
3,1,4,10.000000<br>
 +
3,2,5,100.000000<br>
 +
4,1,6,0.000000<br>
 +
4,2,7,0.000000<br>
 +
END<br>
 +
BEGIN,SNMP,DEVICES<br>
 +
NUMBER,PEERNAME,VERSION,COMMUNITY,DEVMASK,NAME<br>
 +
1,192.168.1.109,2,special,0001,Dell<br>
 +
END<br>
 +
BEGIN,SNMP,TRAPSENDRULES<br>
 +
BRANCH,INDEX,TEST,SENDONTRUE,SENDONFALSE,CONDOBJ,CONDVAL,HYST,DEVMASK,REPTRUE,REPFALSE,REPTIME,ONTIME,OFFTIME,TRUEMSG,FALSEMSG<br>
 +
1,1,GT,Y,Y,0,10.000000,0.000000,0001,0,0,0.000000,0.000000,0.000000,Value is up,value is down<br>
 +
END
 +
 +
== SNMP (agent/server) MIBVARS Section ==
 +
 +
'''Branch''' – Specifies which of the 4 data branches of the MIB this object should be made available in. Data will be automatically converted as necessary. Object type does not matter. Regardless of the local object’s native data type, the data will be presented to SNMP according to the format for that branch.
 +
 +
{| class="wikitable"
 +
|-
 +
! Branch number !! Data format
 +
|-
 +
| 1 || Signed 32-bit integer (INTEGER)
 +
|-
 +
| 2 || Unsigned 64-bit integer (COUNTER64)
 +
|-
 +
| 3 || 32-bit or 64-bit floating point (see note)
 +
|-
 +
| 4 || Octet String
 +
|}
 +
 +
Note: The floating point branch (3) will default to OPAQUE DOUBLE (Net-SNMP type), but may be configured to be 32-bit or 64-bit Opaque Float or Double, or the 32-bit or 64-bit version of RFC 6340 Octet String interpretation. This selection is a configuration property of the SNMP agent task.
 +
 +
'''Index''' – 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''' – Refers to the local object number mapped at this location (branch and index) in the MIB.
 +
 +
'''Scale''' – 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.
 +
 +
== SNMP (agent/server) DEVICES Section ==
 +
 +
The DEVICES section in the SNMP server (agent) specify which remote SNMP devices traps or informs should be sent to as a result of the trap send rules.
 +
 +
'''Number''' – 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. This number is therefore simply a row number on the list for database reference.
 +
 +
'''PeerName''' – 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''' – 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.
 +
 +
'''Community''' – Is the community string as defined for SNMP v1 and v2c.
 +
 +
'''DevMask''' – 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.
 +
 +
'''Name''' – Simply a reference in the web UI for the user to identify this device.
 +
 +
'''SecLevel''' - 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''' - Sets the SNMP security name, analogous to username in SNMP terms. (Used only for SNMPv3.)
 +
 +
'''AuthType''' - 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''' - Sets the authentication phrase, analogous to an SNMP password. (Used only for SNMPv3.)
 +
 +
'''PrivType''' - Sets the privacy type, may be “NOPRIV”, “DES”, or “AES”. This determines which encryption algorithm will be used. (Used only for SNMPv3.)
 +
 +
'''PrivPhrase''' - Sets the privacy phrase which is used as the encryption key. (Used only for SNMPv3.)
 +
 +
'''EngineId''' - 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.
 +
 +
== SNMP (agent/server) TRAPSENDRULES Section ==
 +
 +
'''Branch''' – 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''' – Specifies the index or row number in the given branch for looking up the local object nubmer.
 +
 +
'''Test''' – 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  
 +
 +
{| class="wikitable"
 +
|-
 +
! Test label !! Test performed on object versus threshold
 +
|-
 +
| GT || Object greater than threshold  
 +
|-
 +
| GE || Object greater than or equal threshold  
 +
|-
 +
| LT || Object less than threshold  
 +
|-
 +
| LE || Object is less than or equal threshold  
 +
|-
 +
| EQ || Object is equal threshold  
 +
|-
 +
| NE || Object is not equal threshold  
 +
|-
 +
| DEV || Object deviates from threshold by hysteresis amount  
 +
|-
 +
| DELTA || Object has changed by threshold amount
 +
|}
 +
 +
'''SendOnTrue''' – Enter “N” to disable, or “Y” to enable the sending of a trap when the condition specified by this rule tests “true”.
 +
 +
'''SendOnFalse''' – Enter “N” to disable, or “Y” to enable the sending of a trap when the condition specified by this rule tests “false”.
 +
 +
'''SendInform''' – Enter “N” to send the message as an SNMP Trap, or “Y” to send the message as an SNMP Inform.
 +
 +
'''CondObj''' – Overrides the conditional value when given (non-zero), and provides the local object from which a test threshold should be retrieved.
 +
 +
'''CondVal''' – Provided no conditional object number is given, this becomes the threshold value for test purposes.
 +
 +
'''Hyst''' – Specifies the hysteresis value to be applied in the test process (see API notes).
 +
 +
'''DevMask''' – 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.
 +
 +
'''RepTrue''' – 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.
 +
 +
'''RepFalse''' – 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''' – Specifies the amount of time in seconds to wait in between repeated sending of the same Trap message as indicated by the repeat count attributes above.
 +
 +
'''OnTime''' – Specifies a minimum amount of time in seconds 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''' – Specifies the minimum amount of time in seconds 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.
 +
 +
'''TrueMsg''' – Provides a user defined message that will be delivered as one of the varbinds in any “true” Trap or Inform message sent.
 +
 +
'''FalseMsg''' – 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:35, 21 May 2019

SNMP Agent CSV Files

A CSV file may be imported to configure various aspects of the IoTServer (or Babel Buster gateway). A single CSV file may contain multiple sections. When a file including an “Objects” section is imported by the Data Engine, local objects will be configured. When a file including one or more “Modbus” sections is imported by an instance of the Modbus Engine, Modbus gateway functionality will be configured. The same Modbus file may be imported by a Modbus Client or Modbus Server, and either RTU or TCP, and only those sections of interest to that Modbus function will be imported. The CSV file may also contain one or more SNMP sections, and so forth.

A section begins when the word “Begin” appears in the first column of a line. All lines up to and including a line that begins with the word “End” will be taken to be part of that section.

The line immediately following the “Begin” line must be a header line. A Header line is one which labels the columns of data that will follow the Header line.

All lines following the Header line are data lines that are expected to contain the same number of columns as the Header line, and whose contents are defined by the labels found in each column of the Header line.

Labels in the section Begin and End lines, and labels in the Header line are NOT case sensitive and will be interpreted equally whether upper case, lower case, or some combination of both (for readability).

Labels may NOT contain embedded spaces. A label is terminated by a comma, line-end, or space. Labels may not be encapsulated in quote characters; however, data content in data lines may be encapsulated in quote characters and may contain embedded spaces or blanks if quoted.

Some labels in the Header line may be considered optional. The minimum required columns are indicated in the definition of each data section.

Columns in the Header line do not have to follow any particular order. They may be rearranged to the user’s liking. The only restriction is that data in subsequent data lines must match up with the labels placed in the Header line. Data lines may contain fewer columns than the Header line, but may not contain more. Data columns that the user wishes to deliberately omit, but omit between included columns, should be indicated by place holder commas (which will simply appear as blank cells in a spread sheet program).

A Begin line will contain three columns:
Column 1: BEGIN
Column 2: Function as noted below
Column 3: Sub-function as noted in definition of the Function.

Functions may be any of the following (with this listed expanded from time to time):

  • LOCALDATA
  • MODBUS
  • SNMP

Sub-functions:
SNMP (client)

  • DEVICES
  • READMAPS
  • WRITEMAPS
  • WALKRULES

SNMP (agent)

  • MIBVARS
  • DEVICES
  • TRAPSENDRULES

SNMP (trap receiver)

  • TRAPRECVRULES

NOTE: The same SNMP CSV file may NOT contain both client and server sections as DEVICES becomes ambiguous. SNMP requires different applications for different purposes (csiSnmpClient, csiSnmpAgent, csiSnmpTrapRecv). A fourth application, csiTrapHandler, is also associated with csiSnmpAgent.

SNMP Agent (Server) Example

BEGIN,SNMP,MIBVARS
BRANCH,INDEX,OBJECT,SCALE
1,1,1,0.000000
1,2,2,0.000000
1,3,3,0.000000
1,4,4,10.000000
1,5,5,100.000000
2,1,3,0.000000
3,1,4,10.000000
3,2,5,100.000000
4,1,6,0.000000
4,2,7,0.000000
END
BEGIN,SNMP,DEVICES
NUMBER,PEERNAME,VERSION,COMMUNITY,DEVMASK,NAME
1,192.168.1.109,2,special,0001,Dell
END
BEGIN,SNMP,TRAPSENDRULES
BRANCH,INDEX,TEST,SENDONTRUE,SENDONFALSE,CONDOBJ,CONDVAL,HYST,DEVMASK,REPTRUE,REPFALSE,REPTIME,ONTIME,OFFTIME,TRUEMSG,FALSEMSG
1,1,GT,Y,Y,0,10.000000,0.000000,0001,0,0,0.000000,0.000000,0.000000,Value is up,value is down
END

SNMP (agent/server) MIBVARS Section

Branch – Specifies which of the 4 data branches of the MIB this object should be made available in. Data will be automatically converted as necessary. Object type does not matter. Regardless of the local object’s native data type, the data will be presented to SNMP according to the format for that branch.

Branch number Data format
1 Signed 32-bit integer (INTEGER)
2 Unsigned 64-bit integer (COUNTER64)
3 32-bit or 64-bit floating point (see note)
4 Octet String

Note: The floating point branch (3) will default to OPAQUE DOUBLE (Net-SNMP type), but may be configured to be 32-bit or 64-bit Opaque Float or Double, or the 32-bit or 64-bit version of RFC 6340 Octet String interpretation. This selection is a configuration property of the SNMP agent task.

Index – 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 – Refers to the local object number mapped at this location (branch and index) in the MIB.

Scale – 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.

SNMP (agent/server) DEVICES Section

The DEVICES section in the SNMP server (agent) specify which remote SNMP devices traps or informs should be sent to as a result of the trap send rules.

Number – 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. This number is therefore simply a row number on the list for database reference.

PeerName – 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 – 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.

Community – Is the community string as defined for SNMP v1 and v2c.

DevMask – 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.

Name – Simply a reference in the web UI for the user to identify this device.

SecLevel - 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 - Sets the SNMP security name, analogous to username in SNMP terms. (Used only for SNMPv3.)

AuthType - 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 - Sets the authentication phrase, analogous to an SNMP password. (Used only for SNMPv3.)

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

PrivPhrase - Sets the privacy phrase which is used as the encryption key. (Used only for SNMPv3.)

EngineId - 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.

SNMP (agent/server) TRAPSENDRULES Section

Branch – 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 – Specifies the index or row number in the given branch for looking up the local object nubmer.

Test – 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

Test label Test performed on object versus threshold
GT Object greater than threshold
GE Object greater than or equal threshold
LT Object less than threshold
LE Object is less than or equal threshold
EQ Object is equal threshold
NE Object is not equal threshold
DEV Object deviates from threshold by hysteresis amount
DELTA Object has changed by threshold amount

SendOnTrue – Enter “N” to disable, or “Y” to enable the sending of a trap when the condition specified by this rule tests “true”.

SendOnFalse – Enter “N” to disable, or “Y” to enable the sending of a trap when the condition specified by this rule tests “false”.

SendInform – Enter “N” to send the message as an SNMP Trap, or “Y” to send the message as an SNMP Inform.

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

CondVal – Provided no conditional object number is given, this becomes the threshold value for test purposes.

Hyst – Specifies the hysteresis value to be applied in the test process (see API notes).

DevMask – 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.

RepTrue – 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.

RepFalse – 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 – Specifies the amount of time in seconds to wait in between repeated sending of the same Trap message as indicated by the repeat count attributes above.

OnTime – Specifies a minimum amount of time in seconds 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 – Specifies the minimum amount of time in seconds 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.

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

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