SNMP Client CSV Files
Contents
SNMP Client 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 Client Example
The following illustrates an SNMP client CSV file. There will typically be only one instance of a client, unless multiple instances are implemented for load sharing purposes.
BEGIN,SNMP,DEVICES
NUMBER,PEERNAME,VERSION,COMMUNITY,POLLTIME,TIMEOUT,RETRIES,MAXVARBINDS,MAXRECVSIZE,MAXSENDSIZE,POLLTOLERANCE,NAME
1,192.168.1.137,2,birchwood,10.000000,0,0,3,0,0,1.000000,spx-pro
2,192.168.1.23,2,private,10.000000,0,0,3,0,0,1.000000,v210
3,192.168.1.20,2,public,10.000000,0,0,3,0,0,1.000000,apc
END
BEGIN,SNMP,READMAPS
DEVICE,OID,HINT,SCALE,OFFSET,DESTOBJ,POLLTIME,DEFVALUE,FAILCOUNT,INDEXOBJ,INDEXVAL
1,1.3.6.1.4.1.3815.1.4.1.1.1.1.2.1,NONE,0.000000,0.000000,1,10.000000,0.000000,0,0,0
1,1.3.6.1.4.1.3815.1.4.1.1.1.1.2.2,NONE,0.000000,0.000000,2,10.000000,0.000000,0,0,0
2,1.3.6.1.4.1.3815.1.4.1.1.1.1.2.6,NONE,0.000000,0.000000,3,10.000000,0.000000,0,0,0
1,1.3.6.1.4.1.3815.1.4.1.1.1.1.2.3,NONE,0.000000,0.000000,4,10.000000,0.000000,0,0,0
2,1.3.6.1.4.1.3815.1.4.1.1.1.1.2.4,NONE,0.000000,0.000000,5,10.000000,0.000000,0,0,0
2,1.3.6.1.4.1.3815.1.4.1.1.1.1.2.5,NONE,0.000000,0.000000,6,10.000000,0.000000,0,0,0
END
BEGIN,SNMP,WRITEMAPS
SOURCEOBJ,SCALE,OFFSET,DEVICE,OID,ASNSELECT,SENDPERIODIC,POLLTIME,SENDMAXQUIET,MAXQUIETTIME,SENDONDELTA,DELTA,MINQUIETTIME,INDEXOBJ,INDEXVAL
20,0.000000,0.000000,2,1.3.6.1.4.1.3815.1.4.1.1.1.1.2.5,INTEGER,N,0.000000,N,0.000000,Y,0.000000,0.000000,0,0
END
BEGIN,SNMP,WALKRULES
DEVICE,OID,METHOD,HINT,STARTOBJ,OBJCOUNT,POLLTIME,INDEXOBJ,INDEXVAL
3,1.3.6.1.2.1.33.1.6.2.1.*(2).*,MASK,NONE,14,24,10.000000,0,0
END
SNMP (client) DEVICES Section
The DEVICES section identifies remote SNMP devices that will be read or written by the IoTServer as directed by read and write maps.
Number – A number ranging from 1 to device table size, and is referenced in read and write maps, and table walk rules, as the device to which the map applies.
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 SNMP Get or Set, which in turn determines certain aspects of how the message is formatted. Version may be 1, 2, or 3 where 2 means v2c.
Community – The community string as defined for SNMP v1 and v2c.
PollTime – Poll time in seconds, can be fractional. Used as default when read, write, or walk rule does not have a poll time specified.
Timeout – Integer number of seconds for session timeout.
Retries – Number of times that the SNMP engine should automatically retry a Get or Set if it fails.
MaxVarBinds – Specifies the maximum number of varbinds that may be included in the same request. When multiple values are requested from the same device, the client will attempt to group them into a single SNMP Get or Set for efficiency (less network traffic). The client will group up to this many varbinds into the same request.
MaxRecvSize – Provides a limit on the maximum message size that should be accepted, defaults to 1500 if omitted (recommended).
MaxSendSize – Provides a limit on the maximum message size that should be sent, defaults to 1500 if omitted (recommended). The maxVarBinds should be set to 1 if the maxSendSize is reduced.
PollTolerance – Poll tolerance in seconds, can be fractional. Poll tolerance refers to the amount of time overlap permitted when the client is attempting to group varbinds into a single Get or Set. In other words, if a map or rule timeout is not quite zero but is less than the poll tolerance, it will be treated as zero and grouped into the Get or Set that is already under way.
Name – Arbitrary reference name for use in the web UI.
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.)
SNMP (client) READMAPS Section
Device – Identifies which device from the device list this map applies to, i.e., determines which IP address to try to establish a connection with.
OID – A dot field character string specifying the OID to be read from the remote SNMP device using a Get request. The string must have only digits and periods and no embedded spaces.
Hint – Provides direction on how to interpret data in the event the value type is Octet String. All ASN data types are interpreted according to their type; however, Octet String will default to being interpreted as a character string unless this hint says otherwise, and the length is exactly 4 or 8 bytes (octets).
| Hint Label | Description |
|---|---|
| None | No special interpretation |
| Float | Treat 4-byte Octet String as RFC 6340 IEEE 754 32-bit floating point |
| Double | Treat 8-byte Octet String as RFC 6340 IEEE 754 64-bit floating point |
Scale – Provides a scale factor if non-zero (has the effect of being 1 if zero). Data received from a remote SNMP device is multiplied by this factor (if non-zero) before being placed in the local object. Applies to numeric values and numeric local objects only.
Offset – Provides an offset to work in conjunction with scale factor. This value will be added to the data value received from a remote SNMP device before being placed in the local object. Applies to numeric values and numeric local objects only.
DestObj – Specifies which local object the result of this read operation should be placed in.
PollTime – Poll time in seconds, can be fractional. The sets the rate at which the remote SNMP device will be polled. This poll time is not guaranteed to be met. Polling is done in round-robin fashion. In a very busy system, more than this time may expire before the next poll. If less than this time has expired, then the system will wait this amount of time until polling again.
DefValue – Provides the default value that the local object should be set to in the event the FailCount is exceeded.
FailCount – Optional, provides a count of read failures, if non-zero, that can occur before the local object will be set to the default value given in this map. If zero, the default value will never be applied. If 1, then the default value will be applied upon the first failure (probably not recommended), and so on. The count is reset by a successful read.
IndexObj – Optional, allows for selectively enabling this read operation. If an index object (local object number) is given, and its value matches the IndexVal value, then this read operation will take place. If an IndexObj is given but the local object’s value does not match the IndexVal, then this read operation will be skipped.
IndexVal – Optional, used in conjunction with IndexObj (see note above).
SNMP (client) WRITEMAPS Section
SourceObj – Specifies the local object number that contains the data that should be sent by this write map.
Scale – Provides a scale factor if non-zero (has the effect of being 1 if zero). Data to be written is retrieved from the local object and then multiplied by this scale factor before being sent to the remote SNMP device. Applies to numeric values and numeric local objects only.
Offset – Provides an offset to work in conjunction with scale factor. This value is added to the value retrieved from the local object (after being multiplied by scale) before being sent to the remote SNMP device. Applies to numeric values and numeric local objects only.
Device – Identifies which device from the device list this map applies to, i.e., determines which IP address to try to establish a connection with.
OID – A dot field character string specifying the OID to be written in the remote SNMP device using a Set request. The string must have only digits and periods and no embedded spaces.
AsnSelect – Specifies how data should be formatted in the Set request. The selection is made from the following table:
| ASN Select Label | Interpretation |
|---|---|
| Integer | 32-bit signed integer (ASN x02) |
| TimeTicks | 32-bit unsigned integer (ASN x43) |
| Gauge | 32-bit unsigned integer (ASN x42) |
| Counter | 32-bit unsigned integer (ASN x41) |
| OctetStr | String of 8-bit bytes (ASN x04) |
| Counter64 | 64-bit unsigned integer (ASN x46) |
| OpaqueFloat | Net-SNMP 32-bit floating point (ASN x78) |
| OpaqueDouble | Net-SNMP 64-bit floating point (ASN x79) |
| OpaqueU64 | Net-SNMP 64-bit unsigned integer (ASN x7B) |
| OpaqueI64 | Net-SNMP 64-bit signed integer (ASN x7A) |
| OpaqueCounter64 | Net-SNMP 64-bit unsigned integer (ASN x76) |
| BitStr | SNMP bit string (ASN x03) |
| ObjectID | SNMP object ID (ASN x05) |
| IpAddress | 32-bit IPv4 address (ASN x40) |
| OctetStrFloat | RFC 6340 32-bit floating point, Octet String (ASN x04, hint FLOAT) |
| OctetStrDouble | RFC 6340 64-bit floating point, Octet String (ASN x04, hint DOUBLE) |
SendPeriodic – Set to “N” to disable, or “Y” to enable periodic sending of the Set request at the poll rate given by PollTime.
PollTime – Poll time in seconds, can be fractional. This poll time is not guaranteed to be met. Polling is done in round-robin fashion. In a very busy system, more than this time may expire before the next poll. If less than this time has expired, then the system will wait this amount of time until polling again. The sets the rate at which the remote SNMP device will be updated, provided “sendPeriodic” has been enabled. This poll time will be disregarded if sendPeriodic is not enabled.
SendDelta – Set to “N” to disable, or “Y” to enable the “send on delta” feature where Set requests are made based on changes in the local object value (see delta below).
Delta – Specifies the margin by which the local object value should change before sending another Set request to send the new value to a remote SNMP device. Once the changed value has been sent, the new local value is retained for future comparison in determining subsequent additional change. The delta value is disregarded if sendDelta is not enabled.
SendMaxQuiet – Set to “N” to disable or “Y” to enable the MaxQuietTime feature. If disabled, the MaxQuietTime will be disregarded.
MaxQuietTime – Time in seconds, can be fractional. If a Set request has not been made either as a result of poll timing or value changing by delta within this time period, then a Set request will be made anyway. This specifies the maximum amount of time that should expire without any Set request being made for any reason.
MinQuietTime – Time in seconds, can be fractional. This specifies the mínimum amount of time that should elapse between sending of Set requests for this write map. The minimum quiet time has the effect of throttling network traffic.
IndexObj – Optional, allows for selectively enabling this read operation. If an index object (local object number) is given, and its value matches the IndexVal value, then this read operation will take place. If an IndexObj is given but the local object’s value does not match the IndexVal, then this read operation will be skipped.
IndexVal – Optional, used in conjunction with IndexObj (see note above).
SNMP (client) WALKRULES Section
Device – Identifies which device from the device list this rule applies to, i.e., determines which IP address to try to establish a connection with.
OID – A dot field character string specifying the starting OID for the table walk. The table is walked using GetNext requests, therefore the OID must specify an OID preceeding the first OID that one wishes to read.
The table OID is different than OIDs for read and write maps. The table OID includes optional wildcard fields when the walk method is Index or Mask. For example, to walk the alarm table of a UPS using RFC 1628, the OID would be 1.3.6.1.2.1.33.1.6.2.1.*(2).*. The *(2) means allow any value in the second to last field but only act on the value when this field is 2. The last asterisk means disregard the last field entirely (which for RFC 1628 increments with each new alarm until reaching some rollover point, then starts back at 1 again).
Method – Defines the method of table walk to be used with values as follows:
| Method Label | Method |
|---|---|
| Normal | Normal – see documentation |
| Sparse | Sparse – see documentation |
| Wildcard | Wildcard – see documentation |
| Index | Index – see documentation |
| Mask | Mask – see documentation |
The table walking process can become complicated by the fact that tables are allowed to have missing rows, or rows may have intermittent missing columns. In some applications, rows will be populated only temporarily and then they will disappear. The table walk method identified as "Normal" expects the given column to exist in all rows through the range of rows defined by the starting OID and the count. The remaining methods accommodate the other complications permitted by SNMP. (See additional documentation for full description of methods.)
Hint – Provides direction on how to interpret data in the event the value type is Octet String. All ASN data types are interpreted according to their type; however, Octet String will default to being interpreted as a character string unless this hint says otherwise, and the length is exactly 4 or 8 bytes (octets).
| Hint Label | Description |
|---|---|
| None | No special interpretation |
| Float | Treat 4-byte Octet String as RFC 6340 IEEE 754 32-bit floating point |
| Double | Treat 8-byte Octet String as RFC 6340 IEEE 754 64-bit floating point |
StartObj – Specifies the first local object number that may be filled by this table walk, used in conjunction with count (below).
ObjCount – Specifies the number of local objects, starting at StartObj, that may be filled by this table walk. Most table walks are going to result in filling multiple objects with data.
PollTime – Poll time in seconds, can be fractional. The sets the rate at which the table in the remote SNMP device will be walked. This poll time is not guaranteed to be met. Polling is done in round-robin fashion. In a very busy system, more than this time may expire before the next poll. If less than this time has expired, then the system will wait this amount of time until polling again.
IndexObj – Optional, allows for selectively enabling this read operation. If an index object (local object number) is given, and its value matches the IndexVal value, then this read operation will take place. If an IndexObj is given but the local object’s value does not match the IndexVal, then this read operation will be skipped.
IndexVal – Optional, used in conjunction with IndexObj (see note above).
