SNMP
Interface to the PI System
Version 1.4.1.0
Revision C
How to Contact Us
OSIsoft, Inc.777 Davis St., Suite 250
San Leandro, CA 94577 USA
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)
Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA / Worldwide Offices
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSI Software Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
OSIsoft Japan KK
Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V.
Mexico City, Mexico
Sales Outlets and Distributors
· Brazil
· Middle East/North Africa
· Republic of South Africa
· Russia/Central Asia / · South America/Caribbean
· Southeast Asia
· South Korea
· Taiwan
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 LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Unpublished – rights reserved under the copyright laws of the United States.
© 2000-2007 OSIsoft, Inc. PI_PISNMP.doc
Table of Contents
Introduction 1
Reference Manuals 2
Supported Features 2
Diagram of Hardware Connection 5
Principles of Operation 7
PI SNMP’s Role in SNMP Networks 7
PI SNMP Internal Operation 7
PI SNMP User Operation Summary 8
PI Data Input and Output 9
Installation Checklist 11
Interface Installation 13
Naming Conventions and Requirements 13
PI Interface Configuration Utility 13
Interface Directories 14
PIHOME Directory Tree 14
Interface Installation Directory 14
Interface Installation Procedure 14
Installing Interface as a Windows Service 15
Installing Interface Service with PI Interface Configuration Utility 15
Installing Interface Service Manually 18
Digital States 19
PointSource 21
PI Point Configuration 23
Point Attributes 23
Tag 23
PointSource 23
PointType 24
Location1 24
Location2 24
Location3 26
Location4 27
Location5 27
InstrumentTag 27
ExDesc 28
Scan 34
Shutdown 34
SourceTag 35
Conversion 35
Performance Point Configuration 37
Configuring Performance Points with PI ICU (Windows) 37
Configuring Performance Points Manually 38
I/O Rate Tag Configuration 41
Monitoring I/O Rates on the Interface Node 41
Configuring I/O Rate Tags with PI ICU (Windows) 41
Configuring I/O Rate Tags Manually 43
Configuring PI Point on the PI Server 43
Configuration on the Interface Node 43
Startup Command File 45
Configuring the Interface with PI ICU 45
pisnmp Interface Tab 48
Command-line Parameters 51
Sample PISNMP.bat File 56
pisnmp.ini File -- Obsolete 57
Interface Node Clock 59
Security 61
Starting / Stopping the Interface 63
Starting Interface as a Service 63
Stopping Interface Running as a Service 63
Buffering 65
Configuring Buffering with PI ICU (Windows) 65
Configuring Buffering Manually 69
Example piclient.ini File 70
Appendix A: Error and Informational Messages 71
Message Logs 71
Messages 71
Location5 72
System Errors and PI Errors 73
Common Problems 73
Unexpected Value 73
PI SNMP Startup 73
Point Loading 74
No New Value 75
Value of 0 75
I/O Timeout 75
Bad Input 76
Configure 76
Missed Scans 77
Appendix B: snmpget 79
Appendix C: OID Examples 81
Appendix D: Basic SNMP for PI Users 83
Appendix E: Tutorial on Using PI SNMP with Routers 87
Appendix F: PI SNMP Technical Details 93
Appendix G: ifAlias Support 95
Appendix H: Known Issues 99
Appendix I: Acknowledgments 101
Net-SNMP 101
OpenSSL 105
Revision History 107
SNMP Interface to the PI System 3
Introduction
OSIsoft’s PI SNMP data collection interface program gathers information from SNMP-enabled devices residing in a TCP/IP network. The operation of PI SNMP requires that these devices be able to send and receive messages via the SNMP protocol. In particular, they must have an SNMP Agent that supports SNMPv1, SNMPv2c, or SNMPv3.
Because RMON (Remote Monitoring) is a specific application of the SNMP protocol, PI SNMP supports the retrieval of RMON values.
PI SNMP Basic (a limited version of the full PI SNMP program) is also available from OSIsoft. PI SNMP Basic has the following limitations:
· it gets data for up to 32 PI points
· only one copy of the program may be running at a time
· it runs only on a machine that is also running the PI Server
· it sends data only to this PI Server machine
In addition, the filename of PI SNMP Basic is pisnmp_basic.exe (versus pisnmp.exe for the full version).
The following table summarizes the differences between the full and basic versions of PI SNMP.
PI SNMP / PI SNMP BasicMaximum point count / Point count of PI Server / 32
Availability / Available for purchase / Installed as part of PI Server 3.3 and higher
Can run on a PI Interface node / Yes / No
Must run on a PI Server node / No / Yes
Must send data to the PI Server node on which it runs / No / Yes
Number of copies that can run simultaneously / Unlimited / 1
Filename / pisnmp.exe / pisnmp_basic.exe
PI SNMP runs on a Microsoft Windows NT (version 4.0 or higher), Windows 2000, Windows XP, or Windows Server 2003 computers. Unless otherwise noted, the remainder of this document uses the term “Windows” to refer to all four.
The flow of data for the Interface is bi-directional. Specifically, PI SNMP retrieves values from SNMP devices (i.e., PI input points) as well as sets values on SNMP devices (i.e., PI output points).
PI SNMP does not require any special hardware. A standard network interface card on the Windows machine is sufficient.
In order to utilize PI SNMP effectively, the user should be familiar with both basic SNMP and PI technologies. For example, for SNMP, the user should be familiar with the terms Management Information Base (MIB), Object Identifier (OID), and community string. Users who are not familiar with SNMP should consult Appendices B and C of this document.
On the PI side, the user should be adept at creating and editing PI points. Also, the user needs to know the differences between time-based and event based data collection in PI.
Reference Manuals
OSIsoft
· PI Server manuals
· PI API Installation manual
· UniInt Interface User Manual
· PI API manual
· PI ICU User Manual
Supported Features
Feature / Support /Part Number / PI-IN-OS-SNMP-NTI
PI-IN-OS-SNMPB-NT (Basic version)
* Platforms / Windows (NT4, 2000, XP, Server 2003) (Intel)
APS Connector / No
Point Builder Utility / Yes
ICU Control / Yes
PI Point Types / PI 3.x (float16 / float32 / float64 / int16 / int32 / digital / string)
Sub-second Timestamps / Yes
Sub-second Scan Classes / Yes
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / Yes
Outputs from PI / Yes
Inputs to PI: Scan-based / Unsolicited / Event Tags / Scan-based / Event Tags
Supports Questionable Bit / No
Supports Multi-character PointSource / Yes
Maximum Point Count / Point Count of PI Server (full version only)
32 point limit for basic version
* Uses PI SDK / No
PINet String Support / Not applicable
* Source of Timestamps / PI Server machine
* History Recovery / No
* UniInt-based
* Disconnected Startup
* SetDeviceStatus / Yes
Yes
Yes
Failover / No
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 / Integers and octet strings
Serial Based Interface / No
* See paragraphs below for further explanation.
Platforms
The Interface is designed to run on the above mentioned Microsoft Windows operating systems. On Windows NT4 service pack 4 is required; otherwise, no specific service packs are required beyond what the PI API requires.
Uses PI SDK
The PI SDK and the PI API are bundled together and must be installed on each PI Interface node. This Interface does not specifically make PI SDK calls.
Source of Timestamps
The clock on the computer running the PI Server provides the source of timestamps for the values sent by PI SNMP. The Interface writes a timestamp that reflects the time at which it receives data from the SNMP devices.
UniInt-based
UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by developers, and is integrated into many interfaces, including this interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of OSIsoft’s interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniIntsupplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.
The UniInt Interface User Manual is a supplement to this manual.
Disconnected Start-Up
The PI SNMP interface is built with a version of UniInt that supports disconnected start-up. Disconnected start-up is the ability to start the interface without a connection to the PI server. This functionality is enabled by adding -cachemode to the list of start-up parameters or by enabling disconnected startup using the ICU. Refer to the UniInt Interface User Manual for more details on UniInt Disconnect startup.
SetDeviceStatus
The Interface is built with a version of UniInt that supports interface health points. The health point with the point attribute Exdesc = [UI_DEVSTAT] is used to represent the status of the source devices. The following events can be written into the point:
a) "Good" - the interface is properly communicating and reading data from the devices. If no data collection points have been defined, this indicates the interface has successfully started.
b) "3 | n devices(s) in error | Device1,...,DeviceN" - the interface has determined that the listed device(s) are offline. A device is considered offline when all its scan classes violate the consecutive timeout limit or have "I/O Timeout" written to all of its points.
The event "2 | Connected / No Data | " is not used by this interface.
Please refer to the UniInt Interface User Manual for more information on how to configure interface health points.
Vendor Software Required on Foreign Device
In order for PI SNMP to retrieve data from the foreign device, the device must be running an SNMP Agent. Devices such as network routers and switches typically come with SNMP Agents by default. Other network-enabled devices such as workstations, servers, and printers may also have SNMP Agents built-in. Alternatively, third-parties may supply SNMP Agents for these devices.
Additional PI Software
OSIsoft strongly recommends the use of the PI SNMP Tag Builder plug-in for PI SMT 3 to assist with the tag building process. This software is available from the OSIsoft Technical Support site at http://techsupport.osisoft.com/. For further details, consult the plug-in documentation.
Device Point Types
PI SNMP supports the retrieval of integer and string data. PI SNMP can also retrieve MAC addresses and IP addresses from SNMP Agents.
Diagram of Hardware Connection
SNMP Interface to the PI System 3
Principles of Operation
PI SNMP’s Role in SNMP Networks
In SNMP terminology, the PI SNMP data collector behaves like an SNMP Manager. It retrieves information from network devices via the SNMP Agent running on these devices.
However, PI SNMP is not a complete SNMP Manager. It cannot receive data via traps sent by SNMP Agents. Thus, PI SNMP’s primary purpose is to gather statistics and data -- not to control or configure network nodes.
PI SNMP Internal Operation
When the Interface starts up, it retrieves from the PI Server a set of points that have the same point source as that specified in the Interface’s startup command file. The Interface then begins loading its points. It first checks the point’s Location1 attribute to make sure that it matches the value of the "id" startup command parameter. It then looks in
· the Extended Descriptor attribute for the OID (Object Identifier) specification;
· the Extended Descriptor attribute for the community string information if the data is to be read from an SNMPv1 or SNMPv2c agent; or
· the Extended Descriptor attribute for a username, authentication password, and privacy password if the data is to be read from an SNMPv3 agent;
· the Instrument Tag attribute for the hostname/IP address of the SNMP Agent;
· the Location2 attribute to determine whether to retrieve a value from the SNMP Agent or to set a value on the SNMP Agent.
The Interface stores all this information internally for later use; specifically, when it utilizes the community string to query the SNMP Agent for the OID value.
For input points that have Location3 set to 1, PI SNMP groups together those points that reference a common SNMP Agent.
When PI SNMP is ready to poll SNMP Agents for data, it creates a separate thread to poll each SNMP Agent separately. After it receives a value from an SNMP Agent for a particular OID, PI SNMP applies the conversion factor (for numeric points) and sends the resulting value back to the UniInt interface template.
PI SNMP User Operation Summary
The following steps summarize how to use PI SNMP to retrieve data from SNMP enabled network devices.
1. For a particular network element, the user determines the OID representation of the statistic in which he is interested. Recall that OIDs are defined by standards body, or are proprietary to individual manufacturers of network device. As an example, on a router, the total number of octets received on the third network interface is represented by the OID
.1.3.6.1.2.1.2.2.1.10.3
or
interfaces.ifTable.ifEntry.ifInOctets.3