SNMP Interface to the PI System

Versions 1.4.0.0 Revision D How to Contact Us

OSIsoft, Inc. Worldwide Offices

777 Davis St., Suite 250 OSIsoft Australia San Leandro, CA 94577 USA Perth, Australia Auckland, New Zealand Telephone OSI Software GmbH (01) 510-297-5800 (main phone) Altenstadt, Germany (01) 510-357-8136 (fax) (01) 510-297-5828 (support phone) OSI Software Asia Pte Ltd. Singapore [email protected] OSIsoft Canada ULC Montreal, Canada Houston, TX OSIsoft, Inc. Representative Office Johnson City, TN Mayfield Heights, OH Shanghai, People’s Republic of China Phoenix, AZ OSIsoft Japan KK Savannah, GA Tokyo, Japan Seattle, WA OSIsoft Mexico S. De R.L. De C.V. Yardley, PA Mexico City, Mexico Sales Outlets and Distributors  Brazil  South America/Caribbean  Middle East/North Africa  Southeast Asia  Republic of South Africa  South Korea  Russia/Central Asia  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.

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 The PIHOME Directory Tree...... 14 Interface Installation Directory...... 14 Interface Installation Procedure...... 14 Installing the Interface as a Windows Service...... 15 Installing the Interface Service with PI Interface Configuration Utility...... 15 Installing Interface Service Manually...... 17

Digital States...... 19

PointSource...... 21

PI Point Configuration...... 23 Point Attributes...... 23 Tag...... 23 PointSource...... 23 PointType...... 24

SNMP Interface to the PI System iii Table of Contents

Location1...... 24 Location2...... 24 Location3...... 26 Location4...... 27 Location5...... 27 InstrumentTag...... 27 ExDesc...... 28 Scan...... 33 Shutdown...... 33 SourceTag...... 34 Conversion...... 34

Performance Point Configuration...... 35 Configuring Performance Points with PI ICU...... 35 Configuring Performance Points Manually...... 36

I/O Rate Point Configuration...... 37 Monitoring I/O Rates on the Interface Node...... 37 Configuring I/O Rate Points with PI ICU...... 37 Configuring I/O Rate Points Manually...... 38 Configuring the I/O Rate Point on the PI Server...... 39 Configuration on the Interface Node...... 39

Startup Command File...... 41 Configuring the Interface with PI ICU...... 41 pisnmp Interface Tab...... 44 Command-line Parameters...... 47 Sample pisnmp.bat File...... 52 pisnmp.ini File -- Obsolete...... 52

Interface Node Clock...... 53

Security...... 55

Buffering...... 57 Configuring Buffering with PI ICU...... 57 Configuring Buffering Manually...... 60 Example piclient.ini File...... 61

Appendix A: Error and Informational Messages...... 63

iv Message Logs...... 63 Messages...... 63 Location5...... 64 System Errors and PI Errors...... 65 Common Problems...... 65 Unexpected Value...... 65 PI SNMP Startup...... 66 Point Loading...... 66 No New Value...... 67 Value of 0...... 68 I/O Timeout...... 68 Bad Input...... 68 Configure...... 69 Missed Scans...... 69

Appendix B: snmpget...... 71

Appendix C: OID Examples...... 73

Appendix D: Basic SNMP for PI Users...... 75

Appendix E: Tutorial on Using PI SNMP with Routers...... 79

Appendix F: PI SNMP Technical Details...... 85

Appendix G: ifAlias Support...... 87

Appendix H: Known Issues...... 91

Appendix I: Acknowledgments...... 93 Net-SNMP...... 93 OpenSSL...... 97

Revision History...... 99

SNMP Interface to the PI System v 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 Basic Maximum point count Point count of PI 32 Server Availability Available for Installed as part of PI purchase 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 No Yes node on which it runs Number of copies that can run Unlimited 1 simultaneously 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).

SNMP Interface to the PI System 1 Introduction

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 Interface User Manual  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 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 PI Point Yes Attribute Changes Exception Reporting Yes Outputs from PI Yes Inputs to PI: Scan-based / Unsolicited / Scan-based / Event Tags Event Tags Supports Questionable Bit No Supports Multi-character PointSource Yes

2 Feature Support 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 Yes Disconnected Startup Yes * SetDeviceStatus Yes Failover No Vendor Software Required on PI Interface No Node * Vendor Software Required on Foreign Yes Device Vendor Hardware Required No * Additional PI Software Included with Yes Interface * 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 and greater. 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 UniInt-supplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.

SNMP Interface to the PI System 3 Introduction

The UniInt Interface User Manual is a supplement to this manual. SetDeviceStatus The Interface is built with UNIINT 4.3.0.31. New functionality has been added to support 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.

4 Diagram of Hardware Connection

SNMP Interface to the PI System 5 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

SNMP Interface to the PI System 6 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 PI SNMP 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. Event-based inputs occur whenever there is a change in value in the PI event point.

SNMP Interface to the PI System 7 Principles of Operation

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.

8 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 the user is unfamiliar with PI interfaces, he/she should 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. 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. Run the PI SNMP Tag Builder plug-in or 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 absolute value. 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.

SNMP Interface to the PI System 9 Interface Installation

OSIsoft 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 a power failure. 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. This typical scenario assumes that Bufserv is not enabled on the PI Server node. 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 Requirements

In the installation procedure below, it is assumed that the name of the interface executable is pisnmp.exe and that the startup command file is called pisnmp.bat. It is customary for the user to rename the executable and the startup command file when multiple copies of the interface are run. For example, one would typically use pisnmp1.exe and pisnmp1.bat for interface number 1, pisnmp2.exe and pisnmp2.bat for interface number 2, and so on. When an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line parameters in a file that has the same root name. 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. So, for the above example, the following files should be present: C:\pipc\Interfaces\snmp\pisnmp1.exe C:\pipc\Interfaces\snmp\pisnmp1.bat

SNMP Interface to the PI System 10 C:\pipc\Interfaces\snmp\pisnmp2.exe C:\pipc\Interfaces\snmp\pisnmp2.bat However, if the PI ICU is used, then the above renaming requirements do not apply because the PI ICU manages multiple copies of interfaces without the user having to copy and rename files. 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 running 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. Installing the Interface as a Windows Service

The PI SNMP interface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually. The next two sections describe these procedures.

Installing the Interface Service with PI Interface Configuration Utility The PI Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service:

Service Configuration

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

12 ID This is the service id used to distinguish multiple instances of the same interface using the same executable.

Display name The 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 as The 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.

Password If 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 Password If a password is entered in the Password text box, then it must be confirmed in the Confirm Password text box.

Startup Type The 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.  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.

Dependencies The 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 Button To add a dependency from the list of Installed services, select the dependency name, and click the Add button.

- Remove Button To 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.

Create The 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.

Start or Stop Service To 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.

Status of Status of the Service the ICU Interface installed or Service uninstalled

Installing Interface Service Manually Help for installing the interface as a service is available at any time with the command: pisnmp.exe –help Change to the directory where the pisnmp1.exe executable is located. Then, consult the following table to determine the appropriate service installation command.

14 Windows Service Installation Commands on a PI Interface Node or a PI Server Node with Bufserv implemented Manual service pisnmp.exe –install –depend “tcpip bufserv” Automatic service pisnmp.exe –install –auto –depend “tcpip bufserv” *Automatic service pisnmp.exe –serviceid X –install –auto –depend “tcpip bufserv” with service id Windows Service Installation Commands on a PI Interface Node or a PI Server Node without Bufserv implemented Manual service pisnmp.exe –install –depend tcpip Automatic service pisnmp.exe –install –auto –depend tcpip *Automatic service pisnmp.exe –serviceid X –install –auto –depend tcpip with service id *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.

SNMP Interface to the PI System 15 Digital States

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

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. For more information about PI digital tags and editing digital state sets, see the PI Server manuals.

User-defined Digital State Sets 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. 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, the digital state set must be created 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

A newer tool is available to create user-defined digital state sets. The PI Digital State Editor plug-in for PI SMT 3 is a graphical way to edit digital state sets.

SNMP Interface to the PI System 16 System Digital State Set Similar to digital state sets is the system digital state set. This set is used for all tags, regardless of 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.

SNMP Interface to the PI System 17 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 $ may be used to identify points that belong to the SNMP Interface. To implement this, the PointSource attribute would be set to $ for every PI Point that is configured for the SNMP Interface. Then, if -ps=$ is used on the startup command-line of the SNMP Interface, the Interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of $. 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 parameter. 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.

Case-sensitivity for PointSource Attribute In all cases, the PointSource character that is supplied with the -ps command-line parameter is not case sensitive. That is, -ps=P and -ps=p are equivalent. It is only necessary to be careful with the case of the PointSource during point definition and only if the Interface will be running on a PINet node communicating to a PI Server.

Reserved Point Sources Several 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 (PI 3). Therefore, it would be confusing to use Lab as the PointSource character for an interface. Lastly, the % character is treated as a special character in .bat files, and thus should not be used if the interface will be run interactively.

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.

SNMP Interface to the PI System 18 PI Point Configuration

The PI point is the basic building block for controlling data flow to and from the PI Server. A single point is configured for each measurement value that needs to be archived. Use the point attributes below to define what data to transfer. 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. Tag A tag is a label or name for a point. Any tag name can be used in accordance to the normal PI point naming conventions.

Length The length of the Tag field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.

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 255 Below 1.6 3.4.370.x or higher 255 Below 1.6 Below 3.4.370.x 255

PointSource The PointSource is a unique single or multiple 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 argument and the “Point Source” section.

PointType Typically, device data types do not need to exactly match PI point types. For example, integer values from a device can be sent to PI floating or digital points. Similarly, a floating-point value from the device can be stored into PI integer or digital points, although the values will be truncated. PI SNMP supports the retrieval of SNMP data into the following PI point types:  Int16  Int32  Float16  Float32  Float64  Digital  String For more information on the individual point types, see the PI Server Manuals.

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, PI SNMP can be configured 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 Location Value sent to the PI type 2 counter 1 rate value; see below all others 0 scanned value

20 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 -1 Let the Interface decide see table below -2 Integer 1234 -3 String Abcd -4 IP address 192.168.10.100

For output points with Location2 set to -1, the SNMP data type is based on the point type of the Interface point. Specifically,

Interface Point Source Point SNMP Data Type and Value Type Type Integer Integer Integer value Integer Float Integer representation of float value Integer Digital Integer representation of digital value Integer String Integer representation of string value String Integer String representation of integer value String Float String representation of float value String Digital String representation of digital value String String String 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 is set 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 tag PI 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.

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). In summary,

SNMP OID requests Location3 single 0

22 multiple 1

Location4

Scan-based Inputs For interfaces that support scan-based collection of data, Location4 defines the scan class for the PI point. The scan class determines the frequency at which input points are scanned for new values. For more information, see the description of the -f flag in the section called “Startup Command File.”

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.

Location5 The Location5 attribute is used for point-level debugging.

Location Debugging 5 0 none 1 minimal 2 medium 3 maximum

If a PI SNMP point is not receiving the values it should be receiving, set its Location5 attribute to 3 to perform debugging. PI SNMP then writes debugging messages to the message log. Stop the logging of these debugging messages by setting Location5 to 0.

Because PI SNMP automatically responds to point attribute changes, it is not necessary to stop and restart the program for changes to Location5 to take effect.

InstrumentTag

Length The length of the InstrumentTag field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.

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: host=192.168.100.11; host=router1; The remote SNMP port can also be specified by appending it to the hostname or IP address: host=192.168.100.11:5161; When the remote port is specified in this manner, it will override the port specified via the /port= parameter or the pisnmp.ini file.

ExDesc

Length The length of the Extended Descriptor field is limited by the version of the PI API, the version of the PI Server, and sometimes by a specific Interface. The table below explains this in more detail. When the maximum possible lengths differ for the software installed on site, the shortest length applies.

The Extended Descriptor attribute holds various required and optional information that the Interface uses in order to successfully retrieve data from an SNMP device or to successfully set data on an SNMP device.

Object Identifier (OID=) This item is necessary to specify the SNMP OID whose value the Interface is to collect or to set. For example,

24 OID=.1.3.6.1.2.1.1.3.0; For OIDs that are part of the standard MIB-II, the textual representation may be used. For example, OID=system.sysUptime.0; For OIDs that are part of the interfaces.ifTable.ifEntry group, the following abbreviated form may be used: OID_I=ifInOctets.3; The Interface treats the above as equivalent to: OID=interfaces.ifTable.ifEntry.ifInOctets.3;

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 interfaces.ifTable.ifEntry.ifInOctets.25 represents the number of inbound octets received on this Serial1/0.1 interface. Accordingly, there may be 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.ifInOctets.31 However, the point tag1 is still configured with an Extended Descriptor containing the ifIndex of 25. As a result, tag1 is no longer collecting data for Serial1/0.1. In addition, there may be difficulty realizing that the ifIndex for Serial1/0.1 has changed from 25 to 31. To help, PI SNMP allows specification of a KEY value in the ExDesc that should be matched before the data retrieved is declared to be good. In the example above, before the router reboot, the OID interfaces.ifTable.ifEntry.ifDescr.25 represents the description of the interface whose index is 25. A likely value for this OID is: Serial1/0.1 If tag1 is configured with the Extended Descriptor: KEY=Serial1/0.1; OID_I=ifInOctets.25 PI SNMP understands that the index number in question is 25. Accordingly, it sends an SNMP request to the network device and asks for the value of: interfaces.ifTable.ifEntry.ifDescr.25 If the value returned does not match the one specified by the KEY value in the point configuration, then PI SNMP writes Bad Input to tag1.

Therefore, after a router reboot, if the router re-assigns indices to its interfaces, then the value for interfaces.ifTable.ifEntry.ifDescr.25 will most likely not be “Serial1/0.1.” In this manner, if points contain Bad Input, check their configuration. When using the PI SNMP Tag Builder plug-in for PI SMT 3.x to build points, the plug-in automatically enters the KEY value into the Extended Descriptor. Otherwise, manually find the values for 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. 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. In this 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 to ensure 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.

26 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 SNMPv1 V=1; SNMPv2c V=2c; SNMPv3 V=3;

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, CS=public; For output points, use the keyword WCS= ("Write Community String"). For example, WCS=private; A drawback of entering the network device’s community string into the PI point configuration is that anyone with access to the PI point database can find out these community strings. In this scenario, the PI System Manager should use either the -pwd 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, do not 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.

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: EVENT=PItag, Here, PItag is a specification for an event point. The Interface must be connected to the PI Server to receive the notifications of new values for PItag. An input for the interface point is triggered when a new value is sent to the Snapshot of the event point. The new value for the event point does not need to be different than the previous Snapshot value to trigger the input. However, the timestamp of the new value must be greater than (more recent than) or equal to the timestamp of the previous value.

Performance Points 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

Specification Meaning / Purpose Mandatory? OID= SNMP Object Identifier Either OID=, OID_I=, or OID_I= OID_G= is required. OID_G_R= is required OID_G= and OID_G_R= when OID_G= is used.

28 Specification Meaning / Purpose Mandatory? KEY= Match interface description No before sending value to PI Server IPADDR=1 Store IP Address as dotted No decimal into a PI string point V= SNMP version No, defaults to SNMPv1 CS= SNMPv1 / SNMPv2 Yes, if using SNMPv1 or Community String for input SNMPv2 for inputs. points WCS= SNMPv1 / SNMPv2 Yes, if using SNMPv1 or Community String for output SNMPv2 for outputs. points USER= SNMPv3 username Only if V=3 is specified. APW= SNMPv3 authentication No password AUTH= SNMPv3 authentication No, defaults to MD5. protocol PPW= SNMPv3 privacy password No EVENT= Event-based data collection No PERFORMANCE_POINT Performance point No

Scan By default, the Scan attribute has a value of 1, which means that scanning is turned on for the point. Setting the scan attribute to 0 turns scanning off. If the scan attribute is 0 when the interface starts, SCAN OFF will be written to the PI point. If the scan attribute is changed from 1 to 0 while the interface is running, SCAN OFF will also be written to the PI point after the point edit is detected by the interface. 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.

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 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 argument is specified. One can disable SHUTDOWN events from being written to PI when PI is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, one can change the default behavior of the PI Shutdown Subsystem 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 (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 the point 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;  with the value of 2 The attributes for the interface point should be similar to:

Attribute Value InstrumentTag host=192.168.10.100; ExDesc OID=.1.3.6.1.4.1.4761.99.1.4.0; WCS=private; SourceTag trigger1

PI SNMP performs outputs according to the standard UniInt mechanism. That is, whenever the SourceTag receives a new value, the Interface performs an SNMP SET for the interface point that references such a SourceTag. Accordingly, to send a value of 2 to the SNMP device, enter (via manual input or another method) the value of 2 into point named trigger1.

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.

30 Performance Point Configuration

One can configure performance points to monitor the amount of time in seconds that an interface 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”, the point configuration can be automatically corrected by ICU by right-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 ICU detects that a Performance Point is not defined with the following, it will be marked Incorrect:

Attribute Details Tag Tag name that appears in the list box Point Source Point Source for tags for this interface, as specified on the first tab Compressing Off Excmax 0 Descriptor Interface name + “ Scan Class # Performance Point”

Rename To rename a Performance Point, right mouse click the line belonging to the tag to be renamed, and select “Rename”.

SNMP Interface to the PI System 31 Performance Point Configuration

Status The Status column in the Performance Points table indicates whether the Performance Point exists for the scan class in column 2.  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. Performance points are configured 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 -f startup 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.

32 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. One I/O Rate tag can be configured 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

The 10-minute rate averages (in events/minute) can be monitored with a client application such as PI ProcessBook 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

SNMP Interface to the PI System 33 I/O Rate Point Configuration

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 number are not in the IORates.dat file

Event Counter The 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.

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

Snapshot The Snapshot column holds the snapshot value of the I/O Rate point, provided that the I/O Rate point exists in PI Server. The Snapshot column is updated when the IORates/Status Tags tab is clicked, and when the interface is first loaded.

Right Mouse Button Menu Options

Create Create the suggested I/O Rate tag with the tag name indicated in the Tagname column.

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

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

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

Search Allow the user to search the PI Server for a previously defined I/O Rate tag. Configuring I/O Rate Points Manually

There are two configuration steps. 1. Configuring the PI Point on the PI Server 2. Configuration on the Interface Node

34 Configuring the I/O Rate Point on the PI Server Create an I/O Rate Point with the following PI point attribute values.

Attribute Value PointSource L PointType float32 Compressing 0 ExcDev 0

Configuration on the Interface Node The following procedure for I/O Rate point configuration on the interface node assumes that 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/Create a file called iorates.dat in the PIHOME\dat directory. The PIHOME directory is defined either by the PIPCSHARE entry or the PIHOME entry in the pipc.ini file, which is located in the %windir% directory. If both are specified, the PIPCSHARE entry takes precedence. Since the PIHOME directory is typically C:\PIPC, the full name of the iorates.dat file will typically be C:\PIPC\dat\iorates.dat. Add a line in the iorates.dat file of the form: snmp001, x where snmp001 is the name of the I/O Rate Tag and x corresponds to the first instance of the -ec=x parameter in the startup command file. X can be any number between 2 and 34 or between 51 and 200, inclusive. To specify additional rate counters for additional copies of the interface, create additional I/O Rate tags and additional entries in the iorates.dat file. The event counter, -ec=x, should be unique for each copy of the interface. 2. Set the -ec=x parameter on the startup command file of the interface to match the event counter in the iorates.dat file. The interface must be stopped and restarted in order for the I/O Rate tag to take effect. I/O Rates will not be written to the tag until 10 minutes after the interface is started.

SNMP Interface to the PI System 35 Startup Command File

Command-line parameters can begin with a hyphen -. For example, -ps=M. For Windows, command file names have a .bat extension. The Windows continuation character (^) allows for the use of multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters. The PI Interface Configuration Utility (PI ICU) provides a tool for configuring the Interface startup command file. Configuring the Interface with PI ICU

Note: PI ICU requires PI 3.3 or greater. The PI Interface Configuration Utility provides a graphical user interface for configuring PI interfaces. If the interface is configured by the PI ICU, the batch file of the interface (PISNMP.bat) will be maintained by the PI ICU and all configuration changes will be kept in that file and the module database. The procedure below describes the necessary steps for using PI ICU to configure the PI CybectecSMP Interface. From the PI ICU menu, select Interface, then NewWindows Interface Instance from EXE..., 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:

“Interface name as displayed in the ICU (optional)” will have PI- pre-pended to this name and it will be the display name in the services menu. Click on Add. The following display should appear:

SNMP Interface to the PI System 36 Note that in this example the Host PI System is localhost, which means that the interface will be configured to communicate with the local PI Server. However, to configure the interface to communicate with a remote PI Server, select ‘Interface => Connections…’ item from PI ICU menu and make it the default server. If the remote node is not present in the list of servers, it can be added. Once the interface is added to PI ICU, 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. Click on Apply to enable the PI ICU to manage this copy of the PI SNMP Interface.

The next step is to make selections in the interface-specific tab (i.e. “pisnmp”) that allow the user to enter values for the startup parameters that are particular to the PI SNMP Interface.

Since the PI SNMP Interface is a UniInt-based interface, in some cases the user will need to make appropriate selections in the UniInt tab. This tab allows the user to access UniInt features through the PI ICU and to make changes to the behavior of the interface. To set up the interface as a Windows Service, use the Service tab. This tab allows configuration of the interface to run as a service as well as to starting and stopping of the interface. The interface can also be run interactively from the PI ICU. To do that go to menu, select the Interface item and then Start Interactive. For more detailed information on how to use the above-mentioned and other PI ICU tabs and selections, please refer to the PI Interface Configuration Utility User Manual. The next section describes the selections that are available from the pisnmp tab. Once selections have been made on the PI ICU GUI, press the Apply button in order for PI ICU to make these changes to the interface’s startup file.

38 pisnmp Interface Tab

Read community string from 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 in the 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 comments USER=username; SNMPv3 username AUTH=MD5; Authentication protocol. Can be MD5 or SHA APW=password; Authentication password PPW=password; Privacy password

For example, host=router1; router1 is our main router CS=public; read community string for 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 host=router3; USER=manager; SNMPv3 user for AUTH=SHA; Use SHA authentication APW=23oaktree; authentication password for PPW=hummingbird; privacy password for 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 multiple community strings or usernames are needed to access different data on the same SNMP agent, either a separate copy of the interface must be run, or separate aliases for the SNMP device in the interface node’s hosts file must be created. Then create an entry in pisnmp.pwd for each alias. (- PWD)

The pisnmp.pwd file has been encrypted This tells the interface that the pisnmp.pwd file is to be encrypted. To avoid storing the information in pisnmp.pwd 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 to keep a copy for reference. Tto edit the attributes for a particular host after those attributes have been encrypted, create a new pisnmp.pwd with 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 will remain. So, for example, if there is security information for ten hosts in pisnmp.enc and only one needs to change, 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. (-ENC)

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

Number of GetRequest retries The 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. (-RETRIES=#)

Number of tags per set The 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

40 GetRequest message. The default number of tags per set is 5. This setting is equivalent to the –setcount= parameter in the startup file. (-SETCOUNT=#)

SNMP port number This is the port number that the interface uses to communicate with the SNMP enabled device. The default is 161. This setting is equivalent to the –port= parameter in the startup file. (-PORT=#)

Timeout duration (msec) The number in this text box specifies the number of milliseconds that PI SNMP will wait for a reply from the network device. The default timeout is 3000 milliseconds. If PI SNMP does not get a reply after the specified number of retries and timeouts, it writes I/O Timeout to the point(s) for that particular scan. This setting is equivalent to the –timeout= parameter in the startup file. (-TIMEOUT=#)

Consecutive timeouts The number in this text box specifies the consecutive number of timeouts threshold for a device to be considered inaccessible. If PI SNMP exceeds this value when it attempts to poll a particular device, and the scan period has elapsed, then the polling of the device terminates. PI SNMP writes I/O Timeout to the remaining tags specific to the device. If the scan period has not elapsed, then PI SNMP will continue its attempt to process the tags for the device until the scan period has elapsed. This setting is equivalent to the –cto= parameter in the startup file. The default value is 3.

Write “Configure” to rejected points Checking this box tells the interface to write Configure to rejected points. This setting is equivalent to the –cr parameter in the startup file. (-CTO=#)

Get data from one device Checking this box allows the interface to retrieve data from a single device using either the TCP/IP address of the device or the hostname. This setting is equivalent to the – device= parameter in the startup file.

IP Address These four text boxes allow entry of a TCP/IP address for the single device configuration. The values must be number between 1-255 for each text box. (-DEVICE=###.###.###.###)

Hostname This box is used to enter the hostname for the singe device configuration. (-DEVICE=)

Allow SNMP SETs/PI outputs To have the interface to support SNMP SETs/PI outputs, check this box. (-OUT)

Additional parameters The Additional Parameters text box allows entry of any additional startup parameters which the ICU control does not provide.

Command-line Parameters

The PI SNMP Interface requires a number of parameters for proper operation. These parameters may appear in any order on the command line. The dash character (-) precedes each parameter.

Note: The UniInt Interface User Manual includes details about other command-line parameters that may be useful.

Parameter Description -cr If the –cr parameter is specified, the interface will write Optional Configure to rejected points. By default, the interface will not write any values to rejected points. -cto=# The –cto parameter specifies the consecutive number of Optional timeouts threshold for a device to be considered inaccessible. If PI SNMP exceeds this value when it attempts to poll a Default: -cto=3 particular device, the polling of the device terminates and I/O Timeout is written to the remaining tags of the device that are in the same scan class.

Before version 1.4.0.0 of the interface, if the scan period has not elapsed, the interface will continue its attempt to process the tags for the device until the scan period has elapsed. From version 1.4.0.0, this no longer occurs and the value specified by this parameter is treated as a hard limit.

The default value is 3. -device= The –device parameter tells PI SNMP to retrieve data or from one device only. The device can be either an IP address -device= or a hostname. This parameter may only be used with a Optional device that supports the ifAlias group. See Appendix G for more information.

42 Parameter Description -ec=# The first instance of the -ec parameter on the command line Optional is used to specify a counter number, #, for an I/O Rate point. If # is not specified, then the default event counter is 1. Also, if the -ec parameter is not specified at all, there is still a default event counter of 1 associated with the interface. If there is an I/O Rate point that is associated with an event counter of 1, each copy of the interface that is running without -ec=# explicitly defined will write to the same I/O Rate point. This means that one should either explicitly define an event counter other than 1 for each copy of the interface or one should not associate any I/O Rate points with event counter 1. Configuration of I/O Rate points is discussed in the section called “I/O Rate Tag Configuration.” For interfaces that run on Windows nodes, subsequent instances of the -ec parameter may be used by specific interfaces to keep track of various input or output operations. One must consult the interface-specific documentation to see whether subsequent instances of the -ec parameter have any effect. Subsequent instances of the -ec parameter can be of the form -ec*, where * is any ASCII character sequence. For example, -ecinput=10, -ecoutput=11, and -ec=12 are legitimate choices for the second, third, and fourth event counter strings. -enc The –enc parameter tells PI SNMP to encrypt the contents Optional of pisnmp.pwd and incorporate the results into a file named pisnmp.enc. If pisnmp.enc doesn’t exist, it is created. Once its contents have been encrypted, pisnmp.pwd is deleted. See the previous section describing the PI ICU for further details. -f=SS The -f parameter defines the time period between scans in or terms of hours (HH), minutes (MM), and seconds (SS). The -f=SS,SS scans can be scheduled to occur at discrete moments in time or with an optional time offset specified in terms of hours (hh), -f=HH:MM:SS minutes (mm), and seconds (ss). If HH and MM are omitted, or then the time period that is specified is assumed to be in -f=HH:MM:SS,hh:mm:ss seconds. Each instance of the -f parameter on the command line Required for reading scan- defines a scan class number for the Interface. There is no based inputs limit to the number of scan classes that can be defined. The first occurrence of the -f flag on the command line defines the first scan class of the Interface, the second occurrence defines the second scan class, and so on. PI Points are associated with a particular scan class number via the Location4 attribute. For example, all PI Points that have Location4 set to 1 will receive input values at the frequency defined by the first scan class. Similarly, all points that have Location4 set to 2 will receive input values

Parameter Description at the frequency specified by the second scan class, and so on. Two scan classes are defined in the following example: -f=00:05:00,00:00:05 -f=00:10:00 The first scan class has a scanning frequency of 5 minutes with an offset of 5 seconds, and the second scan class has a scanning frequency of 10 minutes. When an offset is specified, the scans occur at discrete moments in time according to the formula: scan times = (reference time) + n(frequency) + offset where n is an integer and the reference time is midnight on the day that the Interface started. In the above example, frequency is 5 minutes and offset is 5 seconds for the first scan class. These numbers mean that if the Interface started at 05:06:06, the first scan would be at 05:06:10, the second scan would be at 05:11:10, and so on. Since no offset is specified for the second scan class, the absolute scan times are undefined. The definition of a scan class does not guarantee that the associated points will be scanned at the given frequency. If the Interface is under a large load, then some scans may occur late or be skipped entirely. See the section called “Performance Point Configuration” for more information on skipped or missed scans. Wall Clock Scheduling Scan classes that strictly adhere to wall clock scheduling are now possible. This feature is available for the Interface. Previously, wall clock scheduling was possible, but not across daylight savings time. For example, -f=24:00:00,08:00:00 corresponds to one scan a day starting at 8 AM. However, after a Daylight Savings Time change, the scan would occur either at 7 AM or 9 AM, depending upon the direction of the time shift. To schedule a scan once a day at 8 AM (even across daylight savings time), use -f=24:00:00,00:08:00,L. The ,L at the end of the scan class tells the Interface to use the new wall clock scheduling algorithm

44 Parameter Description -host=host:port The –host parameter is used to specify the PI Server Required machine. 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 Server 3.x. OSIsoft recommends explicit definition of the host and port on the command line by using the -host parameter. Nevertheless, if either the host or port is not specified, the Interface will attempt to use defaults. Defaults: On Windows, the default port number and PI Server name is specified in the pilogin.ini or piclient.ini file. The piclient.ini file is ignored if a pilogin.ini file is found. Refer to the PI API Installation Instructions manual for more information on the piclient.ini and pilogin.ini files. Examples: The Interface is running on a PI Interface node, the name of the PI Server 3.x is marvin, and the IP address of Marvin is 206.79.198.30. Valid -host parameters would be: -host=marvin -host=marvin:5450 -host=206.79.198.30 -host=206.79.198.30:5450 -id=# The -id parameter is used to specify the interface Required identifier. The interface identifier is a string that is no longer than 9 characters in length. UniInt concatenates this string to the header that is used to identify error messages as belonging to a particular interface. See the section called “Error and Informational Messages” for more information. UniInt always uses the -id parameter in the fashion described above. This interface also uses the -id parameter to identify a particular interface copy number that corresponds to an integer value that is assigned to Location1. For this interface, one should use only numeric characters in the identifier. For example, -id=1. -out The –out parameter enables SNMP SET/PI output support Optional in the Interface. If this parameter is not present, PI SNMP rejects points whose Location2 attribute is negative. -port=# The –port parameter specifies the port number that the Optional interface uses to communicate with the SNMP enabled device. The default is 161. Default: -port=161

Parameter Description -ps=x The -ps parameter specifies the point source for the Required interface. X is not case sensitive and can be any unique single or multiple character string. For example, -ps=P and -ps=p are equivalent. The point source that is assigned with the -ps parameter corresponds to the PointSource attribute of individual PI Points. The interface will attempt to load only those PI points with the appropriate point source. -pwd The –pwd parameter tells PI SNMP to read a SNMPv1 / Optional SNMPv2c community string or SNMPv3 security information from the pisnmp.pwd file instead of from a point’s Extended Descriptor. See the previous section describing the PI ICU for the format of the pisnmp.pwd file. -q When the -q parameter is present, Snapshots and Exceptions Optional are queued before they are sent to the PI Server. The maximum queue size is close to 4000 bytes. The queue is flushed between scans if it is not filled. -retries=# The –retries parameter specifies the number of times PI Optional SNMP retries its transmission of an SNMP GetRequest message to the network device. The default number of Default: -retries=3 retries is 3. -setcount=# The –setcount parameter specifies the number of tags per Optional set. When Location3=1, PI SNMP groups tags into a set in order to get multiple OID values for a single SNMP Default: -setcount=5 GetRequest message. The default number of tags per set is 5. -sio The -sio ("suppress initial outputs") parameter tells the Optional, but recommended Interface not to perform outputs when it first starts up. In other words, if -sio is not present, the Interface will perform SNMP SETs at initial startup. -stopstat= If the -stopstat parameter is present on the startup digstate command line, then the Interface will write the digital state to each of its points when it stops. Default: Intf Shut -stopstat= If -stopstat=digstate is present on the command "Intf Shut" line, then the Interface will write the digital state, Optional digstate, to each of its points when it stops. For PI Server 3.x, digstate must be in the system digital state table. If neither -stopstat nor -stopstat=digstate is specified on the command line, then the Interface does not write a digital state when it stops. Examples: -stopstat="Intf Shut" The entire parameter is enclosed within double quotes when there is a space in digstate.

46 Parameter Description -timeout=# The –timeout parameter specifies the number of Optional milliseconds that PI SNMP will wait for a reply from the network device. The default timeout is 3000 milliseconds. Default: -timeout=3000 If PI SNMP does not get a reply after the specified number of retries and timeout, it writes I/O Timeout to the point(s) for that particular scan.

Sample PISNMP.bat File

The following is an example startup command file: REM======REM REM PISNMP.bat REM REM Sample startup file for the PI SNMP Interface to the PI System REM REM======REM REM OSIsoft strongly recommends using PI ICU to modify startup files. REM REM Sample command line REM pisnmp.exe -f=00:10:00 -f=00:00:10 -host=XXXXXX:5450 -ps=$ ^ -id=1 -stopstat=”Intf Shut” REM End of pisnmp.bat File pisnmp.ini File -- Obsolete

Prior to version 1.3.0.0, PI SNMP used a file named pisnmp.ini for certain configuration parameters. The Interface will still use this file if it is present, but OSIsoft recommends that all configuration parameters be specified in the pisnmp.bat file instead. Parameters in pisnmp.bat will take precedence over parameters in pisnmp.ini. The following table illustrates the pisnmp.bat equivalents to the old pisnmp.ini parameters:

pisnmp.ini Parameter pisnmp.bat Parameter consecutive_timeouts= cto= port= port= retries= retries= tags_per_set= setcount= timeout= timeout=

SNMP Interface to the PI System 47 Interface Node Clock

Make 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.

SNMP Interface to the PI System 48 Security

If the home node is a PI 3 Server, 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 a PI 3 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 Serve, it writes a –999 error. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging, p.56

PI Server v3.2 For 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,proxyaccount piapimachine,piadmin @quit In place of piapimachine, put the name of the PI Interface node as it is seen by PI Server.

PI Server v3.3 and Higher

Use of piconfig For 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,PIUser a_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

SNMP Interface to the PI System 49 Security

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

Trust Editor The Trust Editor plug-in for PI System Management Tools 3.x may also 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.

50 Buffering

For complete information on buffering, please refer to the PI API Installation InstructionSNMP Interface to the PI System. 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 XP as it was for NT4 and 2000. Configuring Buffering with PI ICU

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 API Buffering (bufserv) process. The user can start and stop the API Buffering process from the Service tab:

SNMP Interface to the PI System 51 Buffering

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

Service Name The Service name displays the name of the PI API Buffering Service.

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

Log On As Log on as indicates the Windows user account under which the PI API Buffering service is set up to start. To modify the user account or password under which bufserv runs, use the Microsoft Windows Services applet.

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

Service Startup Type The Startup Type indicates whether the PI API Buffering service is set up 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.

Start / Stop Service The Start / Stop buttons allow for the PI API Buffering service to be started and stopped. After a change is made to any of the settings on the Settings tab, the Save button must be clicked, and then the service must be stopped and restarted for the changes to take effect.

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

52 Enable API Buffering Enables the API Buffering feature.

Maximum File Size Maximum 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 Rate Send 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. The Use Default button places the default value into the text box. To keep this value, click the Apply button.

Primary Memory Buffer Size Primary memory buffer size is the size in bytes of the Primary memory buffer. Default value is 32768. Range is 64 to 2,000,000. The Use Default button places the default value into the text box. To keep this value, click the Apply button.

Secondary Memory Buffer Size Secondary memory buffer size is the size in bytes of the Secondary memory buffer. Default value is 32768. Range is 64 to 2,000,000. The Use Default button places the default value into the text box. To keep this value, click the Apply button.

Max Transfer Objects Max 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. The Use Default button places the default value into the text box. To keep this value, click the Apply button.

Pause Rate When 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. The Use Default button places the default value into the text box. To keep this value, click the Apply button.

Retry Rate When 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. The Use Default button places the default value into the text box. To keep this value, click the Apply button.

Max Theoretical Send Rate The theoretical maximum send rate is calculated as follows: max = MAXTRANSFEROBJS / SENDRATE * 1000 Default value is 5000. Configuring Buffering Manually

PI API Buffering 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. Instead, it sends data directly to the PI Server.

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 data to the PI Server.

The piclient.ini file is found in the dat subdirectory of the PIHOME directory. So, on Windows, this file is typically located in c:\pipc\dat

This file follows the conventions of Microsoft Windows initialization files with sections, keywords within sections, and values for keywords. All PI API Buffering settings are entered in a section called [APIBUFFER]. To modify settings, simply edit the piclient.ini file with a text editor (e.g., Notepad) so that keywords have the desired values. The following settings are available for PI API Buffering configuration:

Keywords Values Defaul Description

54 t 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)

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 PI Interface machine and the PI Server machine.

Keywords Values Defaul Description t PIHOMENODE string none On Unix machines, this keyword specifies the default PI Server. On Windows the default PI Server is in pilogin.ini 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 File

On Windows the default server information is stored in the pilogin.ini file. So, the piclient.ini file would only have the [APIBUFFER] section. The entry 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. This setting means that PI Buffer Server waits 10 minutes after losing a connection before retrying. So, given these parameters, a piclient.ini file might look like: [APIBUFFER]

BUFFERING=1 MAXFILESIZE=100000 ; The PI API connection routines have a 1 minute default timeout. RETRYRATE=600

56 Appendix A: Error and Informational Messages

The string PI SNMP 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 Logs

During non-interactive execution on Windows, check the pipc.log file for messages. This file is located in a subdirectory where the PI API is installed. For example, C:\pipc\dat\pipc.log Messages are written to the log file at the following times.  When the Interface starts many informational messages are written to the log. These include the version of the Interface, the version of the UniInt template, the version of the PI API, the command-line parameters used, and the number of points being serviced.  As the Interface retrieves points, messages are sent to the log if there are any problems with the configuration of the points.  When anomalous events occur, the Interface writes messages to the log. Messages

The following is an example of a successful startup of the Interface:

25-Oct-04 20:00:32 PI SNMP-> Starting PI SNMP, version 1.3.0.0 25-Oct-04 20:00:32 PI SNMP-> pisnmp.exe -PS=$ -ID=1 -host=localhost:5450 -maxstoptime=120 -pisdktimeout=60 -sio -perf=8 -f=00:05:00 -f=00:02:00 25-Oct-04 20:00:32 PI SNMP-> Starting interface as a service (pisnmp1), Point source: $ 25-Oct-04 20:00:32 PI SNMP-> Local node cd52603c (192.168.8.40), WinSock Supported Network 25-Oct-04 20:00:32 PI SNMP-> Uniint version>@(#)uniint.cxx 3.5.11 25-Oct-04 20:00:32 PI SNMP-> API version> 1.3.9.4 25-Oct-04 20:00:32 PI SNMP-> The PI SDK is enabled 25-Oct-04 20:00:32 PI SNMP-> PI SDK Version 1.3.1, Build 247 25-Oct-04 20:00:33 PI SNMP-> Setting PISDK Connection Timeout to 15 seconds for server localhost 25-Oct-04 20:00:33 PI SNMP-> Setting PISDK General Timeout to 60 seconds for server localhost 25-Oct-04 20:00:33

SNMP Interface to the PI System 57 Appendix A: Error and Informational Messages

pisnmp.exe>PI API> Initial connection to [localhost:5450][1] 25-Oct-04 20:00:33 PI SNMP-> PIAPI successfully connected to piserver localhost:5450 25-Oct-04 20:00:33 PI SNMP-> Server Version: PI 3.4, Build 363.97 25-Oct-04 20:00:33 PI SNMP-> PISDK successfully connected to piserver localhost via port 5450 25-Oct-04 20:00:33 PI SNMP- 1> Scan performance summary every 8.000000 hours 25-Oct-04 20:00:34 PI SNMP- 1> Uniint is running in Extended API Mode with options 0xc9 25-Oct-04 20:00:34 PI SNMP- 1> 2 Scan classes have been defined 25-Oct-04 20:00:34 PI SNMP- 1> Scan class 1, update period = 300.000000 seconds, unspecified phase offset 25-Oct-04 20:00:34 PI SNMP- 1> Scan class 2, update period = 120.000000 seconds, unspecified phase offset 25-Oct-04 20:00:34 PI SNMP- 1> 1 UNSOLICITED Scan class has been defined 25-Oct-04 20:00:34 PI SNMP- 1> 4 points found for point source $ 25-Oct-04 20:00:34 PI SNMP- 1> 0 unique event classes have been established 25-Oct-04 20:00:34 PI SNMP- 1> 0 output points have been established 25-Oct-04 20:00:34 PI SNMP- 1> (UTC time on server node - UTC time on interface node) = 0 seconds 25-Oct-04 20:00:34 PI SNMP- 1> (Local time on server node - local time on interface node) = 0 seconds 25-Oct-04 20:00:34 PI SNMP- 1> PI SNMP is polling for values from SNMP Agents Location5

The Location5 attribute specifies the debugging level for the PI point. Currently, the Interface supports 4 levels of debugging: 0, 1, 2, and 3, with the larger numbers resulting in more information being printed to the log file. For example, when Location5 has a value of 3, the Interface prints messages regarding the value it received from the SNMP Agent and the value it sent to the UniInt interface template:

25-Oct-04 20:23:00 PI SNMP- 1> pt (localhost_sysUptime_abs), rx data type: not explicitly checked for 25-Oct-04 20:23:00 PI SNMP- 1> val.integer is 1598036 25-Oct-04 20:23:00 PI SNMP- 1> pt (localhost_sysUptime_abs), t=1061583780.03 drval=0.185 ival=0 istat=0 returned to UniInt System Errors and PI Errors

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

58 PI Server 3.x Node Descriptions of operating system and PI System errors can be displayed 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

PI Interface Node Descriptions of PI System errors can be displayed by using the pilogsrv program. This program is located in the bin subdirectory of the directory where the PI API is installed. Use the -e command line parameter followed by the error number. For example, C:> cd \pipc\bin C:> pilogsrv -e -999 [-999] Request Not Permitted Without Login Common Problems

Unexpected Value If a PI point is receiving a value that is unexpected, set the point’s Location5 attribute to 3. Then, PI SNMP will print information to the message log regarding the value it received from the SNMP device and the value that it sent to the UniInt interface template. For example,

25-Oct-04 13:23:00 PI SNMP- 1> pt (localhost_sysUptime_abs), rx data type: not explicitly checked for 25-Oct-04 13:23:00 PI SNMP- 1> val.integer is 1598036 25-Oct-04 13:23:00 PI SNMP- 1> pt (localhost_sysUptime_abs), t=1061583780.03 drval=0.185 ival=0 istat=0 returned to UniInt The above indicates that the Interface  received a value of 1598036 from the SNMP device,  sent a value of 0.185 to the UniInt Interface template. (The point’s conversion attribute is 0.00000011574, which is 0.185 divided by 1598036.) It may take up to 2 minutes for the Interface to be aware of the change to Location5. The Interface will have to perform the scan associated with the point before a new value is recorded.

Be sure to set Location5 back to 0 afterwards. Otherwise, the Interface will continue to write the debug messages to the log.

PI SNMP Startup The following are the most common reasons why PI SNMP fails to start.

Connection to PI Server PI SNMP does not start unless it can connect to the PI Server. Run apisnap to confirm.

Required Command-line Parameters PI SNMP does not start unless the user has specified all required command line parameters. These parameters are:  -id= id number; must be between 1 and 99  -ps= point source character For PI SNMP basic, the following is also required:  -host=localhost:5450 Point Loading The following are the most common reasons why PI SNMP fails to load a point into its list of points to service.

Cannot Translate OID Before sending a request to a network device, PI SNMP needs to translate textual OIDs (e.g., system.sysUptime.0) into their numeric format (e.g., .1.3.6.1.2.1.1.3.0). If it cannot do so, it prints the out a message such as the following: PI SNMP- 1> Cannot translate OID: interfaces.ifTable.ifEntry.ifInOctects.3; cannot add Tag: router_ rx_Ethernet0/0 Make sure that the spelling of the OID is correct. In the above example, ifInOctects should be spelled ifInOctets. Also, confirm that below the directory where the pisnmp program itself is located, there is a mibs directory containing MIB definition files. Otherwise, messages such as the following will appear The Service tab allows for some API Buffering service configuration. For further configuration changes, use the Services applet. Cannot find module (IP-MIB): At line 0 in (none) Cannot find module (IF-MIB): At line 0 in (none) Cannot find module (TCP-MIB): At line 0 in (none) Cannot find module (UDP-MIB): At line 0 in (none) Cannot find module (SNMPv2-MIB): At line 0 in (none) Cannot find module (SNMPv2-SMI): At line 0 in (none) while running PI SNMP.

ID and PointSource PI SNMP loads points based on the –id= and –ps= command line parameters. These must match a point’s Location1 and point source attributes, respectively.

60 Field Not Found If –pwd or –enc do not appear in the startup command line, PI SNMP needs to find either the string CS= or USER= within a point’s extended descriptor attribute, depending on the version specified with V=.

Matching Community String Not Found in pisnmp.pwd If –pwd or –enc appear in the startup command line, PI SNMP looks in either the pisnmp.pwd or pisnmp.enc file for a matching device name. PI SNMP needs to find either a community string or a set of SNMPv3 security attributes that correspond to the given device name specified in the PI point’s instrument tag attribute.

OID Field Not Found PI SNMP needs to find an OID specification within either the instrument tag or extended descriptor attribute. See the section on point configuration for details.

Host Not Found PI SNMP needs to find the string host= within a point’s instrument tag attribute.

OID Not Valid If PI SNMP cannot translate a textual OID into its numeric form, it does not load the point.

No New Value The following are some of the reasons why the PI Server does not show new values for a point configured for an instance of PI SNMP that is running.

Point Not Loaded PI SNMP has not loaded the point in question into its list of points to service. Upon startup, the program prints a message similar to the following: PI SNMP- 2> 15 points found for point source $ Confirm that a message such as this displays accurately the number of points that are configured. Always test PI SNMP by running with a small number of points first. Consult the previous section for more information on Point Loading. For testing purposes, set a point’s Location5 attribute to be 1 in order to see whether PI SNMP loaded the point.

PI Server Configuration The PI Server must be configured to allow PI SNMP to write values. See the Security section for more information.

Value of 0 The following are some of the reasons why PI Server shows a value of 0 for a point configured for an instance of PI SNMP that is running.

Conversion Factor is Zero If the point’s conversion factor point attribute is zero, PI SNMP will write a value of zero for the point.

OID Value is Zero If the OID value itself is zero, PI SNMP will write the value of zero for the corresponding PI point. Run snmpget to check. For points with Location2 set to 1 (SNMP “counter” values), PI SNMP will write the value of zero if the OID value is not changing. Run snmpget twice in succession to check.

I/O Timeout The following are some of the reasons why PI Server shows the status of I/O Timeout for a PI SNMP point.

SNMP Agent Not Responding The SNMP Agent on the network device is not responding. Run snmpget to check the response of the SNMP agent on the network device.

Incorrect Security Information Either the community string (CS) or the SNMPv3 username and password(s) specified in the point’s extended descriptor attribute or pisnmp.pwd file are incorrect. Be aware that community strings and passwords often are case sensitive. That is, “Public” is not the same as “public”. Run snmpget to check the validity of a community string or password.

SNMP Agent Not Responding Fast Enough The SNMP Agent on the network device is not responding quickly enough. Try increasing the timeout= value in the pisnmp.ini configuration file.

Bad Input The following are the reasons why PI Server shows the status of Bad Input for a PI SNMP point.

KEY Value Mismatch The KEY value specified in the extended descriptor does not match the one received from the network device. For example, for a point with an extended descriptor of KEY=Serial1/0.1; OID_I=ifInOctets.25 the value received from the network device for interfaces.ifTable.ifEntry.ifDescr.25 is not Serial1/0.1. The most likely cause of this problem is that after a reboot, the network device re-assigned index numbers to its interfaces. Rebuild the PI points so that they contain the correct index numbers.

62 Incorrect Host for Device The host specified within the point’s instrument tag attribute is incorrect. Run snmpget to check the validity of a host.

Configure The following are some of the reasons why PI Server shows the status of Configure for a PI SNMP point.

OID Does Not Exist The network device reported back that the OID specified in the point’s instrument tag (or extended descriptor) attribute is non-existent. Run snmpget to check the existence of an OID on the network device.

Location3=1 and OID Does Not Exist for a Point in the Set When Location3=1, PI SNMP groups up to 5 points (containing either identical host= and CS= or host= and user= parameters) into a single SNMP GET request. If any one of the points in this set has an OID that is not recognized by the remote device, PI SNMP writes Configure for all of the points in this set. PI SNMP also prints a message similar to the following: PI SNMP- 2> Device reports at least 1 unknown OID in the following set of 2 tags: PI SNMP- 2> Tag: router_tx_Ethernet0/0, OID: interfaces.ifTable.ifEntry.ifOutOctets.85 PI SNMP- 2> Tag: router_jab_4, OID: rmon.statistics.etherStatsTable.EtherStatsEntry .etherStatsJabbers To find out which point contains the unsupported OID, use the snmpget program.

SNMP Agent Erroneously Reports that the OID Does Not Exist A network device may erroneously report that the OID does not exist. OSIsoft itself has experienced intermittently such behavior.

Invalid Counter Tag A point configured with Location2=1 must be of type COUNTER as returned by the SNMP Agent. Run snmpget to check the OID type as returned by the SNMP Agent.

Missed Scans If the Interface consistently misses scans, it is probably attempting to retrieve values from SNMP devices that are not readily accessible. For example, PI SNMP is collecting data for  100 points from device 1,  100 points from device 2,  100 points from device 3,  100 points from device 4, and  100 points from device 5.

If device 3 is removed from the network, PI SNMP still polls this device for the associated points, using a default timeout of 3000 milliseconds and 3 retries. Thus, scans will be missed. To improve this condition, try changing one or more of the startup command parameters:

 decrease the number of retries (-retries),  decrease the timeout interval (-timeout), or

 decrease the number of consecutive timeouts (-cto). For example, pisnmp.exe -retries=0 -timeout=1000 -cto=1

64 Appendix B: snmpget

The supplied snmpget utility from the UCD-SNMP project (http://www.ece.ucdavis.edu/ucd-snmp/) allows retrieval of a single SNMP value from a device. This program is installed in the same directory as the interface executable. For example, in C:\pipc\interfaces\snmp\ Some useful snmpget parameters follow: snmpget –v -c -l -u -a -A= -X= For a full list of snmpget parameters, run: snmpget -h For example, to obtain a value using SNMPv2c: C:> snmpget –v 2c –c public router1 .1.3.6.1.2.1.1.1.0 For SNMPv3, a security level must be specified along with the username and any passwords. If no passwords are configured, use noAuthNoPriv. If an authentication password is configured with no privacy password, use authNoPriv. If both authentication and privacy passwords are configured, use authPriv. Here are some examples: C:> snmpget -v 3 -l noAuthNoPriv -u manager router1 . 1.3.6.1.2.1.1.1.0 C:> snmpget -v 3 -l authNoPriv -u manager -a SHA -A 23oaktree router1 .1.3.6.1.2.1.1.1.0 C:> snmpget -v 3 -l authPriv -u manager -a MD5 -A 23oaktree –X hummingbird router1 .1.3.6.1.2.1.1.1.0 (The output from the above commands would display the name of the operating system running on the network device.) If snmpget is unsuccessful in retrieving information from a particular network device, then PI SNMP itself also will have difficulties.

SNMP Interface to the PI System 65 Appendix C: OID Examples

The following are examples of valid OIDs in both textual and numeric forms. They are useful for testing PI SNMP as well as for determining the existence of an SNMP Agent on a particular network device. That is, for each of the following OIDs, use the snmpget program to query an SNMP Agent for it particular value: C:> snmpget –v 1 –c public 192.168.100.10 .1.3.6.1.2.1.1.1.0 system.sysDescr.0 .1.3.6.1.2.1.1.1.0 This OID represents the description of the network device, such as hardware and operating system.

system.sysUptime.0 .1.3.6.1.2.1.1.3.0 This OID indicates the time (in hundredths of a second, or centiseconds) since the network management portion of the system was last initialized.

interfaces.ifTable.ifEntry.ifInOctets.1 .1.3.6.1.2.1.2.2.1.10.1 This OID indicates the total number of octets (a group of 8 bits) received, including framing characters, on the first network interface.

interfaces.ifTable.ifEntry.ifOutOctets.1 .1.3.6.1.2.1.2.2.1.16.1 This OID indicates the total number of octets (a group of 8 bits) transmitted, including framing characters on the first network interface.

interfaces.ifTable.ifEntry.ifInOctets.2 .1.3.6.1.2.1.2.2.1.10.2 This OID indicates the total number of octets (a group of 8 bits) received, including framing characters, on the second network interface.

interfaces.ifTable.ifEntry.ifOutOctets.2 .1.3.6.1.2.1.2.2.1.16.2 This OID indicates the total number of octets (a group of 8 bits) transmitted, including framing characters on the second network interface.

SNMP Interface to the PI System 66 Appendix D: Basic SNMP for PI Users

This section of the document gives basic SNMP information to users who are familiar with the PI System, but not SNMP. For a more detailed explanation about SNMP, consult a book such as SNMP, SNMPv2, SNMPv3, and RMON 1 and 2, Third Edition, by William Stallings (Addison-Wesley, 1999, ISBN 0201485346).

What is SNMP? SNMP stands for Simple Network Management Protocol. It is a protocol for communications among devices of a computer network. SNMP runs on top of TCP/IP. As an analogy, OSIsoft’s PINet protocol also runs over TCP/IP. The PINet protocol allows communication between PI Server and PI data collection interfaces programs; between PI Server and PI-ProcessBook; and so on. SNMP allows communications between devices such as PCs, routers, bridges, and switches.

What Software is Necessary for SNMP to Run? Just as OSIsoft’s PINet protocol requires PINetMgr software (residing on the PI Server node) and PI API software (used by PI data collection interface programs and PI client applications), SNMP devices have either SNMP Manager software or SNMP Agent software. Because PI SNMP behaves like an SNMP Manager:

What Type of Information is Available via SNMP? Various types of information are available. Currently, the most common are related to network performance and management. For example, most routers have SNMP Agent software running on them. These Agents allow SNMP Managers to retrieve  standard information as defined by standards bodies (e.g., ISO)  proprietary information specific to a particular device or manufacturer

How Does the SNMP Manager and SNMP Agent Agree on what Information is Available? The type of information exchanged between the SNMP Manager and the SNMP Agent is defined by MIBs (Management Information Base). The most common MIB is called

68 MIB-II (or MIB-2). This MIB is related to network management. It defines information such as  the number of octets (group of 8 bits) received on a particular physical interface  the number of octets (group of 8 bits) sent on a particular physical interface A particular element in a MIB is called an OID (Object Identifier). For example, the OID for each of the above are:  .iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifInOctets  .iso.org.dod.internet.mgmt.mib-2.interfaces.ifTable.ifEntry.ifOutOctets

Because the use of MIB-II is widely prevalent, the above is often abbreviated as:  interfaces.ifTable.ifEntry.ifInOctets  interfaces.ifTable.ifEntry.ifOutOctets The numerical representations of these two OIDs are:  .1.3.6.1.2.1.2.2.1.10  .1.3.6.1.2.1.2.2.1.16 A particular occurrence of an OID is called an instance. This instance number is added to the end of the OID. Continuing with the examples above, “the number of octets received on the first physical interface” is given by  interfaces.ifTable.ifEntry.ifInOctets.1  .1.3.6.1.2.1.2.2.1.10.1

For OIDs where there is only a single occurrence, a zero is used. For example, system.sysUptime is “the time since the network management portion of the system was last reinitialized”. Thus, the only instance of system.sysUptime is system.sysUptime.0

What is a COUNTER Value? Some OID values are given in terms of a COUNTER. A COUNTER is an unsigned 32- bit integer ranging from 0 to 4,294,967,295. When a COUNTER value reaches the maximum, it rolls over to 0. In particular,  interfaces.ifTable.ifEntry.ifInOctets  interfaces.ifTable.ifEntry.ifOutOctets are both COUNTERs. Therefore, if PI SNMP stores the raw values for these OIDs, such values will be continuously increasing numbers up to the maximum. A graphical trend of these numbers probably will not be meaningful. Alternatively, PI SNMP can be configured to store COUNTER values per unit time. If Location2 is set to 1, PI SNMP will store the difference between two successive readings divided by the scan time. For example, scanned value = 2000 previous value = 200

scan time = 1 minute stored value = (2000 – 200)/60 = 30 A graphical trend of such values will be more meaningful because it provides the number of octets transferred per second.

What is SNMPv3? SNMPv3 was drafted in response to the perceived security deficiencies of earlier SNMP specifications. SNMPv3 adds authentication and privacy enhancements to the existing SNMP standard. SNMPv3 uses a user-based security model instead of community strings, and SNMPv3 messages can be securely signed and encrypted using authentication and privacy passwords.

70 Appendix E: Tutorial on Using PI SNMP with Routers

PI SNMP is ideally suited for monitoring the performance of network routers. By definition, a router is a device that connects two or more data networks and routes traffic among them.

Example cases Consider an organization with three departments: Sales, Accounting, and Engineering. Each department’s computers are on its own separate network. In addition, the company itself has a connection to the Internet via its ISP (Internet Service Provider). So, its network diagram may look like the following:

A typical provisioning of the interfaces on the router may be:

Interface Speed Connection to Description Ethernet0 10 Mbps Sales Ethernet1 10 Mbps Accounting FastEthernet 100 Mbps Engineering Serial1/0 512 Kbps ISP

SNMP Interface to the PI System 71 Appendix E: Tutorial on Using PI SNMP with Routers

That is,

Another example is the case of the Internet Service Provider itself. It too has a router, which directs traffic from an Internet backbone to its many customers:

A typical router provisioning may be:

Interface Speed Connection to Description ATM2/0.1 512 Kbps Customer1 ATM2/0.2 384 Kbps Customer2 ATM2/0.3 384 Kbps Customer3 Serial2 1.544 Mbps Internet backbone

That is,

72 A final example is the operation of the PI Universal Data Server/Data Archive receiving data from different areas of a plant, each with its own PI data collection interface program:

A typical router provisioning may be:

Interface Speed Connection to Description Ethernet1 10 Mbps Foxboro area of the plant Ethernet2 10 Mbps Honeywell area of the plant Ethernet3 10 Mbps Yokogawa area of the plant Ethernet0 10 Mbps PI Server area of the plant

That is,

SNMP and Interfaces Under SNMP, the interfaces in a router are indexed by an Object Identifier (OID) called ifIndex. This index is a positive integer, and allows the user to reference and correlate other interface OID variables (e.g., interface speed). The SNMP Agent on the router automatically assigns the value of ifIndex. Examples of interface descriptions (interfaces.ifTable.ifEntry.ifDescr) and speeds (interfaces.ifTable.ifEntry.ifSpeed) in our first example are:

ifInde OID variable OID value x 3 OID=interfaces.ifTable.ifEntry.ifDescr.3 Serial1/0 4 OID=interfaces.ifTable.ifEntry.ifDescr.4 Ethernet0 5 OID=interfaces.ifTable.ifEntry.ifDescr.5 Ethernet1 100 OID=interfaces.ifTable.ifEntry.ifDescr.100 FastEthernet 3 OID=interfaces.ifTable.ifEntry.ifSpeed.3 512,000 4 OID=interfaces.ifTable.ifEntry.ifSpeed.4 10,000,000 5 OID=interfaces.ifTable.ifEntry.ifSpeed.5 10,000,000 100 OID=interfaces.ifTable.ifEntry.ifSpeed.100 100,000,000

74 For the example ISP:

ifInde OID variable OID value x 101 OID=interfaces.ifTable.ifEntry.ifDescr.101 ATM2/0.1 102 OID=interfaces.ifTable.ifEntry.ifDescr.102 ATM2/0.2 103 OID=interfaces.ifTable.ifEntry.ifDescr.103 ATM2/0.3 200 OID=interfaces.ifTable.ifEntry.ifDescr.200 Serial2 101 OID=interfaces.ifTable.ifEntry.ifSpeed.101 512,000 102 OID=interfaces.ifTable.ifEntry.ifSpeed.102 384,000 103 OID=interfaces.ifTable.ifEntry.ifSpeed.103 384,000 200 OID=interfaces.ifTable.ifEntry.ifSpeed.200 1,544,000

For PI Server receiving data, examples may be:

ifInde OID variable OID value x 1 OID=interfaces.ifTable.ifEntry.ifDescr.1 Ethernet0 2 OID=interfaces.ifTable.ifEntry.ifDescr.2 Ethernet1 3 OID=interfaces.ifTable.ifEntry.ifDescr.3 Ethernet2 4 OID=interfaces.ifTable.ifEntry.ifDescr.4 Ethernet3 1 OID=interfaces.ifTable.ifEntry.ifSpeed.1 10,000,000 2 OID=interfaces.ifTable.ifEntry.ifSpeed.2 10,000,000 3 OID=interfaces.ifTable.ifEntry.ifSpeed.3 10,000,000 4 OID=interfaces.ifTable.ifEntry.ifSpeed.4 10,000,000

Be aware that the value of ifIndex does not have to start at 1, and that these indices are not necessarily consecutive. Also, note that the value for the OID variable interfaces.ifTable.ifEntry.ifSpeed.X, where X is an ifIndex value, reflects engineering units of bits per second.

Traffic monitoring In order to determine the amount of traffic traversing on a router’s particular interface (i.e., for ifIndex=X), look at the values for the following OID variables:  interfaces.ifTable.ifEntry.ifEntry.ifInOctets.X  interfaces.ifTable.ifEntry.ifEntry.ifOutOctets.X SNMP defines the former as the total number of octets (a group of 8 bits) received on the interface, including framing characters. The latter OID variable represents the total number of octets transmitted on the particular interface, including framing characters.

For the given examples:

These OID variables indicate the total number of octets received/transmitted. However, the per unit time versions of these variables may be of interest. That is, it may be desirable to know  the number of octets per second received on the interface  the number of octets per second transmitted on the interface PI SNMP performs such a measurement if a PI point is configured with Location2 set to 1. (Please see the main section of this manual for details.) So, for the three example scenarios cited above, use PI SNMP to monitor the amount of traffic for each interface provisioned on the router. Consequently, it becomes easy to determine which department (e.g., Sales, Accounting, or Engineering), which customer (Customer1, Customer2, or Customer3), or which area of the plant (Foxboro, Honeywell, or Yokogawa) is utilizing the most bandwidth.

PI SNMP Tag Builder Plug-in for PI SMT 3.x As mentioned previously, the interfaces that are provisioned on a router are indexed by the ifIndex variable. Correlating this interface index number (e.g., 4) to an interface description (e.g., Ethernet0) and other interface OID variables is often difficult. For this reason, OSIsoft provides the PI SNMP Tag Builder plug-in for PI SMT 3.x. Consult the plug-in documentation for details.

76 Appendix F: PI SNMP Technical Details

Message Size For PI tags whose Location3 field is zero, PI SNMP does not group multiple requests for information into a single SNMP GetRequest message. In other words, the PDU (Protocol Data Unit) that PI SNMP sends to a network device contains a GetRequest for only a single OID. The size of such a message is of the order of 80 octets. The size of a GetResponse PDU from the network device depends on the OID value requested, and can vary greatly. For example, the value for system.sysDescr.0 returned by the network device may be a descriptor such as: IOS (tm) 3600 Software (C3660-DS-M), Version 12.0(5)T1, RELEASE SOFTWARE (fc1) Copyright (c) 1986-1999 by cisco Systems, Inc. Compiled Thu 19-Aug-99 18:15 by cmong The above returned value by itself consists of 213 octets. With the addition of the various headers (SNMP, UDP, IP), the size of the complete message is about 280 octets. When PI SNMP retrieves numeric values, the size of the returned message is also about 80 octets. For comparison, a single PING message from a Windows machine contains about 64 octets.

Supported MIBs The current version of PI SNMP supports textual OIDs for the following branches of the MIB-II (.1.3.6.1.2.1) tree:  system (1)  interfaces (2)  ip (4)  icmp (5)  tcp (6)  udp (7)  transmission (10)  snmp (11)  rmon (16) For example, the user may specify either system.sysUptime.0 or .1.3.6.1.2.1.1.3.0 in the Extended Descriptor field of the PI tag configuration.

SNMP Interface to the PI System 77 Appendix F: PI SNMP Technical Details

However, OIDs from other branches of the MIB-II tree need to be configured with numeric values. In particular, vendor specific OIDs (those which begin with . 1.3.6.1.4.1) need to be specified in their numeric form. When in doubt about the validity of a textual OID within PI SNMP, use the snmpget program to confirm.

78 Appendix G: ifAlias Support

Re-assignment of Indices When a router reboots, the SNMP agent on this router often assigns a different index number to a particular instance of one of its interfaces. For example, an interface named Serial1/0.1 has an ifIndex value of 25. Thus, the OID variable interfaces.ifTable.ifEntry.ifInOctets.25 represents the number of inbound octets received on this Serial1/0.1 interface. Accordingly, a PI tag called tag1 may be 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.ifInOctets.31 However, the tag tag1 is still configured with an extended descriptor containing the ifIndex of 25. As a result, tag1 is no longer is collecting data for Serial1/0.1. In addition, it may be difficult to realize that the ifIndex for Serial1/0.1 has changed from 25 to 31.

Non-volatile Feature of ifAlias RFC 2233 specifies that if an SNMP agent supports the ifAlias OID variable, then its value must not change during a router reboot: ... the ifAlias name is non-volatile, and thus an interface must retain its assigned ifAlias value across reboots, even if an agent chooses a new ifIndex value for the interface. Thus, if the router supports ifAlias, PI SNMP can be configured so that it will collect correct data even after a router reboot. To find out whether the router supports ifAlias, run a command such as the following: C:> snmpwalk -M .\mibs 10.8.10.1 public .1.3.6.1.2.1.31.1.1.1.18 For the above commands, use the IP address of the router and the correct community string. If the above command results in items similar to ifMIB.ifMIBObjects.ifXTable.ifXEntry.ifAlias.1 = to ISP ifMIB.ifMIBObjects.ifXTable.ifXEntry.ifAlias.2 = to LAN ifMIB.ifMIBObjects.ifXTable.ifXEntry.ifAlias.3 = remote office

then the router supports ifAlias. If the results do not contain ifMIB.ifMIBObjects.ifXTable.ifXEntry.ifAlias then the router doses not support ifAlias.

SNMP Interface to the PI System 79 Appendix G: ifAlias Support

Data Collection Based on ifAlias To collect data based on ifAlias, specify in the Extended Descriptor OID_I=ifInOctets (to retrieve inbound traffic values) or OID_I=ifOutOctets (outbound traffic). Do not specify the interface index number. The value of the ifAlias must also be specified for the particular interface. The keyword is IFALIAS. For the above example ifAlias values, to collect inbound traffic values for the network interface that represents “to LAN”, put OID_I=ifInOctets; IFALIAS="to LAN"

into the Extended Descriptor of a PI tag such as tag1. (Note that double quotes must be used because of the space between “to” and “LAN”.) During data retrieval for tag1, PI SNMP obtains all the ifAlias names from the router. It then matches the IFALIAS value of tag1 with these ifAlias names to determine the interface index number. In this example, the interface number is 2. PI SNMP then internally constructs the OID interfaces.ifTable.ifEntry.ifInOctets.2 and sends the appropriate request to the router.

If the router reboots and the SNMP agent reassigns interface indices such that ifMIB.ifMIBObjects.ifXTable.ifXEntry.ifAlias.1 = remote office ifMIB.ifMIBObjects.ifXTable.ifXEntry.ifAlias.2 = to ISP ifMIB.ifMIBObjects.ifXTable.ifXEntry.ifAlias.3 = to LAN PI SNMP still reads correct values for tag1 because it will now internally construct the OID interfaces.ifTable.ifEntry.ifInOctets.3 in order to get the data from the router.

Configuration To configure PI SNMP to use ifAlias based data collection, specify –device= on the startup command file, with the value of this parameter being the IP address or name of the router. For example, pisnmp –ps=$ -id=1 –host=localhost:5450 –device=10.8.10.1 …

PI SNMP needs to retrieve the various ifAlias names at startup. Thus, it needs the community string of the router. Specify this community string via the pisnmp.pwd file. For example, host=10.8.10.1; CS=public; community string for 10.8.10.1 Limitations Because a particular router (via device=) needs to be specified at PI SNMP startup, this configuration limits data collection to a single device. Also, for simplicity, PI SNMP groups all tags into sets, regardless of the value of Location3. Finally, the specified router must also support the OID system.sysUptime.0 If this OID is not supported, PI SNMP exits.

80 Summary 1. Run one of the following to determine whether the router supports ifAlias: snmpwalk -M .\mibs 10.8.10.1 public .1.3.6.1.2.1.31.1.1.1.18 snmpwalk -M ./mibs 10.8.10.1 public .1.3.6.1.2.1.31.1.1.1.18 2. Configure PI tags with Extended Descriptors containing OID_I=ifInOctets; IFALIAS="ifAlias_name_of_the_interface" or OID_I=ifOutOctets; IFALIAS="ifAlias_name_of_the_interface" The former specifies data collection for inbound traffic while the latter outbound traffic. Note: Do not specify the interface index number.

3. Specify the router by adding –device= to the startup command line. For example, pisnmp –ps=$ -id=1 –host=localhost:5450 –device=10.8.10.1 …

4. The Extended Descriptor need not contain the host= specification because all data comes from the router specified by –device= on the startup command line.

5. The Extended Descriptor need not contain the CS= specification because PI SNMP uses the community string in the pisnmp.pwd file. So, this file must be configured accordingly.

6. PI SNMP groups all tags into sets, regardless of the value of Location3.

7. The router must support the OID system.sysUptime.0 Otherwise, PI SNMP exits.

8. It is still ok to specify non-interfaces tags. For example, a tag can be configured with an Extended Descriptor OID=system.sysUptime.0; to retrieve the uptime of the router.

SNMP Interface to the PI System 81 Appendix H: Known Issues

Restart of SNMP Agent When an SNMP Agent restarts (e.g., after a reboot of the network device), it generally resets all COUNTER variables to zero. Such a restart will result in a subsequent value for PI tags configured as time-normalized values (i.e., with Location2=1) not being correct. Consider the following example for PI_tag1, which is configured for the OID interfaces.ifTable.ifEntry.ifInOctets.1: During the case of a normal operation (i.e., no SNMP Agent restart), if PI SNMP is configured for 5 minute scan intervals on the hour (-f=00:05:00,00:00:00) and the OID values on the network device and scan times are: 08:00:00 (a scan time for PI SNMP) OID value = 400,000 (value x) 08:02:59 (not a scan time for PI SNMP) OID value = 500,000 (value y) 08:05:00 OID value = 600,000 (value z) The number of octets received during the above 5-minute time interval is 200,000 (z -x). Thus, the time-normalized value—and that which is stored in PI_tag1—is 666.67 (200,000/300) octets/second. If an SNMP Agent were to restart between PI SNMP scans: 08:00:00 (a scan time for PI SNMP) OID value = 400,000 08:03:00 (SNMP Agent restart, and not a scan time for PI SNMP) OID value = 0 because of an SNMP Agent restart 08:05:00 (a scan time for PI SNMP) OID value = 100,000 For this situation, PI SNMP determines that the number of octets received during this 5-minute interval is 4,294,667,296. (100,000 - 400,000 = –300,000, or Hexadecimal FFFB6C20; for an unsigned value, this is 4,294,667,296.) Meanwhile, because of the possibility of the above situation, the user should configure a tag that records system.sysUptime.0 for each of the network devices that are providing data to PI SNMP. In this manner, the user will know the approximate time at which the SNMP Agent restarted. If a user knows beforehand that an SNMP Agent will restart (for example, because of the need to reboot a router), he should first stop the PI SNMP program. He can then re-run PI SNMP after the restart of the SNMP Agent.

SNMP Interface to the PI System 82 Appendix I: Acknowledgments

PI SNMP contains components from the Net-SNMP and OpenSSL projects. Copyright notices and acknowledgments follow. Net-SNMP

Part 1: CMU/UCD copyright notice:

Copyright 1989, 1991, 1992 by Carnegie Mellon University Derivative Work - 1996, 1998-2000 Copyright 1996, 1998-2000 The Regents of the University of California All Rights Reserved Permission to use, copy, modify and distribute this software and its documentation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permission notice appear in supporting documentation, and that the name of CMU and The Regents of the University of California not be used in advertising or publicity pertaining to distribution of the software without specific written permission. CMU AND THE REGENTS OF THE UNIVERSITY OF CALIFORNIA DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL CMU OR THE REGENTS OF THE UNIVERSITY OF CALIFORNIA BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM THE LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Part 2: Networks Associates Technology, Inc copyright notice:

Copyright (c) 2001-2003, Networks Associates Technology, Inc All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.

* Neither the name of the Networks Associates Technology, Inc nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Part 3: Cambridge Broadband Ltd. copyright notice:

Portions of this code are copyright (c) 2001-2003, Cambridge Broadband Ltd. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * The name of Cambridge Broadband Ltd. may not be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Part 4: Sun Microsystems, Inc. copyright notice:

84 Copyright © 2003 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara, California 95054, U.S.A. All rights reserved. Use is subject to license terms below. This distribution may include materials developed by third parties. Sun, Sun Microsystems, the Sun logo and Solaris are trademarks or registered trademarks of Sun Microsystems, Inc. in the U.S. and other countries. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of the Sun Microsystems, Inc. nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Part 5: Sparta, Inc copyright notice:

Copyright (c) 2003-2004, Sparta, Inc All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of Sparta, Inc nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Part 6: Cisco/BUPTNIC copyright notice:

Copyright (c) 2004, Cisco, Inc and Information Network Center of Beijing University of Posts and Telecommunications. All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: * Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. * Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. * Neither the name of Cisco, Inc, Beijing University of Posts and Telecommunications, nor the names of their contributors may be used to endorse or promote products derived from this software without specific prior written permission. THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. OpenSSL

86 Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this software must display the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to endorse or promote products derived from this software without prior written permission. For written permission, please contact [email protected]. 5. Products derived from this software may not be called "OpenSSL" nor may “OpenSSL" appear in their names without prior written permission of the OpenSSL Project. 6. Redistributions of any form whatsoever must retain the following acknowledgment: "This product includes software developed by the OpenSSL Project for use in the OpenSSL Toolkit (http://www.openssl.org/)" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Copyright (C) 1995-1998 Eric Young ([email protected]) All rights reserved. Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: 1. Redistributions of source code must retain the copyright notice, this list of conditions and the following disclaimer. 2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution. 3. All advertising materials mentioning features or use of this software must display the following acknowledgement:

"This product includes cryptographic software written by Eric Young ([email protected])" The word 'cryptographic' can be left out if the routines from the library being used are not cryptographic related :-). 4. If any Windows specific code (or a derivative thereof) is included from the apps directory (application code) an acknowledgement must be included: "This product includes software written by Tim Hudson ([email protected])"

88 Revision History

Date Author Comments 8-Sep-2003 E Tam Interface v1.2.0.0; used skeleton v1.12 3-Oct-03 Chrys Fixed some typos 25-Oct-2003 E Tam change version to be v1.2.0.2 14-May-2004 T Johnson SNMPv3 support. 25-Oct-04 T Johnson New command line parameters, new ICU control, pisnmputil replaced with SMT 3.x plug-in, acknowledgments. 08-Nov-2004 E Tam SNMP SETs (PI outputs) and –out startup parameter 18-Nov-2004 E Tam Updated ICU control screenshot (-out parameter) 10-Jan-05 T Johnson Version 1.3.0.4 15-Feb-05 T Johnson Rev B: Revised SMT3 Tag Builder info 16-Feb-05 Chrys Version 1.3.0.4 Rev C: changed note that tag builder is part of interface install; made minor format changes; moved common problems into error section; fixed section breaks 18-Feb-05 MPKelly Fixed sample pisnmp.bat file to correct placement of quotes around the /stopstat=”Intf Shut” parameter. 20-Sep-05 T Johnson Added -cr command line parameter. 09-Nov-2005 T Johnson Corrected snmpget syntax 09-Nov-2005 T Johnson Version 1.3.1.2 11-Nov-2005 Janelle Version 1.3.1.2, Rev A: removed references from the first person, changed to third person; fixed headers and footers. Alphabetized the command line parameter section; alphabetized parameters in the sample bat file section. 14-Nov-2005 T Johnson Version 1.3.1.2, Rev B: Added Windows 2003 (Intel) in supported platforms; removed –f from required parameters in .bat file, put in optional parameters. 07-Sep-2006 TJohnson Version 1.3.2.0. Port can be appended to the agent’s hostname or IP address to override the /port= parameter. 12-Sep-2006 Janelle Version 1.3.2.0 Revision A: update to Skeleton 2.5.2, update hardware diagrams, remove hyphens from product names, set to Final, minor formatting changes, fixed headers. 18-Dec-2006 MKelly Version 1.3.2.0 Revision B; updated supported features table and ICU Control screenshots.

SNMP Interface to the PI System 89 19-Feb-2007 PChow Version 1.4.0.0 Revision A: Added SetDeviceStatus description in Supported Features and set DisconnectedStartup support to yes. 19-Apr-2007 PChow Version 1.4.0.0 Revision B: Described the minor change in the way the cto parameter is used in the Command-line Parameters section. 24-Apr-2007 PChow Version 1.4.0.0 Revision C: Updated the SetDeviceStatus description in Supported Features – the description for the “Good” event now specifies this event is written even when no data collection points have been defined. 2-May-2007 Janelle Version 1.4.0.0 Revision D: added default information to startup command line parameters table, minor formatting changes.