SNMPTrap
Interface to the PI System

Version 1.1.3.0

How to Contact Us

OSIsoft, Inc.
777 Davis St., Suite 250
San Leandro, CA94577USA
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)

Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA / Worldwide Offices
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSI Software Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
OSIsoft Japan KK
Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V.
Mexico City, Mexico
Sales Outlets and Distributors
  • Brazil
  • Middle East/North Africa
  • Republic of South Africa
  • Russia/Central Asia
/
  • South America/Caribbean
  • Southeast Asia
  • South Korea
  • Taiwan


OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party’s products or any affiliation with such party of any kind.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Unpublished – rights reserved under the copyright laws of the United States.
© 2003-2007 OSIsoft, Inc. PI_SNMPTrap.doc

Table of Contents

Introduction

Reference Manuals

Supported Features

Examples of Supported Devices

Diagram of Connections

Principles of Operation

SNMP Traps

Message Components of Input Points

Output Points

Installation Checklist

Interface Installation

Naming Conventions and Requirements

Interface Directories

PIHOME Directory Tree

Interface Installation Directory

Interface Installation Procedure

Installing Interface as a Windows Service

Installing Interface Service with PI ICU

Installing Interface Service Manually

Digital States

PointSource

PI Point Configuration

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

ExDesc

Conversion

Scan

Shutdown

Output Points

Trigger Method 1 (Recommended)

Trigger Method 2

Exception Specifications

Other Attributes

Default Points

bdp

Performance Point Configuration

I/O Rate Point Configuration

Monitoring I/O Rates on the Interface Node

Configuring I/O Rate Tags with PI ICU (Windows)

Configuring I/O Rate Tags Manually

Configuring PI Point on the PI Server

Configuration on the Interface Node

Startup Command File

Configuring the Interface with PI ICU

Manual Maintenance of the Startup Command File

Command-line Parameters

Sample pisnmptrap.bat File

Interface Node Clock

Security

Windows

Starting / Stopping the Interface on Windows

Starting Interface as a Service

Stopping Interface Running as a Service

Buffering

Configuring Buffering with PI ICU (Windows)

Configuring Buffering Manually

Example piclient.ini File

Appendix A: Error and Informational Messages

Message Logs

System Errors and PI Errors

Appendix B: Troubleshooting

Interface Level Debugging (-dbg)

Point Level Debugging (Location5)

Common Problems

Interface Exits on Startup

Point Not Receiving New Values

Output Point Not Loaded

-15011 Error for Output Point

Appendix C: Additional Operational Information

CIDR Notation

IP Address Resolution

Data Rates and Record Processing

Appendix D: Using the Interface as Part of a Notification System

PI point for Monitoring

PI point for Calculation

PI point for Notification

Summary

Revision History

SNMP Trap Interface to the PI System1

Introduction

A large data communications network often consists of hundreds, if not thousands, of devices. As a result, monitoring so many devices via periodic polling can result in an undesired increase in network traffic. Consequently, a network management program may implement a method of management whereby instead of constantly requesting status information from the network devices, it receives from these devices unsolicited reports of unusual events.

For example, as soon as a network router restarts, it will notify the network management program about its initialization. This notification message is typically sent via the Simple Network Management Protocol (SNMP). In SNMP terminology, such a message is known as an SNMP trap.

SNMP traps can be sent not only by devices that route traffic (such as routers and switches), but by any device that contains an SNMP Agent. For example, a computer runs a Web server program (e.g., Internet Information Server). This computer also has an SNMP Agent present. When this machine reboots, the SNMP Agent likewise restarts. Accordingly, this SNMP Agent sends an SNMP trap message that contains information about such an initialization.

OSIsoft’s PI SNMPTrap Interface program provides a subset of the functionality of a network management program. Specificially, PI SNMPTrap receives SNMP trap messages and stores them into the PI Server. The Interface is capable of processing SNMP version 1 traps. Furthermore, the user can configure the Interface to send an SNMP version 1 trap to a network management program.

For traps received, PI SNMPTrap supports both generic trap messages and enterprise specific trap messages. Examples of the former are:

  • cold start (0) – signifies that the sending device is reinitializing itself such that the SNMP agent’s configuration or the device implementation may have been altered.
  • warm start (1) – signifies that the sending device is reinitializing itself such that neither the SNMP agent configuration nor the device implementation has been altered.
  • link down (2) – signifies that the sending device recognizes a failure in one of its communication links.
  • link up (3) – signifies that the sending device recognizes that one of its communication links has come up.
  • authentication failure (4) – signifies that the sending device has received an SNMP request that it cannot authenticate.
  • EGP neighbor loss (5) – in a device running the Exterior Gateway Protocol (EGP), this trap signifies that an EGP neighbor has changed to a down state.

An example of an enterprise specific trap is a message sent by a temperature measuring device such as the following:

Enterprise: 1.3.6.1.4.1.1200.8.7.6

Trap type: 6 (Enterprise Specific)

Specific trap type: 1 (temperature is above the threshold)

OID: 1.3.6.1.4.1.1200.8.7.6.1 (sensor number)

Value: 3

OID: 1.3.6.1.4.1.1200.8.7.6.2 (temperature in degrees F)

Value: 81

For traps sent, PI SNMPTrap supports only enterprise-specific traps. That is, the Interface does not have the ability to send generic trap messages.

Note: The SNMP protocol is based on the User Datagram Protocol (UDP), which does not guarantee the delivery of data. Therefore, to monitor devices effectively, users may wish to use PI SNMPTrap in conjunction with OSIsoft’s PISNMP Interface program. PISNMP provides the ability to collect data periodically from SNMP-enabled devices.

PI SNMPTrap runs on Windows NT (version 4.0), Windows 2000, or Windows XP computers. Unless otherwise noted, the remainder of this document uses the term “Windows” to refer to all these.

PI SNMPTrap requires

  • PI Server version 3.3.361.43 or higher, and
  • PI-SDK v1.3.1.237 or higher,
  • PI-API v1.3.4 or higher (automatically included as part of PI-SDK), and
  • Internet Explorer, v4.0 or higher

PI SNMPTrap does not require any special hardware. A standard network interface card on the Windows NT machine is sufficient.

The direction of data flow is bidirectional; that is, from the device sending SNMP traps to the PI Server and from the PI Server to a device receiving SNMP traps.

Reference Manuals

OSIsoft
  • UniInt Interface User Manual
  • PI-ICU User Manual
  • PI Server Manuals
  • PI-API Installation Instructions
  • PI-API Manual
  • Regular Expressions Tutorial For Use with the PI-HTML Interface
Internet RFCs (Request for Comments)
  • RFC 1157

Users who wish to store enterprise specific trap messages into PI will need information on the vendor-specific OIDs that define such messages. Such information is available in the MIB files supplied by the vendor.

Supported Features

Feature / Support
Part Number / PI-IN-OS-SNMPT-NTI
* Platforms / Windows NT 4.0 / 2000 / XP
APS Connector / No
Point Builder Utility / No
ICU Control / Yes
PI Point Types / float16 / float32 / float64 / int16 / int32 / string / digital
Sub-second Timestamps / Yes
Sub-second Scan Classes / No
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / Yes
Inputs to PI: Scan-based / Unsolicited / Event Tags / Unsolicited
Supports Questionable Bit / No
Supports Multi-character PointSource / Yes
Maximum Point Count / Maximum point count of PI Server
* Uses PI SDK / Yes
PINet String Support / Not applicable
* Source of Timestamps / PI Server machine
History Recovery / No
* UniInt-based
Disconnected Startup
SetDeviceStatus / Yes
Yes
Yes
Failover / None
Vendor Software Required on PI Interface Node / PINet Node / No
* Vendor Software Required on Foreign Device / Yes
Vendor Hardware Required / No
* Additional PI Software Included with Interface / Yes
Device Point Types / Not applicable
Serial-Based Interface / No

* See paragraphs below for further explanation.

Platforms

The Interface is designed to run on the above mentioned Microsoft Windows operating systems and greater. Windows NT 4.0 requires Service Pack 6.

Please contact OSIsoft Technical Support for more information.

Uses PI SDK

The PI SDK and the PI API are bundled together and must be installed on each PI Interface node. This interface specifically makes PI SDK calls to create PI points. In addition, when the PI Server version is earlier than 3.4.370.52, or when the PI API version is earlier than 1.6.02, the Interface uses the PI SDK to retrieve a PI point's tagname, Extended Descriptor, and Instrument Tag attributes.

Source of Timestamps

The clock on the computer running the PI Server provides the source of the timestamps for the data sent by PI SNMPTrap. For an input point, the Interface writes a timestamp that reflects the time at which it processed the SNMP Trap message. For an output point, the Interface uses a timestamp that reflects the time at which the triggering event occurred.

UniInt-based

UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by developers, and is integrated into many interfaces, including this interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of OSIsoft’s interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniIntsupplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.

The UniInt Interface User Manual is a supplement to this manual.

SetDeviceStatus

For a Health Tag whose Extended Descriptor attribute contains [UI_DEVSTAT], the Interface writes the following values:

a)"1 | Starting" - the interface has started.

b)"Good" - the interface has received SNMP traps and has processed them.

c)"4 | Intf Shutdown" - the interface has shut down.

d)"5 | internal queue is full" - the interface's internal queue is full, and the interface cannot receive additional SNMP traps.

Please refer to the UniInt Interface User Manual file for more information on how to configure Health Tags.

Vendor Software Required on Foreign Device

The remote device must have software capable of sending SNMP Trap messages.

Additional PI Software

The interface distribution includes a RegExp tutorial document and RegExp Tester program. These two files provide information on Regular Expressions. Users may need to make use of Regular Expressions when they want to extract a portion of string data contained in an SNMP trap. (Strictly speaking, these files are not “PI Software” because they are completely independent of PI. However, they facilitate the use of this interface.)

Examples of Supported Devices

During the testing of previous versions of this Interface, customers have reported compatibility between the following devices and PI SNMPTrap:

  • Cisco 7206 running IOS 12.3-1a sending all SNMP traps
  • Cisco PIX 515 running version 6.3(1) sending all SNMP traps
  • Windows 2000 Server 5.00.2195 SP4 sending Windows Event Log entries configured via the Evntwin tool

Diagram of Connections

SNMP Trap Interface to the PI System1

Principles of Operation

SNMP Traps

An SNMP trap is an unsolicited message sent by an SNMP Agent to an SNMP Manager program. As defined by the Internet standards document RFC 1157, the following are examples of SNMP trap types along with their numeric values:

  • cold start (0) – signifies that the sending device is reinitializing itself such that the SNMP agent’s configuration or the device implementation may have been altered.
  • warm start (1) – signifies that the sending device is reinitializing itself such that neither the SNMP agent configuration nor the device implementation has been altered.
  • link down (2) – signifies that the sending device recognizes a failure in one of its communication links.
  • link up (3) – signifies that the sending device recognizes that one of its communication links has come up.
  • authentication failure (4) – signifies that the sending device has received an SNMP request that it cannot authenticate.
  • EGP neighbor loss (5) – in a device running the Exterior Gateway Protocol (EGP), this trap signifies that an EGP neighbor has changed to a down state.
  • Enterprise specific (6) – signifies that the trap message is specific to a particular vendor.

Message Components of Input Points

An SNMP trap message contains information other than the numeric trap type listed above. In particular, every SNMP trap message has the IP address of the SNMP Agent that originated the trap. Other additional data are available depending on the trap type. For example, the cold start generic trap may contain the following components:

Agent address: 192.168.8.72

Enterprise: 1.3.6.1.4.311.1.1.3.1.1

Trap type: 0 (cold start)

Specific trap type: 0

The link up generic trap may contain the following components:

Agent address: 192.168.10.100

Enterprise: 1.3.6.1.4.311.1.1.3.1.1

Trap type: 3 (link up)

Specific trap type: 0

OID 1: 1.3.6.1.2.1.2.2.1.1.2

Value of OID 1: 2 (link number 2 has come up)

An enterprise specific trap may contain the following components:

Agent address: 192.168.10.8

Enterprise: 1.3.6.1.4.1.1200.8.7.6

Trap type: 6 (Enterprise Specific)

Specific trap type: 1 (temperature is above the threshold)

OID1: 1.3.6.1.4.1.1200.8.7.6.1 (sensor number)

Value of OID1: 3

OID2: 1.3.6.1.4.1.1200.8.7.6.2 (temperature in degrees F)

Value of OID2: 81

PI Points

Because a PI point holds only a single value, multiple points are necessary if a user wishes to store all of the components of a single trap message. For example, the cold start trap given above requires 4 PI points:

Name of PI point / Value
aTrap / 0
aTrap_device / 192.168.8.72
aTrap_enterprise / 1.3.6.1.4.311.1.1.3.1.1
aTrap_specific / 0

Similarly, the link up trap mentioned above requires 5 points:

Name of PI point / Value
aTrap / 3
aTrap_device / 192.168.10.100
aTrap_enterprise / 1.3.6.1.4.311.1.1.3.1.1
aTrap_specific / 0
aTrap_linkNumber / 2

Finally, the enterprise specific trap mentioned previously requires 6 points:

Name of PI point / Value
aTrap / 6
aTrap_device / 192.168.10.8
aTrap_enterprise / 1.3.6.1.4.1.1200.8.7.6
aTrap_specific / 1
aTrap_sensorNumber / 3
aTrap_temperature / 81

Of course, a user may not want to store every component of a single trap message. For this situation, he simply does not build the unwanted points.

During point building, the user provides filtering conditions that tell the Interface which traps are relevant to which points. For example, for a particular point, the Interface should process

  • traps that are either link up or link down; or
  • traps that originate from devices with IP addresses 192.168.0.1 through 192.168.0.100; or
  • traps that contain an enterprise specification that begin with 1.3.6.1.9;or
  • traps that meet other filtering conditions

Also, during point building, the user tells the Interface what type of value it should write to the point. For example, the Interface can write to the point

  • the generic trap type value (e.g., 0 through 6); or
  • the specific trap type value; or
  • the IP address of the SNMP Agent that sent the trap (e.g., 192.168.0.1);or
  • the OID value contained within enterprise specific traps (e.g., 81).

If the OID value contained within enterprise specific traps is a string value (e.g., “The temperature is 109 degrees”) the user can configure the Interface to extract a particular portion of the string (e.g., “temperature” or 109) and store only this portion into the PI point.

The Interface Point Configuration section of this manual provides details.

Values Sent to PI

As defined in RFC 1157, the values associated with generic SNMP trap types range from 0 (cold start) to 6 (enterprise specific trap). However, users can configure interface points such the Interface reserves the value of 0 for a “normal status”. This configuration allows the Interface to properly represent traps as digital states (i.e., discrete values). So, the Interface writes to PI Server the actual trap value plus an offset of one:

Trap type / Value sent to PI
<no trap received; normal status> / 0
cold start / 1
warm start / 2
link down / 3
link up / 4
authentication failure / 5
EGP neighbor loss / 6
Enterprise specific / 7

Thus, the above example for cold start becomes:

Name of PI point / Value sent to PI
aTrap / 1 (instead of 0)
aTrap_device / 192.168.8.72
aTrap_enterprise / 1.3.6.1.4.311.1.1.3.1.1
aTrap_specific / 0

The link up example becomes:

Name of PI point / Value sent to PI
aTrap / 4 (instead of 3)
aTrap_device / 192.168.10.100
aTrap_enterprise / 1.3.6.1.4.311.1.1.3.1.1
aTrap_specific / 0
aTrap_linkNumber / 2

The enterprise specific example becomes

Name of PI point / Value
aTrap / 7 (instead of 6)
aTrap_device / 192.168.10.8
aTrap_enterprise / 1.3.6.1.4.1.1200.8.7.6
aTrap_specific / 1
aTrap_sensorNumber / 3
aTrap_temperature / 81

Accordingly, the Interface writes the value of 0 (to represent normal status) with a timestamp 10 seconds later than the timestamp of the trap value.

For example, an SNMP Agent sends a “cold start” trap message. The user can configure a point such that PI SNMPTrap to write the following values to PI Server:

Point / Timestamp / Value stored in PI
aTrap / 4-Sep-02 11:00:00 / 1 (cold start)
aTrap / 4-Sep-02 11:00:10 / 0 (normal status)

This time offset of 10 seconds is user configurable, on a per point basis.

Step Attribute

When points are configured such that the Interface writes a value of 0 after it writes the value of the SNMP trap type, the Interface allows the user to view occurrences of SNMP traps as pulses. (Of course, the Step attribute of the PI point needs to be set to ON).