SNMPTrap Interface to the PI Systemcdn.osisoft.com/interfaces/2104/PI_SNMPTrap_1.1.3.0.doc · Web viewPI-API v1.3.4 or higher (automatically included as part of PI-SDK), and

SNMPTrapInterface to the PI System

Version 1.1.3.0

How to Contact UsOSIsoft, Inc. 777 Davis St., Suite 250San Leandro, CA 94577 USA

Telephone(01) 510-297-5800 (main phone)(01) 510-357-8136 (fax) (01) 510-297-5828 (support phone)

[email protected]

Houston, TX Johnson City, TN Mayfield Heights, OHPhoenix, AZ Savannah, GASeattle, WAYardley, PA

Worldwide Offices

OSIsoft AustraliaPerth, AustraliaAuckland, New Zealand

OSI Software GmbH Altenstadt, Germany

OSI Software Asia Pte Ltd.Singapore

OSIsoft Canada ULCMontreal, Canada

OSIsoft, Inc. Representative OfficeShanghai, People’s Republic of China

OSIsoft Japan KKTokyo, 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

www.osisoft.com

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 LEGENDUse, 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

http://www.osisoft.com/

mailto:[email protected]

Table of Contents

Introduction....................................................................................................................1Reference Manuals......................................................................................................2

Supported Features......................................................................................................3

Examples of Supported Devices..................................................................................5

Diagram of Connections...............................................................................................5

Principles of Operation.................................................................................................7SNMP Traps.............................................................................................................7

Message Components of Input Points......................................................................7

Output Points..........................................................................................................12

Installation Checklist...................................................................................................15

Interface Installation....................................................................................................17Naming Conventions and Requirements....................................................................17

Interface Directories...................................................................................................18

PIHOME Directory Tree..........................................................................................18

Interface Installation Directory................................................................................18

Interface Installation Procedure..................................................................................18

Installing Interface as a Windows Service..................................................................18

Installing Interface Service with PI ICU...................................................................18

Installing Interface Service Manually......................................................................23

Digital States................................................................................................................25

PointSource..................................................................................................................27

PI Point Configuration.................................................................................................29Point Attributes...........................................................................................................29

Tag.........................................................................................................................29

PointSource............................................................................................................29

PointType...............................................................................................................30

Location1................................................................................................................30

SNMP Trap Interface to the PI System iii

Location2................................................................................................................30

Location3................................................................................................................34

Location4................................................................................................................35

Location5................................................................................................................35

InstrumentTag........................................................................................................35

ExDesc...................................................................................................................41

Conversion..............................................................................................................43

Scan.......................................................................................................................43

Shutdown................................................................................................................43

Output Points..............................................................................................................44

Trigger Method 1 (Recommended).........................................................................44

Trigger Method 2....................................................................................................44

Exception Specifications.........................................................................................44

Other Attributes......................................................................................................45

Default Points.............................................................................................................45

-bdp.......................................................................................................................48

Performance Point Configuration...............................................................................49

I/O Rate Point Configuration.......................................................................................51Monitoring I/O Rates on the Interface Node...............................................................51

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

Configuring I/O Rate Tags Manually..........................................................................53

Configuring PI Point on the PI Server.....................................................................53

Configuration on the Interface Node.......................................................................53

Startup Command File.................................................................................................55Configuring the Interface with PI ICU.........................................................................55

Manual Maintenance of the Startup Command File...................................................59

Command-line Parameters.........................................................................................60

Sample pisnmptrap.bat File........................................................................................62

Interface Node Clock...................................................................................................63

Security.........................................................................................................................65Windows.....................................................................................................................65

Starting / Stopping the Interface on Windows...........................................................67Starting Interface as a Service...................................................................................67

SNMP Trap Interface to the PI System iv

Stopping Interface Running as a Service...................................................................67

Buffering.......................................................................................................................69Configuring Buffering with PI ICU (Windows).............................................................69

Configuring Buffering Manually..................................................................................73

Example piclient.ini File..............................................................................................74

Appendix A: Error and Informational Messages.......................................................75Message Logs............................................................................................................75

System Errors and PI Errors.......................................................................................75

Appendix B: Troubleshooting.....................................................................................77Interface Level Debugging (-dbg)...............................................................................77

Point Level Debugging (Location5)............................................................................79

Common Problems.....................................................................................................80

Interface Exits on Startup.......................................................................................80

Point Not Receiving New Values............................................................................81

Output Point Not Loaded........................................................................................81

-15011 Error for Output Point.................................................................................81

Appendix C: Additional Operational Information......................................................83CIDR Notation............................................................................................................83

IP Address Resolution................................................................................................84

Data Rates and Record Processing...........................................................................84

Appendix D: Using the Interface as Part of a Notification System..........................89PI point for Monitoring............................................................................................89

PI point for Calculation...........................................................................................90

PI point for Notification...........................................................................................92

Summary................................................................................................................93

Revision History...........................................................................................................95

SNMP Trap Interface to the PI System v

IntroductionA 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)

SNMP Trap Interface to the PI System 1

Introduction

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 PI SNMP Interface program. PI SNMP 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 bi-directional; 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.

2

Supported FeaturesFeature 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 PI Point 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

YesYesYes

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.


Introduction

PlatformsThe 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 SDKThe 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 TimestampsThe 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-basedUniInt 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 UniInt-supplied 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.

SetDeviceStatusFor 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 DeviceThe remote device must have software capable of sending SNMP Trap messages.

Additional PI SoftwareThe 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

4

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 DevicesDuring 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


Principles of Operation

SNMP TrapsAn 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 PointsAn 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:


Enterprise: 1.3.6.1.4.311.1.1.3.1.1

Trap type: 3 (link up)


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



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 PointsBecause 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 ValueaTrap 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:




aTrap_specific 0

aTrap_linkNumber 2

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



aTrap_enterprise 1.3.6.1.4.1.1200.8.7.6

aTrap_specific 1


Name of PI point ValueaTrap_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 PIAs 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



Trap type Value sent to PI

EGP neighbor loss 6

Enterprise specific 7

Thus, the above example for cold start becomes:

Name of PI point Value sent to PIaTrap 1 (instead of 0)



aTrap_specific 0

The link up example becomes:

Name of PI point Value sent to PIaTrap 4 (instead of 3)



aTrap_specific 0

aTrap_linkNumber 2

The enterprise specific example becomes

Name of PI point ValueaTrap 7 (instead of 6)


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 PIaTrap 4-Sep-02 11:00:00 1 (cold start)

10

Point Timestamp Value stored in PI

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 AttributeWhen 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).

For example, the following example PI-ProcessBook display shows PI SNMPTrap receiving the following SNMP traps:

cold start (stored in PI as a value of 1)

link up (stored in PI as a value of 4)

link up (stored in PI as a value of 4)

PI SNMPTrap provides a warning if it encounters a non-digital PI point whose Step attribute is OFF and is configured to have a normal status value written to it.

Timestamp Correlation of ValuesThe timestamp for all points that are components of the same SNMP trap message share the same timestamp. For example, a router with IP address 192.168.10.10 sends an SNMP Link Down trap that indicates network interface number 5 has failed. PI SNMPTrap writes the following values:



Point Timestamp Value stored in PIaTrap 4-Sep-02 11:00:00 3

aTrap_device 4-Sep-02 11:00:00 192.168.10.10

aTrap_linkNumber 4-Sep-02 11:00:00 5

Digital State SetPI SNMPTrap automatically creates a Digital State Set named SNMPTrapIntf for use with digital PI points that hold the SNMP trap value. The digital states associated with SNMPTrapIntf are:

Digital state ValuenoTrap 0

coldStart 1

warmStart 2

linkDown 3

linkup 4

authenFail 5

egpLoss 6

entSpecific 7

If the PI Server already has a Digital State Set named SNMPTrapIntf, the Interface does not try to modify it.

Default PointsThe user can configure PI SNMPTrap such that every time the Interface starts, it builds points that record information contained in the various traps received. As a result, it can immediately collect data. See the Point Configuration section for more information.

Output Points

Message ComponentsAs mentioned previously in this document, the Interface allows the user to send enterprise specific traps. Such a trap may contain the following components:Agent address: 192.168.10.8

Enterprise: 1.3.6.1.4.1.1200.8.7.6




Value of OID1: 3

12


Value of OID2: 81

The values for the above components either are automatically set by the Interface or are specified by the user in PI point attribute fields. In particular,Agent address: automatically set by PI SNMPTrap

Enterprise: specified in the PI point's Instrument Tag

Trap type: automatically set by PI SNMPTrap

Specific trap type: specified in the PI point's Instrument Tag

OID1: specified in the PI points' Extended Descriptor

Value of OID1: specified in the PI point's Extended Descriptor

OID2: specified in the PI points' Extended Descriptor

Value of OID2: specified in the PI point's Extended Descriptor

System Digital StateAs with all UniInt-based interfaces, PI SNMPTrap attempts to send an output when either the output point's source tag or the output point itself receives a new value. However, if this new value is a member of the system digital state set (e.g., Calc Failed), then the Interface does not send a SNMP Trap. Instead, if the output point has a source tag, the Interface writes Bad Output to the output point. (If the output point does not have a source tag, the Interface does not write Bad Output to it.)

However, if an output point's source tag's snapshot value is Filtered (system digital state number 244), then the Interface does not write Bad Output to the output point. The user can change this digital state that the Interface ignores by using the –idsnum ("ignore digital state number") startup command parameter. For example, to tell PI SNMPTrap not to write Bad Output when the value of the source tag is Failed (system digital state 241), run the Interface with -idsnum=241.

To tell the Interface to write Bad Output to the output point even when the source tag's snapshot value is Filtered, use -idsnum=0.

-sio Startup ParameterIf the user wants the Interface to service output points, he must specify the –sio ("suppress initial outputs") startup command parameter.

If the user is using the PI-ICU, he must check the "Suppress initial outputs" checkbox:



Otherwise, PI SNMPTrap rejects all points configured as output.

Floating Point ValuesThere is no floating point data type in the SNMP standards. So, a floating point value sent as an SNMP Integer data type is rounded up to the nearest integer. For example, the number 3.82 is sent as 4.

Alternatively, the user can choose to send a floating point value as an SNMP String data type. In this case, the number 3.82 is sent as "3.82".

Application ExampleAppendix D of this document describes the use of the output feature of the PI SNMPTrap Interface as part of a monitoring and notification system which sends an SNMP Trap message when a variable being monitored exceeds a threshold. The example uses the PI IP Flow Interface and the PI Performance Equation Scheduler.

14

Installation ChecklistFor those users who are familiar with running PI data collection interface programs, the following checklist provides assistance for getting the Interface running. Those who are not familiar with PI interfaces should return to this section after reading the rest of the manual in detail.

1. If the PI Server is version 3.3.361.43 or higher, install the PI-ICU.

2. Install the PI-SDK and the PI-API. (Installation of the PI-ICU automatically installs these products.)

3. Confirm connectivity between this machine and the PI Server by running the apisnap and AboutPI-SDK programs.

4. Install the PI SNMPTrap program files by running the installation program.

5. Choose a point source for use by the Interface (–ps).

6. In preparation for digital points, create an appropriate digital state set.

7. The –bdp startup parameter tells the Interface itself to build points. Follow the rules below for building points manually:

For input points, the InstrumentTag specifies filtering conditions for trap messages. For output points, the InstrumentTag specifies the trap destination and enterprise OID.

For input points, the ExDesc specifies optional Regular Expression search and substitution strings. For output points, the ExDesc specifies the OID type and value.

Location1 specifies the interface identification number.

Location2 whether a point is input or output; if the former, it indicates the type of data to write to PI. (For output points, be sure to specify the –sio startup parameter later.)

Location3 (applicable only for points with Location2 equal to 0) indicates whether to write a normal status if no traps are received.

Location4 is not used and should be 0.

Location5 is used for debugging.

8. If desired, configure an I/O Rate point.

9. Configure the Interface to be used with the PI-ICU. Alternatively, edit the Interface startup command file (pisnmptrap.bat) using the supplied pisnmptrap.bat_new file as a template.

10. Modify the security of the PI Server. Edit the PI Trust or PI Proxy table as appropriate.

11. Stop the PI Buffer Server.

12. Interactively start the Interface.

13. On the device containing the SNMP Agent, generate some SNMP trap messages to be sent to the Interface.

14. Verify that data are correctly being written to the PI Server.


15. Stop the Interface and start the PI Buffer Server.

16. Start the Interface as service.

17. Verify that data are correctly being written to the PI Server.

18. Confirm that the Interface re-starts after a complete computer shutdown and restart.


Interface InstallationOSIsoft recommends that interfaces be installed on PI Interface Nodes instead of directly on the PI Server node. A PI Interface Node is any node other than the PI Server node where the PI Application Programming Interface (PI API) has been installed (see the PI API manual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. The primary function of the PI Server is to archive data and to service clients that request data.

After the interface has been installed and tested, Bufserv should be enabled on the PI Interface Node (once again, see the PI API manual). Bufserv is distributed with the PI API. It is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when communication to the PI Server is lost. Communication will be lost when there are network problems or when the PI Server is shut down for maintenance, upgrades, backups, or unexpected failures.

In most cases, interfaces on PI Interface Nodes should be installed as automatic services. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of an interruption in electrical power.

The guidelines are different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as an automatic service and install the interface as an automatic service that depends on the PI Update Manager and PI Network Manager services. Bufserv can be enabled on the PI Server node so that interfaces on the PI Server node do not need to be started and stopped in conjunction with PI, but it is not standard practice to enable buffering on the PI Server node. See the UniInt Interface User Manual for special procedural information.

Naming Conventions and RequirementsIn the installation procedure below, it is assumed that the name of the interface executable is pisnmptrap.exe and that the startup command file is called pisnmptrap.bat.

When Configuring the Interface ManuallyWhen an interface is configured as a Windows service, the executable file name (i.e., pisnmptrap.exe) and the command file (i.e., pisnmptrap.bat) must have the same root name (i.e., pisnmptrap). The reason is that at service startup, the interface executable (i.e., pisnmptrap.exe) looks specifically for startup parameters in a .bat file (i.e., pisnmptrap.bat) that has the same root name (i.e., pisnmptrap as the executable.

Thus, when manually configuring the interface and running multiple copies, the user needs to copy and rename both the executable and the startup command file. For example, copy pisnmptrap.exe so that pisnmptrap1.exe results and copy pisnmptrap.bat so that pisnmptrap1.bat results. Subsequently, pisnmptrap1.exe and pisnmptrap1.bat are typically used for interface instance number 1. Repeat the process so that pisnmptrap2.exe and pisnmptrap2.bat are used for interface instance number 2, and so on.


Interface Directories

PIHOME Directory TreeThe PIHOME directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file; it is located in the directory where Windows itself is installed.

A typical pipc.ini file contains the following lines:[PIPC]PIHOME=c:\Program Files\PIPC

The above lines define the \Program Files\PIPC directory as the root of the PIHOME directory tree on the C: drive.

OSIsoft recommends using \Program Files\PIPC as the root directory name. The PIHOME directory does not need to be on the C: drive.

Interface Installation DirectoryIf installing the interface manually, place all copies of the interface into a single directory. The suggested directory is:PIHOME\Interfaces\SNMPTrap\Replace PIHOME with the corresponding entry in the pipc.ini file.

Interface Installation ProcedureThe PI SNMPTrap Interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000 and greater operating systems. When running on Windows NT 4.0 systems, the PI SNMPTrap Interface setup program will install the Windows Installer itself if necessary. To install, run the installation kit executable (e.g., SNMPTrap_x.x.x.x.exe).

Installing Interface as a Windows ServiceThe PI SNMPTrap Interface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually.

Installing Interface Service with PI ICUThe PI Interface Configuration Utility provides a graphical user interface for creating, editing, and deleting the Interface as a Windows service. However, before the user can create the PI SNMPTrap Interface service, he first has to configure PI ICU to recognize the Interface.

From the PI ICU menu, select Interface, New Windows Interface from EXE, and then Browse to the PISNMPTrap.exe executable file. Select a PI Server from the Host PI System dropdown list box. Then, enter values for Point Source and Interface ID#. A window such as the following results:


A display such as the following should then appear:

Near the top of the PI ICU screen, the Interface Type should be snmptrap. If not, use the drop-down box to change the Interface Type to be snmptrap.


Interface Installation

To install the Interface as a service, click Service.

20

The above picture shows that this pisnmptrap1 service is dependent on the tcpip and pinetmgr (PI Network Manager) services.

Finally, click Create to create the interface service.

If the user wishes to remove the interface service, he should click Remove.

To start the PI SNMPTrap Interface service, click the start button ( ) located on the PI ICU toolbar.

When the PI SNMPTrap Interface service is currently running, the user can click the stop button ( ) to stop it.

Service Configuration

Service nameThe Service name box shows the name of the current interface service. This service name is obtained from the interface executable.

IDThis is the service id used to distinguish multiple instances of the same interface using the same executable.

Display nameThe Display Name text box shows the current Display Name of the interface service. If there is currently no service for the selected interface, the default Display Name is the service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft suggests that the prefix “PI-” be appended to the beginning of the interface to indicate that the service is part of the OSIsoft suite of products.

Log on asThe Log on as text box shows the current “Log on as” Windows User Account of the interface service. If the service is configured to use the Local System account, the Log on as text box will show “LocalSystem.” Users may specify a different Windows User account for the service to use.

PasswordIf a Windows User account is entered in the Log on as text box, then a password must be provided in the Password text box, unless the account requires no password.

Confirm PasswordIf a password is entered in the Password text box, then it must be confirmed in the Confirm Password text box.

Startup TypeThe Startup Type indicates whether the interface service will start automatically or needs to be started manually on reboot.

If the Auto option is selected, the service will be installed to start automatically when the machine reboots.


Interface Installation

If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.

Generally, interface services are set to start automatically.

DependenciesThe Installed services list is a list of the services currently installed on this machine. Services upon which this Interface is dependent should be moved into the Dependencies

list using the button. For example, if PI API Buffering is running, then “bufserv” should be selected from the list at the right and added to the list on the left. To remove a

service from the list of dependencies, use the button, and the service name will be removed from the “Dependencies” list.

When the PI Interface is started (as a service), the services listed in the dependency list will be verified as running (or an attempt will be made to start them). If the dependent service(s) cannot be started for any reason, then the PI interface service will not run.

Note: Please see the PI Log and Operating System Event Logger for messages that may indicate the cause for any server not running as expected.

- Add ButtonTo add a dependency from the list of Installed services, select the dependency name, and click the Add button.

- Remove ButtonTo remove a selected dependency, highlight the service name in the Dependencies list, and click the Remove button.

The full name of the service selected in the Installed services list is displayed below the Installed services list box.

CreateThe Create button adds the displayed service with the specified Dependencies and with the specified Startup Type.

Remove The Remove button removes the displayed service. If the service is not currently installed, or if the service is currently running, this button will be grayed out.

22

Start or Stop ServiceTo Start or Stop an interface service, use the Start button and a Stop button on the ICU toolbar. If this interface service is not currently installed, these buttons will remain grayed out until the service is added. If this interface service is running, the Stop button is available. If this service is not running, the Start button is available.

The status of the Interface service is indicated in the lower portion of the PI ICU dialog.

Installing Interface Service ManuallyHelp for installing the interface as a service is available at any time with the command:pisnmptrap.exe –help

Change to the directory where the pisnmptrap.exe executable is located. Then, consult the following table to determine the appropriate service installation command.

Windows Service Installation Commands on a PI Interface Node or a PI Server Nodewith Bufserv implemented

Manual service pisnmptrap.exe –install –depend “tcpip bufserv”

Automatic service pisnmptrap.exe –install –auto –depend “tcpip bufserv”

*Automatic service with service id

pisnmptrap.exe –serviceid X –install –auto –depend “tcpip bufserv”

Windows Service Installation Commands on a PI Interface Node or a PI Server Nodewithout Bufserv implemented

Manual service pisnmptrap.exe –install –depend tcpip

Automatic service pisnmptrap.exe –install –auto –depend tcpip

*Automatic service with service id

pisnmptrap.exe –serviceid X –install –auto –depend tcpip

*When specifying service id, the user must include an id number. It is suggested that this number correspond to the interface id (-id) parameter found in the interface .bat file.

Check the Microsoft Windows services control panel to verify that the service was added successfully. The services control panel can be used at any time to change the interface from an automatic service to a manual service or vice versa.


Status of the ICU Status of the

Interface Service

Service installed or uninstalled

Digital StatesFor more information regarding Digital States, refer to the PI Server documentation.

Digital State SetsPI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Server manuals.

An interface point that contains discrete data can be stored in PI as a digital tag. A Digital tag associates discrete data with a digital state set, as specified by the user.

At startup, if the Interface does not find a digital state set named SNMPTrapIntf, it will create it. This digital state set contains enumerations for the generic trap types offset by one. Specifically,

Digital state ValuenoTrap 0

coldStart 1

warmStart 2

linkDown 3

linkup 4

authenFail 5

egpLoss 6

entSpecific 7

If the PI Server already has a Digital State Set named SNMPTrapIntf, the Interface does not try to modify it.

System Digital State SetSimilar to digital state sets is the system digital state set. This set is used for all tags, regardless of point type, to indicate the state of a tag at a particular time. For example, if the interface receives bad data from an interface point, it writes the system digital state Bad Input to PI instead of a value. The system digital state set has many unused states that can be used by the interface and other PI clients.


PointSource The PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For example, the string SNMPTrap may be used to identify points that belong to the PI SNMPTrap Interface. To implement this identification, the user would set the PointSource attribute to SNMPTrap for every PI Point that is configured for the PI SNMPTrap Interface. Then, if -ps=SNMPTrap is used on the startup command-line of the PI SNMP Trap Interface, the Interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of SNMPTrap. Before an interface loads a point, the interface usually performs further checks by examining additional PI point attributes to determine whether a particular point is valid for the interface. For additional information, see the -ps startup command parameter.

Case-sensitivity for PointSource AttributeThe case of the PointSource character point attribute is not significant.

In addition, the PointSource character that is supplied with the -ps command-line parameter is not case sensitive. That is, -ps=N and -ps=n are equivalent.

Reserved Point SourcesSeveral subsystems and applications that ship with PI are associated with default PointSource characters. The Totalizer Subsystem uses the PointSource character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Do not use these PointSource characters or change the default point source characters for these applications. Also, if a PointSource character is not explicitly defined when creating a PI point; the point is assigned a default PointSource character of Lab. Therefore, it would be confusing to use Lab as the PointSource character for an interface.

Note: Do not use a point source character that is already associated with another interface program. However it is acceptable to use the same point source for multiple instances of an interface.


PI Point ConfigurationThe PI point is the basic building block for controlling data flow to and from the PI Server. A single point is configured for each value that needs to be archived.

Every two minutes, PI SNMPTrap checks the PI Server for changes to PI points whose PointSource is associated with the Interface. The Interface automatically incorporates these changes into its point list.

However, PI SNMPTrap can process only 25 point changes every 30 seconds. If more than 25 points are added, edited, or deleted, PI SNMPTrap will process the first 25 points, wait 30 seconds, process the next 25 points, and so on. As soon as the Interface has processed all point changes, it will resume checking for point updates every two minutes.

Point AttributesUse the point attributes below to define

which SNMP Trap messages to process, and

the value that the Interface writes to a particular PI point

TagA tag is a label or name for a point. Any tag name can be used in accordance with the normal PI point naming conventions.

PI System documentation often uses the terms tag and point synonymously.

LengthFor many OSIsoft interfaces, the length of the Tag field is limited by the version of the PI API, and the version of the PI Server. However, the PI SNMP Trap Interface uses the PI SDK (if necessary) to retrieve tagnames. Thus, the maximum length of this field is 1023, independent of the versions of the PI API or PI Server.

PI API PI Server Maximum Length

1.6 or higher 3.4.370.x or higher 1023

1.6 or higher Below 3.4.370.x 1023

Below 1.6 3.4.370.x or higher 1023

Below 1.6 Below 3.4.370.x 1023

PointSourceThe PointSource is a unique character or character string that is used to identify the PI point as a point that belongs to a particular interface. For additional information, see the -ps command-line parameter and the “Point Source” section.


PointTypePI SNMPTrap supports the following PI 3.x point types: Digital Int16 Int32 Float16 Float32 Float64 StringFor more information on these point types, see the PI Server manual.

Location1The Location1 attribute associates a point with a particular copy of PI SNMPTrap. Location1 is a positive integer. Its value is equal to the -id= parameter used in the startup command file (described later).

For example, if -id=1 then Location1 should be set to 1.

Location2To indicate that a point is an output point set Location2 to -6.

For an input point, Location2 indicates the type of value that the Interface will write to the point. The following table summarizes the acceptable values for Location2.

Location2 Value type-6 Location2 equal to -6 indicates that the point is an output point

0 generic trap type value, offset by 1

1 generic trap type value

2 specific trap type value

3 IP address or hostname of SNMP Agent

4 enterprise identifier

5 link number when generic trap type is Link Up or Link Down

6 value of an OID within enterprise specific trap variables

100 link description when a Cisco device sends a generic trap type of Link Up or Link Down

101 link type when a Cisco device sends a generic trap type of Link Up or Link Down

102 reason for status change of a link when a Cisco device sends a generic trap type of Link Up or Link Down


Location2 = 0If Location2 is 0, the Interface writes the value of the generic trap type, offset by 1. For example, for the trap message:Agent address: 192.168.8.72

Enterprise: 1.3.6.1.4.311.1.1.3.1.1



the Interface writes a value of 1, which is 0 (cold start) plus the offset of 1.

Location2 = 1If Location2 is 1, the Interface writes the value of the generic trap type. For example, for the trap message:Agent address: 192.168.8.72

Enterprise: 1.3.6.1.4.311.1.1.3.1.1



the Interface writes a value of 0, which corresponds to cold start.

Location2 = 2If Location2 is 2, the Interface writes the value of the specific trap type. For example, for the trap message:Agent address: 192.168.10.8

Enterprise: 1.3.6.1.4.1.1200.8.7.6




Value of OID1: 3


Value of OID2: 81

the Interface writes a value of 1.

Location2 = 3If Location2 is 3, the Interface writes the IP address or hostname of the SNMP Agent. For example, for the trap message:Agent address: 192.168.8.72

Enterprise: 1.3.6.1.4.311.1.1.3.1.1



the Interface writes a value of “192.168.8.72”.


PI Point Configuration

However, if the Interface runs with the –resolve startup command parameter, PI SNMPTrap writes the host name that corresponds to the IP address of the SNMP Agent.

Location2 = 4If Location2 is 4, the Interface writes the value of the enterprise identifier. For example, for the trap message:Agent address: 192.168.8.72

Enterprise: 1.3.6.1.4.311.1.1.3.1.1



the Interface writes a value of “1.3.6.1.4.311.1.1.3.1.1”.

Location2 = 5If Location2 is 5, the Interface writes the link number contained within a Link Up or Link Down trap messages. For example, for the trap message:Agent address: 192.168.10.100

Enterprise: 1.3.6.1.4.311.1.1.3.1.1



OID 1: 1.3.6.1.2.1.2.2.1.1.2

Value of OID 1: 2 (link 2 is the link in question)

the Interface writes a value of 2.

Location2 = 6If Location2 is 6, the Interface writes the value of an OID within an enterprise-specific trap. For example, for the trap message:Agent address: 192.168.10.8

Enterprise: 1.3.6.1.4.1.1200.8.7.6




Value of OID1: 3


Value of OID2: 81

the Interface writes a value of either 3 or 81, depending on the filtering conditions as indicated in the InstrumentTag attribute.

If the value of an OID within an enterprise-specific trap is a string, the user can tell the Interface to store only a portion of the string. For example, for the following example trap message:Agent address: 192.168.10.8

32

Enterprise: 1.3.6.1.4.1.100.3.4.5


Specific trap type: 2 (warning from device)

OID1: 1.3.6.1.4.1.100.3.4.5.1 (warning message)

Value of OID1: The temperature is now 213.

the goal is to store the word temperature in a PI string point and the number 213 in a numeric point.

If the value of OID1 is consistently in the formatThe <measurement> is now <value of measurement>.

the user can use Regular Expressions and Substitutions to parse out the actual <measurement> and <value for measurement>. That is, for the string point, the point’s Extended Descriptor attribute should contain:

RegExp=The\s(\w*)\sis\snow\s(\d*)\.; Sub=$1;

(The above tells the Interface to write temperature into a PI string point.)

For the numeric point, the following should be in the Extended Descriptor attribute:RegExp=The\s(\w*)\sis\snow\s(\d*)\.; Sub=$2;

(The above tells the Interface to write 213 into a PI numeric point.)

Note that a semicolon indicates the end of the RegExp expression. Similarly, a semicolon terminates the Sub expression.

Please see the Regular Expressions Tutorial (included with the interface distribution) for more information on using Regular Expressions.

Location2 = 100

Location2 = 101

Location2 = 102Cisco Systems has redefined some of the generic trap messages such that they provide additional information in the OID variables. For example, a Cisco device may send the following Link Up message:Agent address: 192.168.10.8

Enterprise: 1.3.6.1.4.1.9.1.45

Trap type: 3 (Link Up)


OID1: 1.3.6.1.2.1.2.2.1.1.23

Value of OID1: 23 (link 23 is the link in question)

OID2: 1.3.6.1.2.1.2.2.1.2.23

Value of OID2: Loopback1 (link description)

OID3: 1.3.6.1.2.1.2.2.1.3.23

Value of OID3: 24 (link type)



OID4: 1.3.6.1.4.1.9.2.2.1.1.20.23

Value of OID4: up (reason for link status change)

Depending on the value of Location2, the Interface writes the following values:

Point Location2 Valuelink_description 100 Loopback1

link_type 101 24

link_change_reason 102 Up

However, not all Cisco devices support the sending of Link Description, Link Type, and Reason for Link Status change.

If the goal is for the Interface to write the value of 23 (i.e., the link number), set Location2 to 5.

Location3For points with Location2 set to 0, the Location3 attribute indicates whether the Interface will write a value of 0 (to indicate normal status) if a point does not receive a trap value within a certain number of seconds. The value of Location3 represents the number of seconds, after which the Interface does not receive a trap for a point, that PI SNMPTrap writes a value of 0. For example, a point named link_traps has attributes as follows:

Attribute ValueLocation2 0

Location3 10

InstrumentTag GT=2,3; DEVICE=*; ENT=*;

The Interface receives the following trap message at 11:00:00:Agent address: 192.168.10.100

Enterprise: 1.3.6.1.4.311.1.1.3.1.1



OID 1: 1.3.6.1.2.1.2.2.1.1.2

Value of OID 1: 2 (link 2 is the link in question)

The Interface does not receive any link up or link down traps between 11:00:00 and 11:00:10. The Interface writes the following to link_traps:

Timestamp Value stored in PI11:00:00 4, which is 3 plus 1

11:00:10 0, which represents normal status

34

If Location3 is 0, the Interface does not write a 0 value to indicate normal status.

For points with Location2 not equal to 0, the Interface ignores the value of Location3.

Location4The Interface does not currently use Location4. However, this attribute should be zero to accommodate future enhancements.

Location5Location5 causes the Interface to log debugging messages. For normal operations, Location5 should be zero. However, during a first time installation of PI SNMPTrap or the investigation of anomalous behavior, the user may wish to set Location5 to a non-zero value. See the Troubleshooting section of this manual for details.

InstrumentTag

LengthFor many OSIsoft interfaces, the length of the InstrumentTag field is limited by the version of the PI API and the version of the PI Server. However, the PI SNMP Trap Interface uses the PI SDK (if necessary) to retrieve a point's IntstrumentTag. Thus, the maximum length of this field is 1023, independent of the versions of the PI API or PI Server.





Below 1.6 Below 3.4.370.x 1023

The Instrument Tag attribute specifies filtering conditions so that the Interface knows which trap messages should be processed for a given point. The user provides filtering conditions via keywords and values.

A semicolon terminates each keyword-value pair. For example, KEYWORD1=VALUE1; KEYWORD2=VALUE2;

The Interface uses the following keywords: DEVICE

ENT

GT

ST

OID

MULTI_OID

Keywords are case insensitive. That is,



DEVICE=192.168.100.1;

is the same as device=192.168.100.1;

DEVICEThe DEVICE keyword specifies the IP address of an SNMP Agent. The user can use the asterisk character for all IP addresses, or he may specify a range of addresses via CIDR (Classless Inter-Domain Routing) notation. For example, the user has the following points configured:

Point InstrumentTag Location2router1_traps DEVICE=192.168.10.1; ENT=*;

GT=0,1,2,3,4,5,6;0

workstation_traps DEVICE=192.168.10.11/30; ENT=*; GT=0,1,2,3,4,5,6;

0

all_traps DEVICE=*; ENT=*; GT=0,1,2,3,4,5,6;

0

(Note that 192.168.10.11/30 is CIDR notation for

192.168.10.11

192.168.10.12

192.168.10.13

192.168.10.14

For those who are unfamiliar with CIDR notation, a section in this manual titled “Additional Operational Information” provides a quick tutorial.)

The Interface receives the following trap: Agent address: 192.168.10.1

Enterprise: 1.3.6.1.4.311.1.1.3.1.1



Because Location2 is 0, the Interface writes the following values to the following 2 points:

Point Valuerouter1_traps 1

all_traps 1

The Interface does not write a value to the point named workstation_traps because the value of the Agent address within the received trap message does not fulfill the filtering condition specified via DEVICE=.

36

ENTThe ENT keyword indicates the value of the enterprise identifier contained within a trap message. The asterisk character serves as a wildcard matching specification. For example, the user has the following points configured:

Point InstrumentTag Location2cisco_traps ENT=1.3.6.1.4.1.9.*; DEVICE=*;

GT=0,1,2,3,4,5,6;0

workstation_traps ENT=1.3.6.1.4.1.311.1.1.3.1.1; DEVICE=*; GT=0,1,2,3,4,5,6;

0

all_traps ENT=*; DEVICE=*; GT=0,1,2,3,4,5,6;

0


Enterprise: 1.3.6.1.4.311.1.1.3.1.1




Point Valueworkstation_traps 1

all_traps 1

The Interface does not write a value to the point named cisco_traps because the value of the Enterprise specification within the received trap message does not fulfill the filtering condition specified via ENT=.

GTThe GT keyword indicates the value of the generic trap type contained within the trap message. Generic trap types range from 0 (cold start trap) to 6 (enterprise specific trap). A comma separates multiple numbers. The asterisk character indicates that a point will match all generic trap type values. For example, the user has the following points configured:

Point InstrumentTag Location2linkDownUp_traps GT=2,3; DEVICE=*; ENT=*; 0

start_traps GT=0,1; DEVICE=*; ENT=*; 0

all_traps GT=0,1,2,3,4,5,6; DEVICE=*; ENT=*;

0

The Interface receives the following trap:




Enterprise: 1.3.6.1.4.311.1.1.3.1.1




Point Valuestart_traps 1

all_traps 1

The Interface does not write a value to the point named linkDownUp_traps because the value of the generic trap specification within the received trap message does not fulfill the filtering condition specified via GT=.

STThe ST keyword indicates the value of the specific trap type contained within the trap message. A comma separates multiple numbers. The asterisk character indicates that a point will match all specific trap type values. For example, the user has the following points configured:

Point InstrumentTag Location2Temperature_traps ST=1; GT=6; DEVICE=*;

ENT=1.3.6.1.4.1.1200.8.7.6;3

humidity_traps ST=2; GT=6; DEVICE=*; ENT=1.3.6.1.4.1.1200.8.7.6;

3

all_traps ST=*; GT=6; DEVICE=*; ENT=1.3.6.1.4.1.1200.8.7.6;

3


Enterprise: 1.3.6.1.4.1.1200.8.7.6




Value of OID1: 3


Value of OID2: 81


38

Point ValueTemperature_traps 192.168.10.8

all_traps 192.168.10.8

The Interface does not write a value to the point named humidity_traps because the specific trap type value within the received trap message does not fulfill the filtering condition specified via ST=.

OIDThe OID keyword indicates an OID specification contained within the trap message. The asterisk character serves as a wildcard matching specification. For example, the user has the following points configured:

Point InstrumentTag Location2sensor_number ST=1; GT=6; DEVICE=*;

ENT=1.3.6.1.4.1.1200.8.7.6; OID=1.3.6.1.4.1.1200.8.7.6.1;

6

temperature ST=1; GT=6; DEVICE=*; ENT=1.3.6.1.4.1.1200.8.7.6; OID=1.3.6.1.4.1.1200.8.7.6.2;

6


Enterprise: 1.3.6.1.4.1.1200.8.7.6




Value of OID1: 3


Value of OID2: 81


Point Valuesensor_number 3

Temperature 81

For points with a wildcard matching specification, the Interface writes the value of the first matching OID. For example, the user has the following point configured:

Point InstrumentTag Location2



Trapvalue ST=1; GT=6; DEVICE=*; ENT=1.3.6.1.4.1.1200.8.7.6; OID=1.3.6.1.4.1.1200.8.7.6.*;

6


Enterprise: 1.3.6.1.4.1.1200.8.7.6




Value of OID1: 3


Value of OID2: 81

The Interface writes the value of 3 (corresponding to the value of OID1) to the point named trapvalue. If the user wants to store the values corresponding to both OID1 and OID2, he must configure two separate points as indicated in the previous example.

MULTI_OIDThe MULTI_OID keyword is valid only for points with Location2 equal to 6. It indicates whether the Interface writes multiple OID variable binding values to a single point configured with a wildcard matching specification. For example, the user has the following point configured:

Point InstrumentTag Location2Trapvalue ST=1; GT=6; DEVICE=*;

MULTI_OID=1; ENT=1.3.6.1.4.1.1200.8.7.6; OID=1.3.6.1.4.1.1200.8.7.6.*;

6


Enterprise: 1.3.6.1.4.1.1200.8.7.6




Value of OID1: 3


Value of OID2: 81

The Interface writes the values of 3 (corresponding to the value of OID1) and 81 (corresponding to the value of OID2) to the point named trapvalue. The time difference between these 2 values is 16 microseconds (0.000016 seconds); for example:

40

Point Timestamp ValueTrapvalue 28-Jun-2005 10:11:15.623959 3

Trapvalue 28-Jun-2005 10:11:15.623975 81

If the user does not specify the MULTI_OID keyword, the default behavior is as if MULTI_OID=0. That is, the Interface writes the value of the first matching OID.

Required KeywordsSome keywords are required and some are optional.

Keyword Required? Default valueDEVICE Yes <not applicable>

ENT Yes <not applicable>

GT Yes <not applicable>

ST No 0

OID No *

MULTI_OID No 0

Determining OID specificationsTo find out the appropriate values for ENT and OID, the user should use a MIB browser and load the MIB file supplied by the device vendor. OSIsoft’s PI-SNMP Tag Configurator can also load MIB files and display OID specifications.

To confirm the values of OIDs, the user can run the Interface with the -dbg startup parameter. PI-SNMPTrap will then display the values of ENT and OID for traps received. See the Troubleshooting section for more information.

ExDesc

LengthFor many OSIsoft interfaces, the length of the Extended Descriptor field is limited by the version of the PI API and the version of the PI Server. However, the PI SNMP Trap Interface uses the PI SDK (if necessary) to retrieve a point's Extended Descriptor. Thus, the maximum length of this field is 1023, independent of the versions of the PI API or PI Server.





Below 1.6 Below 3.4.370.x 1023



Input PointFor an input point, the Extended Descriptor holds Regular Expression and Substitution parsing specifications. For example, ExDesc may contain:RegExp=The\s(\w*)\sis\snow\s(\d*)\.; Sub=$1;

Note that a semicolon indicates the end of the RegExp expression. Similarly, a semicolon terminates the Sub expression.

However, the Interface uses these specifications only when the value of an OID within an enterprise-specific trap is a string. Please see the description on the Location2 attribute for more information.

When the Interface fails to match the Regular Expression and/or Substitution specifications, it writes Bad Input to the point. To indicate that the Interface should not write Bad Input to the point under these conditions, add

RegExpFailed=0;to the Extended Descriptor. That is, RegExp=The\s(\w*)\sis\snow\s(\d*)\.; Sub=$1; RegExpFailed=0;

Output PointFor an output point, the Extended Descriptor holds a list of OIDs, OID variable types, and OID values. The keywords aren_OID

n_OIDT

n_OIDV

where "n" is a positive integer representing the ordinal number of the OID/OID variable type/OID variable value.

n_OID specifies an OID such as .1.3.6.1.4.1.23257.1.100.1

n_OIDT specifies the OID variable type; acceptable values are S for String and I for Integer.

n_OIDV specifies the OID value.

For example, a user wishes to send the following SNMP Trap to a device at IP address 192.168.8.100:Enterprise: 1.3.6.1.4.1.1200.8.7.6



First OID: 1.3.6.1.4.1.1200.8.7.6.1 (sensor number)

Value of first OID: 3

Second OID: 1.3.6.1.4.1.1200.8.7.6.2 (temperature in degrees F)

Value of second OID: 81

He configures the following in the Extended Descriptor:1_OID=.1.3.6.1.4.1.1200.8.7.6.1; 1_OIDT=I; 2_OIDV=3; 2_OID=.1.3.6.1.4.1.1200.8.7.6.2; 2_OIDT=I; 2_OIDV=81;

42

If the user omits n_OIDT, the Interface uses the PointType of the output PI point itself. That is,

PI PointType n_OIDT OID data typeString S String

Digital S String

IntXX I Integer

FloatXX I Integer

If the user omits n_OIDV, the Interface uses value of the output point's source tag as the value of the OID within the SNMP Trap message. If the output point does not have a source tag, then the Interface uses the value of the output point itself.

ConversionThe Interface uses the Conversion attribute as a multiplier.

Scan The Scan attribute has the default value of 1, indicating that the Interface should collect data for the point. Setting the Scan attribute to 0 turns data collection off. If the Scan attribute is 0 when the interface starts, the Interface writes SCAN OFF to the point. If the user changes the Scan attribute from 1 to 0 while the interface is running, the Interface also writes SCAN OFF.

There is one other situation, which is independent of the Scan attribute, where UniInt will write SCAN OFF to a PI point. If a point that is currently loaded by the interface is edited so that the point is no longer valid for the interface, the point will be removed from the interface, and SCAN OFF will be written to the point. For example, if the PointSource of a PI point that is currently loaded by the interface is changed, the point will be removed from the interface and SCAN OFF will be written to the point.

ShutdownThe Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Server manuals.

Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are independent of the SHUTDOWN events that are written by the interface when the -stopstat=Shutdown command-line parameter is specified.

SHUTDOWN events can be disabled from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, the default behavior of the PI Shutdown Subsystem can be changed to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the \PI\dat\Shutdown.dat file, as discussed in PI Server manuals.



Bufserv It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when the Server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shut down, Bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface.

Output Points Output points have Location2 set to -6.

Outputs are triggered for UniInt-based interfaces. That is, outputs are not scheduled to occur on a periodic basis. There are two mechanisms for triggering an output.

Trigger Method 1 (Recommended)For trigger method 1, a separate trigger point must be configured. The output point must have the same point source as the interface. The trigger point can be associated with any point source, including the point source of the interface. Also, the point type of the trigger point does not need to be the same as the point type of the output point.

The output point is associated with the trigger point by setting the SourceTag attribute of the output point equal to the tag name of the trigger point. An output is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous value that was sent to the Snapshot to trigger an output, but the timestamp of the new value must be more recent than the previous value. If no error is indicated, then the value that was sent to the trigger point is also written to the output point. If the output is unsuccessful, then an appropriate digital state that is indicative of the failure is usually written to the output point. If an error is not indicated, the output still may not have succeeded because the interface may not be able to tell with certainty that an output has failed.

Trigger Method 2For trigger method 2, a separate trigger point is not configured. To trigger an output, write a new value to the Snapshot of the output point itself. The new value does not need to be different than the previous value to trigger an output, but the timestamp of the new value must be more recent than the previous value.

Trigger method 2 may be easier to configure than trigger method 1, but trigger method 2 has a significant disadvantage. If the output is unsuccessful, there is no tag to receive a digital state that is indicative of the failure, which is very important for troubleshooting.

Exception SpecificationsBecause a trap message is an anomalous event, OSIsoft strongly recommends that the Interface runs such that it bypasses exception reporting. That is, PI SNMPTrap should run with the –sn startup parameter (described later) so that it ignores these point attributes:

exception deviation

exception minimum time

44

exception maximum time

Other AttributesThe Archiving point attribute is not unique to PI SNMPTrap but is required for proper operation. Consult the PI Server manuals for a detailed explanation.

Default PointsThe user can configure the PI SNMPTrap Interface such that every time it runs, it builds the following points:

Tagname Attribute ValueST_startTraps_trend Location2 0 (generic trap value,

offset by 1)

Location3 60

InstrumentTag DEVICE=*; ENT=*; GT=0,1; ST=0;

PointType Digital

DigitalSet SNMPTrapIntf

ST_startTraps Location2 0 (generic trap value, offset by 1)

Location3 0


PointType Digital


ST_startTraps_device Location2 3 (IP address or hostname of SNMP Agent)


PointType String

ST_entTraps_trend Location2 0 (generic trap value, offset by 1)

Location3 60

InstrumentTag DEVICE=*; ENT=*; GT=6; ST=*;

PointType Digital


ST_entTraps Location2 0 (generic trap value, offset by 1)

Location3 0



Tagname Attribute ValueInstrumentTag DEVICE=*; ENT=*; GT=6;

ST=*;

PointType Digital


ST_entTraps_device Location2 3 (IP address or hostname of SNMP Agent)


PointType String

ST_entTraps_spec Location2 2 (specific trap value)


PointType Int32

ST_linkTraps_trend Location2 0 (generic trap value, offset by 1)

Location3 60

IntrumentTag DEVICE=*; ENT=*; GT=2,3; ST=0;

PointType Digital


ST_linkTraps Location2 0 (generic trap value, offset by 1)

Location3 0


PointType Digital


ST_linkTraps_device Location2 3 (IP address or hostname of SNMP Agent)


PointType String

ST_linkTraps_interface Location2 5 (link number)


PointType Int32

46

Tagname Attribute ValueST_AF_egpLoss_Traps_trend Location2 0 (generic trap value,

offset by 1)

Location3 60


PointType Digital


ST_AF_egpLoss_Traps Location2 0 (generic trap value, offset by 1)

Location3 0


PointType Digital


ST_AF_egpLoss_device Location2 3 (IP address or hostname of SNMP Agent)


PointType String

The points ST_startTraps_trend, ST_startTraps, and ST_startTraps_device record information regarding cold start and warm start traps. Values for ST_startTraps_trend are suitable for trending because the Interface writes a zero value (to indicate normal status) if no such traps are received after 60 seconds.

The points ST_entTraps_trend, ST_entTraps, ST_entTraps_device, and ST_entTraps_spec record information regarding enterprise specific traps. Values for ST_entTraps_trend are suitable for trending because the Interface writes a zero value (to indicate normal status) if no such traps are received after 60 seconds.

The points ST_linkTraps_trend, ST_linkTraps, ST_linkTraps_device, and ST_linkTraps_interface record information regarding link up and link down traps. Values for ST_linkTraps_trend are suitable for trending because the Interface writes a zero value (to indicate normal status) if no such traps are received after 60 seconds.

The points ST_ AF_egpLoss_Traps_trend, ST_ AF_egpLoss_Traps, and ST_ AF_egpLoss_Traps_device record information regarding EGP loss and authentication failure traps. Values for ST_ AF_egpLoss_Traps_trend are suitable for trending because the Interface writes a zero value (to indicate normal status) if no such traps are received after 60 seconds.

Thus, unlike most other OSIsoft interface programs, PI SNMPTrap does not require that the user manually build points before it can start collecting data. That is, PI SNMPTrap can automatically build the above points and write values to them.



-bdpIf the user wishes PI SNMPTraps to run with the above default points, he should use the -bdp ("build default points") parameter on the startup command line. (Command line parameters are described in a later section of this manual.)

When a user manually modifies the point attributes for the above points, he should make sure not to use the –bdp startup command parameter. Otherwise, during startup the Interface will overwrite the modifications.

48

Performance Point ConfigurationThis Interface does not support Performance Points.


I/O Rate Point ConfigurationAn I/O Rate point measures the throughput of an interface. In particular, the value of an I/O Rate point represents a 10-minute average of the total number of values per minute that the Interface sends to the PI Server. Because values are averaged over a 10-minute interval, the first calculated value is not written to the PI Server until 10 minutes after the Interface has started. The user can configure one I/O Rate tag for each copy of the Interface that is in use.

Monitoring I/O Rates on the Interface NodeBecause an I/O Rate point is a PI point, the user can run standard PI client applications to monitor its value. For example, the user can use PI ProcessBook to build and view a trend that displays the most recent 8-hour values for an I/O Rate point.

Configuring I/O Rate Tags with PI ICU (Windows)The PI Interface Configuration Utility (PI ICU) provides a graphical user interface for creating and managing I/O Rates points. Click the IORates section:

PI-ICU currently allows for one I/O Rate point to be configured for each copy of the Interface that is in use.

Enable IORates for this InterfaceThe Enable IORates for this interface check box enables or disables I/O Rates for the current interface. To disable I/O Rates for the selected interface, uncheck this box. To enable I/O Rates for the selected interface, check this box.

Tag StatusThe Tag Status column indicates whether the I/O Rate tag exists in PI. The possible states are:

Created – This status indicates that the tag exist in PI

Not Created – This status indicates that the tag does not yet exist in PI


Deleted – This status indicates that the tag has just been deleted

Unknown – This status indicates that the PI ICU is not able to access the PI Server

In FileThe In File column indicates whether the I/O Rate tag listed in the tag name and the event counter is in the IORates.dat file. The possible states are:

Yes – This status indicates that the tag name and event counter are in the IORates.dat file

No – This status indicates that the tag name and event counter are not in the IORates.dat file

Event CounterThe Event Counter correlates a tag specified in the iorates.dat file with this copy of the interface. The command-line equivalent is /ec=x, where x is the same number that is assigned to a tag name in the iorates.dat file.

TagnameThe tag name listed under the Tagname column is the name of the I/O Rate tag.

SnapshotThe Snapshot column holds the snapshot value of the I/O Rate tag, if the I/O Rate tag exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is clicked, and when the Interface is first loaded.

Right Mouse Button Menu OptionsCreateCreate the suggested I/O Rate tag with the tag name indicated in the Tagname column.

DeleteDelete the I/O Rate tag listed in the Tagname column.

RenameAllow the user to specify a new name for the I/O Rate tag listed in the Tagname column.

Add to FileAdd the tag to the IORates.dat file with the event counter listed in the Event Counter Column.

SearchAllow the user to search the PI Server for a previously defined I/O Rate tag.

Configuring I/O Rate Tags ManuallyThere are two configuration steps.


1. Configuring the PI Point on the PI Server

2. Configuration on the Interface Node

Configuring PI Point on the PI ServerCreate an I/O Rate Tag with the following point attribute values.

Attribute Value

PointSource L

PointType float32

Compressing 0

ExcDev 0

Configuration on the Interface NodeThe following procedure for I/O Rate point configuration on the interface node assumes that the tag name of this point is sysnmptrap01. With respect to I/O Rate point configuration, an interface node is the computer on which the Interface runs.

1. Edit or create the file named iorates.dat in the dat subdirectory of the directory where the PI API was installed. To find out the name of this PI API directory, look at the pipc.ini file located in the Windows directory (typically, C:\WinNT or C:\Windows). The pipc.ini file contains an entry for PIHOME and PIPCSHARE. The PI API directory is given either by the value for PIPCSHARE (if both PIHOME and PIPCSHARE exist in pipc.ini) or by the value for PIHOME (if only PIHOME exists).

Because PIHOME is typically C:\program files\PIPC, the full name of the iorates.dat file is typically C:\program files\PIPC\dat\iorates.dat.

In the iorates.dat file, add the tag name of the I/O Rate point; followed by a comma; and finally, followed by a number between 2 and 34 or between 51 and 200, inclusive. For example:sysnmptrap01,11

2. Set the value for the -ec parameter in the Interface’s startup command file (described later) to be the same number as that entered in the iorates.dat file. For the above example,pisnmptrap.exe –ec=11 ...

Because the Interface’s startup command file has changed, the user needs to stop and restart the Interface in order for these changes to take effect.


Startup Command FileCommand-line parameters can begin with a / or with a -. For example, the /ps=M and –ps=M command-line parameters are equivalent.

Configuring the Interface with PI ICUOn Windows, the PI Interface Configuration Utility (PI ICU) is a graphical tool that allows a user to configure the Interface’s startup command file. OSIsoft strongly recommends that the user run the PI ICU to configure and maintain the Interface's startup command file.

When running the PI ICU, the user should make sure that "snmptrap" is selected for the Type of interface. That is,

OSIsoft recommends that the user configure this Interface to

bypass exception, and write the digital state "Intf Shut" at interface shutdown.

In addition, output points require that "Suppress initial outputs" be selected. So, PI ICU’s Uniint tab should look like the following:


General ParametersBy default, the Interface receives traps on the standard SNMP trap port number of 162. To use a different port number, check the Port for receiving traps box and enter in the appropriate number. For example, to use port 7000:

By default, the Interface has an internal queue size of 100,000. To use a different size, check the Maximum internal queue size box and enter in an appropriate number. If no value is specified this parameter, the Interface uses a size of 100,000. See the section Data Records and Record Processing (in the Chapter titled Additional Operational Information) for more information.


For points with Location2 equal to 3, the Interface writes the IP address of the SNMP Agent to the PI point. To translate this IP address to a hostname, click the Resolve IP address to hostname box:

For points with Location2 equal to 6, when the Interface receives an OID value that is itself an OID, it writes this value without a leading dot. For example,1.3.6.1.2.1.2.2.1.3

To tell the Interface to write this OID value with a leading dot (i.e., .1.3.6.1.2.1.2.2.1.3), check the Write OIDs so that they have a leading dot box.

Source Tag for Ouput – System Digital State BehaviorAs with all UniInt-based interfaces, PI SNMPTrap attempts to send an output when either the output point's source tag or the output point itself receives a new value. However, if this new value is a member of the system digital state set (e.g., Calc Failed), then the Interface does not send a SNMP Trap. Instead, if the output point has


Startup Command File

a source tag, the Interface writes Bad Output to the output point. (If the output point does not have a source tag, the Interface does not write Bad Output to it.)

However, if an output point's source tag's snapshot value is Filtered (system digital state number 244), then the Interface does not write Bad Output to the output point. The preceding describes the interface's behavior when the following option is selected:

If the Filtered digital state is not appropriate, choose the second option button and pick a digital state from the drop down list box:

To indicate that the Interface should write Bad Output when the snapshot value of the source tag is any digital state, choose the third option button:

Point BuildingTo tell the Interface to build points at startup so that it can immediately start collecting data, select either the Build points at startup or Build points at startup with debug enabled option button. The former builds points with Location5 set to 0 while the

58

latter with Location5 set to 3. (See the Troubleshooting section for information on Location5.)

Debugging ParametersTo tell the Interface to print the details of every trap message that it receives, check the Log details of traps received box. See the Troubleshooting section for information.

To tell the Interface not to write values to PI Server, check the Do not write values to PI Server box. This option is most useful when the user also selects Log details of traps received and Build points at startup with debug enabled.

Manual Maintenance of the Startup Command FileFor proper operation, the Interface requires various command-line parameters. The user should put these parameters, along with the name of the Interface executable, into a startup command file. For example,pisnmptrap.exe –ps=X –id=1 –ec=11

For Windows, various filename extensions are associated with command files. For example, .bat and .cmd are both acceptable. However, only the .bat extension is valid for a command file used by the Interface.

The name of the startup command file must be the name of the Interface executable, with the .exe extension replaced by the .bat extension. Thus, the startup command file for this Interface will typically be pisnmptrap.bat. (The installation program installs a sample command file named pisnmptrap.bat_new. Users who are not using the PI ICU should use this file as a template for their own pisnmptrap.bat.)

The contents of a PI Interface command file may contain the caret line continuation character (^). For example, a pisnmptrap.bat file with contentspisnmptrap.exe ^



ps=X ^id=1 ^ec=11

is equivalent to the above example.

The maximum length of each line in a command file is 1024 characters. The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters. If a value for a parameter contains a space, use a pair of double quotes to the parameter value. For example,pisnmptrap.exe –ps=X –id=1 –stopstat="Intf Shut"

Command-line ParametersParameter Description

-bdp

Optional

The –bdp parameter tells the Interface to build its default points at startup.

-dbg

Optional

The –dbg parameter tells the Interface to print interface-level debug messages. Please see the Troubleshooting section for more information.

-dbgpts

Optional

The –dbgpts parameter tells the Interface to build points such that the Interface will provide point-level debug messages. In particular, the Interface builds points with Location5 set to 3. Please see the description for the Location5 attribute in the Troubleshooting section for more information.

In order for –dbgpts to take effect, the user must also specify -bdp.

-ec=x

Optional

The -ec parameter on the command line specifies a counter number, x, for an I/O Rate point. The value of x should be between 2 and 34, inclusive, or 51 and 200, inclusive.

Configuration of an I/O Rate point is discussed in the section called “I/O Rate Point Configuration”.

-host=host:port

Required

The –host parameter specifies the PI Server computer. host is either the IP address of the PI Sever node or the TCP/IP name of the PI Server node. port is the TCP port number for TCP/IP communication. The port is always 5450 for a PI 3.x Server.

-id=#

Required

The –id parameter specifies a positive number that corresponds to a point’s Location1 attribute. In particular, each instance of the Interface uses the –ps and –id parameters to identify uniquely its particular list of points to service. In addition, the Interface uses the value of this parameter in the messages that it writes to the log file. For example, if the user specifies –id=1, then the message log file will have contents such as:

02-Apr-07 14:51:12

PI SNMPTrap 1> Number of points with pointsource loaded is 2

60

Parameter Description

-idsnum=

Optional

The value of the –idsnum parameter tells the Interface not to write Bad Output to an output point when its source tag value is the system digital state value of this parameter. For example, when the user specifies

–idsnum=241

then the Interface does not write Bad Output to an output point when its source tag's snapshot value is Failed. By default, the Interface uses -idsnum=244 (Filtered).

To indicate that the Interface should write Bad Output when the source tag's value is any system digital state, use –idsnum=0.

-maxIntQueue=#

Optional

The -maxIntQueue parameter specifies the maximum size of the Interface’s internal queue. If the user does not specify a value for this parameter, the Interface uses a size of 100,000. See the section Data Records and Record Processing (in the Chapter titled Additional Operational Information) for more information.

-noIO

Optional

The -noIO parameter tells the Interface not to write any values to its points. This parameter is useful when –dbg (interface level debugging) is also enabled.

-oad

Optional

The -oad parameter tells the Interface to write OID values with a leading dot. That is, if -oad is present, the Interface writes a value such as ".1.3.6.1.2.1.2.2.1.3". Otherwise, the Interface writes "1.3.6.1.2.1.2.2.1.3".

-ps=C...

Required

The –ps parameter specifies the point source character or character string for the Interface. Each instance of the Interface uses the –ps and –id parameters to identify uniquely its particular list of points to service.

The value for the –ps parameter is not case sensitive. That is, –ps=N is identical to –ps=n.

-q

Optional

When the -q parameter is present, Snapshots and exceptions are queued before they are sent to the PI Server.

The maximum queue size is close to 4000 bytes. The queue is flushed periodically if it is not filled.

-resolve

Optional

The –resolve parameter tells the Interface to resolve IP addresses into host names for points with Location2 set to 3.

-sio

Required if there are output points

The -sio parameter stands for “suppress initial outputs.” This parameter tells the interface to send outputs (SNMP Traps) only when they are explicitly triggered.

-sn

Optional, but recommended

The –sn parameter tells the Interface to bypass exception reporting. Because an SNMP trap is by definition an exceptional event, the user should use –sn.



Parameter Description

-stopstator-stopatat=digstate

Default:-stopstat="Intf Shut"

Optional

If the -stopstat parameter is present on the startup command line, then the Interface writes the digital state, Intf Shut, to each PI Point when it stops.

If -stopstat=digstate is present on the command line, then the Interface writes the digital state, digstate, to each PI Point when it stops. digstate must be in the system digital state table. The Interface uses the first occurrence in the table.

If neither -stopstat nor -stopstat=digstate is present on the command line, then the Interface does not write a digital state at shutdown.

Example:-stopstat="Intf Shut"

The entire parameter value is enclosed within double quotes when there is a space in digstate.

-trapport=#

Optional

The -trapport parameter specifies the UDP port number on which the Interface receives SNMP traps. By default, the Interface receives traps on port number 162.

Sample pisnmptrap.bat FileThe following is an example of the contents of a startup command file for the PI SNMPTrap Interface:REM ==========================================================================REMREM PISNMPTrap.batREMREM Sample startup file for the SNMPTrap Interface to the PI SystemREMREM ==========================================================================REMREM OSIsoft strongly recommends using PI ICU to modify startup files.REMREM Sample command line.\pisnmptrap.exe -host=XXXXXX:5450 -id=1 -ps=X ̂ -stopstat="Intf Shut" –snREM End of PISNMPTrap.bat File

The installation program installs a sample command file named pisnmptrap.bat_new. The user may use this file as a starting template to configure the pisnmptrap.bat file.

62

Interface Node ClockMake sure that the time and time zone settings on the computer are correct. To confirm, run the Date/Time applet located in the Windows Control Panel. If the locale where the interface node resides observes Daylight Saving Time, check the box marked “Automatically adjust clock for daylight saving changes”. For example,

In addition, make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. That is,

C:> set

Make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel, click the Environment tab, and remove TZ from the list of environment variables.


Security

Windows The PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Server. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Server manuals.

Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure.See “Trust Login Security” in the chapter “PI System Management” of the PI Universal Data Server System Management Guide.

If the interface cannot write data to the PI Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. If the interface cannot send data to a PI2 Server, it writes a –999 error. See the section "Appendix A: Error and Informational Messages" for additional information on error messaging.

PI Server v3.3 and Higher

Security Configuring using Trust EditorThe Trust Editor plug-in for PI System Management Tools 3.x may be used to edit the PI Trust table.

See the PI System Management chapter in the PI Server manual for more details on security configuration.

Security configuration using piconfigFor PI Server v3.3 and higher, the following example demonstrates how to edit the PI Trust table:C:\PI\adm> piconfig@table pitrust@mode create@istr Trust,IPAddr,NetMask,PIUsera_trust_name,192.168.100.11,255.255.255.255,piadmin@quit

For the above,

Trust: An arbitrary name for the trust table entry; in the above example,

a_trust_name

IPAddr: the IP Address of the computer running the Interface; in the above example,

192.168.100.11

NetMask: the network mask; 255.255.255.255 specifies an exact match with IPAddr


PIUser: the PI user the Interface to be entrusted as; piadmin is usually an appropriate user

PI Server v3.2For PI Server v3.2, the following example demonstrates how to edit the PI Proxy table:C:\PI\adm> piconfig@table pi_gen,piproxy@mode create@istr host,proxyaccountpiapimachine,piadmin@quitIn place of piapimachine, put the name of the PI Interface node as it is seen by PI Server.


Starting / Stopping the Interface on Windows This section describes starting and stopping the interface once it has been installed as a service. See the UniInt Interface User Manual to run the interface interactively.

Starting Interface as a ServiceIf the interface was installed a service, it can be started from PI ICU, the services control panel or with the command:pisnmptrap.exe –start

To start the interface service with PI ICU, use the button on the PI ICU toolbar.

A message will be echoed to the screen informing the user whether or not the interface has been successfully started as a service. Even if the message indicates that the service started successfully, make sure that the service is still running by checking in the services control panel.

There are several reasons that a service may immediately terminate after startup. One is that the service may not be able to find the command-line parameters in the associated .bat file. For an interface service startup to succeed, the root name of the .bat file and the .exe file must be the same, and the .bat file and the .exe file must be in the same directory.

If the service terminates prematurely for whatever reason, no error messages will be echoed to the screen. The user must consult the pipc.log file, the Windows Event Viewer, or other sources of error messages. See the section “Appendix A: Error and Informational Messages,” for additional information.

Stopping Interface Running as a ServiceIf the interface was installed a service, it can be stopped at any time from PI ICU, the services control panel or with the command:pisnmptrap.exe –stopThe service can be removed by:pisnmptrap.exe –remove

To stop the interface service with PI ICU, use the button on the PI ICU toolbar.


BufferingFor complete information on buffering, please refer to the PI-API Installation Instruction.

PI Interface Node buffering consists of a buffering process which runs continuously on the local node, a PI API library whose calls can send data to this buffering process, and a utility program for examining the state of buffering and controlling the buffering process.

Note: Change the Local Security Policy on Windows XP. 1. Open “Administrative Tools” from the control panel. 2. Open “Local Security Policy” from administrative tools. 3. Browse to “Security Options” under “Local Policies.” 4. Double click on “System Objects: Default owner for objects created by members of the Administrators group.” 5. Change the dropdown from “Object Creator” to “Administrators group.”

The behavior of Bufserv should now be the same on Windows XP as it was for Windows NT 4 and 2000.

Configuring Buffering with PI ICU (Windows)Buffering is enabled through the PI Interface Configuration Utility’s Tools>API Buffering… menu. Unless buffering is explicitly enabled, the PI API will not buffer data, sending data directly to the home node.

The API Buffering… dialog allows the user to view and configure the parameters associated with the PI API Buffering (bufserv) process. The user can start and stop the PI API Buffering process from the Service tab:


Service TabThe Service tab allows for some PI API Buffering service configuration. For further configuration changes, use the Services applet.

Service NameThe Service name displays the name of the PI API Buffering Service.

Display NameThe Display name displays the full name associated with the PI API Buffering service.

Log On AsLog on as indicates the Windows user account under which the PI API Buffering service is setup to start automatically on reboot, or manually.

PasswordPassword is the name of the password for the Windows user account entered in the Log on as: above.

Confirm passwordReenter the password to verify it has been typed correctly both times.

DependenciesThe Dependencies lists the Windows services on which the PI API Buffering service is dependent.

Dependent ServicesThe Dependent services area lists the Windows services that depend on bufserv to function correctly.

Start / Stop ServiceThe Start / Stop buttons allow for the PI API Buffering service to be started and stopped. If the service is not created, this box will show Not Installed.

After a change is made to any of the settings on the Settings tab, the OK button must be clicked to save these settings, and then the service must be stopped and restarted for the changes to be picked up by bufserv.

Service Startup TypeThe Startup Type indicates whether the PI API Buffering service is setup to start automatically on reboot or manually on reboot, or is disabled.

If the Auto option is selected, the service will be installed to start automatically when the machine reboots.

If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.

If the Disabled option is selected, the service will not start at all.

Generally, the PI API Buffering service is set to start automatically.


Create/Remove ServiceThe Create / Remove buttons allow for the creation or removal of the PI API Buffering service. Clicking the Create button will cause the service to be created using the Log on as and passwords given. Once the service is created the Start / Stop buttons will be activated.

Settings TabThe Settings tab allows for configuration of the 7 configurable settings used by PI API Buffering. Default values are used if no other value is provided.

Enable BufferingEnable the PI API Buffering feature.

Maximum File SizeMaximum buffer file size in kilobytes before buffering fails and discards events. Default value is 100,000. Range is 1 to 2,000,000.

The Use Default button places the default value into the text box. To keep this value, click the Apply button.

Send RateSend rate is the time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds). Default value is 100. Range is 0 to 2,000,000.



Buffering

Primary Memory Buffer SizePrimary memory buffer size is the size in bytes of the Primary memory buffer. Default value is 32768. Range is 64 to 2,000,000.


Secondary Memory Buffer SizeSecondary memory buffer size is the size in bytes of the Secondary memory buffer. Default value is 32768. Range is 64 to 2,000,000.


Max Transfer ObjectsMax transfer objects is the maximum number of events to send between each SENDRATE pause. Default value is 500. Range is 1 to 2,000,000.


Pause RateWhen buffers are empty the buffering process will wait for this number of seconds before attempting to send more data to the home node. Default value is 2. Range is 0 to 2,000,000.


Retry RateWhen the buffering process discovers the home node is unavailable it will wait this number of seconds before attempting to reconnect. Default value is 120. Range is 0 to 2,000,000.


Max Theoretical Send RateThis is the theoretical max send rate which is calculated like this:max = MAXTRANSFEROBJS / SENDRATE * 1000Default value is 5000. This value is automatically calculated for the user and can not be changed.

There are no additional steps needed to install buffering after installing the PI API. The delivered PI API library supports both buffered and un-buffered calls.

72

Configuring Buffering ManuallyBuffering is enabled through the use of a configuration file, piclient.ini. Unless this file is modified to explicitly enable buffering, the PI API will not buffer data, sending data directly to the home node.

There are no additional steps needed to install buffering after installing the PI API. The delivered PI API library supports both buffered and un-buffered calls.

Note: When buffering is configured to be on, the bufserv process must be started before other programs using the PI API, so that these programs can access the shared buffering resources. Any program that makes a connection to a PI Server has this requirement even if it does not write to PI.

Configuration of buffering is achieved through entries in the piclient.ini file. The file is found in the .dat subdirectory of the PIHOME directory (typically c:\program files\pipc\dat) under Windows. This file follows the conventions of Microsoft Windows initialization files with sections, keywords within sections, and values for keywords. All buffering settings are entered in a section called [APIBUFFER]. To modify settings, simply edit the piclient.ini file in a text editor (Notepad on Windows) to the desired values.

The following settings are available for buffering configuration:

Keywords Values Default Description

BUFFERING 0, 1 0 Turn off/on buffering. OFF = 0, ON = 1,

PAUSERATE 0 – 2,000,000 2 When buffers are empty the buffering process will wait for this long before attempting to send more data to the home node (seconds)

RETRYRATE 0 – 2,000,000 120 When the buffering process discovers the home node is unavailable it will wait this long before attempting to reconnect (seconds)

MAXFILESIZE 1 – 2,000,000 100,000 Maximum buffer file size before buffering fails and discards events. (Kbytes)

MAXTRANSFEROBJS

1 – 2,000,000 500 Maximum number of events to send between each SENDRATE pause.

BUF1SIZE 64 – 2,000,000

32768 Primary memory buffer size. (bytes)

BUF2SIZE 64 – 2,000,000

32768 Secondary memory buffer size. (bytes)

SENDRATE 0 – 2,000,000 100 The time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds)


Buffering

In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define the default PI server and an optional time offset change that may occur between the client and server.

Keywords Values Default Description

DSTMISMATCH 0 – 2,000,000 0 The time that the server and client local time offset is allowed to jump. Typically, 3600 if the nodes are in time zones whose DST rules differ (seconds)

Example piclient.ini FileOn Windows, the default server information is stored in the pilogin.ini file so the piclient.ini would only have the [APIBUFFER] section. The BUFFERING=1 indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to 100 Megabytes of data storage. Do not use commas or other separators in the numeric entries. The retry rate is set to 600 seconds, meaning “Wait 10 minutes after losing a connection before retrying”.

On Windows a piclient.ini file might look like:[APIBUFFER]BUFFERING=1MAXFILESIZE=100000; The PI API connection routines have a 1 minute default timeout.RETRYRATE=600

74

Appendix A:Error and Informational Messages

The string PI SNMPTRAP ID> is pre-pended to error and informational messages written to the message log. The value of the -id parameter on the startup command line determines the ID identifier.

Message LogsThe name of the message log is pipc.log. It is located in the dat subdirectory where the PI API is installed. For example,C:\Program Files\PIPC\dat\pipc.logMessages are written to this file at the following times:

At startup, the Interface writes many informational messages log. These include the version of the Interface, the version of the UniInt template, the command-line parameters used, and the version of the PI API found.

As the Interface retrieves points from the PI Server, it writes messages to the log if there are problems with the configuration of the points.

System Errors and PI ErrorsOperating system errors are associated with positive error numbers. Errors related to the PI System are associated with negative error numbers.

The user can obtain descriptions of operating system and PI System errors with the pidiag program found on the computer running PI Server. This program is located in the adm subdirectory of the directory where PI Server is installed. Use –e command line parameter followed by the error number. For example,C:\PI\adm\pidiag –e 100[100] Cannot create another system semaphore.

C:\PI\adm\pidiag –e -10401[-10401] No Write Access - Secure Object


Appendix B:Troubleshooting

Interface Level Debugging (-dbg)

Trap DetailsThe startup parameter –dbg tells the Interface to print information to the PIPC.LOG regarding every trap message that it receives. For example, if the Interface receives the following trapAgent address: 192.168.10.8

Enterprise: 1.3.6.1.4.1.1200.8.7.6



OID: 1.3.6.1.4.1.1200.8.7.6.1

Value: 3

OID: 1.3.6.1.4.1.1200.8.7.6.2

Value: 81

it will log the following:PI SNMPTrap 1> dbg> Msg #1-1 GT:6 ST:1 ENT=1.3.6.1.4.1.1200.8.7.6 t=1070490548.589005

PI SNMPTrap 1> dbg> Agent name: 192.168.10.8 Agent IP: 192.168.10.8

PI SNMPTrap 1> dbg> OID=1.3.6.1.4.1.1200.8.7.6.1

PI SNMPTrap 1> dbg> ASN_INTEGER, value: 3

PI SNMPTrap 1> dbg> Msg #1-2 GT:6 ST:1 ENT=1.3.6.1.4.1.1200.8.7.6 t=1070490548.589005



PI SNMPTrap 1> dbg> ASN_INTEGER, value: 81

Because the trap message contains two OID variable bindings, the Interface needs to break up the message into two messages (Msg #1-1 and Msg #1-2) for internal processing purposes.

If after receiving the above, the Interface then receives from a Cisco device the following trapAgent Address: 199.8.7.6

Enterprise: 1.3.6.1.4.1.9.1.45


Trap type: 3 (Link Up)


OID1: 1.3.6.1.2.1.2.2.1.1.23

Value of OID1: 23 (link 23 is the link in question)

OID2: 1.3.6.1.2.1.2.2.1.2.23

Value of OID2: Loopback1 (link description)

OID3: 1.3.6.1.2.1.2.2.1.3.23

Value of OID3: 24 (link type)

OID4: 1.3.6.1.4.1.9.2.2.1.1.20.23

Value of OID4: up (reason for link status change)

it will log the following:PI SNMPTrap 1> dbg> Msg #2-1 GT:3 ST:0 ENT=1.3.6.1.4.1.9.1.45 t=1070490552.264008



PI SNMPTrap 1> dbg> Link number: 23

PI SNMPTrap 1> dbg> Msg #2-2 GT:3 ST:0 ENT=1.3.6.1.4.1.9.1.45 t=1070490552.264008



PI SNMPTrap 1> dbg> Cisco Link Description: Loopback1




PI SNMPTrap 1> dbg> Cisco Link Type: 24



PI SNMPTrap 1> dbg> OID=1.3.6.1.4.1.9.2.2.1.1.20.23

PI SNMPTrap 1> dbg> Cisco Link Reason: up

Because this trap is the second one received by the Interface, the informational messages begin with 2; i.e., Msg #2-1.

Because this trap message contains four OID variable bindings, the Interface needs to break up the message into four messages (Msg #2-1 through Msg #2-4) for internal processing purposes.


Point Configuration

As the above examples show, the –dbg startup parameter provides details (i.e., Generic Trap, Specific Trap, Enterprise information) on trap messages received. The user can then use this information for point configuration purposes (i.e., specification of GT=, ST=, ENT=).

Point Level Debugging (Location5)A non-zero value in a point’s Location5 point attribute tells the Interface to print point-specific debugging messages to the message log. The user does not have to stop and re-start the Interface to enable/disable these debugging messages.

The following settings for Location5 are available:

Location5 Meaning

0 no debugging messages

1 minimum debugging; information on point loading and values sent to the UniInt interface template

2 medium debugging; information found in minimum debugging plus information on which trap message matched the point

3 maximum debugging; information found in medium debugging plus information on trap messages that do not match the point

The following is an example of messages in the log file when the point named snmptraptest is set to minimum debugging:

PI SNMPTrap 1> pt (snmptraptest) debug setting is 1

PI SNMPTrap 1> pt (snmptraptest) LOADED

PI SNMPTrap 1> pt (snmptraptest) t=1070562580.599014 rval=1.00 ival=0 istat=0 sent/would have been sent to UniInt

PI SNMPTrap 1> pt (snmptraptest) t=1070562640.607010 zero value sent/would have been sent to UniInt

The following is an example of messages in the log file when the point named snmptraptest is set to medium debugging:




PI SNMPTrap 1> pt (snmptraptest) matched with the following trap:

PI SNMPTrap 1> Msg #1-1 GT=0 ST=0 DEV=199.8.7.6 ENT=1.3.6.1.4.1.1824


The following is an example of messages in the log file when the point named snmptraptest is set to maximum debugging:


Appendix B: Troubleshooting




PI SNMPTrap 1> pt (snmptraptest) matched with the following trap:

PI SNMPTrap 1> Msg #2-1 GT=0 ST=0 DEV=199.8.7.6 ENT=1.3.6.1.4.1.1824

PI SNMPTrap 1> pt (snmptraptest) ST= not matched; Msg #3-1 ST=23


Common Problems

Interface Exits on StartupIf the Interface immediately exits upon startup, possible causes are

required command line parameters are not specified, or

the communications port for receiving SNMP traps is already being used

Command-line parameters not specifiedPI SNMPTrap requires all of the following command line parameters

–ps= (point source characters)

–id= (interface identifaction number)

-host= (hostname of PI Server)

If the user omits any of these parameters, the Interface exits.

Trap receiving port already usedIf another program is already using the default SNMP trap port of 162, the Interface exits and prints messages such as:PI SNMPTrap 1> fatal> cannot open port number = 162PI SNMPTrap 1> fatal> cannot open session to listen for SNMP TrapsPI SNMPTrap 1> Interface initialization error, Intf halted

The user should stop the other program that is currently listening for SNMP traps on port 162. For example, if the Microsoft Windows SNMP Trap Service is running, the user should stop it.

Alternatively, the user can specify a value for the -trapport= parameter in the startup command file and re-start the Interface. However, the user must then configure all SNMP trap generating devices to send trap messages to this port number.

Point Not Receiving New ValuesIf a point does not receive new values, a possible reason is that the Interface does not have sufficient permission to send data to PI Server. The message log will show an error

80

number of –10401. Check the entries in the PI Proxy Table (PI Server v3.2) or the PI Trust Table (PI Server v3.3 and higher).

The user can also enable point-level debugging to find out whether the Interface has matched any traps with the particular point.

Output Point Not LoadedThe Interface does not load an output point (i.e., Location2 set to -6) if the –sio startup command parameter is missing.

-15011 Error for Output PointIf the Source Tag for output is of type String, and the output point itself is of type Integer or Float, an error of -15011 may occur when the Interface cannot convert the string expression into a numerical result. To avoid this error, use a Source Tag for output that is of type Integer or Float.


Appendix C:Additional Operational Information

CIDR NotationCIDR notation is a shorthand method of specifying continuous IP addresses. It consists of an IP address in dotted decimal notation, the slash character (“/”), and a number between 1 and 32. This number is related to the number of continuous IP addresses starting from given IP address, inclusive. For example,192.168.100.11/30

indicates the following 4 IP addresses:192.168.100.11

192.168.100.12

192.168.100.13

192.168.100.14

The number 4 is determined from the formula2^(32-X)where X is the number after the “/”.

Another example is192.168.100.11/31Using the above formula gives2^(32-31)or 2. So, the above CIDR indicates the following addresses:192.168.100.11192.168.100.12

The following table is helpful while using CIDR notation:

/X Number of continuous addresses

32 1

31 2

30 4

29 8

28 16

27 32

26 64

25 128

24 256


23 512

22 1024

21 2048

Further values follow the formula: 2^(32-X).

IP Address ResolutionIf the user specifies the –resolve command line parameter, the Interface will attempt to translate an IP address (e.g., 192.168.10.100) to a hostname (e.g., “Device1”) for points whose Location2 value is 3.

However, the underlying function call ( gethostbyaddr() ) for IP address to name translation can take a long time to complete. So, to prevent unnecessary delays, the Interface keeps a cache of hostnames and IP address mappings. The Interface clears this cache at 4:00 AM each day.

The disadvantage of this caching feature is that the points with Location2 equal to 3 may contain an incorrect hostname if, on the user's network, the mapping of IP addresses to hostnames changes frequently.

Data Rates and Record Processing

Internal QueuePI SNMPTrap processes SNMP trap messages/records as soon as it receives them. When these messages are arriving at a rate that is faster than that which PI SNMPTrap is processing, the Interface’s internal queue grows to accommodate this condition. For example, if PI SNMPTrap is receiving records at 200 per second, but is only processing these records at 190 per second, the internal queue will have 20 records after 2 seconds. If these data rates were to continue, the internal queue will have 600 records after 1 minute and 6000 records after 10 minutes.

When there are about 100,000 records in the internal queue, PI SNMPTrap stops accepting new trap messages, resulting in data loss. As soon as the Interface has caught up with processing these 100,000 records, it resumes accepting new ones. To inform the user of such behavior, PI SNMPTrap writes to the log file messages such as:01-Jun-05 14:34:24

PI SNMPTrap 1> internal queue already has 100000 records; suspending new records

01-Jun-05 14:34:34

PI SNMPTrap 1> internal queue ready again for new records; 3240 records lost

In addition, the Interface writes I/O Timeout to its list of points.

01-Jun-05 14:34:24

PI SNMPTrap 1> UTC of I/O Timeout is 1121289439.840012

Although the above behavior regarding the maximum internal queue size results in data loss, the Interface must perform such action in order to prevent catastrophic failure. That


is, if the Interface continues to receive SNMP trap messages faster than it can process them, it will use up more and more of the computer’s memory, resulting in a crash of the machine itself.

Performance CountersPI SNMPTrap exposes interface-specific performance counters. These counters allow the user to monitor

the size of the internal queue (i.e., number of unprocessed records),

the percentage of the internal queue that is currently being used,

the rate at which the Interface is processing trap records,

the rate at which the Interface is receiving trap records.

The user can use the Windows Performance Monitor program to look at the above variables. To launch Performance Monitor, run perfmon.exe at the command prompt. For example,C:> perfmon.exe

To observe counters specific to PI SNMPTrap, first click on the plus symbol (‘+’).


Appendix C: Additional Operational Information

Then, in the resulting window, look in the list of Performance objects for “PI SNMPTrap Interface” (or similar object):

Finally, add the appropriate counters:

86

PI-Performance Monitor InterfaceInstead of (or in addition to) using the Windows Performance Monitor program, the user can use OSIsoft’s PI-Performance Monitor Interface to monitor the performance counters described above. In this manner, there is real-time as well as historical information regarding the SNMP trap data rates seen by PI SNMPTrap.

Please consult the PI-Performance Monitor Interface manual for information on the use of this program.

Prevention of Data LossWhen the Interface is operating efficiently,

the rate at which the Interface is processing trap records is equal to the rate at which the Interface is receiving trap records,

the size of the internal queue is less than 1000, and

the percentage of the internal queue used is less than 1.

Any of the following conditions

the rate at which the Interface is processing trap records is less than the rate at which the Interface is receiving SNMP trap records,

the size of the internal queue is greater than 75000, and

the percentage of the internal queue used is greater than 75.

indicates that the Interface cannot process all the trap records that it is receiving.

So, the user should try some (or all of the following)

decrease the number of points serviced by the Interface,


Appendix C: Additional Operational Information

remove point-level debugging from interface points (i.e., set Location5 to 0)

remove interface level debugging (i.e., do not run with the –dbg parameter)

minimize the number of points that perform Regular Expressions operations

increase the internal queue size via the –maxIntQueue startup command parameter,

run the Interface on a more powerful machine

Otherwise, the Interface’s internal queue will fill to its maximum, resulting in data loss.

88

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

This section describes how to use the output feature of the PI SNMPTrap Interface as part of a monitoring and notification system which sends an SNMP Trap message when a variable being monitored exceeds a threshold. Other parts of this system include a data collection interface program (e.g., PI IP Flow) and a calculations program (e.g., PI Performance Equation Scheduler).

The steps for implementing this monitor and alerting solution include:

configuring a PI point for the monitoring interface program (i.e., the "monitoring" point);

configuring a PI point for the calculations program (i.e., the "calculation" point); and

configuring an output PI point for the PI SNMPTrap Interface itself (i.e., the "notification" point).

The following example discusses a situation whereby a user wants to send an SNMP Trap whenever the amount of Web traffic on the network exceeds 10 megabytes.

PI point for MonitoringThe PI point for monitoring is a point that monitors the variable or event in question. So, to determine the number of bytes on the network that involves Web traffic, a user configures a point named nf_webTraffic for use with the PI IP Flow Interface:

That is, the Instrument Tag contains:


1_A=R; 1_SP=80; 1_PROT=6; 2_A=R; 2_DP=80; 2_PROT=6;

After creating this point, the user then runs the PI IP Flow Interface. Accordingly, PI IP Flow writes to the point named nf_webTraffic a value that represents the number of bytes on the network that consists of Web traffic.

PI point for CalculationThe PI point for calculation analyzes whether a given condition is true; that is, whether the previous point has exceeded a threshold amount. This point is typically a PI Performance Equation Scheduler (PI-PE) point.

As indicated earlier, the user wants to send an SNMP Trap if nf_webTraffic exceeds10 megabytes. So, he creates the following event-based scheduled PI-PE point named analysis_nf_webTraffic:


That is, the Event tag attribute field is: nf_webTraffic

The Equation is:if ('nf_webTraffic' > 10000000) then 'nf_webTraffic' else digstate("Filtered")



Thus, if the amount of Web traffic exceeds 10 megabytes, then the value of analysis_nf_webTraffic will be this amount. Otherwise, the value of analysis_nf_webTraffic will be the system digital state Filtered.

PI point for NotificationThe PI point for notification is an output point serviced by the PI SNMPTrap Interface. This output point results in an SNMP Trap being sent. To conclude the above example, the user wants to send an SNMP Trap to the device at IP address 192.168.10.100 when the amount of Web traffic exceeds 10 megabytes. In particular he wants to send an SNMP Trap that contains the following two OIDs: first OID: .1.3.6.1.4.1.23257.1.100.2

value of first OID: Web traffic threshold exceeded

second OID: .1.3.6.1.4.1.23257.1.100.1;

value of second OID: <number of bytes of Web traffic>

Thus, the user configures the following point named notify_nf_webTraffic:

92

That is, the Source tag attribute field is analysis_nf_webTraffic

The Extended Descriptor contains: 1_OID=.1.3.6.1.4.1.23257.1.100.2;

1_OIDT=S;

1_OIDV=Web traffic threshold exceeded;

2_OID=.1.3.6.1.4.1.23257.1.100.1;

(Because 2_OIDV is omitted and the point type of notify_nf_webTraffic is Float32, the Interface uses Integer for the 2_OID_2 type. Similarly, because 2_OIDV is omitted, the Interface uses the value of notify_nf_webTraffic for the value of 2_OID.)

The value of Location2 is -6 to indicate that the point is an output point.

The Instrument Tag contains: DEST=192.168.10.100; ENT=.1.3.6.1.4.1.23257.1.100;

SummarySo, putting all of the above together:

The PI IP Flow Interface monitors the amount of Web traffic on a network. It writes this number to the point named nf_webTraffic.

The PI-PE Scheduler point named analysis_nf_webTraffic is event-based. Its event point is nf_webTraffic. So, whenever nf_webTraffic receives a new value, the PI-PE Scheduler checks whether this new value is greater than 10,000,000. If the value is not, PI-PE Scheduler writes Filtered to analysis_nf_webTraffic. Otherwise, it writes the value of nf_webTraffic to analysis_nf_webTraffic.



The PI SNMPTrap Interface output point named notify_nf_webTraffic has a source tag that is analysis_nf_webTraffic. Thus, whenever analysis_nf_webTraffic gets a new value, there is a chance to send an SNMP Trap. Specifically, when the value of analysis_nf_webTraffic is a system digital state such as Filtered (i.e., nf_webTraffic is not greater than 10,000,000), then the Interface does not send an SNMP Trap. However, when the value of analysis_nf_webTraffic is greater than 10,000,000 (i.e., nf_webTraffic is greater than 10,000,000), the Interface sends an SNMP Trap containing an OID value with this number.

Below is a screenshot of the Ethereal application capturing such an SNMP Trap message:

94

Revision HistoryDate Author Comments

5-Apr-2004 E Tam v1.0.0.0; used interface skeleton v1.11

28-Jun-2005 E Tam v1.1.0.0; add –maxIntQueue parameter

3-Aug-2005 M Kelly Added new screenshots for the ICU Control section, added new example batch file. Fixed headers and footers.

5-Aug-2005 M Kelly Fixed sample batch file which was missing two command line parameters.

8-Aug-2006 ETam v1.1.1.1 (beta version) ; use n_OID instead of OID_n

30-Apr-2007 ETam v1.1.2.0; use skeleton v2.5.2

3-May-2007 Janelle Version 1.1.2.0, Revision A: update hardware diagram, add serial based interface information to supported features table.

8-May-2007 ETam Version 1.1.2.0, Revision B: add missing InstrumentTag information

15-May-2007 ETam v1.1.3.0; use skeleton v2.5.2


Documents

SNMPTrap Interface to the PI Systemcdn.osisoft.com/interfaces/2104/PI_SNMPTrap_1.1.3.0.doc · Web viewPI-API v1.3.4 or higher (automatically included as part of PI-SDK), and