Traceroute
Interface to the PI System

Version 1.0.0.0
Rev F

1

UniInt End-User Interface to the PI System

How to Contact Us

OSIsoft, Inc.
777 Davis St., Suite 250
San Leandro, CA94577USA
Telephone
(01) 510-297-5800 (main phone)
(01) 510-357-8136 (fax)
(01) 510-297-5828 (support phone)

Houston, TX
Johnson City, TN
Mayfield Heights, OH
Phoenix, AZ
Savannah, GA
Seattle, WA
Yardley, PA / Worldwide Offices
OSIsoft Australia
Perth, Australia
Auckland, New Zealand
OSI Software GmbH
Altenstadt,Germany
OSI Software Asia Pte Ltd.
Singapore
OSIsoft Canada ULC
Montreal, Canada
OSIsoft, Inc. Representative Office
Shanghai, People’s Republic of China
OSIsoft Japan KK
Tokyo, Japan
OSIsoft Mexico S. De R.L. De C.V.
Mexico City, Mexico
Sales Outlets and Distributors
  • Brazil
  • Middle East/North Africa
  • Republic of South Africa
  • Russia/Central Asia
/
  • South America/Caribbean
  • Southeast Asia
  • South Korea
  • Taiwan


OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, Sigmafine, gRecipe, sRecipe,and RLINK. All terms mentioned in this book that are known to be trademarks or service marks have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party's products or any affiliation with such party of any kind.
RESTRICTEDRIGHTS LEGEND
Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the Rights in Technical Data and Computer Software clause at DFARS 252.227-7013
Unpublished -- rights reserved under the copyright laws of the United States.
© 2006 OSIsoft, Inc. PI_TraceRt.doc

1

UniInt End-User Interface to the PI System

Table of Contents

Introduction

Reference Manuals

Supported Features

Diagram of Hardware Connection

Principles of Operation

Installation Checklist

Interface Installation on Windows

Naming Conventions and Requirements

Interface Directories

The PIHOME Directory Tree

Interface Installation Directory

Interface Installation Procedure

Installing the Interface as a Windows Service

Installing the Interface Service with PI ICU

Installing the Interface Service Manually

Using tracert

On Demand Traceroute

Digital States

PointSource

PI Point Configuration

Point Attributes

Tag

PointSource

PointType

Location1

Location2

Location3

Location4

Location5

InstrumentTag

ExDesc

Scan

Shutdown

Performance Point Configuration

Configuring Performance Points with PI ICU (Windows-Intel)

Configuring Performance Points Manually

I/O Rate Tag Configuration

Monitoring I/O Rates on the Interface Node

Configuring I/O Rate Tags with PI ICU (Windows)

Configuring I/O Rate Tags Manually

Configuring the PI Point on the PI Server

Configuration on the Interface Node

Startup Command File

Configuring the Interface with PI ICU

tracert Interface Tab

Command-Line Parameters

Sample PITraceRt.bat File

Interface Node Clock

Security

Windows

Starting / Stopping the Interface on Windows

Starting Interface as a Service

Stopping Interface Running as a Service

Buffering

Configuring Buffering with PI ICU (Windows)

Configuring Buffering Manually

Example piclient.ini File

Appendix A: Error and Informational Messages

Message Logs

Messages

System Errors and PI Errors

Appendix B: Using PI BatchView to View Traceroute Data

Appendix C: Using PI Batch Generator to Create Traceroute Batches

Revision History

1

Traceroute Interface to the PI System1

Introduction

Traceroute is a network tool that attempts to determine all routing points on the network path from a source machine to a specified destination.

OSIsoft’s PI Traceroute Interface periodically executes traceroutes for network destinations specified by the user in a tag configuration. The interface stores the data it collects in the PI Server. Data is transferred in a single direction and consists of traceroute hops (routing points) and latency.

The PI Traceroute Interface runs on Windows 2000, XP, and 2003 computers.

Ideally, the PI Traceroute Interface should run against PI server version versions 3.3.x or higher. PI2 is not supported. Due to its lack of the PI Batch Database PI 3.2.x is supported only if the interfaced is running with the /nb switch.

No special hardware is required for the PI Traceroute Interface. All that is needed is a computer running Windows 2000 or better and a network card.

Reference Manuals

OSIsoft
  • UniInt End User Document
  • PI Server Manual
  • PI-API Installation Instructions

Supported Features

Feature / Support
Part Number / PI-IN-OS-TR-NTI
*Platforms / NTI (2000, XP, 2003)
APS Connector / No
Point Builder Utility / No
ICU Control / Yes
PI Point Types / integer, float16, float32, float64, string
Sub-Second Timestamps / No
Sub-Second Scan Classes / No
Automatically Incorporates PIPoint Attribute Changes / Yes
Exception Reporting / No
Outputs from PI / No
Inputs to PI: Scan-Based / Unsolicited / Event Tags / Yes
Supports Questionable Bit / No
Maximum Point Count / None
Supports Multi-character PointSource / Yes
*Uses PI-SDK / Yes
PINet to PI 3 String Support / No
* Source of Timestamps / The interface node
* History Recovery / Optional (see below)
* Failover / No
* UniInt-Based / Yes
Vendor Software Required on PI-API / PINet Node / No
Vendor Software Required on Foreign Device / No
Vendor Hardware Required / No
* Additional PI Software Included with Interface / No
Device Point Types / N/A

* See paragraphs below for further explanation.

Platforms
The Interface is designed to run on the above mentioned Microsoft Windows operating systems and greater.
Uses PI SDK

The PI SDK and the PI API are bundled together and must be installed on each PI Interface node. This Interface specifically makes PI SDK calls to create PI Points, access the PI Module Database, and the PI Batch Database.

Source of Timestamps

The source of all timestamps generated by the PI Traceroute Interfaceis the local machine where the interface runs. In order to minimize the effect of time drift, the interface calculates the time difference between the local machine and the PI Server and uses this value to adjust the timestamps of events sent to the PI server. This calculation is repeated every time before the PI Traceroute Interfacesends data to the PI server.

History Recovery

If the PI buffer service is configured and running on the interface node, the PI Traceroute Interfacewill continue to collect data if the connection to the PI Server is lost. The PI buffer service maintains a queue of data that needs to be written to the PI server when it is offline. This traceroute data is recovered once the PI server comes back on line and events queued by the PI buffer service are sent to the PI server.

Unfortunately, there is no way to buffer calls to the batch database that signal the start or end of a PI unit batch. However, you can configure the PI Traceroute Interfaceto maintain an Active tag for each configured traceroute destination by using the /at command line parameter. Active tags are digital tags that signal when a traceroute is running and when it has stopped. These tags can be used to rebuild the batch data using the PI batch generator interface.

Thus, the interface can run in either one or two modes. In the standard mode of operation the interface does its own updates to the batch database.In this mode there is no history recovery for batch data; however, open batches will be closed when the interface starts if they were left open for some reason (for example, ungraceful termination of the interface).

The second mode of operation, which is activated with the /nb switch, does not update the batch database. When specifying the /nb switch you can use the PI Batch Generator interface to update batches and provide complete history recovery based on the active tags. Please refer to the PI Batch Generator Interface User’s Manual for more details on batch recovery.

UniInt-Based

UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by developers, and is integrated into many interfaces, such as the PI Traceroute Interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of our interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniIntsupplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.

The UniInt End User Document is a supplement to this manual.

Additional PI Software

It is recommended that PI BatchView 3.0 or greater be used to view data collected by the PI Traceroute Interface. This gives the user a quick visual way to determine the status of a connection.

Diagram of Hardware Connection

1

Traceroute Interface to the PI System1

Principles of Operation

In order to provide a thorough description of the Principles of Operation of the PI Traceroute Interface, a full description of the traceroute algorithm is included in the following section entitled “Description of Traceroute Algorithm”. This is recommended reading; however, those who are already familiar with the traceroute algorithm may skip this section and go directly to the section entitled “Description of PI Traceroute InterfaceOperation”

Description of Traceroute Algorithm

Traceroute is an algorithm that attempts to determine all routing points on the path a packet takes to reach a specified destination on the network. Additionally, the traceroute algorithm tries to gauge the latency between each routing point or “hop.” It is common for an operating system to have a tool that implements this algorithm. For example, the Windows operating system ships with a command line tool called “tracert” which implements the traceroute algorithm. The next few paragraphs will detail the basics of the traceroute algorithm.

Atraceroute programstarts by constructing a probe packet with theTime To Live (TTL) field in the IP packet header set to 1. The probe is usually anInternet Control Message Protocol (ICMP) packet but User Datagram Protocol (UDP) and Transmission Control Protocol (TCP)packets work just as well in addition to having advantages such as being able to pass through firewalls that block inbound ICMP traffic. Currently the PI Traceroute Interfacesupports only ICMP and UDP probes.Once the probe is constructed it is sent out on the network,where it begins the journey to thetraceroute destination specified in its IP header.

When a router receives anIP packet from the network it decreases the TTL field in the IP header.If the TTL is decreased to 0 the router sends an ICMP “time-to-live expired” packet back to the machine where the probe originated(the traceroute source). Thus, when a traceroute probe sent with TTL of 1reaches the first router in the path to its destination, the router sends a “time-to-live expired” packet back to the traceroute program. The “time-to-live expired” packet sent by the router carries the IP address of the router in the destination field of its IP header which the traceroute program records as the IP address of the first hop to the traceroute destination.

After receivinga “time-to-live expired” packet the traceroute program sends out a new probe with a TTL that is one plus the TTL of the previously sent probe. In this way it will determine the next hop in the path to the traceroute destination. For example: when a probe with a TTL of 2 reaches the first router in its path, the TTL will be decreased by one and forwarded on to the next router. When the probe reaches the second router the TTL will be decreased to zero and a “time-to-live expired” packet, with the IP address of the second router in the destination field of the IP header, will be sent to the traceroute program.

When a probe is sent that has a TTL field big enough to reach the traceroute destination the traceroute destination will send either an ICMP “echo reply” packet,if the probe it received is an ICMP packet, or an ICMP “destination unreachable” packet,if the probe is a UDP or TCP packet. These reply packets will signal the end of the traceroute algorithm to the traceroute program. If no reply is received for a specified timeout period the algorithm requires that the traceroute terminate.

In addition to recording hops, the traceroute program records the time the packet was sent and the time the reply was received and uses this data to determine latency between the traceroute source and the hop that replied to the probe.Latency is defined as the time it takes for a packet on the network to travel from source to destination.The measurement in time is expressed in terms or round-trip time. There are several factors that determine latency in a more exhaustive definition but in this manual we will regard latency as the sum of:

1. The time it takes for a traceroute probe packet to reach a routepoint.

2. The time it takes for the routepoint network stack to respond to the probe.

3. The time it takes for a reply to reach the machine that sent the probe.

Description of PI Traceroute InterfaceOperation

The PI Traceroute Interfacemimics traceroute programs such as the Windows “tracert” utility and allows users to store information gathered by executing the traceroute algorithm on a PI Server.

At startup the interface first tries to establish a connection with the PI server. If a successful connection is established the interface retrieves all tags from the PI server with pointsource attributes that match the pointsource the interface is configured to use. Next, the interface validates the configuration of each tag. If the tag fails validation it is rejected by the interface and one or more messages are printed in the log file informing the user that the tag was rejected and what tag configuration attribute failed validation. Conversely, if a tag is successfully validated it is loaded by the interface.

Tags loaded by the PI Traceroute Interfacefall into a number of different categories. In fact, there are six different types of traceroute tags; three of which are required in order to store traceroute information for a specified network destination. The following is a list of all six types of PI Traceroute Interfacetags that are used to collect traceroute information:

  • Latency or the time it takes to receive a reply from a routing point is stored in the “latency” tag.
  • The network locations of the hops (IP address or hostname)are stored in the “routepoints” tag. This tag is also referred to as the base tag because it holds all configuration information that defines the operating parameters of a traceroute (destination network address, type of traceroute probe to use, etc.).
  • The total time it takes for the traceroute to complete is stored in the “time” tag.

The above tags are automatically created by the interface if missing. The following three tags are optional:

  • The “active” tag is a digital tag that is set to the state “running” when a traceroute is in progress and “stopped” when it is done or idle. The creation of active tags is enabled by specifying the /at flag in the interface startup command line.
  • The total number of hops for a traceroute is stored in the “hops” tag. For more information on how to activate the use of this tag see the Point Configuration section of this manual.
  • Sometimes a traceroute will re-send a traceroute probe if no reply has been received for the previous probe. These retries are stored in the “retries” tag. For more information on how to activate the use of this tag see the Point Configuration section of this manual.

As tags are loaded the interface begins to schedule traceroutes based on the scan class of the base (routepoint) tag which is specified by the Location4 attribute. The value in Location4 corresponds to a scan class defined in the interface startup/configuration batch file. Scan classes are specified by the /f=parameter and they are assigned an implicit number based on the order they appear in the configuration file. The scan class serves to tell the interface how often it should execute a traceroute based on period and offset values.

When the interface determines that it should initiate a traceroute for a particular base tag based on its scan class it starts to sends out traceroute probes and waits for reply packets. Each reply is examined to determine what routepoint along the network path it was received from and that information is written to the routepoint tag in the form of an event with a string value that is either the IP address of the routepoint or its hostname (configurable).

Each event in the routepoint’s tag maintains a one to one mapping with an event in the latency tag based on the event’stimestamp. The events in the latency tag have values Lithat represent the time it takes to receive a reply to a probesent by X0 to Xi (where i goes from 1 to n and n is the number of routing points along a network path and X0 is the address of the source machine). At the end of each traceroute the interface writes the total time it took for the traceroute to complete with a timestamp corresponding to the time the first probe was sent.

Below is an example that compares running the “tracert” (fig. 1) utility in Windows to the data that the PI Traceroute Interfacestores in PI for the same traceroute destination. The “tracert” utility results are organized in five columns. The first column is the hop number. The next three columns are latencies of probes send to the corresponding hop and the last number is the IP address of the hop. The traceroute utility has three latency columns because instead of sending only one probe for each TTL increment it sends three.

Fig. 1

Figure 2 (below) is an example of data stored in the traceroute tags viewed through the PI Datalink add-in for Microsoft Excel. Column D shows the latency in milliseconds for each hop, column F shows the IP address for each hop, and column H shows the total time it took for the traceroute to complete. Columns C, E, and G are timestamps that correspond to values on their right. All timestamps along a row are the same, this is the one to one mapping described in previous paragraphs.