SNMP Trap Receiver 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 Trap Receiver Example

The trap receiver runs as a separate task independent of both the SNMP server (agent) and SNMP client. This allows the trap receiver to have its own “new data” flag which allows the IoTServer to function as a trap forwarder if desired. The following illustrates a trap receive CSV configuration file.

BEGIN,SNMP,TRAPRECVRULES
PEERNAME,TRAPOID,VAROID,HINT,FIXED,FIXEDVAL,TIMEOUT,TIMEOUTVAL,RESULTOBJ
192.168.1.67,1.3.6.1.4.1.3815.1.3.1.1.1,1.3.6.1.4.1.3815.1.3.1.1.1.1.2.1.0,NONE,N,0.000000,0,0.000000,22
END

SNMP (agent/server) TRAPRECVRULES Section

Peername – Specifies the peername that the trap is expected to be received from. If an IP address is given, then the IP address of the incoming trap message is checked. If a host name is given and the incoming trap message contains a host that could be looked up (via DNS lookup), then the host name field is checked instead of IP address.

TrapOID – Specifies the Trap OID that is expected. Traps and Informs always contain a Trap OID identifying the trap or inform, along with additional varbinds with a data payload. The Trap OID must match the OID given here before action will be taken.

VarOID – Specifies the varbind OID to look for in the message if the Peername and Trap OID match.

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

Fixed – Enter “Y” to specify that a fixed value should be placed in the local object when this trap is received, rather than try to derive a data value from the trap message. Enter “N” to parse data from the trap varbind to be placed in the local object.

FixedVal – The fixed value to be placed in the local object any time this trap is received, assuming the Fixed column indicates “Y”. This feature is most often used in conjunction with the Timeout feature.

Timeout – Integer number of seconds for trap receive timeout. Note that this is not a session timeout, it provides for an automatic reset of the local object value. If zero, then the timeout feature is disabled.

TimeoutVal – Specifies the fixed value that should be placed in the local object after the timeout period has expired. The typical scenario is that either the value gleaned from the trap message itself, or the fixed value, would be placed in the local object upon receiving the trap. Then ‘timeout’ period later, the timeout value is placed in the local object, replacing the trap value.

ResultObj – Specifies the local object where data retrieved from the varbind called out by VarOID will be placed (or fixed value will be placed) assuming the VarOID is found, and Peername and Trap OID match.

SNMP Trap Receiver CSV Files