SNMP Interface to the PI System

Table of ContentsIntroduction...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

SNMP Interface to the PI System

Version 1.3.0.4

Rev C

OSI Software GmbH Hauptstrae 30 D-63674 Altenstadt 1Deutschland

OSI Software, Ltd

P O Box 8256Symonds StreetAuckland 1035 New ZealandOSI Software, Asia Pte Ltd

152 Beach Road

#09-06 Gateway EastSingapore, 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 HP-UX 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.

pjb1666063951.doc

 2000-2005 OSIsoft, Inc All rights reserved

777 Davis Street, Suite 250, San Leandro, CA 94577

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

PI-Interface Configuration Utility 9

Interface Directories 9

The PIHOME Directory Tree 9

Interface Installation Directory 10

Interface Installation Procedure 10

Naming Conventions and Requirements 10

Installing the Interface as a Windows Service 11

Installing the Interface Service with PI-Interface Configuration Utility 11

Installing the Interface Service Manually 13

Digital States 15

PointSource 17

Interface Point Configuration 19

Point Attributes 19

Tag 19

PointSource 19

PointType 19

Location1 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 45

pisnmp.ini File Obsolete 46

Interface Node Clock 47

Security 49

Starting / Stopping the Interface 51

Using the PI-ICU 51

Not Using the PI-ICU 51

Buffering 53

Configuring Buffering with PI-ICU 53

Configuring Buffering Manually 56

Example piclient.ini File 58

Appendix A: Error and Informational Messages 59

Message Logs 59

Messages 59

Location5 60

System Errors and PI Errors 61

Common Problems 61

Unexpected Value 61

PI-SNMP Startup 62

Point Loading 62

No New Value 63

Value of 0 64

I/O Timeout 64

Bad Input 64

Configure 65

Missed Scans 65

Appendix B: snmpget 67

Appendix C: OID Examples 69

Appendix D: Basic SNMP for PI Users 71

Appendix E: Tutorial on Using PI-SNMP with Routers 75

Appendix F: PI-SNMP Technical Details 81

Appendix G: ifAlias Support 83

Appendix H: Known Issues 87

Appendix I: Acknowledgments 89

Revision History 91

OSIsoft’s PI-SNMP data collection interface program gathers information from enabled devices residing in a TCP/IP network The operation of PI-SNMP requires thatthese devices be able to send and receive messages via the SNMP protocol In

SNMP-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 Basic

purchase Installed as part of PI Server 3.3 and higher

Must send data to the PI Server node on which it runs

Number of copies that can run

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

APS Connector Currently Available No

PI Point Types PI 3.x (float16 / float32 / float64 / int16 /

int32 / digital / string)

Automatically Incorporates PI Point

Inputs to PI: Scan-based / Unsolicited /

Maximum Point Count Point Count of PI Server (full version only)

PINet to PI 3.x String Support Not applicable

* Additional PI Software Included with

* 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 UniInt-supplied 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 comewith 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

4

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, andprivacy 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 SNMPAgent 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 thestatistic 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

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 networkdevices to the PI Server Time-based inputs occur at fixed time frequencies

Event-based 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

Installation Checklist

For those users who are familiar with running PI data collection interface programs, this checklist helps you get the PI-SNMP Interface running If you are not familiar with PI interfaces, you should return to this section after reading the rest of the manual

in detail

You should follow the steps in the order listed below

1 Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)

2 If you plan on using the PI SNMP Tag Builder plug-in on the interface node, install PI SMT 3.x

3 Confirm PI-API connectivity to the PI Server by running the apisnap program

4 Run the PI-SNMP installation program

5 Test the connection between the PI Interface node and the SNMP Agent by using

snmpget or the PI SNMP Tag Builder plug-in for PI SMT 3.x.

6 Choose a point source for use by the Interface

7 Use the PI-ICU to configure startup parameters Alternatively, manually edit the startup command file

8 Configure PI points to be used by the Interface You can run the PI SNMP Tag

Builder plug-in Or, you can use another utility and follow these guidelines: Location1 is the interface instance.

Location2 tells the Interface to store the changes in value rather than the absolutevalue Location2 also indicates input (SNMP Agent to PI Server) or output (PI Server to SNMP Agent)

Location3 tells the Interface to group common points.

Location4 is the scan class.

Location5 enables point level debugging

ExDesc holds the OID (i.e., variable to retrieve) For SNMPv1 and SNMPv2c

points, the Extended Descriptor holds the community string For SNMPv3 points, the Extended Descriptor holds a username, authentication type, authentication password, and privacy password

InstrumentTag specifies the SNMP Agent

9 Configure performance points

10 Configure an I/O Rate point

11 Modify the security of the PI Server For PI 3.x, edit the PI Trust or PI Proxy table

as appropriate

12 Stop the PI Buffer Server

13 Interactively start 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 Confirm that the Interface re-starts after a complete machine shutdown and restart

Interface Installation

OSIsoft recommends that you install PI data collection interface programs on PI Interface nodes instead of on PI Server nodes A PI Server node is a computer on which the PI Server runs A PI Interface node is any computer that has the PI Application Programming Interface (PI-API) installed and which is not a PI Server node

The primary function of a PI Server node is to run the applications that compose the PI Server These applications archive data and provide data to client computers that request them Thus, if PI interface programs are absent from the PI Server node, then

PI Server applications need not compete with these interface programs for this computer’s resources

After you have installed and tested the Interface, you should enable the PI Buffer Server application PI Buffer Server (also known as Bufserv) is a utility program distributed with the PI-API It provides the capability to store and forward events to the PI Server The primary purpose of Bufserv is to allow continuous data collection when communications between the PI Interface node and the PI Server is lost

Communications will be lost when network problems exist, or when the PI Server is shut down because of maintenance, upgrades, backups, or unexpected failures

Please see the PI-API Installation manual for instructions on installing the PI-API and

PI Buffer Server

After confirming that the Interface and PI points have been configured properly to collect data, you should install the Interface as an automatic service under Windows AWindows service keeps running even after the user has logged off An automatic service automatically restarts when the computer itself restarts This feature is useful

in the event of an interruption in electrical power to the computer

PI-Interface Configuration Utility

The PI-Interface Configuration Utility is an application that aids in PI System management by consolidating the setup and configuration options required for new and existing PI Interfaces Although PI-ICU itself runs only on Windows machines, it is compatible with all PI Server versions 3.3.361.43 or higher

PI-ICU must be installed on the computer on which the interface is installed

Interface Directories

The PIHOME Directory Tree

Installation of the PI-API (or any other OSIsoft product that runs on Microsoft Windows) creates the PIHOME directory tree In particular, it creates a PIHOME entry

in the pipc.ini configuration file The pipc.ini file is an ASCII text file located in the directory where Windows itself is installed

A typical pipc.ini file contains the following lines:

[PIPC]

PIHOME=C:\pipc

The above entry defines the C:\pipc directory as the root of the PIHOME directory tree on the C: drive The PIHOME directory does not need to be on the C: drive.

Interface Installation Directory

The PI-SNMP Interface is installed typically under the PIHOME directory in a subdirectory named \interfaces\snmp For example,

C:\pipc\interfaces\snmp

The basic version of PI-SNMP is installed typically under the PIHOME directory in a subdirectory named \interfaces\snmp_basic For example,

C:\pipc\interfaces\snmp_basic

Interface Installation Procedure

The PI-SNMP interface setup program uses the services of the Microsoft Windows Installer Windows Installer is a standard part of Windows 2000 When running on Windows NT 4.0 systems, the PI-SNMP setup program will install the Windows Installer itself if necessary To install, run the PISNMP_x.x.x.x.exe installation kit After you run the setup program, a directory structure and files such as the following result:

C:\pipc\interfaces\snmp\mibs\*.txt C:\pipc\interfaces\snmp\libsnmp.dll C:\pipc\interfaces\snmp\pi_pisnmp.doc C:\pipc\interfaces\snmp\pi_pisnmp_x.x.x.x.txt C:\pipc\interfaces\snmp\pisnmp.bat.new

C:\pipc\interfaces\snmp\pisnmp.exe C:\pipc\interfaces\snmp\pisnmp.pdb C:\pipc\interfaces\snmp\pisnmp.pwd C:\pipc\interfaces\snmp\snmpget.bat.new C:\pipc\interfaces\snmp\snmpget.exe C:\pipc\interfaces\snmp\snmpwalk.bat.new C:\pipc\interfaces\snmp\snmpwalk.exe

The basic version of PI-SNMP is installed as part of the PI Server A directory structure and files such as the following result:

C:\pipc\interfaces\snmp_basic\pi_pisnmp.doc C:\pipc\interfaces\snmp_basic\pi_pisnmp_x.x.x.x.txt C:\pipc\interfaces\snmp_basic\pisnmp_basic.bat.new C:\pipc\interfaces\snmp_basic\pisnmp_basic.exe

and so on

Naming Conventions and Requirements

If you run multiple copies of the Interface, it is customary for you to copy and rename the executable and the startup command files For example, you would typically have

pisnmp1.exe and pisnmp1.bat for interface instance number 1, pisnmp2.exe and

pisnmp2.bat for interface instance number 2, and so on The reason is that when an

interface runs as a service (e.g., pisnmp1), it looks for a command file (e.g.,

pisnmp1.bat) that has the same root name as the executable (e.g., pisnmp1.exe).

So, for the above example, you should have the following files:

C:\pipc\interfaces\snmp\pisnmp1.exe C:\pipc\interfaces\snmp\pisnmp1.bat C:\pipc\interfaces\snmp\pisnmp2.exe C:\pipc\interfaces\snmp\pisnmp2.bat

However, if you are using the PI-ICU, then the above renaming requirements do not apply because the PI-ICU manages multiple copies of interfaces without your having tocopy and rename files

Installing the Interface as a Windows Service

To install the Interface as a Windows service, you can

 use the PI-Interface Configuration Utility, or

 manually enter commands

The next two sections describe these procedures

Installing the Interface Service with PI-Interface Configuration Utility

The PI-Interface Configuration Utility provides a graphical user interface for creating, editing, and deleting the Interface as a Windows service However, before you can create the PI-SNMP Interface service, you first have to configure PI-ICU to recognize the Interface

From the PI-ICU menu, select Interface, New, and then Browse to the pisnmp.exe executable file Then, enter values for Point Source and Interface ID# A window such

as the following results:

Click Add

You should then see a display such as the following:

Interface Installation

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

Also, add an entry for the Scan Classes The value of this entry specifies the frequency

at which PI-SNMP polls SNMP Agents

Click Apply to enable PI-ICU to manage this copy of the PI-SNMP Interface.

To install the Interface as a service, click on the Service tab

The above shows that this pisnmp1 service is dependent on the bufserv (PI-Buffer Server) service

Finally, click on Create to create the interface service.

If you wish to remove the interface service, click on Remove.

To start the PI-SNMP Interface service, click on the start button ( ) located on the PI-ICU toolbar

When the PI-SNMP Interface service is currently running, you can click on the stop button ( ) to stop it

You can determine the current status of the Interface service by looking at the lower portion of the PI-ICU screen For example,

shows that the Interface service is currently installed, but it is stopped

Installing the Interface Service Manually

You can get help for installing the interface as a Windows service by using the -helpcommand line parameter For example,

C:\pipc\interfaces\snmp\pisnmp.exe –help

Interface Installation

C:\pipc\interfaces\snmp_basic\pisnmp_basic.exe –help

To manually install the Interface service, open a Windows command prompt window and go to the directory where the pisnmp.exe executable is located Then, consult thefollowing table to determine the appropriate service installation command

Windows Service Installation Commands on a PI Interface Node

with Bufserv Implemented

Manual service pisnmp.exe –install –depend "bufserv pinetmgr" –display

"PI-SNMP"

Automatic service pisnmp.exe –install –auto –depend "bufserv pinetmgr" –display

"PI-SNMP"

Windows Service Installation Commands on a PI Interface Node

without Bufserv Implemented

Manual service pisnmp.exe –install –depend "pinetmgr" –display "PI-SNMP"

Automatic service pisnmp.exe –install –auto –depend "pinetmgr" –display "PI-SNMP"

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

Digital States

For more information regarding Digital States, refer to the PI Server Manuals

User-defined Digital State Sets

PI 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

You can store into a PI digital point those device values that can be represented as discrete data For example, for the OID

interfaces.ifTable.ifEntry.ifOperStatus, the list of strings and discrete values are:

 Up (1)

 Down (2)

 Testing (3)However, because PI enumerates digital state values from 0, you need create the digitalstate set for the above values with a “dummy” first entry For example, to use

piconfig to create a custom digital state set called OperStat:

C:> piconfig (Ls - ) PIconfig> @table pids (Ls - PIDS) PIconfig> @mode create (Cr - PIDS) PIconfig> @istr set, state, (Cr - PIDS) PIconfig> OperStat, dummy, up, down, testing

You can also use the PI Digital State Editor plug-in for PI SMT 3 to create user-defineddigital state sets:

System Digital State Set

Similar to user-defined digital state sets is the system digital state set This set is used for all points, regardless of point type, to indicate the state of a point at a particular time For example, you can configure the Interface so that when it shuts down, it writesthe system digital state Intf Shut to all the points for which it had been collecting data

The PI point is the basic building block for controlling data flow to and from the

PI Server The PointSource attribute is a single character that is used to identify a PI point as one that belongs to a particular interface For example, you may choose the letter $ to identify points that belong to the PI-SNMP Interface To implement this identification, configure PI points such that their PointSource attribute is $ Then, if you use -ps=$ on the Interface’s startup command line (described later) and start the Interface, PI-SNMP receives from PI Server a list of every point that has its

PointSource set to $

However, before the Interface begins data measurement for a point from this list, it examines additional PI point attributes This examination further determines the validity of a PI point for use with the Interface For additional information, see the section on Point Configuration and the description of the -ps parameter in Startup Commands

PI Server version 3.x comes pre-configured with applications that use some of the otherwise available point source characters Accordingly, you should not use any of thefollowing point source characters to associate PI points with the PI-SNMP Interface:

PI Point Configuration

The PI point is the basic building block for controlling data flow to and from PI Server You configure a single point for each measurement value that needs to be archived Usethe point attributes below to define the data to measure

Point Attributes

Every two minutes, PI-SNMP 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-SNMP can process only 25 point changes every 30 seconds If more than

25 points are added, edited, or deleted, PI-SNMP 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

Use the point attributes below to define how PI-SNMP associates PI points with data available from SNMP Agents

Note: The PI SNMP Tag Builder plug-in to PI SMT 3.x is recommended for tag building.

PI-SNMP supports the retrieval of SNMP data into the following PI point types:

SNMP Data Types

SNMP data types are typically integers and octet strings Store SNMP integer data into

a PI point of PointType Int16, Int32, Float16, Float32, or Float64 If SNMP integers will always be part of a predetermined set of values (e.g., 1 through 5), these integers may be stored in a PI Digital point Store SNMP octet strings into a PI point of PointType String

Location1

Location1 indicates to which copy of the interface the point belongs The value of this attribute must match the -id startup parameter

Location2

The Location2 attribute determines whether a point is an input or an output

Input – Location2 greater than or equal to zero Output – Location2 negative

Input Points

For input points, Location2 affects how PI-SNMP sends SNMP “counter” values to the

PI Server Specifically, you can tell PI-SNMP to collect counter values not as an absolute number but as a rate That is, the value sent to PI Server is the difference between the scanned value and the previous value divided by the time (in seconds) between scans

Set Location2 to 0 for SNMP values that are not “counter.”

SNMP type Location2 Value sent to the PI

For example, if Location2 is set to 1:

scanned value = 2000 previous value = 200 scan time = 1 minute value sent to PI Server = (2000 – 200)/60 = 30

The “previous value” mentioned above refers to the value read by PI-SNMP and not to the previous value in the PI Server Thus, for points with Location2 set to 1, it initially takes PI-SNMP two scans before it sends a value to the PI Server

Whenever Location 2 is set to 1, the value as returned from the SNMP Agent must be

of type “counter” as defined in the MIB Otherwise, PI-SNMP writes the digital state CONFIGURE to the point However, it is permissible for an SNMP “counter” value to have Location2 set to 0 In this case, the scanned value is sent to the PI Server

Output Points

For output points (Location2 less than zero), Location2 specifies the SNMP data type that the Interface uses to perform an SNMP SET to an OID value The following table indicates the acceptable Location2 values for an output point

Location2 SNMP Data Type Example / Comments

Interface Point Type Source Point Type SNMP Data Type and Value

In the table above, an interface or source point type of Integer refers to Int16 and Int32.Similarly, a source point type of Float refers to Float16, Float32, and Float64

For output points, the Interface does not support an interface point type of Digital, Float16, Float32, or Float64

Be sure to use the –out startup command parameter (described later) to enable SNMP SET/PI output support in the Interface

Location3

For input points, the Location3 attribute indicates whether the point is a part of a set of multiple OID requests to be sent to a network device By default, PI-SNMP sends a single request for each PI point to retrieve its corresponding OID value If Location3 isset to 1, then PI-SNMP groups together the point with other points that have these identical attributes:

 SNMP device name (host= in the InstrumentTag)

 community string (CS= in the ExDesc) for SNMPv1 and SNMPv2c points

 username (USER= in the ExDesc) for SNMPv3 points

 Location4 value or PI event tagPI-SNMP groups these points into sets of up to 5 This size is configurable, and its configuration is described in a later section Then, for every set, PI-SNMP sends a single request to the SNMP Agent on the network device in order to retrieve these 5 OID values

PI Point Configuration

Note: Be aware that the grouping of points into a set requires the specification of

identical network device names That is, even though host=router and

host=192.168.100.10 may refer to the same network device, PI-SNMP will not group a point configured with host=router together with a point configured with host=192.168.100.10.

When PI-SNMP first starts up, it prints a summary of the sets it has allocated For example,

PI-SNMP- 1> There are 5 points/tags with Location3=1; Summary:

PI-SNMP- 1> Set=1, Device=router, Scan class=2, Tags=4 PI-SNMP- 1> Set=2, Device=router, Event tag=router_rx_Ethernet0/0, Tags=1

A single request for multiple OIDs increases data collection efficiency However, such

a message may be so large in physical size that it will be fragmented into multiple packets and may not reach its destination Also, a message with requests for multiple OIDs may overwhelm the capability of the SNMP Agent on the network device

In addition, if the SNMP agent on the network device indicates that it does not

recognize any one of the OIDs in this set, PI-SNMP writes Configure for all of the

points in this set PI-SNMP also writes to the log file messages similar to the following:

PI-SNMP- 1> Device reports at least 1 unknown OID in the following set of 2 tags: PI-SNMP- 1> Tag: router_tx_Ethernet0/0, OID: interfaces.ifTable.ifEntry.ifOutOctets.85 PI-SNMP- 1> Tag: router_jab_4, OID: rmon.statistics.etherStatsTable.EtherStatsEntry etherStatsJabbers

To find out which point contains the unsupported OID, use the snmpget program (described later)

Event-based Inputs

Location 4 should be set to zero for these points See the section on the ExDesc for more information on event-based inputs

22

to stop and restart the program for changes to Location5 to take effect.

InstrumentTag

The InstrumentTag attribute holds the IP address or hostname of the SNMP device for which to retrieve a value (i.e., input point) or to send a value (i.e., output point) Examples of an InstrumentTag attribute are:

Object Identifier (OID=)

This item is necessary to specify the SNMP OID whose value the Interface is to collect

or to set For example,

Key Identifier (KEY=)

When a router reboots, it often assigns a different index number to a particular instance

of one of its network interfaces For example, an interface named Serial1/0.1 has

an ifIndex value of 25 Thus, the OID variable

PI Point Configuration

interfaces.ifTable.ifEntry.ifInOctets.25

represents the number of inbound octets received on this Serial1/0.1 interface Accordingly, you may have a PI point named tag1 configured with an Extended Descriptor such as:

OID_I=ifInOctets.25

After a router reboot, the Serial1/0.1 interface may be assigned an ifIndex of 31 Therefore, the number of inbound octets received on the interface is now given by the OID

interfaces.ifTable.ifEntry.ifDescr.X

and put these into the KEY= entries

Currently, the Interface uses the KEY value only for input points, and only to match values of

interfaces.ifTable.ifEntry.ifDescr.X

with OIDs from the interfaces group

24

In addition, a Cisco router may support the following command:

router(config)# snmp-server ifindex persist

Such a command tells the router not to renumber the interface indices after a reboot Inthis situation, the KEY= identifier will not be necessary

Note: After issuing ifIndex persistence commands, it is necessary to save the

configuration by using the copy running-config startup-config EXEC mode command toensure consistent ifIndex values See the Cisco IOS documentation for more

information

Row Identifier (OID_G= and OID_G_R=)

Another option for dealing with certain dynamic OIDs is to specify the sequence number of an OID within a particular group This is accomplished by using the OID_G= parameter to specify an OID group and OID_G_R= to designate the row within that group For example, a group of OIDs may be:

.1.3.6.1.2.1.87.1.3.1.3.25 1.3.6.1.2.1.87.1.3.1.3.49 1.3.6.1.2.1.87.1.3.1.3.53

during one scan On the next scan, this group may be:

.1.3.6.1.2.1.87.1.3.1.3.19 1.3.6.1.2.1.87.1.3.1.3.44 1.3.6.1.2.1.87.1.3.1.3.54

If an Extended Descriptor is:

OID_G=.1.3.6.1.2.1.87.1.3.1.3; OID_G_R=2;

the interface will read from 1.3.6.1.2.1.87.1.3.1.3.49 on the first scan, and

1.3.6.1.2.1.87.1.3.1.3.44 on the second scan.

SNMP IP Address Data Type (IPADDR=)

If the data type returned from the SNMP device is an IP Address, the Interface can store the dotted decimal representation of the IP Address Put the following in the Extended Descriptor for a PI string point:

IPADDR=1;

That is, PI-SNMP will store a value such as “192.168.10.1” Otherwise, PI-SNMP will not be able to store the IP Address (which is a 32-bit numeric value) into the PI string point

SNMP Version (V=)

Specify the version of SNMP to use with the V= parameter:

Version Extended Descriptor

PI Point Configuration

If a version is not specified, the Interface defaults to SNMPv1

SNMPv1 / SNMPv2c Community String (CS= and WCS=)

If this point is to read a value using SNMPv1 or SNMPv2c, the correct SNMP community string must be specified via the keyword CS= For example,

or –enc startup parameter (described later) and put the community string in a file called pisnmp.pwd Thus, if –pwd or –enc is specified in the startup command file, donot put CS= or WCS= in a point’s Extended Descriptor

SNMPv3 Username (USER=)

If this point is to be read using SNMPv3, a username is required Specify the username

in the Extended Descriptor as follows:

USER=username;

The username may instead be specified in the pisnmp.pwd file

SNMPv3 Authentication Password (APW=)

The SNMPv3 agent may require an authentication password, in order to verify that the request came from a trusted source This authentication password can be specified in the Extended Descriptor, for example:

APW=password;

The authentication password may instead be specified in the pisnmp.pwd file

SNMPv3 Authentication Protocol (AUTH=)

One of two authentication protocols may be specified:

AUTH=MD5;

for MD5 authentication, or

AUTH=SHA;

for SHA authentication Consult the documentation for the device to determine which

to use If neither is specified, the interface will default to MD5 This parameter may instead be specified in the pisnmp.pwd file

SNMPv3 Privacy Password (PPW=)

The SNMPv3 agent may require that the data request be encrypted for privacy The DES encryption algorithm uses a plain-text password to generate a key used to encrypt the message This password can be specified in the Extended Descriptor as follows:

PPW=password;

The privacy password may instead be specified in the pisnmp.pwd file

26

Event-based Data Collection (EVENT=)

If the Interface is to collect SNMP values at times based on an event in a PI point rather than based on a periodic time interval, specify the following at the beginning of the Extended Descriptor:

The Interface checks the extended descriptor for the string

“PERFORMANCE_POINT” If it finds this character string, the Interface treats this point as a performance point See the section called “Performance Points.”

Summary of Information Specified in Extended Descriptor

OID=

OID_I=

OID_G= and OID_G_R=

OID_G= is required OID_G_R= is required

when OID_G= is used

before sending value to PI Server

No

IPADDR=1 Store IP Address as dotted

decimal into a PI string point No

Community String for input points

Yes, if using SNMPv1 or SNMPv2 for inputs

Community String for output points

Yes, if using SNMPv1 or SNMPv2 for outputs

PI Point Configuration

Scan

By default, the Scan attribute has a value of 1, indicating that the Interface will retrieveSNMP values for the point Setting the scan attribute to 0 tells the Interface not to retrieve SNMP values for the point If the scan attribute is 0 when the Interface starts, PI-SNMP writes the SCAN OFF digital state to the point If you change the scan attribute from 1 to 0 while the Interface is running, PI-SNMP also will write SCAN OFF

to the point after it has detected this point attribute change

There is one other situation, which is independent of the Scan attribute, where PI-SNMP 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, PI-SNMP removes the point from service, and writes SCAN OFF to the point For example, if youchange the PointSource of a PI point that is currently loaded by PI-SNMP, the Interfacewill no longer service the point and write SCAN OFF to it

Shutdown

The 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 the PI Server manuals

By setting the Shutdown attribute to 0 for each point, you can disable SHUTDOWN events from being written when PI Server restarts

Alternatively, you can change the default behavior of the PI Shutdown Subsystem as described above You will need to edit the Shutdown.dat file to do so Please see the

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 you specify the -stopstat=Shutdown command-line parameter.

Bufserv

It is undesirable to write shutdown events when Bufserv (PI Buffer Server) 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 Server is shut down, Bufserv will continue to store data collected by the interface, making it undesirable to write SHUTDOWN events to the PI points serviced by this interface

SourceTag

The SourceTag attribute is used only for output points The SourceTag is the name of the PI point whose value will be written to the SNMP device The interface point is thepoint that contains the actual OID reference to the SNMP device

For example, to perform an SNMP SET

 to a device with IP address 192.168.10.100;

 to the OID 1.3.6.1.4.1.4761.99.1.4.0;

28

 with the value of 2The attributes for the interface point should be similar to:

Conversion

PI-SNMP uses the value in the conversion attribute as a multiplier PI-SNMP multiplies the scanned value by the conversion attribute value before sending it to the

PI Server

Note: If this attribute is set to 0, all values for the point will be 0 A warning message is

sent to the log file when the point is loaded

Performance Point Configuration

One can configure performance points to monitor the amount of time in seconds that aninterface takes to complete a scan for a particular scan class The closer the scan completion time is to 0 seconds, the better the performance The scan completion time

is recorded to millisecond resolution

Configuring Performance Points with PI-ICU

The PI-Interface Configuration Utility (PI-ICU) provides a graphical user interface for creating and managing Performance Points

Create

To create a Performance Point, right mouse click the line belonging to the tag to be

created, and select Create

Delete

To delete a Performance Point, right mouse click the line belonging to the tag to be

deleted, and select Delete

Correct

If the “Status” of a point is marked “Incorrect”, you can automatically correct the point configuration by using PI-ICU and right mouse clicking on the line belonging to the tag

to be corrected, and selecting Correct The Performance Points are created with the

following PI attribute values If PI-ICU detects that a Performance Point is not defined

with the following, the Performance Point will be marked Incorrect:

Descriptor Interface name + “ Scan Class # Performance Point”

 Created – Indicates that the Performance Point does exist

 Not Created – Indicates that the Performance Point does not exist

 Deleted – Indicates that a Performance Point existed, but was just deleted by the user

Scan Class

The Scan Class column indicates which scan class the Performance Point in the

Tagname column belongs to There will be one scan class in the Scan Class column for

each scan class listed in the Scan Classes combo box on the Uniint Parameters tab.

Tagname

The Tagname column holds the Performance Point tag name.

Snapshot

The Snapshot column holds the snapshot value of each Performance Point that exists in

PI The Snapshot column is updated when the Performance Points/Counters tab is

clicked, and when the interface is first loaded

Configuring Performance Points Manually

Performance point configuration is the same on all operating system platforms You configure Performance points as follows

1 Set the Extended Descriptor to contain:

PERFORMANCE_POINT

or to:

PERFORMANCE_POINT=interface_id

where interface_id corresponds to the number that is specified with the

-id parameter on the startup command line of the Interface The character string

PERFORMANCE_POINT is case insenstive The interface_id does not need to be

specified if there is only one copy of an interface that is associated with a particular point source

2 Set Location4 to correspond to the scan class whose performance is to be monitored For example, to monitor scan class 2, set Location4 to 2 See the -fstartup parameter for a description of scan classes

3 Set the PointSource attribute to correspond to the -ps parameter on the startup command line of the Interface

4 Set the PointType attribute to float32

I/O Rate Point Configuration

An 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 sent by the Interface to the PI Server Because values are averaged over a 10-minute interval, the first value is not written to PI Server until 10 minutes after the Interface has started You can configure one I/O Rate point for each copy of the Interface that is in use

PI System documentation often use the terms Event Counter Tag and I/O Rate Point

synonymously

Monitoring I/O Rates on the Interface Node

Because an I/O Rate point is a PI point, you can use standard PI client applications to monitor its value For example, you 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 Points with PI-ICU

The PI-Interface Configuration Utility (PI-ICU) provides a graphical user interface for creating and managing I/O Rate Points

Enable IORates for this Interface

The Enable IORates for this interface check box enables or disables the I/O Rate point

for the Interface To disable the I/O Rate point, uncheck this box To enable the I/O Rate point, check this box

Tag Status

The Tag Status column indicates whether the I/O Rate point currently exists in PI

Server The possible states are:

 Created – This status indicates that the point exists in PI Server

 Not Created – This status indicates that the point does not yet exist in PI Server

 Deleted – This status indicates that the point has just been deleted

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

In File

The In File column indicates whether the I/O Rates point listed in the Tagname column and the event counter number listed in the Event Counter column are in the

IORates.dat file The possible states are:

 Yes – This status indicates that the I/O Rate point and the event counter number are in the IORates.dat file

 No – This status indicates that the I/O Rate point and the event counter numberare not in the IORates.dat file

Event Counter

The Event Counter number correlates a point specified in the IORates.dat file

with this Interface This correlation results from the command line parameter

IORates/Status Tags tab is clicked, and when the interface is first loaded.

Right Mouse Button Menu Options

If the Enable IORates for this interface box is checked, you can use the right mouse

button to bring up the following menu options

Configuring I/O Rate Points Manually

There are two main steps The first occurs on PI Server and the second on the computer on which the Interface runs

Configuring the I/O Rate Point on the PI Server

Create an I/O Rate Point with the following PI point attribute values

Configuration on the Interface Node

The following procedure for I/O Rate point configuration on the interface node assumesthat the tag name of this point is sysnmp01 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 You can find out the name of this PI-API directory by looking at the pipc.ini file located in the Windows directory 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

Startup Command File

Using PI-ICU to Maintain Startup Command File

On Windows, the PI-Interface Configuration Utility (PI-ICU) is a graphical tool that allows you to configure the Interface’s startup command file When using the PI-ICU,

select “pisnmp” for the Type of interface That is,

The interface-specific tab (i.e., “pisnmp”) allows you to enter values for the startup parameters that are particular to PI-SNMP That is,

1 Using pisnmp.pwd instead of Exdesc

This check box tells the Interface not to look for the community string or SNMPv3 security information in a point’s Extended Descriptor Instead, the Interface should use

a file called pisnmp.pwd Selecting this check box is equivalent to specifying –pwd inthe startup command file

The pisnmp.pwd file is a plain text file Use any standard text editor such as

notepad to create or modify this file The format of its contents is similar to the

specification of host and security information in a PI point’s instrument tag and extended descriptor attributes:

host=device_name; user comments CS=community_string; read community string of previous entry

Or, for SNMPv3 agents:

host=device_name; user commentsUSER=username; SNMPv3 usernameAUTH=MD5; Authentication protocol Can be MD5 or SHAAPW=password; Authentication password

1 2

3

4 5 6 7 8

9

1 0 1 1

1 3

1 2

PPW=password; Privacy passwordFor example,

host=router1; router1 is our main router CS=public; read community string for <router1>

host=192.168.100.10 CS=company123; read community string for <192.168.100.10>

WCS=company456; write community string for <192.168.100.10> host=switch2;

CS=gnomes11; read community string for <switch2>

host=router3;

USER=manager; SNMPv3 user for <router3>

AUTH=SHA; Use SHA authentication APW=23oaktree; authentication password for <router3>

PPW=hummingbird; privacy password for <router3>

Note that blank lines are allowed only at the end of the file Also, only one community string or username can be specified for a particular host If you need to use multiple community strings or usernames to access different data on the same SNMP agent, you’ll need to either run a separate copy of the interface, or create separate aliases for the SNMP device in the interface node’s hosts file You can then create an entry in

pisnmp.pwd for each alias.

2 The pisnmp.pwd file has been encryptedThis tells the interface that the pisnmp.pwd file is to be encrypted If you don’t want the information in pisnmp.pwd to be stored in plaintext, check this box When the interface starts, it will read the pisnmp.pwd file and encrypt the contents to a file named pisnmp.enc The pisnmp.pwd file is deleted after it is encrypted, so back it up

if you want to keep a copy for reference If you wish to edit the attributes for a particular host after those attributes have been encrypted, create a new pisnmp.pwdwith the new security information and restart the interface The new host record in

pisnmp.pwd will be encrypted and will replace the old encrypted host record Any

host records in pisnmp.enc that do not have replacement records in pisnmp.pwd willremain So, for example, if you have security information for ten hosts in pisnmp.enc and you wish to change only one of them, just create a record for that one particular host in pisnmp.pwd The other host records in pisnmp.enc will be left untouched Selecting this check box is equivalent to specifying –enc in the startup command file

3 Edit pisnmp.pwdThis button opens the pisnmp.pwd file with the Notepad application for editing

4 Number of GetRequest retriesThe number in this text box specifies the number of times PI-SNMP retries its transmission of an SNMP GetRequest message to the network device The default number of retries is 3 This setting is equivalent to the –retries= parameter in the startup file

5 Number of tags per setThe number in this text box specifies the number of tags per set When Location3=1, PI-SNMP groups tags into a set in order to get multiple OID values for a single SNMP