Overview:

Simple Network Management Protocol (SNMP) is a TCP protocol which allows data interrogation of, and control over network devices.  The Internet Engineering Task Force (IETF) describes the SNMP protocol in a collection of Request For Comment (RFC) documents. Traps are a particular message type of the SNMP protocol which are described in RFC 1215 “A Convention for Defining Traps” and RFC 1157 “A Simple Network Management Protocol” which are freely available on the internet along with may other sources of information on this protocol.

Driver:

The SNMPII driver works with two windows services via the WinSNMP API.  These services must be installed and running on the IOserver as described in the SNMPII Help document.

The information in this document is assuming a driver version SNMP v2.07.12.000 or later.  Earlier versions of this driver do have known issues which regards to reading and sending traps.  At the time of writing this driver is a hotfix version and not a full release available from support to customers with a current support agreement..

SNMP Model:

The model consists of two types of software components connected by a TCP/IP network, those are Agents and Managers.  And also three types of communication messages or protocol data units (PDUs) Requests and Responses, and also Traps.  A Typical SNMP managed system would include a PC which runs an application that implements the manager component of the SNMP Network; The SNMP manager PC would poll data in network devices (SNMP agents) on the network for necessary information and then send control messages to the devices to optimise network performance.  A trap may be created in the case of an unexpected event occurring at a device, an SNMP agent, which will then send an unsolicited message, to the PC manager describing the event.

Requests:

Requests are made from a Manager application to an Agent application.  A request can be either to ask for data from an agent or to set a value in the agent.

Response:

A response message is directly related to an initial request.  A response will be from an Agent to the Manager containing whatever data has been requested.

Traps:

Traps can be sent by both agents and managers and received by managers.  These are unsolicited meaning that the recipient will not know when a trap is going to arrive.  Typically an application which is designed to receive a trap will continuously check if it has received a trap and then trigger some action.

In a typical application designed to process incoming traps a set of trap templates is known to the trap receiver.  Based on the source of the trap and the Generic and Specific type of the trap, the application will undertake some specific action.

Citect’s SNMP driver implement raw access SNMP traps by exposing a number of Variable address which can be used to access a trap queue.  To receive, generate and process traps in Citect project designers will need to develop cicode to manage the trap queue.

Varibinds:

A varibind is a combination of the object ID which identifies the variable in the device.  These numbers are described in the devices MIB file.  The second component is the OIDs data.  Hence the Varibind is a binding of Variable and Data. A single trap message may contain multiple varbinds.

Trap Tags:

T0 – Source Enterprise Number
This is the enterprise number of the agent or manager sending the trap.  Each device that implements SNMP should have a unique Enterprise number administered by the Internet Assigned Numbers Authority (iana).

T1 – Source IP address
This is the address where the trap is created.  The driver will set this by default to the local PCs IP address.

T2 – Trap Generic Type
The generic trap type should be an integer between 0 and 6.  The numbers 0 to 5 have predefined meanings.  When creating an enterprise specific trap the generic type should be set to 6.

T3 – Trap Specific Type
Only applies to generic type 6 traps.  The specific type is used to differentiate between enterprise specific traps.  This integer allows the receiver to check against known trap types to know what data is included and how to process the information.

T4 – Time Stamp
The time stamp of when the trap was created.  The SNMPII driver sets this value to the time number of 100ths of a second since the node started.

T5 – Varibind OID
The Object ID of the varibind

T6 – Varibind Data
Data of the Varibind.

TN – Trap Next:
The SNMP trap methods don’t fit neatly into the Citect IO device model.  The trap queue and variable address can be thought of as belonging to the driver and not any configured device. (Even though they must be configured against an SNMP device)  In a project which uses SNMP traps there should only be one set of trap tags which will access a queue of traps received by the driver, the source of the traps can be any SNMP device on the network, not necessarily configured in Citect.

There are three modes which the traps can exist in, an empty queue, received traps, and generated trap.  When the queue is empty all the trap tags will return empty strings except TN and TNVB which will return 0.  When the queue is empty received traps will populate the trap tags with the oldest trap in the queue.  Reading TN will return the number of traps in the queue.  Each time TN is written to (regardless of the value written) the trap tags will be set to the next item in the queue and the current trap is deleted. 

When generating a trap, first writes to any of T0 to T4, the trap tags will now only show the newly created trap.  If traps are received during the time a trap is being created TN will increase but the trap tags will have the generated traps values.  When TF is written the trap tags still retain the generated trap, the trap can therefore be forwarded several times.  Again writing to TN will delete the generated trap and set the trap tags to the next set of values in the trap queue.

TNVB – Trap Subfield Varibind number:
TNVB is used to index the sub filds of a trap.  When viewing a received trap reading TNVB will return the number of subfields contained in the trap.  Writing to TNVB will update the Tags T5 and T6.  Note that reading TNVB will always return the number of varibinds in the trap and not the current varibind index for the data avaibable from T5 and T6.

When creating a trap writing an integer to TNVB which less then TNVB -1 will set the values of T5 and T6 to the written numbers varibind index.  If TNVB = 0 then writing 0 to TBVB will create the first varibind in the new trap.  Once 0 is written to TNVB T5 and T6 can be written to and TNVB will return 1 because there is now 1 varibind in the queue.  TNVB should only ever be written in the rang 0 to the existing TNVB, writing the read value of TNVB back to TNVB will add a new varibind to the trap and increase TNVB by 1.

TF – Trap Forward
The IP address of the target device.  Once written the trap will be forwarded to that address.  Note that the trap is retained so it can be sent to multiple addresses.

Generating Traps:

Step 1) Write to any of T0 to T4, the other 4 tags will be initialized to default values.

The enterprise number, Generic Type, Specific Type, Trap Address, can all be modified.  At this stage received taps will increase the read value of TN but not affect the newly created trap data.  To return to the trap queue write any number to TN which will delete the new trap and set the pointer to the oldest received trap.

Step 2) In order to add varibinds to the trap the SubField tag must have the number 0 written to it in order to initialize the first Varibind. 

Step 3) Once 0 is written to TNVB it is possible to write to T5 and T6.  If T5 is written first T6 will remain empty, if T6 is written first T5 will be given a default value.

Step 4) To add more varibinds to a trap TNVB needs to be incremented in unit steps 1 then 2 then 3 etc.  For each varibind data may be added to T5 and T6.  TNVB will always read the total number of Varibinds in the current trap.  The different varibinds can be displayed by writing the required index to TNVB

Step 5) Once the trap has been created it can be sent by writing a target IP address to the trap forwarding tag TF.  The trap will NOT be deleted after writing to TF, and can be sent to several locations by writing to TF several times.  TN must be written to in order to delete the generated trap and return to the received queue.

Trouble shooting:

The SNMP driver must be online.  That will require that at least one SNMP device is configured in the project and is online.  It is possible to create a device which references the PC running the IO server.

The SNMP must be installed and running on the IOserver PC.  Both the SNMP service and the SNMP Trap servers are running correctly.  Microsoft’s TrapUtil.exe can be used to test the correct operation of the SNMPTrap service.

The Trap service snmptrap.exe needs to be listening on the trap port 162.  If another application has this port Citect’s SNMP driver may not work correctly.  The simplest way to check is to type at a command prompt.

Netstat –a –b