PI Interface for SNMP User Guide

Transcription

1 PI Interface for SNMP User Guide

2 OSIsoft, LLC 1600 Alvarado Street San Leandro, CA USA Tel: (01) Fax: (01) Web: PI Interface for SNMP User Guide by OSIsoft, LLC. All rights reserved. No part of this publication may be reproduced, stored in a retrieval system, or transmitted, in any form or by any means, mechanical, photocopying, recording, or otherwise, without the prior written permission of OSIsoft, LLC. OSIsoft, the OSIsoft logo and logotype, Managed PI, OSIsoft Advanced Services, OSIsoft Cloud Services, OSIsoft Connected Services, PI ACE, PI Advanced Computing Engine, PI AF SDK, PI API, PI Asset Framework, PI Audit Viewer, PI Builder, PI Cloud Connect, PI Connectors, PI Data Archive, PI DataLink, PI DataLink Server, PI Developer s Club, PI Integrator for Business Analytics, PI Interfaces, PI JDBC driver, PI Manual Logger, PI Notifications, PI ODBC, PI OLEDB Enterprise, PI OLEDB Provider, PI OPC HDA Server, PI ProcessBook, PI SDK, PI Server, PI Square, PI System, PI System Access, PI Vision, PI Visualization Suite, PI Web API, PI WebParts, PI Web Services, RLINK, and RtReports are all trademarks of OSIsoft, LLC. All other trademarks or trade names used herein are the property of their respective owners. U.S. GOVERNMENT RIGHTS Use, duplication or disclosure by the U.S. Government is subject to restrictions set forth in the OSIsoft, LLC license agreement and as provided in DFARS , DFARS , FAR , FAR , as applicable. OSIsoft, LLC. Version: Published: 25 September 2017

3 Contents Introduction to PI Interface for SNMP...1 Reference manuals for PI Interface for SNMP... 1 Supported operating systems... 2 Features supported by PI Interface for SNMP... 3 MIBs supported by the PI Interface for SNMP...4 How the PI Interface for SNMP works... 5 Basics of SNMP... 5 PI Interface for SNMP logic... 6 SNMP message size...7 Installation checklist... 9 Read-only and read-write interfaces... 9 Disable read-write interface updates to the data source... 9 Data collection steps Interface diagnostics (optional)...11 Advanced interface features (optional) Installation instructions Name conventions and requirements Interface directories...13 PIHOME directory tree PIHOME64 directory tree...14 Interface installation directory Interface installation procedure Silent installation procedure PI trust for interface authentication Install interface as Windows service Install interface service with PI Interface Configuration Utility (ICU) Install interface service manually PI Point configuration Use PI SNMP Tag Builder Point attributes Tag (PI point name)...22 PointSource (point source) PointType (data type)...23 Location1 (interface instance) Location Location3 (Allow grouping) Location4 (scan class) Location Instrument tag (SNMP device) ExDesc (SNMP settings) Output points Startup command files PI Interface for SNMP User Guide iii

4 Contents Configure the PI Interface for SNMP with PI ICU Pisnmp Interface page Command-line parameters for the PI Interface for SNMP Specific considerations regarding PI Point configurations for the PI Interface for SNMP Router traffic data collection Example 1 - Business setting Example 2 - Internet Service Provider Example 3 - PI Data Archive Use ifalias to ensure data collection after router reboot Troubleshooting the PI Interface for SNMP Testing SNMP object identifiers (OIDs)...48 Error and informational messages Message logs Messages...53 Location Common problems...54 System errors and PI errors Error descriptions UniInt failover specific error messages Errors (phase 1 & 2)...60 Errors (phase 2)...61 Unable to open synchronization file...61 Error opening synchronization file PI SDK options...63 Tutorial on using PI SNMP with routers Example cases SNMP and interfaces...68 Traffic monitoring PI SNMP tag builder plug-in for PI SMT 3.x...71 PI SNMP technical details...73 Message size...73 Supported MIBs ifalias support Re-assignment of indices Non-volatile feature of ifalias...75 Data collection based on ifalias Configuration Limitations Summary Acknowledgments Acknowledgments...79 Net-SNMP iv PI Interface for SNMP User Guide

5 Contents OpenSSL Glossary of interface terms buffering...85 ICU ICU Control...85 n-way buffering pigetmsg utility PIHOME PIHOME pipc.log file...86 point...86 PI API PI Data Archive...86 PI Data Archive collective PI Data Archive computer...86 PI ICU...87 PI Interface Configuration Utility...87 PI message log PI Message Subsystem...87 PI point PI point attribute...87 PI SDK PI SMT PI System Management Tools tag attribute Technical support and other resources PI Interface for SNMP User Guide v

6 Contents vi PI Interface for SNMP User Guide

7 Introduction to PI Interface for SNMP The PI Interface for SNMP gathers information from SNMP-enabled devices residing in a TCP/IP network. The devices must be able to send and receive messages using the SNMP protocol. Specifically, they must run an SNMP agent that supports SNMPv1, SNMPv2c, or SNMPv3. Because remote monitoring (RMON) is a specific application of the SNMP protocol, the interface supports the retrieval of RMON values. The interface can retrieve values from SNMP devices into input points in the PI Data Archive and can set values on SNMP devices using output points. However, the interface cannot receive data by means of traps sent by SNMP agents. Its purpose is to gather statistics and data, not to control or configure network nodes. This guide assumes that you are familiar with the basics of SNMP and PI System technologies. Note: The SNMPGet and SNMPWalk utilities, which were included in previous releases of the interface, are no longer supported or distributed. The Tag Builder plug-in for PI SMT 3.x can test the connectivity to SNMP devices and build points. To obtain diagnostic information about SNMP devices, use the Getif Utility ( getif.htm), which enables you to test addresses, get access to a routing table, and see a MIB browser to display fully qualified SNMP OID names. OSIsoft is revising terminology to reflect the growth of PI Server from its original single-server architecture. The term PI Data Archive means the component that stores time-series data (formerly called PI Server). The term PI Server means the entire suite of PI System server products, and includes both PI Data Archive and PI Asset Framework. This document uses the revised terminology. Topics in this section Reference manuals for PI Interface for SNMP Supported operating systems Features supported by PI Interface for SNMP MIBs supported by the PI Interface for SNMP Reference manuals for PI Interface for SNMP PI Universal Interface (UniInt) User Guide (%PIHOME%\Interfaces\UniInt\UniInt Interface User Manual.pdf) Describes the configurations and functionality of features common to the UniInt framework. PI Server System Management Guide Documentation for managing PI Servers, interfaces, PI points, and digital state sets. PI Server Configuring PI Server Security Includes information about PI Data Archive security. High Availability Administrator Guide PI Interface for SNMP User Guide 1

8 Introduction to PI Interface for SNMP Describes how to configure high availability and manage PI Data Archive and interfaces when using PI collectives. PI SDK and PI API Online Help Files Documentation for the PI SDK and PI API libraries used by interfaces. The embedded help (.chm) files are located in the %PIHOME%\PIPC\Help\directory. PIHOME is an environment variable that contains the PI API installation path. PI API Installation Instructions User Guide (%PIHOME%\bin\API_install.doc) Details about installing supporting components, including buffering to prevent data loss if the connection to the PI Data Archive is lost. PI Buffering User Guide Describes the requirements for PI Buffer Subsystem (pibufss) and API Buffer Server (bufserv), and procedures for setting up, configuring, and verifying proper buffering for interface nodes. PI Interface Configuration Utility (PI ICU) User Guide (%PIHOME%\ICU\PI Interface Configuration Utility.pdf) Describes how to configure interfaces using PI ICU. OSIsoft Knowledge Base In addition to product and system documentation, you can search the OSIsoft Knowledge Base articles for interface-specific information. For more information about reading message logs, see the OSIsoft Knowledge Base article How to read new UniInt x and later Interface message logs How to read new UniInt x and later Interface message logs ( Release notes Release-specific information about functional updates, bug fixes, and new features. Release notes are provided both for the UniInt framework and for each interface. Supported operating systems PI Interface for SNMP is available in the following platforms in 32-bit or 64-bit in emulation mode. No 64-bit builds of the interface are available. Windows Server 2016 Windows Server 2012 and Windows Server 2012 R2 Windows 10 Windows 8.1 Windows 8 Windows 7 Service Pack 1 Windows Server 2008 Service Pack 2 and 2008 R2 Service Pack 1 2 PI Interface for SNMP User Guide

9 Introduction to PI Interface for SNMP Features supported by PI Interface for SNMP Feature Interface Part Number Auto Creates PI Points Point Builder Utility PI ICU Control Support PI-IN-OS-SNMP-NTI PI Point Types float16 / float32 / float64 / int16 / int32 / digital / string Sub-second Time stamps Sub-second Scan Classes Automatically Incorporates PI Point Attribute Changes Exception Reporting Outputs to data source Read-only interface available Inputs to PI Data Archive Supports Questionable Bit Supports Multi-character PointSource Maximum Point Count Uses PI SDK PINet String Support Source of Time stamps History Recovery UniInt-based Disconnected Startup SetDeviceStatus Failover Vendor Software Required on Interface Node Vendor Software Required on Data Source Device Vendor Hardware Required Additional PI System Software Included with interface Device Point Types Serial-Based interface No Yes Yes Yes Yes Yes Yes Yes No Scan-based / Event Tags No Yes Limited by your license for PI Data Archive No No PI Data Archive No Yes Yes. Enabled using PI ICU. For details, see the PI Universal Interface (UniInt) User Guide. Yes. The health point with the point attribute exdesc = [UI_DEVSTAT] is used to represent the status of the source devices. For details, see the PI Universal Interface (UniInt) User Guide. UniInt failover (phase 2): Cold, Hot and Warm. Enabled using PI ICU. For details, see the PI Universal Interface (UniInt) User Guide. No Yes. The device must be running an SNMP agent. No Yes Integers and octet strings. The interface can also retrieve MAC addresses and IP addresses from SNMP agents. No PI Interface for SNMP User Guide 3

10 Introduction to PI Interface for SNMP MIBs supported by the PI Interface for SNMP The current version of the interface supports textual OIDs for the following branches of the MIB-II ( ) tree: system (1) interfaces (2) ip (4) icmp (5) tcp (6) udp (7) transmission (10) snmp (11) rmon (16) For example, you can specify either system.sysuptime.0 or in the extended descriptor (exdesc) attribute of the PI point. However, OIDs from other branches of the MIB-II tree (in particular, vendor-specific OIDs, which begin with ) must be specified as numeric values. When in doubt about the validity of a textual OID, use the Getif program to validate it. 4 PI Interface for SNMP User Guide

11 How the PI Interface for SNMP works This section explains the basics of SNMP and interface operation. 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 ). Topics in this section Basics of SNMP PI Interface for SNMP logic SNMP message size Basics of SNMP SNMP stands for "Simple Network Management Protocol." SNMP is a protocol for communications among devices on a computer network. SNMP runs on top of TCP/IP and enables communications between devices such as PCs, routers, bridges, and switches. SNMP devices must run SNMP manager or agent software. SNMP managers retrieve device information from SNMP agents, including standard information as specified by relevant ISO standards and proprietary information that is specific to a particular device or manufacturer. The type of information exchanged between the SNMP Manager and the SNMP agent is defined by MIBs (Management Information Bases). The most common MIB is called MIB-II (or MIB-2). MIB-II contains information pertinent to network management. It defines information such as the number of octets (group of 8 bits) sent and received on a particular physical interface. MIBs contain object identifiers (OIDs), which identify the variables that can be read or set using SNMP. For example, the following OIDs identify the variables that contain the number of input and output octets:.iso.org.dod.internet.mgmt.mib-2.interfaces.iftable.ifentry.ifinoctets.iso.org.dod.internet.mgmt.mib-2.interfaces.iftable.ifentry.ifoutoctets MIB-II supports abbreviated syntax; the preceding OIDs can be abbreviated as follows: interfaces.iftable.ifentry.ifinoctets interfaces.iftable.ifentry.ifoutoctets The numerical representations of the preceding OIDs are as follows: A particular occurrence of an OID is called an instance. To address an instance, you add its instance number to the end of the OID. Based on the preceding examples, to address the number of octets received on the first physical interface, specify the instance as follows: interfaces.iftable.ifentry.ifinoctets For OIDs where there is only a single occurrence, a zero is used. For example, the only instance of system.sysuptime is specified as follows: system.sysuptime.0 Some OID values are counters. 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. The interface can be configured to store counter values as rates. If the location2 attribute for a point is set to 1, PI Interface for SNMP User Guide 5

12 How the PI Interface for SNMP works the interface stores 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 = ( )/60 = 30 A trend of such values might be more meaningful for your application, because it provides the number of values transferred per second rather than a series of raw counters. PI Interface for SNMP logic The interface behaves like an SNMP Manager. It retrieves information from network devices using the SNMP agent running on these devices. The following figure shows a typical configuration for the PI Interface for SNMP. To retrieve data from SNMP-enabled network devices, you configure PI points that refer to the desired SNMP statistic for the network element to be monitored. At startup, the interface loads its points from the PI Data Archive. To determine which points it maintains and how to process them, the interface checks the following point attributes: location1 and pointsource: Verify that the interface ID and point source configured for the point matches those configured for this interface instance. exdesc: Reads the OID (Object Identifier) specification for the community string information if the data is to be read from an SNMPv1 or SNMPv2c agent; or the username, authentication password, and privacy password if the data is to be read from an SNMPv3 agent. 6 PI Interface for SNMP User Guide

13 How the PI Interface for SNMP works instrumenttag: Reads the hostname or IP address of the SNMP agent. location2: Indicates whether the point is an input or output point. location3: If set to 1, indicates that the point is part of a group that references a common SNMP agent. By default, PI Interface for SNMP sends a single request for each PI point to retrieve its corresponding OID value When the interface is ready to poll SNMP agents for data, it creates a separate thread for each agent. After the thread receives a value for a particular OID from an SNMP agent, the interface applies the conversion factor (for numeric points) and sends the resulting value to the interface, which forwards it to PI Data Archive. After startup is complete, the interface enters its processing loop, which includes the following tasks: Servicing scan-based input points, processing each scan class in turn. Servicing output points as events arrive. Servicing triggered input points as events arrive. Check the PI point database for points that are added, edited, and deleted. If the interface detects new points or changes to existing points, it reloads points from the PI Data Archive. To ensure that reloading does not interfere with data collection, the interface processes 25 point updates at a time. If more than 25 updates need to be loaded, the interface pauses between batches, waiting 30 seconds or the point update interval that is configured for the instance, whichever is lower. If you ve changed a large number of PI points, stop and restart the interface, to enable it to load all the changes efficiently during startup instead of in batches during normal data collection. Informational and error messages generated by the interface are logged to the PI message log file during interface startup, during data collection, and during shutdown. Additional messages are logged if you enable debugging. For more information about reading message logs, see the OSIsoft Knowledge Base article How to read new UniInt x and later Interface message logs ( id=kb00401). SNMP message size By default, the interface does not group multiple requests for information into a single SNMP GetRequest message. The PDU (Protocol Data Unit) that PI Interface for SNMP sends to a network device contains a GetRequest for a single OID. The size of such a message is approximately 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 might be a descriptor such as the following: IOS I 3600 Software (C3660-DS-M), Version 12.0(5)T1, RELEASE SOFTWARE (fc1) Copyright I by cisco Systems, Inc. Compiled Thu 19-Aug-99 18:15 by cmong The preceding value consists of 213 octets. With the addition of the various SNMP, UDP, and IP headers, the size of the complete message is about 280 octets. PI Interface for SNMP User Guide 7

14 How the PI Interface for SNMP works When the interface retrieves numeric values, the size of the returned message is also about 80 octets. For comparison, a single Ping message from a Windows computer contains about 64 octets. 8 PI Interface for SNMP User Guide

15 Installation checklist If you are familiar with running PI data collection interface programs, this checklist helps you get the interface running. If you are not familiar with PI interfaces, return to this section after reading the rest of the manual in detail. This checklist summarizes the steps for installing this interface. You need not perform a given task if you have already done so as part of the installation of another interface. For example, you only have to configure one instance of buffering for every interface node regardless of how many interfaces run on that node. Read-only and read-write interfaces OSIsoft provides both read-only and read-write options of many interfaces. Due to the inherent security risks associated with writing to the data source, OSIsoft recommends using the readonly option when possible. If you do not need to write to the data source, select the read-only version of the interface. For more information about the read-only version of the interface, or if you are migrating from a read-write version to a read-only version and want to view the migration procedure, refer to the Read-only versus read-write FAQ ( content/en/int-read-faq-v1/guid-9f207c13-40e4-472e-8d40-8d6ee87c86f7) on the online Live Library. If a read-only version is not available, disable interface updates to the data source. For more information, refer to the Disable read-write interface updates to the data source section in this document. If you need to write to the data source, select the read-write version of the interface and secure your points in the following ways: Create an output point whitelist file that is secured so that only authorized users can change it. For more information, refer to the PI Universal Interface (UniInt) Framework User Guide ( AE4FAFE0-FEA3-451B-8EF3-D8875B6F7049) on the online Live Library. Isolate output points using a separate interface instance from the input point interface instance. Disable read-write interface updates to the data source OSIsoft recommends using the read-only option of the interface whenever possible. If a readonly option is not available, perform the following steps to disable outputs using PI ICU to secure the data source. Procedure 1. Open PI ICU and select the interface instance. 2. On the UniInt tab, select Disable all outputs from PI. 3. Click Apply. PI ICU saves the configuration. PI Interface for SNMP User Guide 9

16 Installation checklist Data collection steps The data collection steps below are required. Procedure 1. Confirm that you can use PI SMT to configure PI Data Archive. You do not need to run PI SMT on the same computer on which you run this interface. 2. If you are running the interface on an interface computer, edit the PI Data Archive s Trust table to allow the interface to read attributes and point data. If a buffering application is not running on the interface computer, the PI trust must allow the interface to write data. 3. Run the installation kit for the PI Interface Configuration Utility (ICU) on the interface computer if the ICU will be used to configure the interface. This kit runs the PI SDK installation kit, which installs both the PI API and the PI SDK. 4. Run the installation kit for this interface. The kit also runs the PI SDK installation kit which installs both the PI API and the PI SDK if necessary. 5. If you are running the interface on an interface computer, check the computer s time zone properties. An improper time zone configuration can cause the PI Data Archive to reject the data that this interface writes. 6. Run the ICU and configure a new instance of this interface. Essential startup parameters for this interface are: Point Source (/PS=x) Interface ID (/ID=#) PI Data Archive (/Host=host:port) Scan Class (/F=##:##:##,offset) 7. Use a data source-specific connection tool to confirm connection between the interface computer and the device. 8. If you will use digital points, define the appropriate digital state sets. 9. Add the X, Y, and Z states to the system digital state set. 10. Build input tags and, if desired, output tags for this interface. PtSecurity must permit read access for the PI identity, group, or user configured in the PI trust that is used by the interface. DataSecurity must permit read access (buffering enabled) or read/write access (unbuffered) for the PI identity, group, or user configured in the PI trust that is used by the interface. Note: When buffering is configured, the DataSecurity attribute must permit write access for the buffering application s PI trust or mapping. DataSecurity write permission for the interface s PI trust is required only when buffering is not configured. 11. Start the interface interactively and confirm its successful connection to the PI Data Archive without buffering. (The DataSecurity attribute for interface points must permit write access for the interface s PI trust.) 12. Confirm that the interface collects data successfully. 10 PI Interface for SNMP User Guide

17 Installation checklist 13. If output points are required, confirm that output points update the correct values in the data source. Create an output point whitelist file for the interface instance. 14. Stop the interface and configure a buffering application (either Bufserv or PIBufss). 15. Start the buffering application and the interface. Confirm that the interface works together with the buffering application by physically removing the connection between the interface computer and the PI Data Archive computer. Note: The DataSecurity attribute for interface points must permit write access for the buffering application s PI trust or mapping. The interface s PI trust does not require DataSecurity write permission. 16. Configure the interface to run as a Windows service. Confirm that the interface runs properly as a service. 17. Restart the interface computer and confirm that the interface and the buffering application restart. Interface diagnostics (optional) Perform the following interface diagnostic procedures to implement data gathering mechanisms on your interface. Procedure 1. Configure Scan Class Performance points. 2. Install the PI Interface for Performance Monitor on the interface computer. 3. Configure performance counter points. 4. Configure UniInt Health Monitoring points. 5. Configure the I/O Rate point. 6. Install and configure the Interface Status Utility on the PI Data Archive computer. 7. Configure the Interface Status point. Advanced interface features (optional) Configure UniInt failover; see the corresponding chapter in the PI Universal (UniInt) Framework User Guide ( for details related to configuring the interface for failover. PI Interface for SNMP User Guide 11

18 Installation checklist 12 PI Interface for SNMP User Guide

19 Installation instructions OSIsoft recommends that interfaces be installed on interface computers instead of directly on the PI Data Archive computer. An interface computers is any computer other than the PI Data Archive computer where the PI Application Programming Interface (PI API) is installed (see the PI API manual). With this approach, the PI Data Archive need not compete with interfaces for the machine's resources. The primary function of the PI Data Archive is to archive data and to service clients that request data. After the interface has been installed and tested, buffering should be enabled on the interface computer. Buffering refers to either PI API Buffer Server (Bufserv) or the PI Buffer Subsystem (PIBufss). In most cases, interfaces on interface computer 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 Data Archive computer. In this case, the typical procedure is to install the PI Data Archive as an automatic service and install the interface as an automatic service that depends on the PI Update Manager and PI Network Manager services. Note: By default, buffering is not enabled on the PI Data Archive computer. Bufserv or PIBufss can be enabled on the PI Data Archive computer so that interfaces on the PI Data Archive computer do not need to be started and stopped in conjunction with the PI Data Archive. Name conventions and requirements In the installation procedure below, it is assumed that the name of the interface executable is <interface name>.exe and that the startup command file is called <interface name>.bat (where you replace <interfacename> with the name of your actual interface). Configure the interface manually 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, <interfacename>1.exe and <interfacename1>1.bat would typically be used for instance 1, <interfacename>2.exe and <interfacename>2.bat for instance 2, and so on (where you replace <interfacename> with the name of your actual interface). 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. Interface directories All PI interface installations use a standardized directory structure as described below: PI Interface for SNMP User Guide 13

20 Installation instructions PIHOME directory tree 32-bit Interfaces The [PIHOME] directory tree is defined by the PIHOME entry in the pipc.ini configuration file. This pipc.ini file is an ASCII text file, which is located in the %windir% directory. For 32-bit operating systems, a typical pipc.ini file contains the following lines: [PIPC] PIHOME=C:\Program Files\PIPC For 64-bit operating systems, a typical pipc.ini file contains the following lines: [PIPC] PIHOME=C:\Program Files(X86)\PIPC The above lines define the root of the PIHOME directory on the C: drive. The PIHOME directory does not need to be on the C: drive. OSIsoft recommends using the paths shown above as the root PIHOME directory name. Note: Restrict the Windows accounts that can create or write files in the %PIHOME% folder and subfolders. PIHOME64 directory tree 64-bit interfaces The [PIHOME64] directory tree is defined by a System Environmental Variable called PIHOME64. A typical value for this environmental variable is C:\Program Files\PIPC\. The above lines define the \Program Files\PIPC directory as the root of the PIHOME64 directory tree on the C: drive. OSIsoft recommends using \Program Files\PIPC as the root directory name. The PIHOME64 directory does not need to be on the C: drive. Note: Restrict the Windows accounts that can create or write files in the %PIHOME% folder and subfolders. Interface installation directory The installation kit for the read/write version will automatically install the interface to: PIHOME\Interfaces\<interfacename> (where <interfacename> is the name of your actual interface). Note: PIHOME is defined in the pipc.ini file. 14 PI Interface for SNMP User Guide

21 Installation instructions Interface installation procedure The interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows operating systems. To install, run the appropriate installation kit. 32-bit Interface: <interfacename>_#.#.#.#_.exe 64-bit Interface: <interfacename>_#.#.#.#_x64_.exe Silent installation procedure To launch a silent installation, type: Setup.exe -f silent.ini The silent.ini file is included in the interface installation kit. You can make site-specific alterations to the file as needed. See the silent.ini file for further information and descriptions of available arguments. Note: Please note all other modules in the interface installation kit are configured to be installed by default. PI trust for interface authentication A PI Interface usually runs on an interface computer as a Windows service, which is a noninteractive environment. In order for an interface to authenticate itself to a PI Data Archive and obtain the access permissions for proper operation, the PI Data Archive must have a PI trust that matches the connection credentials of the interface. For more information on interface security and PI trusts, refer to the PI Universal Interface (UniInt) Framework User Guide ( GUID-8F381E6E-78D6-4AF1-BC A003908). Install interface as Windows service The interface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually. Note: For improved security, we recommend running the interface service under a nonadministrative account, such as a Windows built-in service virtual account, the built-in Network Service account, or a non-administrative account that you create. PI Interface for SNMP User Guide 15

22 Installation instructions Install interface service with PI Interface Configuration Utility (ICU) Service configuration The PI Interface Configuration Utility (PI ICU) provides a user interface for creating, editing, and deleting the interface service. The following are descriptions of fields in the PI ICU tool. Service name The Service name box shows the name of the current interface service. This service name is obtained from the interface executable. 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 name to indicate that the service is part of the OSIsoft suite of products. Log on as The Log on as box shows the current "Log on as" Windows account of the interface service. If the service is configured to use the NT Service account, the Log on as will have selected "NT Service." Users may specify a different Windows account for the service to use. Note: As a security best practice, OSIsoft recommends running this interface service under a lest privileged account, such as a Windows service virtual account, the build-in Network Service account, or a non-administrative account that you create. PI ICU versions earlier than x cannot create a service that runs as a Windows built-in service virtual account or the built-in Network Service or NT Service accounts. After ICU creates the interface service, you can change the account with a Windows administrative tool, such as Services on the Control Panel or the sc command-line utility. 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. 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 16 PI Interface for SNMP User Guide

23 Installation instructions button. For example, if API Buffering is enabled, then Bufserv or PIBufss 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 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 interface service will not run. Note: Please see the PI Log and Windows Event Logger for messages that may indicate the cause for any service 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, select 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. 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. 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 The toolbar contains a Start button and a Stop button. 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. PI Interface for SNMP User Guide 17

24 Installation instructions Ready - Status of the ICU Stopped - Status of the Interface Service <interfacename> - Installed - Service installed or uninstalled Note: <interfacename> is the name of your actual interface. Install interface service manually You can access help for installing the interface as a service at any time by using the following command: interfacename.exe /help Procedure 1. Open a Windows command prompt window and change the directory to where the interfacename.exe executable is located. Consult the following table to determine the appropriate service installation command. Note: In the following Windows service installation commands, you may use either a slash (/) or dash (-) as the delimiter. Windows Service Installation Commands on an Interface computer or a PI Data Archive computer with Bufserv implemented Manual service <interfacename>.exe /install /depend "tcpip bufserv " Automatic service interfacename.exe /install /auto / depend "tcpip bufserv" Automatic service with service ID interfacename.exe /serviceid x / install /auto /depend "tcpip bufserv" Windows Service Installation Commands on an Interface computer or a PI Data Archive computer without Bufserv implemented Manual service interfacename.exe /install /depend tcpip Automatic service interfacename.exe /install /auto / depend tcpip Automatic service with service ID interfacename.exe /serviceid X / install /auto /depend tcpip Note: 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. 2. Check the Services control panel to verify that the service was added successfully. 18 PI Interface for SNMP User Guide

25 Installation instructions 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. The service installation commands in this section create an interface service that runs under a low-privilege built-in account. On Windows 7 and Server 2012 and later, the service logs on as the service virtual account. For earlier versions of Windows, the service logs on as Network Service. Note: For best security, run this interface service under an account with minimum privileges, such as a Windows service virtual account, the built-in Network Service account, or a non-administrative account that you create. The services control panel can change the account that the interface service runs under. Changing the account while the interface service is running does not take effect until the interface service is restarted. PI Interface for SNMP User Guide 19

26 Installation instructions 20 PI Interface for SNMP User Guide

27 PI Point configuration The PI point is the basic building block for controlling data flow to and from the PI Data Archive. A single point is configured for each measurement value that needs to be archived. Use PI SNMP Tag Builder To create PI points using PI SMT, perform the following steps: Procedure 1. Choose IT Points > SNMP. The following tabs are displayed in the right pane: 2. On the Tag Settings tab, choose the interface instance for which you want to build points and specify the desired scan class. 3. On the SNMP Settings tab, configure the target devices. 4. On the Build Tags tab, check the SNMP objects for which you want to create PI points and click Assign Tags. The objects you select are listed in the right pane. 5. To create the points, choose the target PI Data Archive, and then click Create Tags. PI Interface for SNMP User Guide 21

28 PI Point configuration Point attributes Use the point attributes below to define the PI point configuration for the interface, including specifically what data to transfer. This document does not discuss the attributes that configure UniInt or PI Data Archive processing for a PI point. Specifically, UniInt provides exception reporting and the PI Data Archive or PIBufss provides data compression. Exception reporting and compression are very important aspects of data collection and archiving, which are not discussed in this document. Note: Depending on the configuration, your interface may not contain all the point attributes in this section. Note: See the PI Universal (UniInt) User Guide ( File/13fa8d2c-b2f5-4b10-96ec-0a7a6b2531e3) and PI Data Archive documentation for information on other point attributes that are significant to PI point data collection and archiving. Tag (PI point name) The Tag attribute (or tag name) is the name for a point. There is a one-to-one correspondence between the name of a point and the point itself. Because of this relationship, PI Data Archive documentation uses the terms "tag" and "point" interchangeably. Follow these rules for naming PI points: The name must be unique in the PI Data Archive. The first character must be alphanumeric, the underscore (_), or the percent sign (%). Control characters such as linefeeds or tabs are illegal. The following characters also are illegal: * '? ; { } [ ] \ ` ''"" Tag length Depending on the version of the PI API and the PI Data Archive, this interface supports Tag attributes whose length is at most 255 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Data Archive versions. Supported tag length PI API PI Data Archive Maximum Length or later x or later or later Earlier than x 255 Earlier than x or later 255 Earlier than Earlier than x PI Interface for SNMP User Guide

29 PI Point configuration PointSource (point source) PointSource is an identifier that associates a PI point with a PI interface instance, enabling the interface to query the PI Data Archive for the points that it updates. This field is not casesensitive. In the interface (batch) startup file, the point source is specified using the /PS command-line parameter. The following point sources are reserved. Do not configure them for interface instances. Reserved point sources Point Source T G R Reserved By Totalizer Subsystem Alarm subsystem Random interface 9 RampSoak interface C Performance equations subsystem PointType (data type) PointType specifies the data type of the point. Typically, item data types do not need to match PI point data types exactly, but the data types must be compatible. For example, integer values from a device can be sent to floating-point or digital PI tags. Similarly, a floating-point value from the device can be sent to integer or digital PI points, although the values might be truncated. Location1 (interface instance) Location1 specifies the instance of the interface to which the PI point belongs. The value of this attribute must match the ID configured for the interface instance. This setting plus PointSource identify the interface instance that writes to a particular point. ( /ID). Location2 The location2 attribute specifies whether a point is an input point, which records SNMP data from a device to the PI Data Archive, or an output point, which writes data from the PI Data Archive to the device. Caution: When outputs are required, securing the output point using a whitelist provides the best defense against accidental or malicious changes to the data source. For information about securing output points using a whitelist file, see the PI Universal Interface (UniInt) User Guide. Location3 (Allow grouping) By default, PI Interface for SNMP sends a single request for each PI point to retrieve its corresponding OID value. To reduce the number of requests, the interface can group points so PI Interface for SNMP User Guide 23

30 PI Point configuration it can issue a single request for multiple points that have identical settings for the following attributes: SNMP device name (host = parameter in the instrumenttag attribute) Community string (CS = parameter in the exdesc attribute) for SNMPv1 and SNMPv2c points User name ( user= parameter in the exdesc attribute) for SNMPv3 points Scan class (location4) To enable grouping for a point, set its location3 attribute to 1. By default, PI Interface for SNMP groups points into sets of five. To configure the number of points in a group using PI ICU, go to the PISNMP tab, check Number of tags per set and specify the desired group size. The recommended maximum number of points per group is 100. Note: When configuring points to be grouped, you must specify the network device (the host parameter) using identical network device names. Even if host= router and host= refer to the same network device, the interface does not group them. When PI Interface for SNMP first starts up, it logs a summary of the groups that 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 Using a single request to read multiple OIDs increases the efficiency of data collection. However, very large requests might be fragmented into multiple packets and might not reach their destination, or they might overwhelm the capability of the SNMP agent to respond. If the SNMP agent does not recognize one or more of the OIDs in the group, all the points in the group are assigned the Configure error state. In this situation, the interface logs messages like the following: To find out which point contains the unsupported OID, use the Getif program. 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 Location4 (scan class) The scan class determines the frequency at which input points are scanned for new values. Set to 0 for event-based (trigger) tags, unsolicited inputs, and output points. For auditing changes to points, set to -1 to record the short-form version of tag attribute changes or -2 to record the long-form version. Location5 The location5 attribute configures the level of detail in the messages that the interface logs for the point. 24 PI Interface for SNMP User Guide

31 PI Point configuration Settings are as follows: Setting (location5) 0 none 1 minimal 2 medium Debugging Level 3 maximum You do not need to stop and restart the interface after changing location5. Note that the interface takes up to two minutes to detect changes to point configuration. Instrument tag (SNMP device) InstrumentTag Length Depending on the version of the PI API and the PI Data Archive, this interface supports an InstrumentTag attribute whose length is at most 32 or 1023 characters. PI API PI Data Archive Maximum Length or later x or later or later Earlier than x 32 Earlier than x or later 32 Earlier than Earlier than x 32 The instrumenttag attribute configures the IP address or host name of the SNMP device that is the data source for an input point or the target of an output point. Note: All PI Interface for SNMP tags must have a host defined in the instrumenttag attribute. The SNMP security file is not a global replacement for this configuration. Specify the setting using the following format (note the semicolon terminator): host=device[:port]; host= ; host=router1; host= :5161; Note: Setting the host=device[:port] in instrumenttag overrides any setting made in the ICU or in the (obsolete) pisnmp.ini file. ExDesc (SNMP settings) Object identifier (OID) Specify the SNMP OID to be read or set. For example: PI Interface for SNMP User Guide 25

32 PI Point configuration OID= ; For OIDs that are part of the standard MIB-II, you can specify the textual representation. For example: OID=system.sysUptime.0; For OIDs that are part of the interfaces.iftable.ifentry group, you can use this abbreviated format: OID_I=ifInOctets.3; The interface treats the preceding entry as equivalent to the following: OID=interfaces.ifTable.ifEntry.ifInOctets.3; Detecting changes in dynamically-assigned indexes When a router is restarted, it often assigns a different index number to a particular instance of one of its network interfaces. Because PI points for the interface are mapped to instances using the index number, this renumbering causes the point to stop collecting data. To detect when an instance has been renumbered, you can specify a key identifier. Before loading the point, the interface sends an SNMP request to the network device and asks for the value of the specified identifier. 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 the point. You can configure the KEY value only for input points, and only to match values from interfaces.iftable.ifentry.ifdescr.x with OIDs from the interfaces group. For example, an interface named Serial1/0.1 has an ifindex value of 25. The OID variable interfaces.iftable.ifentry.ifinoctets.25 represents the number of inbound octets received on this Serial1/0.1 interface. The PI point named tag1 is configured to read this variable by specifying the following setting in its ExDesc attribute: OID_I=ifInOctets.25 After a router reboot, the Serial1/0.1 interface is assigned an ifindex of 31. Therefore, the number of inbound octets received on the interface is now addressed by the OID interfaces.iftable.ifentry.ifinoctets.31. However, the point still addresses the ifindex of 25 and, as a result, is no longer collecting data for Serial1/0.1. Note that, if you use the PI SNMP Tag Builder plug-in for PI SMT 3.x to build points, the KEY value is automatically entered into the exdesc point attribute. Note: Some Cisco routers support the ifindex persist option for the config command, which prevents indexes from being renumbered when the router is restarted. If you are running this configuration, the KEY=identifier is not necessary. After issuing ifindex persistence commands, you must save the configuration by issuing the copy runningconfig startup-config EXEC mode command to ensure consistent ifindex values. See the Cisco IOS documentation for more information. Group and row identifiers To handle row-indexed dynamic OIDs, you can use these settings to specify the group and sequence number of an OID. Set the OID_G= parameter to specify an OID group and OID_G_R= to designate the row in the group. 26 PI Interface for SNMP User Guide

33 PI Point configuration For example, to read the second OID in the group, specify OID_G= ; OID_G_R=2; If a scan returns the following group of OIDs: the interface reads from If the subsequent scan returns: the interface reads from Note: Reading a row-indexed OID takes longer than reading an absolute OID. For best performance, you should specify fixed OIDs by using the OID= parameter, and use the OID_G= and OID_G_R= parameters for dynamic OIDs only. SNMP IP address data type By default, the interface cannot store 32-bit numeric IP addresses in string points. To store the IP address as a string using dot notation, specify the following setting: IPADDR=1; SNMP version Specify the version of SNMP as shown in the following table. Version SNMPv1 SNMPv2c SNMPv3 Extended Descriptor V=1; V=2c; V=3; If a version is not specified, the interface defaults to SNMPv1. SNMPv1 and SNMPv2c community strings For points that are configured to read a value using SNMPv1 or SNMPv2c, you must specify the correct SNMP community string. For example: CS=public; For output points, use the keyword WCS=community-string. For example: WCS=private; PI Interface for SNMP User Guide 27

34 PI Point configuration Caution: Anyone with access to the PI point database has access to these community strings. For tighter security, you can store the community strings in an encrypted file called pisnmp.pwd. To enable this option using PI ICU, go to the PISNMP tab and check Read community string from pisnmp.pwd instead of Exdesc and The pisnmp.pwd file has been encrypted. SNMPv3 authentication settings SNMPv3 adds authentication and privacy enhancements to earlier SNMP specifications. 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. For points that are to be read using SNMPv3, specify the user name and password as follows: USER=username; APW=password; For MD5 authentication, specify AUTH=MD5;. For SHA authentication, specify AUTH=SHA;. Consult the documentation for the device to determine which to use. If you omit this setting, the interface defaults to MD5. 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 that is used to encrypt the message. Specify this password in the extended descriptor (exdesc) attribute, as follows: PPW=password; If you have configured the interface instance to read settings from the pisnmp.pwd file, specify these settings in this file rather than in the point s extended descriptor attribute. The ExDesc attribute configures a variety of run-time settings, two of which are included in every interface and are described in the following table. Note: Keywords must be specified in upper case. Keyword Description Example PERFORMANCE_POINT When set, such point stores the amount of time, in seconds, that it takes an interface to complete a scan for a particular scan class. The lower the scan time, the better the performance. PERFORMANCE_POINT For details, refer to the PI Universal Interface (UniInt) User Guide ( techsupport.osisoft.com/ Downloads/File/13fa8d2cb2f5-4b10-96ec-0a7a6b2531e3). 28 PI Interface for SNMP User Guide

35 PI Point configuration Keyword Description Example TRIG or EVENT For event-driven input points: each time the specified point changes, the SQL query is executed. If the point name contains spaces, you must enclose it in single quotes. If there are subsequent parameters, you must specify a comma after the /EVENT specification. Valid conditions: anychange increment decrement nonzero For details about defining eventdriven points, refer to the PI Universal Interface (UniInt) User Guide ( techsupport.osisoft.com/ Downloads/File/13fa8d2cb2f5-4b10-96ec-0a7a6b2531e3). /EVENT = sinusoid, or /EVENT = sinusoid anychange, Note: To assign values to replaceable parameters in SQL queries, you specify placeholders in the ExDesc attribute. Replaceable parameters in queries are indicated by question marks. ExtendedDescriptor Length PI API PI Data Archive Maximum Length or later x or later or later Earlier than x 80 Earlier than x or later 80 Earlier than Earlier than x 80 Depending on the version of the PI API and the PI Data Archive, this interface supports an ExDesc attribute whose length is at most 80 or 1023 characters. The following table indicates the maximum length of this attribute for all the different combinations of PI API and PI Data Archive versions. Performance Points For UniInt-based interfaces, the extended descriptor is checked for the string PERFORMANCE_POINT. If this character string is found, UniInt treats this point as a performance point. PI Interface for SNMP User Guide 29

36 PI Point configuration Value Digital state set points to track device status PI digital state sets are lists of enumerated strings, enabling points to store the enumerated values and client applications to display the corresponding string. The PI Interface for SNMP defines a digital state set that you can use to record the state of SNMP devices. The Operstat state set is defined the first time that you create SNMP interface points using the SNMP tag builder in PI SMT. The state set contains the following states: 1 Up Description 2 Down 3 Testing If you create points for the interface using some other method, such as PI Point Builder or the PI Tag Configurator plug-in for Microsoft Excel, you can create the digital state set manually using PI SMT. 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, a message is written to the log and the point is not loaded by the interface. There is one exception to the previous statement. If any PI point is removed from the interface while the interface is running (including setting the Scan attribute to 0), SCAN OFF will be written to the PI point regardless of the value of the Scan attribute. Two examples of actions that would remove a PI point from an interface are to change the point source or set the Scan attribute to 0. If an interface-specific attribute is changed that causes the point to be rejected by the interface, SCAN OFF will be written to the PI 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 Data Archive 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 following command-line parameter is specified: /stopstat=shutdown 30 PI Interface for SNMP User Guide

37 PI Point configuration SHUTDOWN events can be disabled from being written to PI points when the PI Data Archive is restarted by setting the Shutdown attribute to 0 for each point. Alternatively, the default behavior of the PI Shutdown Subsystem can be changed to write SHUTDOWN events only for PI points that have their Shutdown attribute set to 0. To change the default behavior, edit the Shutdown.dat file, as discussed in the PI Data Archive manuals. Bufserv and PIBufss It is undesirable to write shutdown events when buffering is being used. Bufserv and PIBufss are utility programs that provide the capability to store and forward events to a PI Data Archive, allowing continuous data collection when the PI Data Archive is down for maintenance, upgrades, backups and unexpected failures. That is, when the PI Data Archive is shutdown, Bufserv or PIBufss will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface. Disabling Shutdown is recommended when sending data to a Highly Available PI Data Archive collective. Refer to the Bufserv or PIBufss manuals for additional information. DataSecurity The PI identity in the PI trust that authenticates the interface must be granted read access by the DataSecurity attribute of every PI point that the interface services. If the interface is used without a buffering application, write access also must be granted. (If the interface is used with a buffering application, the buffering application requires write access but the interface does not.) PtSecurity The PI identity in the PI trust that authenticates the interface must be granted read access by the PtSecurity attribute of every PI point that the interface services. Output points Output points control the flow of data from the PI Data Archive to any destination that is external to the PI Data Archive, such as a PLC or a third-party database. For example, to write a value to a register in a PLC, use an output point. Each interface has its own rules for determining whether a given point is an input point or an output point. There is no de facto PI point attribute that distinguishes a point as an input point or an output point. Note: If outputs to the data source device are not needed, specify a database user with readonly privileges and reference it through the /User_ODBC start-up parameter. Alternatively, implement an explicit output point whitelist, which provides a defense against accidental or malicious changes to a database. PI Interface for SNMP User Guide 31

38 PI Point configuration 32 PI Interface for SNMP User Guide

39 Startup command files Command-line parameters can begin with a forward slash ( / ) or with a dash ( -). For example, the /ps=m and -ps=m command-line parameters are equivalent. Example Startup batch 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 ^ REM REM End of pisnmp.bat File -f=00:00:10 ^ -host=xxxxxx:5450 ^ -ps=snmp ^ -id=1 ^ -stopstat="intf Shut" Configure the PI Interface for SNMP with PI ICU Note: PI ICU requires PI 3.3 or later. 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 PI Module Database. The procedure below describes the necessary steps for using PI ICU to configure the PI SNMP Interface. Procedure 1. From the PI ICU menu, select Interface, then New Windows Interface Instance from EXE, and then browse to the PISNMP.exe executable file. Then, enter values for Host PI System, Point Source and Interface ID#. A window such as the following results: PI Interface for SNMP User Guide 33

40 Startup command files Interface name as displayed in the ICU (optional) will have a PI- pre-pended to this name and it will be the display name in the services menu. 2. Click Add The following message should appear: Note: Note that in this example the Host PI System is RBALARAMAND630. To configure the interface to communicate with a remote PI Server, select 'Interface => Connections ' item from PI ICU menu and select the default server. If the remote node is not present in the list of servers, it can be added. 3. Once the interface is added to PI ICU, near the top of the main PI ICU window, the interface Type should be PISNMP. If not, use the drop-down box to change the interface Type to PISNMP. 34 PI Interface for SNMP User Guide

41 Startup command files 4. Click Apply to enable the PI ICU to manage this instance of the PI SNMP interface. 5. You configure interface-specific settings on the pisnmp tab, shown in the following figure. PI Interface for SNMP User Guide 35

42 Startup command files Note: Since the PI SNMP interface is a UniInt-based interface, in some cases the user will need to make appropriate selections in the UniInt page. This page 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 page. This page allows configuration of the interface to run as a service, as well as to start and to stop the interface service. The interface can also be run interactively from the PI ICU. To do that, select Start Interactive on the Interface menu. For more detailed information on how to use the above-mentioned and other PI ICU pages and selections, please refer to the PI Interface Configuration Utility user guide. The section below describes the selections that are available from the pisnmp page. 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. Pisnmp Interface page Since the startup file of the PI SNMP interface is maintained automatically by the PI ICU, use the Pisnmp page to configure the startup parameters and do not make changes in the file manually. The following is the description of interface configuration parameters used in the PI ICU Control and corresponding manual parameters. 36 PI Interface for SNMP User Guide

43 Startup command files The PI SNMP ICU Control for PI ICU has two sections. A yellow text box indicates that an invalid value has been entered, or that a required value has not been entered. Read community string from pisnmp.pwd instead of Exdesc The check box above 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 <router1> host= CS=company123; read community string for < > WCS=company456; write community string for < > host=switch2; CS=gnomes11; read community string for <switch2> host=router3; USER=manager; SNMPv3 user for <router3> AUTH=SHA; Use SHA authentication APW=23oaktree; authentication password for <router3> PPW=hummingbird; privacy password for <router3> PI Interface for SNMP User Guide 37

44 Startup command files Note: A single HOST entry does not apply to the tags, the HOST entry in the file is not used by the interface as far as the tag definition HOST. 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 host file must be created. An entry then must be created in pisnmp.pwd for each alias. (-PWD) Note: The content of this.pwd file is case sensitive. 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 plain text, 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. To 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. 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 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 38 PI Interface for SNMP User Guide

45 Startup command files 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. (-cto=#) 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. (-CR=#) Allow SNMP SETs/PI outputs To have the interface to support SNMP SETs/PI outputs, check this box. (-OUT) Additional parameters This section is provided for any additional parameters that the current ICU Control does not support. 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 fil IP Address PI Interface for SNMP User Guide 39

46 Startup command files These four text boxes allow entry of a TCP/IP address for the single device configuration. The values must be a number between 1 and 255 for each text box. (- DEVICE=###.###.###.###) Hostname This box is used to enter the host name for the single device configuration. (- DEVICE=<Hostname>) Note: The UniInt Interface User Manual includes details about other command-line parameters, which may be useful. 40 PI Interface for SNMP User Guide

47 Command-line parameters for the PI Interface for SNMP These parameters are provided for debugging purposes, to help you read the file. To ensure a correctly-formatted file, use the PI Interface Configuration Utility to configure the interface. The interface also supports standard UniInt parameters. For details, refer to the PI Universal Interface (UniInt) User Guide. Note: PI Interface for SNMP requires the - delimiter instead of the default UniInt / delimiter. Interface-specific command-line parameters used in the interface startup batch file to configure settings Parameter and syntax -cr -device=<device-spec> -enc -ignoredevice=devicename -out -port=# -pwd -retries=# Description Optional: If the cr parameter is specified, the interface will write Configure to rejected points. By default, the interface will not write any values to rejected points. Optional: Retrieve data only from the specified device. The device can be specified as an IP address or a hostname. This parameter can be used only with a device that supports the ifalias group. Optional: Tells the interface to encrypt the contents of pisnmp.pwd and incorporate the results into a file named pisnmp.enc. If pisnmp.enc does not exist, it is created. After its contents have been encrypted, pisnmp.pwd is deleted. Optional: Tells the interface to ignore the specified device(s). This switch can be used more than once on the command line, for example to exclude scan classes. The devicenamecan be either the name or IP address of the device. The switch supports wildcard characters (*) so multiple devices can be ignored. The wildcard can be placed at the beginning, end, or anywhere in the middle of the devicename string; and more than one wildcard character can be used. Optional: Enables SNMP SET/PI output support in the interface. If this parameter is not present, the interface rejects points whose location2 attribute is negative. Default: Do not allow output points. Optional: Specifies the port number that the interface uses to communicate with the SNMP enabled device. The default is 161. Default: -port=161 Optional: Tells the interface to read a SNMPv1 / SNMPv2c community string or SNMPv3 security information from the pisnmp.pwd file instead of from a point s extended descriptor (exdesc) attribute. Optional: Specifies the number of times the interface retries its transmission of an SNMP GetRequest message to the network device. The default number of retries is 3. Default: -retries=3 PI Interface for SNMP User Guide 41

48 Command-line parameters for the PI Interface for SNMP Parameter and syntax -setcount=# -tc=# -timeout=# Description Optional: Specifies the number of tags per set. When location3 is set to 1, the interface groups tags into a single request for efficiency. The default number of tags per set is 5. Default: -setcount=5 Optional: The tc parameter is used to specify the number of threads used by the interface to collect data from the devices. The number of threads can range from 1 to 50. The default is 10 if the tc parameter is not specified. Default: -tc=10 Optional: Specifies the number of milliseconds that the interface will wait for a reply from the network device. The default timeout is 3000 milliseconds. If the interface 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. Default: -timeout=3000 Maximum: -timeout= Prior to version , the interface stored some of its configuration information in a file named pisnmp.ini. Later versions of the interface use this file if it is present, but settings in the startup batch file, which is maintained using PI ICU, take precedence over settings configured in pisnmp.ini. The following table lists current command-line equivalents to the old pisnmp.ini parameters: Parameter in pisnmp.ini consecutive_timeouts= port= retries= tags_per_set= timeout= Parameter in pisnmp.bat cto= port= retries= setcount= timeout= 42 PI Interface for SNMP User Guide

49 Specific considerations regarding PI Point configurations for the PI Interface for SNMP Below are a list of specific considerations for PI Interface for SNMP: Router traffic data collection Routers connect networks and route traffic among them. Following are examples of how you might configure the interface to monitor routers in typical scenarios. Under SNMP, the interfaces in a router are indexed by an Object Identifier (OID) called ifindex. This index is a positive integer that enables you to reference and correlate other interface OID variables (for example, interface speed). The SNMP agent on the router automatically assigns the value of ifindex. The value of ifindex does not have to start at 1, and the indexes are not necessarily consecutive. The value of the OID variable interfaces.iftable.ifentry.ifspeed.x (where X is an ifindex value) is expressed as bits per second. To determine the amount of traffic that is traversing a particular interface and index, monitor the values of the following OID variables: interfaces.iftable.ifentry.ifentry.ifinoctets.x The total number of octets (a group of 8 bits) received on the interface, including framing characters. interfaces.iftable.ifentry.ifentry.ifoutoctets.x The total number of octets transmitted on the particular interface, including framing characters. These OID variables indicate the total number of octets received or transmitted. However, you might want to track the number of octets per second received or transmitted by the interface. To configure a point that records rate, set its location2 attribute to 1. The PI SNMP Tag Builder plug-in for PI SMT 3.x automates much of the configuration required for such monitoring. Consult the plug-in documentation for details. Example 1 - Business setting Consider an organization with three departments, Sales, Accounting, and Engineering. Each department has its own separate network. In addition, the company itself has a connection to the Internet through its ISP (Internet Service Provider). The following diagram shows how a router ties the networks together. PI Interface for SNMP User Guide 43

50 Specific considerations regarding PI Point configurations for the PI Interface for SNMP The following protocols are used: Interface Description Speed Connection to Ethernet0 10 Mbps Sales Ethernet1 10 Mbps Accounting FastEthernet 100 Mbps Engineering Serial1/0 512 Kbps ISP Examples of interface descriptions (interfaces.iftable.ifentry.ifdescr) and speeds (interfaces.iftable.ifentry.ifspeed) for the preceding configuration are as follows: ifindex OID variable OID value 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, OID=interfaces.ifTable.ifEntry.ifSpeed ,000,000 Example 2 - Internet Service Provider An ISP has a router that directs traffic from an internet backbone to its many customers, provisioned as follows: 44 PI Interface for SNMP User Guide

51 Specific considerations regarding PI Point configurations for the PI Interface for SNMP Interface Description Speed Connection to ATM2/ Kbps Customer1 ATM2/ Kbps Customer2 ATM2/ Kbps Customer3 Serial Mbps Internet backbone Examples of interface descriptions for the ISP: ifindex OID variable OID value 101 OID=interfaces.ifTable.ifEntry.ifDescr OID=interfaces.ifTable.ifEntry.ifDescr OID=interfaces.ifTable.ifEntry.ifDescr OID=interfaces.ifTable.ifEntry.ifDescr OID=interfaces.ifTable.ifEntry.ifSpeed OID=interfaces.ifTable.ifEntry.ifSpeed OID=interfaces.ifTable.ifEntry.ifSpeed OID=interfaces.ifTable.ifEntry.ifSpeed. 200 ATM2/0.1 ATM2/0.2 ATM2/0.3 Serial2 512, , ,000 1,544,000 Example 3 - PI Data Archive This PI Data Archive is configured to receive data from different areas of a plant, each running its own interface, as illustrated in the following figure. PI Interface for SNMP User Guide 45

52 Specific considerations regarding PI Point configurations for the PI Interface for SNMP The following table lists typical router provisioning for such a configuration. Interface Description Speed Connection to 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 Data Archive area of the plant Examples of interface descriptions for the PI Data Archive receiving data: ifindex OID variable OID value 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, PI Interface for SNMP User Guide

53 Specific considerations regarding PI Point configurations for the PI Interface for SNMP Use ifalias to ensure data collection after router reboot RFC 2233 specifies that if an SNMP agent supports the ifalias OID variable, 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." The interface 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. If the interface number is 2, the SNMP interface constructs the following OID: interfaces.iftable.ifentry.ifinoctets.2 and sends the appropriate request to the router. If the router restarts and the SNMP agent reassigns interface indexes, the interface still can read correct values for the tag, because it constructs the following OID to get the data from the router: interfaces.iftable.ifentry.ifinoctets.3 Because a particular device must be specified at startup, this configuration limits data collection to a single device. When configured for a single device, the interface groups all tags into sets, regardless of the value of location3. The specified router must support the system.sysuptime.0 OID. If this OID is not supported, the interface exits. Procedure 1. Configure PI points for the interface instance by setting the extended descriptor attribute keywords as follows: Inbound traffic OID_I=ifInOctets; IFALIAS="ifAlias_name_of_the_interface" Outbound traffic OID_I=ifOutOctets; IFALIAS="ifAlias_name_of_the_interface" Note: Omit the host and cs parameters. 2. Using PI ICU, go to the PISNMP tab and configure the interface instance. 3. Check Get data from one device and specify the device IP address or host name. 4. Check Read community string from pisnmp.pwd instead of Exdesc. 5. Click Edit pisnmp.pwd file and specify the host and community string settings. For example: host= ; cs=public; community string for Save your entries, return to PI ICU, and then click Apply. PI Interface for SNMP User Guide 47

54 Specific considerations regarding PI Point configurations for the PI Interface for SNMP Troubleshooting the PI Interface for SNMP The following sections describe issues you might encounter in configuring and running the interface, with suggestions for resolving the problems. Testing SNMP object identifiers (OIDs) To test an OID, use the Getif program to query an SNMP agent for its value. The following OIDs are useful for testing the interface and determining whether an SNMP agent is running on a particular network device. system.sysdescr Description of the network device, such as hardware and operating system system.sysuptime The time in hundredths of a second since the network management portion of the system was last initialized Interfaces.ifTable.ifEntry.ifInOctets The total number of octets (a group of 8 bits) received, including framing characters, on the first network interface interfaces.iftable.ifentry.ifoutoctets The total number of octets (a group of eight bits) transmitted, including framing characters on the first network interface interfaces.iftable.ifentry.ifinoctets The total number of octets received, including framing characters, on the second network interface interfaces.iftable.ifentry.ifoutoctets The total number of octets transmitted, including framing characters on the second network interface Interface fails to start The following are the most common reasons why the interface fails to start. No connection to PI Data Archive The interface does not start unless it can connect to PI Data Archive. To check connectivity, use the apisnap utility. Missing command-line parameters The interface does not start unless the interface ID and point source are configured. To configure these settings, use PI ICU. 48 PI Interface for SNMP User Guide

55 Specific considerations regarding PI Point configurations for the PI Interface for SNMP Missed scans If the interface consistently misses scans, it is probably attempting to retrieve values from SNMP devices that are not readily accessible, possibly devices that were previously accessible and subsequently removed, resulting in missed scans. To remedy the situation, use PI ICU to adjust the settings for the interface instance as follows: Decrease the number of retries Decrease the timeout interval Decrease the number of consecutive timeouts PI point troubleshooting Information from PI points can be used for troubleshooting. Unexpected value in point If a PI point is receiving an unexpected value, enable logging of debug output by setting the point s location5 attribute to 3. The interface will log detailed information about the value that it received from the SNMP device. The following is an example of debug output from the log: 25-Oct-13 13:23:00 The interface- 1> pt (localhost_sysuptime_abs), rx data type: not explicitly checked for 25-Oct-13 13:23:00 The interface- 1> val.integer is Oct-13 13:23:00 The interface- 1> pt (localhost_sysuptime_abs), t= drval=0.185 ival=0 istat=0 returned to UniInt This indicates that the interface: Received a value of from the SNMP device Sent a value of to the PI Data Archive (The conversion attribute of the point is , which is divided by ) Changes to the location5 attribute might require up to two minutes to take effect. If you have changed a large number of point attributes, consider restarting the interface to enable it to detect all changes during startup. After resolving the problem, be sure to set location5 back to 0 to avoid bloating the log. Point fails to load The following are the most common reasons why the interface fails to load a point into its list of points to service. Cannot Translate OID Before sending a request to a network device, the interface translates textual OIDs (for example, system.sysuptime.0) into their numeric format (for example, ). If it cannot do so, it prints the out a message such as the following: PI Interface for SNMP User Guide 49

56 Specific considerations regarding PI Point configurations for the PI Interface for SNMP The interface - 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 is a misspelling of ifinoctets. Note that some SNMP tools display OIDs incorrectly, for example, omitting the final zero. Confirm that the directory where the PI Interface for SNMP program is located contains a mibs directory containing MIB definition files. If it does not, messages such as the following appear: 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) Matching community string not found in pisnmp.pwd If pwd or enc appear in the startup command line, the interface looks in either the pisnmp.pwd or pisnmp.enc file for a matching device name. The interface 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 instrumenttag attribute. OID field not found The interface requires an OID specification in the instrumenttag or exdesc attribute. Host not found The interface requires the host parameter to be specified in a point's instrumenttag attribute. OID not valid If the interface cannot translate a textual OID into its numeric form, it does not load the point. No new values If a point is not accumulating values, check your configurations. Point not loaded During startup, the interface logs the number of points it has loaded; for example: > 15 points found for point source $. Confirm that the expected number of points is loaded. To test the interface, start by running with a small number of points. To enable debugging output for loading of points, set location5 to 1. PI Data Archive configuration Permissions on the PI Data Archive must be set so as to permit the interface to write to points. For details refer to PI Server Configuring PI Server Security documentation. Value of zero (0) If the conversion point attribute is 0 (zero), the interface writes a value of 0 for the point. If no transformation is required, set conversion to PI Interface for SNMP User Guide

57 Specific considerations regarding PI Point configurations for the PI Interface for SNMP If the OID value is zero, the interface writes a value of 0 (zero) to the corresponding PI point. For points with location2 set to 1 (SNMP "counter" values), the interface writes a value of 0 (zero) if the OID value is not changing. Run Getif twice in succession to check. I/O Timeout If the status of a point is I/O Timeout, check the following. Is the SNMP agent on the network device is responding? Run Getif to check the response of the SNMP agent on the network device. Is the community string (CS) or SNMPv3 username and password correct? Community strings and passwords often are case-sensitive. To check the validity of a community string or password, use the Getif program. Is the SNMP agent on the network device not responding quickly enough? Try increasing the timeout setting using PI ICU. Bad Input An interface point might have a status of Bad Input if the host specified in the point s instrumenttag attribute is incorrect, or if the KEY value specified in the extended descriptor does not match the one received from the network device. For example, for a point with the following options specified in its extended descriptor attribute: 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 reassigned index numbers to its interfaces. Edit the PI points so that they contain the correct index numbers. Configure status The following are possible reasons why an interface point might have a status of Configure. OID does not exist The network device reported back that the OID specified in the point s instrument tag (or extended descriptor) attribute is nonexistent. To check the existence of an OID on the network device, run Getif. Location3=1 and OID does not exist for a point in the set When location3 is set to 1, the interface groups points containing host and user settings into a single SNMP GET request. If any of the points in the group has an OID that is not recognized by the remote device, the interface writes Configure for all of the points in this set. The interface logs the error; for example: The interface- 2> Device reports at least 1 unknown OID in the following set of 2 tags: The interface- 2> Tag: router_tx_ethernet0/0, OID: interfaces.iftable.ifentry.ifoutoctets.85 PI Interface for SNMP User Guide 51

58 Specific considerations regarding PI Point configurations for the PI Interface for SNMP The interface- 2> Tag: router_jab_4, OID: rmon.statistics.etherstatstable.etherstatsentry.etherstatsjabbers To find out which point contains the unsupported OID, use the Getif program. Note that a network device might erroneously report that the OID does not exist. Invalid counter tag A point configured with location2 set to 1 must be of type counter as returned by the SNMP agent. To check the OID type as returned by the SNMP agent, run Getif. Restart of SNMP agent causes incorrect rate calculation When an SNMP agent restarts (for example, after a reboot of the network device), it generally resets all counter variables to zero, which causes rate tags to contain incorrect values. For example, PI_tag1 is configured to scan an OID at five-minute intervals starting on the hour. During normal operation, the OID values for the counter on the network device change as follows: 08:00:00 (scanned): 400,000 08:02:59 (not scanned): 500,000 08:05:00 (scanned): 600,000 The number of octets received during the five-minute time interval is 200,000. The rate stored in PI_tag1, is (200,000/300) octets/second, which is correct. If an SNMP agent were to restart between scans, the values might change as follows: 08:00:00 (scanned): 400,000 08:02:59 (reboot resets counter; not scanned): 0 08:05:00 (scanned): 100,000 In this case, the interface determines that the number of octets received during this five-minute interval is 4,294,667,296, calculated as 100, ,000 = 300,000, or Hexadecimal FFFB6C20; for an unsigned value, this is 4,294,667,296, and clearly incorrect. To detect restarts, configure a tag that records system.sysuptime.0 for each network devices you are tracking, to record the approximate time at which the SNMP agent restarted. If you knows beforehand that an SNMP agent will restart (for example, because of the need to reboot a router), stop the interface program, restart the SNMP agent, then restart the interface. 52 PI Interface for SNMP User Guide

59 Error and informational messages A string NameID is pre-pended to error messages written to the message log. Name is a nonconfigurable identifier that is no longer than 9 characters. ID is a configurable identifier that is no longer than 9 characters and is specified using the -id parameter on the startup commandline. Message logs Messages The location of the message log depends upon the platform on which the interface is running. See the UniInt Interface User Manual for more information. Messages are written to [PIHOME]\dat\pipc.log 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 UniInt, the command line parameters used, and the number of points. As the interface points, messages are sent to the log if there are any problems with the configuration of the points. If the UniInt -dbuniint parameter is found in the command-line, then various informational messages are written to the log file. The following is an example of a successful startup of the interface: 25-Oct-04 20:00:32 PI SNMP-> Starting PI SNMP, version 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 ( ), WinSock Supported Network 25-Oct-04 20:00:32 PI SNMP-> Uniint version>@(#)uniint.cxx Oct-04 20:00:32 PI SNMP-> API version> 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 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 pisnmp.exe>pi API> Initial connection to [localhost:5450][1] 25-Oct-04 20:00:33 PI SNMP-> PIAPI successfully connected to piserver localhost: Oct-04 20:00:33 PI SNMP-> Server Version: PI 3.4, Build PI Interface for SNMP User Guide 53

60 Error and informational messages 25-Oct-04 20:00:33 PI SNMP-> PISDK successfully connected to piserver localhost via port Oct-04 20:00:33 PI SNMP- 1> Scan performance summary every 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 = seconds, unspecified phase offset 25-Oct-04 20:00:34 PI SNMP- 1> Scan class 2, update period = 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 Oct-04 20:23:00 PI SNMP- 1> pt (localhost_sysuptime_abs), t= drval=0.185 ival=0 istat=0 returned to UniInt Common problems Note: SNMPGet is no longer supported as of version x 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, 54 PI Interface for SNMP User Guide

61 Error and informational messages 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 Oct-04 13:23:00 PI SNMP- 1> pt (localhost_sysuptime_abs), t= drval=0.185 ival=0 istat=0 returned to UniInt The above indicates that the interface received a value of from the SNMP device sent a value of to the UniInt interface template (The point's conversion attribute is , which is divided by ) 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 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., ). If it cannot do so, it prints the out a message such as the following: PI SNMP- 1> Cannot translate OID PI Interface for SNMP User Guide 55

62 Error and informational messages : 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. 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=. 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 56 PI Interface for SNMP User Guide

63 Error and informational messages 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. Conversation 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. Runsnmpget 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. Runsnmpgetto 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". PI Interface for SNMP User Guide 57

64 Error and informational messages 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. 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 nonexistent. Runsnmpget 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 PI Interface for SNMP User Guide

65 PI SNMP- 2> Tag: router_jab_4, OID: rmon.statistics.etherstatstable.etherstatsentry.etherstatsjabbers Error and informational messages 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 points from device points from device points from device 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) decrease the number of consecutive timeouts ( -cto ). For example, pisnmp.exe -retries=0 -timeout=1000 -cto=1 System errors and PI errors System errors are associated with positive error numbers. Errors related to PI are associated with negative error numbers. Error descriptions Descriptions of system and PI errors can be obtained with the pidiag utility: \PI\adm\pidiag -e error_number PI Interface for SNMP User Guide 59

66 Error and informational messages UniInt failover specific error messages Message 16-May-06 10:38:00 Meaning PISNMP 1> UniInt failover: Interface in the "Backup" state. Upon system startup, the initial transition is made to this state. While in this state, the interface monitors the status of the other interface participating in failover. When configured for Hot failover, data received from the data source is queued and not sent to the PI Server while in this state. The amount of data queued while in this state is determined by the failover update interval. In any case, there will be typically no more than two update intervals of data in the queue at any given time. Some transition chains may cause the queue to hold up to five failover update intervals worth of data. Message 16-May-06 10:38:05 Meaning PISNMP 1> UniInt failover: Interface in the "Primary" state and actively sending data to PI. Backup interface not available. While in this state, the interface is in its primary role and sends data to the PI Server as it is received. This message also states that there is not a backup interface participating in failover. Message 16-May-06 16:37:21 PISNMP 1> UniInt failover: Interface in the "Primary" state and actively sending data to PI. Backup interface available. Meaning While in this state, the interface sends data to the PI Server as it is received. This message also states that the other copy of the interface appears to be ready to take over the role of primary. Errors (phase 1 & 2) Message Cause Resolution Message Cause Resolution Message Cause Resolution 16-May-06 17:29:06 PISNMP 1> One of the required Failover Synchronization points was not loaded. Error = 0: The Active ID synchronization point was not loaded. The input PI tag was not loaded. The Active ID tag is not configured properly. Check validity of point attributes. For example, make sure Location1 attribute is valid for the interface. All failover tags must have the same PointSource and Location1 attributes. Modify point attributes as necessary and restart the interface. 16-May-06 17:38:06 PISNMP 1> One of the required Failover Synchronization points was not loaded. Error = 0: The Heartbeat point for this copy of the interface was not loaded. The input PI tag was not loaded. The Heartbeat tag is not configured properly. Check validity of point attributes. For example, make sure Location1 attribute is valid for the interface. All failover tags must have the same PointSource and Location1 attributes. Modify point attributes as necessary and restart the interface. 17-May-06 09:06:03 PISNMP > The Uniint FailOver ID (-UFO_ID) must be a positive integer. The UFO_ID parameter has not been assigned a positive integer value. Change and verify the parameter to a positive integer and restart the interface. 60 PI Interface for SNMP User Guide

67 Error and informational messages Message Cause Resolution 17-May-06 09:06:03 PISNMP 1> The Failover ID parameter (-UFO_ID) was found but the ID for the redundant copy was not found. The -UFO_OtherID parameter is not defined or has not been assigned a positive integer value. Change and verify the -UFO_OtherID parameter to a positive integer and restart the interface. Errors (phase 2) Unable to open synchronization file Message Cause Resolution 27-Jun-08 17:27:17 PI Eight Track 1 1> Error 5: Unable to create file '\\georgiaking\georgiakingstorage\unintfailover\ \PIEightTrack_eight_1.dat' Verify that interface has read/write/ create access on file server machine. Initializing UniInt library failed Stopping Interface This message will be seen when the interface is unable to create a new failover synchronization file at startup. The creation of the file only takes place the first time either copy of the interface is started and the file does not exist. The error number most commonly seen is error number 5. Error number 5 is an "access denied" error and is likely the result of a permissions problem. Ensure the account the interface is running under has read and write permissions for the folder. The "log on as" property of the Windows service may need to be set to an account that has permissions for the folder. Error opening synchronization file Message Cause Resolution Sun Jun 29 17:18: PI Eight Track 1 2>WARNING> Failover Warning: Error = 64 Unable to open Failover Control File '\ \georgiaking\georgiakingstorage\eight\pieighttrack_eight_1.dat' The interface will not be able to change state if PI is not available This message will be seen when the interface is unable to open the failover synchronization file. The interface failover will continue to operate correctly as long as communication to the PI Server is not interrupted. If communication to PI is interrupted while one or both interfaces cannot access the synchronization file, the interfaces will remain in the state they were in at the time of the second failure, so the primary interface will remain primary and the backup interface will remain backup. Ensure the account the interface is running under has read and write permissions for the folder and file. The log on as property of the Windows service may need to be set to an account that has permissions for the folder and file. PI Interface for SNMP User Guide 61

68 Error and informational messages 62 PI Interface for SNMP User Guide

69 PI SDK options To access the PI SDK settings for this interface, select this interface from the Interface list and click UniInt - PI SDK in the Parameter Category pane. Disable PI SDK Select this option to set the interface not to use the PI SDK. The command line equivalent for this option is /PISDK=0. Use the Interface's default setting This option does not determine whether the interface uses the PI SDK. Enable PI SDK Select this option to set the interface to use the PI SDK. Choose this option if the PI Data Archive version is earlier than x or the PI API is earlier than , and you want to use extended lengths for the Tag, Descriptor, ExDesc, InstrumentTag, or PointSource point attributes. The maximum lengths for these attributes are: Attribute Enable the Interface to use the PI SDK Tag Descriptor ExDesc InstrumentTag PointSource PI Data Archive earlier than x or PI API earlier than , without the use of the PI SDK PI Interface for SNMP User Guide 63