SNMP
Interface to the PI System
Versions 1.3.1.1 – 1.3.1.2
Rev B
43
SNMP Interface to the PI System 43
How to Contact Us
Phone / (510) 297-5800 (main number)(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web / http://www.osisoft.com
Mail / OSIsoft
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrabe 30
D-63674 Altenstadt 1
Deutschland / OSI Software, Ltd
P O Box 8256
Symonds Street
Auckland 1035 New Zealand
OSI Software, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
Singapore, 189721
Unpublished – rights reserved under the copyright laws of the United States.
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
Trademark statement—PI is a registered trademark of OSIsoft, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HPUX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC Cisco is a registered trademark of Cisco Systems, Inc. VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
PI_PISNMP.doc
Ó 2000-2005 OSIsoft, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577
43
SNMP Interface to the PI System 43
Table of Contents
Introduction 1
Reference Manuals 2
Supported Features 2
Diagram of Hardware Connection 4
Principles of Operation 5
PI-SNMP’s Role in SNMP Networks 5
PI-SNMP Internal Operation 5
PI-SNMP User Operation Summary 6
PI Data Input and Output 6
Installation Checklist 7
Interface Installation 9
Naming Conventions and Requirements 9
PI-Interface Configuration Utility 9
Interface Directories 10
The PIHOME Directory Tree 10
Interface Installation Directory 10
Interface Installation Procedure 10
Installing the Interface as an NT Service 11
Installing the Interface Service with PI-Interface Configuration Utility 11
Installing the Interface Service Manually 14
Digital States 15
PointSource 17
PI Point Configuration 19
Point Attributes 19
Tag 19
PointSource 19
PointType 19
Location1 20
Location2 20
Location3 21
Location4 22
Location5 23
InstrumentTag 23
ExDesc 23
Scan 28
Shutdown 28
SourceTag 29
Conversion 29
Performance Point Configuration 31
Configuring Performance Points with PI-ICU 31
Configuring Performance Points Manually 32
I/O Rate Point Configuration 33
Monitoring I/O Rates on the Interface Node 33
Configuring I/O Rate Points with PI-ICU 33
Configuring I/O Rate Points Manually 35
Configuring the I/O Rate Point on the PI Server 35
Configuration on the Interface Node 35
Startup Command File 37
Using PI-ICU to Maintain Startup Command File 37
Command-line Parameters 41
Sample pisnmp.bat File 46
pisnmp.ini File -- Obsolete 47
Interface Node Clock 49
Security 51
Starting / Stopping the Interface 53
Starting Interface as a Service 53
Stopping Interface Running as a Service 53
Buffering 55
Configuring Buffering with PI-ICU 55
Configuring Buffering Manually 58
Example piclient.ini File 59
Appendix A: Error and Informational Messages 61
Message Logs 61
Messages 61
Location5 62
System Errors and PI Errors 63
Common Problems 63
Unexpected Value 63
PI-SNMP Startup 64
Point Loading 64
No New Value 65
Value of 0 66
I/O Timeout 66
Bad Input 66
Configure 67
Missed Scans 67
Appendix B: snmpget 69
Appendix C: OID Examples 71
Appendix D: Basic SNMP for PI Users 73
Appendix E: Tutorial on Using PI-SNMP with Routers 77
Appendix F: PI-SNMP Technical Details 83
Appendix G: ifAlias Support 85
Appendix H: Known Issues 89
Appendix I: Acknowledgments 91
Net-SNMP 91
OpenSSL 95
Revision History 97
43
SNMP Interface to the PI System 43
Introduction
OSIsoft’s PI-SNMP data collection interface program gathers information from SNMP-enabled devices residing in a TCP/IP network. The operation of PISNMP 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. PI-SNMP requires PI-SDK version 1.2.0 Build 180 (or higher).
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
· UniInt End User Document
· PI Server manuals
· PI-API Installation Instructions
· 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 Currently Available / 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
Maximum Point Count / Point Count of PI Server (full version only)
Uses PI-SDK / Yes
PINet to PI 3.x String Support / Not applicable
* Source of Timestamps / PI Server machine
History Recovery / No
Failover / No
* UniInt-based / Yes
Vendor Software Required on PI Interface 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
* See paragraphs below for further explanation.
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, such as the PI-SNMP Interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many OSIsoft-developed interfaces as possible. UniInt 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 End User Document is a supplement to this manual.
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
43
SNMP Interface to the PI System 43
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
2. The user configures points in the PI point database. This configuration tells PISNMP how to retrieve a value from the remote device.
3. The user runs PI-SNMP in a Windows command prompt to confirm that the PI point configuration correctly represents the data to be collected. This procedure is known as “interactively running the Interface”.
4. The user stops interactive execution of PI-SNMP and installs PI-SNMP as a Windows Service. This procedure allows the Interface continuously to run and collect data.
PI Data Input and Output
The PI-SNMP Interface supports both time-based and event-based inputs from network devices to the PI Server. Time-based inputs occur at fixed time frequencies. Eventbased inputs occur whenever there is a change in value in the PI event point.
As in all UniInt-based interfaces, PI-SNMP supports outputs from the PI Server to an SNMP Agent on an event basis. Specifically, PI-SNMP sends an SNMP SET message to an SNMP Agent when the PI source tag for output receives a new event.
43
SNMP Interface to the PI System 43
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps get the PI-SNMP interface running. If you are not familiar with PI interfaces, return to this section after reading the rest of the manual in detail.
Please follow the steps in the order listed below.
1. Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API).
2. PI SMT 3.x should be installed to take advantage of the PI SNMP Tag Builder.