PI-SNMP Data Collection Program

PI-SNMP Data Collection Program

Version 1.1.4

How to Contact Us

Phone / (510) 297-5800 (main number)
(510) 297-5828 (technical support)
Fax / (510) 357-8136
Internet /
World Wide Web /
Bulletin Board / (510) 895-9423
Telebit WorldBlazer modem (Hayes, MNP, or PEP compatible)
8 data bits, 1 stop bit, no parity, up to 14400 bps
download protocols: Xmodem, Ymodem, Zmodem, Kermit
Mail / OSI Software, Inc.
P.O. Box 727
San Leandro, CA 94577-0427
USA
OSI Software GmbH
Hauptstrae 30
D-63674 Altenstadt 1
Deutschland /
OSI Software, Ltd
P. O. Box 8256
Level One, 6-8 Nugent Street
Auckland 3, New Zealand

Unpublished -- rights reserved under the copyright laws of the United States.
RESTRICTED RIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii)
of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013

Trademark statement—PI is a registered trademark of OSI Software, Inc. Microsoft Windows, Microsoft Windows for Workgroups, and Microsoft NT are registered trademarks of Microsoft Corporation. Solaris is a registered trademark of Sun Microsystems. HPUX is a registered trademark of Hewlett Packard Corp.. IBM AIX RS/6000 is a registered trademark of the IBM Corporation. DUX, DEC VAX and DEC Alpha are registered trademarks of the Digital Equipment Corporation.
PISNMP

2000 OSI Software, Inc. All rights reserved
777 Davis Street, Suite 250, San Leandro, CA 94577

8/5/2003 12:18 PM1

Table of Contents

Acknowledgement

Introduction

Overview

PI’s role in SNMP networks

Software requirements

Hardware requirements

PI-SNMP operation

PI data input and output

PI Software Configuration

Point Database

Digital State Set

Interface Configuration Utility

Command-line Parameters

Startup file

Event Counter

Configuration file

Installation

PI-API verification

Installation on Windows NT

Installation on Solaris

Renaming of files

First-time installation of PI-SNMP

Upgrade of PI-SNMP

SNMP Agent verification/pisnmpget utility

Starting and stopping PI-SNMP

Windows NT service functionality

Multiple copies

Installation checklist

Troubleshooting

Message log

Location5

Common problems

PI-SNMP startup

Point loading

No new value

Value of 0

I/O Timeout

Bad Input

Configure

Additional startup parameters

-v

Appendix A -- OID examples

Appendix B -- Basic SNMP for PI Users

Appendix C -- Tutorial on using PI-SNMP with Routers

Appendix D -- PISNMPUtil Details

Appendix E -- PI-SNMP Technical Details

Appendix F – ifAlias support

Appendix G -- Known Issues

Revision History

Acknowledgement

Portions of this program utilize the work of CarnegieMellonUniversity and the University of California.

Derivative Work -

CMU AND THE REGENTS OF THE UNIVERSITY OF CALIFORNIA DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL CMU OR THE REGENTS OF THE UNIVERSITY OF CALIFORNIA BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM THE LOSS OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

Introduction

OSI Software’s PI-SNMP data collection interface program gathers information from devices residing in a communications network. The operation of PISNMP requires that these devices be able to send and receive messages via the SNMP protocol. In particular, they must have an SNMP Agent that supports SNMPv1 or SNMPv2.

Because RMON (Remote Monitoring) is a specific application of the SNMP protocol, PI-SNMP supports the retrieval of RMON values.

PI-SNMP runs on a Microsoft Windows NT (version 4.0 or higher) or Solaris (version 2.5 or higher) computer. This machine may or may not have the PI Universal Data Server/Data Archive running simultaneously.

For Windows NT, PI-SNMP Basic (a limited version of the full PI-SNMP program) is also available. PI-SNMP Basic has the following limitations:

it gets data for up to 32 PI tags/points
only one copy of the program may be running at a time
it runs only on a machine that is also running the PI Universal Data Server/Data Archive
it sends data only to this PI Universal Data Server/Data Archive machine

In addition, the filename of PI-SNMP Basic is pisnmp_basic.exe (versus pisnmp.exe for the full version).

The following table summarizes the features of PI-SNMP:

Feature / Support
Platforms / Windows NT - Intel / Solaris - Sparc
PI point types / PI 3.x: Digital / String / Float16 / Float32 / Float64 / Int16 / Int32
PI 2.x: Digital / Integer / Real
Sub-second timestamps / Yes
Sub-second scan classes / No
Automatically incorporates PI point attribute changes / Yes
Exception reporting / Done by the program
Outputs from PI / No
History recovery / No
Failover / No
Inputs to PI: Scan-based / unsolicited / event tags / Scan-based / event tags
UniInt-based / Yes
Maximum point count / Unlimited (full version), 32 (basic)
Requires PI-SDK / Program itself does not; Tag building utility (PISNMPUtil) does
Vendor software required on PI-API / PINet node / No
Vendor software required on device containing data / Yes; SNMP Agent software
Vendor hardware required / No
Additional PI software included with the program / Yes
Source of timestamps / PI Universal Data Server machine

In order to utilize PI-SNMP effectively, the user should be familiar with both basic SNMP and PI technologies. For example, for SNMP, the user should be familiar with the terms Management Information Base (MIB), Object Identifier (OID), and community string. Users who are not familiar with SNMP should consult Appendices B and C of this document.

On the PI side, the user should be adept at creating and editing PI tags. Also, the user needs to know the differences between time-based and event based data collection in PI.

In the remainder of this document, “data collector” (rather than interface) will be used to refer to the PISNMP data collection interface program. This nomenclature avoids confusion with “interface” as indicated in SNMP MIBs and other network device terminology.

Overview

PI’s role in SNMP networks

In SNMP terminology, the PI-SNMP data collector behaves like an SNMP Manager. It retrieves information from network devices via the SNMP Agent running on these devices.

However, PI-SNMP is not a complete SNMP Manager. It cannot receive data via traps sent by SNMP Agents. Also, it does not have the ability to instruct the SNMP Agent to set values for variables on network devices. Thus, PI-SNMP’s primary purpose is to gather statistics and data -- not to control or configure network nodes.

Software requirements

PI-SNMP comes in two versions, one for Windows NT and one for Solaris. Accordingly, the operating system required is either:

Windows NT, version 4.0 Service Pack 5 or higher
Solaris 2.5.1 or higher

In addition, TCP/IP services must be installed.

Hardware requirements

PI-SNMP requires a physical connection to the network devices from which it gathers data. This connection is one supported by TCP/IP. Examples are Ethernet and token ring.

PI-SNMP operation

The following steps summarize how to use PI-SNMP to retrieve data from SNMP enabled network devices.

For a particular network element, the user determines the OID representation of the statistic in which he is interested. Recall that OIDs are defined by standards body, or are proprietary to individual manufacturers of network device. As an example, on a router, the total number of octets received on the third network interface is represented by the OID

.1.3.6.1.2.1.2.2.1.10.3

interfaces.ifTable.ifEntry.ifInOctets.3

The user configures tags in the PI point database. This configuration allows each value represented by the OID to be stored into PI.
The user runs PI-SNMP in a Windows NT/Solaris command prompt to confirm that the PI tag configuration correctly represents the data to be collected. This procedure is known as “interactively running the Data Collector”.
For Windows NT, the user stops interactive execution of PI-SNMP and installs PI-SNMP as a Windows NT Service. For Solaris, the user runs PI-SNMP as a background process. Such procedures allow the Data Collector continuously to run and collect data.

PI data input and output

The PI-SNMP Data Collector supports both time-based and event-based inputs from network devices to the PI Universal Data Server/Data Archive. Time-based inputs occur at fixed time frequencies. Eventbased inputs occur whenever there is a change in value in the PI event tag.

Outputs from the PI Universal Data Server/Data Archive are not yet supported.

PI Software Configuration

Point Database

A PI tag corresponds to a single parameter (i.e., a single SNMP object) on a particular network device. For example, an SNMP object may be “the time (in hundredths of a second, or centiseconds) since the network management portion of the system was last initialized”. The OID

.1.3.6.1.2.1.1.3.0

represents this SNMP object. The textual form of this OID is

system.sysUpTime.0

If PI-SNMP does not support the textual representation of an OID, it writes to the log file a message similar to the following:

PI-SNMP-1> Cannot translate OID: rmon.statistics.etherStatsTable.EtherStatsEntr

y.etherStatsJabbers; cannot add Tag: router_Ethernet0/0_Jabbers

The following point/tag attribute fields must be set for proper operation of PISNMP. PI-SNMP monitors updates to the PI point database and automatically incorporates such changes into its point list. Every two minutes, the Data Collector checks for updates to the PI point database and incorporates these changes into its point list. However, PI-SNMP can process only 25 point changes every 30 seconds.

For PI Universal Data Server/Data Archive 3.x, tags are created and their attributes are set via the PI-PointBuilder program, the PIConfig program, or the PI-SMT utility. For PI Data Archive 2.x, tag creation and configuration tools are the Point Bld display, PIDiff, and PI-SMT. Consult the PI Data Archive manual for more information on the use of these tools.

In addition, users who plan primarily to utilize PI-SNMP with network routers will find the PISNMPUtil program helpful for building the appropriate PI tags. Consult Appendices C and D for details.

In the following list of attributes, the field in parentheses is what should be used in PIDiff or PI-SMT. For example, Tagname is the attribute. However, Tag is the field that should be used for point creation/edit.

Tagname

(Tag)

This is the name of the tag/point as it is known in the PI System. PI client applications such as PI-ProcessBook and PIDataLink use this identifier as a means of referencing the values retrieved by PISNMP.

Point source

(PointSource)

Because the PI Universal Data Server/Data Archive stores data collected from a variety of sources, there must be a way of distinguishing whence these data arrived. The point source field serves this purpose. It is a one character value; for example, $. This character must match the one specified in the PI-SNMP’s startup command file (described later).

Valid point source characters are any ASCII character. The user should ensure that the point source character defined for PI-SNMP does not conflict with one used by other PI data collection programs or by PI system programs such as the PI Totalizer. Specifically, one should not pick any of the following point source characters for PI-SNMP:

C (currently used by Performance Equation)
G (Alarms)
L (Manual Input)
Q (SQC)
R (Random Data Generator)
T (Totalizer)
9 (Ramp Soak Data Interface)

PI Data Archive version 2.x requires the user to run the Point Src display to edit the Point Source table. The following chart indicates the minimum and maximum values for the location fields.

Location 1 / Location 2 / Location 3 / Location 4 / Location 5
Minimum / 1 / 0 / 0 / 1 / 0
Maximum / 99 / 1 / 1 / 50 / 0

Instrument tag

(InstrumentTag)

The instrument tag field contains the TCP/IP host name of a network device For example,

host=router1

The underlying TCP/IP software must be able to translate this host into an IP address. Alternatively, the user may directly specify the IP address of the network device in dotted decimal form. For example,

host=192.168.100.11

Extended descriptor

(ExDesc)

The extended descriptor field holds the SNMP community string and the SNMP object identification (OID) variable. The value of the OID variable is that which PISNMP retrieves from the network device and subsequently stores into the PI Universal Data Server/Data Archive. For PI event-based data collection, the extended descriptor contains the PI event tag. A semicolon separates subfields. For example,

CS=public; OID=.1.3.6.1.2.1.1.3.0; event=PI_TAG_1

CS

The CS sub-field contains the community string for managing the SNMP network.

event

The event sub-field is used for event-based data collection. It specifies the PI event tag whose change of value will trigger data collection. The event sub-field should not be specified for time-based data collection.

OID

The OID sub-field contains the complete SNMP object identification, including instance. For example,

CS=public; OID=system.sysUptime.0; event=PI_TAG_1

or for a time-based PI tag,

CS=public; OID=system.sysUptime.0

In the above examples, system.sysUptime.0 indicates the amount of time, in hundredths of a second, since the SNMP Agent has been running.

OID_I

Because the interfaces.ifTable.ifEntry group of OIDs is commonly utilized, the user may specify OID_I and the remaining portion of the regular OID. For example, PI-SNMP considers the following to be equivalent:

OID=interfaces.ifTable.ifEntry.ifInOctets.3

OID_I=ifInOctets.3

Community Strings and security

A drawback of entering the network device’s Community String into the PI tag configuration is that anyone with access to the PI tag database can find out these Community Strings. In this scenario, the PI System Manager should use the pwd startup parameter (described later) and put the Community String in a file called pisnmp.pwd. For these situations, an example extended descriptor field may be:

OID=system.sysUptime.0; event=PI_TAG_1

or for a time-based PI tag,

OID=system.sysUptime.0

Re-assignment of indices

When a router reboots, it often assigns a different index number to a particular instance of one of its interfaces. For example, an interface named Serial1/0.1 has an ifIndex value of 25. Thus, the OID variable

interfaces.ifTable.ifEntry.ifInOctets.25

represents the number of inbound octets received on this Serial1/0.1 interface. Accordingly, you may have a PI tag called tag1 configured with an extended descriptor such as:

OID_I=ifInOctets.25

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

interfaces.ifTable.ifEntry.ifInOctets.31

However, the tag tag1 is still configured with an extended descriptor containing the ifIndex of 25. As a result, tag1 is no longer is collecting data for Serial1/0.1. In addition, you yourself may have difficulty realizing that the ifIndex for Serial1/0.1 has changed from 25 to 31.

To make you aware of this problem, PI-SNMP allows you to specify in the tag configuration a key value that should be matched before the data retrieved is declared to be good. In the example above, before the router reboot, the OID

interfaces.ifTable.ifEntry.ifDescr.25

represents the description of the interface whose index is 25. A likely value for this OID is

Serial1/0.1

If you configure a tag named tag1 with the extended descriptor

KEY=Serial1/0.1; OID_I=ifInOctets.25

PI-SNMP understands that the index number in question is 25. Accordingly, it sends an SNMP request to the network device and asks for the value of

interfaces.ifTable.ifEntry.ifDescr.25

If the value returned does not match the one specified by the KEY value in the tag configuration, then PISNMP writes Bad Input to tag1.

Therefore, after a router reboot, if the router re-assigns indices to its interfaces, then the value for

interfaces.ifTable.ifEntry.ifDescr.25

will most likely not be “Serial1/0.1”. In this manner, if you see that your tags contain Bad Input, you should check their configuration.

When you use the utility program called PISNMPUtil (see Appendices C and D) to build your tags, PISNMPUtil automatically enters the KEY value into the extended descriptor. Otherwise, you will have to manually find out the values for

interfaces.ifTable.ifEntry.ifDescr.X

and put these into the extended descriptor field yourself.

Currently, the KEY value is used only to match values of

interfaces.ifTable.ifEntry.ifDescr.X

with OIDs from the interfaces group.

Scan

(Scan)

The scan field is used by the PI-SNMP to control the processing of a tag. A value of ON indicates that the Data Collector will recognize the tag and attempt to get values. A value of OFF means that it will not.

Point type

(PointType)

For PI Universal Data Server/Data Archive 3.x, a PI-SNMP tag should be configured to be one of the following point types:

Digital
Int16
Int32
Float16
Float32
Float64
String

For PI Data Archive 2.x, the valid point types are:

Digital
Integer
Real

The user should be aware that many SNMP data are unsigned 32-bit integers (e.g., counter values) that range from 0 to 4,294,967,295. The maximum value that a PI integer can hold is either

2,147,483,647 (PI Universal Data Server/Data Archive 3.x)
32,767 (PI Data Archive 2.x)

Thus, one should configure such tags to be either Float32 (PI 3.x) or Real (PI 2.x). However, conversion of a 32-bit integer into a floating point number may result in a loss of precision.

Source tag

(SourceTag)

The source tag field is not currently used.

Location1

(Location1)

A user may run multiple copies of the full version of PI-SNMP on the same machine. The Location1 field is used to associate a tag with a particular copy of PISNMP. Location1 is a positive integer from 1 to 99, inclusive. It should match the id= parameter used in the startup command file (described later).