PI-TCPResponse
Interface

Version 1.0.3

1

PI-TCPResponse Interface1

How to Contact Us

Phone / (510) 297-5800 (main number)
(510) 297-5828 (technical support)
Fax / (510) 357-8136
E-mail /
World Wide Web /
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, Asia Pte Ltd
152 Beach Road
#09-06 Gateway East
Singapore, 189721
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.
PI-IN-OSI-TCP

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

1

PI-TCPResponse Interface1

Table of Contents

Introduction

Reference Manuals

Supported Features

Diagram of Connections

Program Applications

Principles of Operation

Installation Checklist

Interface Installation on Windows NT

Microsoft Windows Installer

PI-SDK Installation and PIHOME

Interface Installation Procedure

Installing the Interface as a Windows NT Service

PointSource

PI Point Configuration

Point Attributes

Examples

Performance Point Configuration

I/O Rate Point Configuration

Monitoring I/O Rate points

Point attributes

Configuration on the interface node

Startup Command File

Using the PI-ICU to maintain the Startup Command File

Manual maintenance of the Startup Command File

Command-Line parameters

Sample pitcpresp.bat file

Interface node clock

Security

Starting / Stopping the Interface

Starting the Interface interactively

Starting the Interface as a service

Stopping the Interface running as a service

Other service related commands

Buffering

Example piclient.ini file

Error and Informational Messages

Message Logs

Messages

System errors and PI errors

Troubleshooting

Location5

Common problems

Technical Details

1

PI-TCPResponse Interface1

Introduction

OSIsoft’s PI-TCPResponse program measures the availability and response times of various essential services that are part of a TCP/IP network. In particular, PITCPResponse allows you to determine the response times of

  • HTTP (Web) servers;
  • SMTP, POP3, and IMAP (mail) servers;
  • FTP servers;
  • DNS (name resolution) servers;
  • Microsoft Windows NT/2000 Terminal Servers; and
  • OSIsoft’s PI Universal Data Servers.

The program can also measure how long a particular device on the network takes to respond to ICMP echo requests (“pings”). Finally, the program can obtain the actual result (and not the response time) of a DNS operation.

PI-TCPResponse stores these response times into OSIsoft’s PI Universal Data Server system. So, you can have access to long-term historical data as well as shortterm current information regarding the performance of your various servers. Therefore, PITCPResponse assists you in proactively managing your network.

Additionally, PI-TCPResponse can help you

  • verify your SLAs (service level agreements),
  • verify DNS load balancing, and
  • test a computer’s readiness for Denial of Service attacks.

The PI-TCPResponse program runs on Windows NT (version 4.0) or Windows 2000 computers. Unless otherwise noted, the remainder of this document uses the term “Windows NT” to refer to both.

PI-TCPResponse requires

  • PI Universal Data Server version 3.2 or higher, and
  • PI-SDK v1.0.0 or higher (the PI-SDK automatically includes the PI-API)

PI-TCPResponse does not require any special hardware. A standard network interface card on the Windows NT machine is sufficient.

Terminology: PI-TCPResponse is not technically an “interface” because it does not transfer to the PI Universal Data Server existing data located on a device. Instead, it measures values and stores these measurements into PI Universal Data Server.

However, PITCPResponse operates within the PI Interface model. For example, PITCPResponse was developed using OSIsoft’s UniInt (Universal Interface) template. Therefore, the rest of this document refers to the PI-TCPResponse data measurement program as an “interface”.

Reference Manuals

The user may find the following documents useful during the operation of the PITCPResponse Interface.

OSI Software
  • UniInt end user document
  • PI Universal Data Server manual
  • PI-API installation instructions
  • PI-API manual

Supported Features

The following table summarizes the features of the PI-TCPResponse Interface:

Feature / Support
Part Number / PI-IN-OS-TCP
Platform / Windows NT (Intel)
PI point types / float16 / float32 / float64 / int16 / int32 / string
Sub-second timestamps / Yes
Sub-second scan classes / No
Automatically incorporates PI point attribute changes / Yes
Exception reporting / Yes; performed by the Interface
Outputs from PI / No
Inputs to PI: scan-based / unsolicited / event tags / Scan-based / event tags
Maximum point count / Unlimited
Uses PI-SDK / Yes
PINet to PI 3.x string support / Not applicable
* Source of timestamps / PI Universal Data Server
History recovery / No
Failover / No
* UniInt-based / Yes
Vendor software required on PIAPI node / No
Vendor software required on foreign device / No
Vendor hardware required / No
Additional PI software included with the interface / No
Device point types / Not applicable

* See paragraphs below for further explanation.

Source of timestamps

The clock on the computer running the PI Universal Data Server provides the source of timestamps for the values sent by PI-TCPResponse.

UniInt-based

UniInt stands for Universal Interface; it is a template created by OSISoft to facilitate the rapid development of data collection interface programs. The purpose of UniInt is to keep a consistent feature set and consistent behavior across as many interfaces as possible. UniInt is constantly being upgraded with new options and features.

UniInt is not a separate product or file. Instead, it is integrated into interface programs such as PI-TCPResponse. In any UniInt-based interface, the UniInt template handles some of the startup parameters while the interface itself handles others.

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

Diagram of Connections

1

PI-TCPResponse Interface1

Program Applications

The following are some specific uses for the PI-TCPResponse Interface.

SLA verification

A Service Level Agreement is a contract between a network provider and its customers. The SLA typically guarantees a certain level of performance of the network.

For example, a corporation has a Wide Area Network (WAN). It has an SLA with the WAN provider. The SLA specifies a minimum response time between various computers on the WAN. This minimum response time is defined in terms of a ping response times. In addition, these minimum response times change during different parts of the day. That is, the SLA calls for a slower response time during regular business hours versus a quicker one during the night.

You can use PI-TCPResponse to perform response time measurements at all hours of the day. These measurements are stored into PI Universal Data Server. You will then have historical data regarding network response times.

So, if you are the network provider, you can prove to your customers that you have met the SLA. Conversely, if you are the customer of the WAN service provider, you can verify that you are receiving the network performance for which you have paid.

Web Server availability

Some network administrators have their web server machines configured so that they do not respond to ping requests. (Examples are and .) To confirm that such Web sites are available, you can use PI-TCPRespone to measure the response times of these servers.

Web Site Hosting verification

Many organizations outsource the management and operation of their Web sites. Web hosting companies that perform these actual management and operational duties often guarantee the level of the availability of the hosted services. When uptime requirements are not met, rebates are provided to customers. For example,

Uptime (monthly %) / Rebate
99.50% to 100.00% / 0%
98.00% to 99.49% / 25%
97.00% to 97.99% / 50%
95.00% to 96.99% / 75%
< 95% / 100%

You can use PI-TCPResponse to constantly perform availability measurements of Web servers. These measurements are stored into PI Universal Data Server. You will then have historical data regarding a Web site’s availability.

So, if you are the Web hosting company, you can prove to your customers that you have met your uptime guarantee. Conversely, if you are the customer, you can check whether you are entitled to compensation because of server downtime.

DNS Load Balancing verification

If you have a Web site that receives heavy traffic, you will often distribute such traffic to different physical machines via DNS Load Balancing. For example, you are responsible for the Web site whose address is . You configure your name server to resolve the address into three distinct IP addresses:

  • 192.168.100.11
  • 192.168.100.12
  • 192.168.100.13

You can use PI-TCPResponse to look up the IP address for the Web site at various times of the day. The results of this lookup are stored into PI Universal Data Server. You can then verify that your DNS server is properly load balancing the address .

IP address to name translation

There are many applications that can determine the amount of network resources consumed by your computers. Some of them (such as OSIsoft’s PI-NetFlow Interface) present their results in terms of IP addresses. For example,

Date / Machine / % network usage
2/1 / 192.168.100.11 / 21
2/2 / 192.168.100.13 / 28
2/3 / 192.168.100.17 / 18
2/4 / 192.168.100.11 / 22

You probably do not have IP address and the corresponding machine names committed to memory. Also, you may be using DHCP for IP addresses assignment, and you have many notebook computers that connect and disconnect from the network every day.

Thus, on 2/1, the machine with the IP address of 192.168.100.11 may actually be the same machine with the IP address of 192.168.100.13 on 2/2. Similarly, on 2/1, the machine assigned to IP address of 192.168.100.11 may be different than the machine assigned to this same IP address of 192.168.100.11 on 2/4.

The reverse name lookup function of PI-TCPResponse allows you periodically to obtain the machine name for a given IP address. The results of this lookup are stored into PI Universal Data Server. You can then have a record of the DHCP assigned addresses and the corresponding machine names.

Denial of service attack readiness

A denial of service attack occurs when hackers use the Internet to constantly and maliciously connect to one or more of your computers. Your computer spends much of its resources processing the requests for these connections. Meanwhile, users who legitimately want to access your computers cannot get through.

You can use PI-TCPResponse to simulate a denial of service attack. Simply configure the Interface to send, at a high frequency, multiple connection requests to the same computer. Then, use another machine to try to access this computer under attack. As a result, you can determine your machine’s readiness for denial of service attacks.

Router fault detection in a WAN

You can use PI-TCPResponse to determine which router in your WAN is periodically malfunctioning. For example, the following picture shows that the network path between the computer with IP address 192.168.100.10 and the computer with IP address of 10.109.200.143 involves three routers:

  • 192.168.100.1
  • 152.63.53.237
  • 10.109.200.1


You can install PI-TCPResponse on 192.168.100.10 and periodically measure ping response times to each of these four devices:

  • 192.168.100.1
  • 152.63.53.237
  • 10.109.200.1
  • 10.109.200.143

Similarly, you can run PI-TCPResponse on 10.109.200.143 and periodically measure ping response times to

  • 10.109.200.1
  • 152.63.53.237
  • 192.168.100.1
  • 192.168.100.10

For a particular moment in time, if you get the following values

Tag / value
ping_192.168.100.10_192.168.100.1 / 10
ping_192.168.100.10_152.63.53.237 / I/O Timeout
ping_192.168.100.10_10.109.200.1 / I/O Timeout
ping_192.168.100.10_10.109.200.143 / I/O Timeout

and

Tag / value
ping_10.109.200.143_10.109.200.1 / 11
ping_10.109.200.143_152.63.53.237 / I/O Timeout
ping_10.109.200.143_192.168.100.1 / I/O Timeout
ping_10.109.200.143_192.168.100.143 / I/O Timeout

you can conclude that the router 152.63.53.237 is malfunctioning. The reason is that for both sets of values, the I/O Timeout occurred starting with 152.63.53.237.

1

PI-TCPResponse Interface1

Principles of Operation

PI-TCPResponse measures the response time of various services that are part of a TCP/IP network. In particular, the PITCPResponse program allows you to determine the response time of

  • HTTP (Web) servers;
  • SMTP, POP3, and IMAP (mail) servers;
  • FTP servers;
  • DNS (name resolution) servers;
  • Microsoft Windows NT/2000 Terminal Servers; and
  • PI Universal Data Servers

PI-TCPResponse also measures how long a particular machine on the network takes to respond to ICMP echo requests (“pings”). In addition, it stores the actual result (and not the response time) of a DNS operation.

In general, PI-TCPResponse measures the response time of a particular service by

  • sending a connection request to the appropriate TCP port of the machine on which the service resides,
  • waiting for the appropriate response message from the server machine.

For example, the Interface measures the response time of the Web server by sending a connection request to TCP port number 80 of the machine named . PI-TCPResponse then waits for a connection confirmation message. The time interval between the sending of the connection request and the receipt of the connection confirmation is the response time.

For the measurement of DNS server response time, PI-TCPResponse does not explicitly make a connection request to TCP port 42. Instead, it uses the standard Winsock functions gethostbyname() or gethostbyaddress() to query the DNS server that is indicated in the Microsoft Windows TCP/IP settings.

For the measurement of ping response times, PI-TCPRespnose does not send a connection request to a TCP port. Instead, it sends an ICMP echo request message and waits for an ICMP echo reply message.

If the Interface does not receive a response within a specified time limit, it writes the digital state I/O Timeout. However, PI-TCPResponse does not wait for a service to respond or to time out before it performs the next measurement. For example, you configure 3 points so that the Interface measures ping response times to 3 machines whose IP addresses are, respectively,

  • 192.168.100.11
  • 192.168.100.12
  • 192.168.100.13

PI-TCPResponse sends three ping requests, one right after the other. It does not wait until the measurement for the response time from 192.168.100.11 is finished before it sends pings to the other two machines.

In contrast, OSIsoft’s PI-Ping program (v1.4.0 and earlier) waits for a ping response time measurement to complete before it sends the next ping request.

1

PI-TCPResponse Interface1

Installation Checklist

For those users who are familiar with running PI data collection interface programs, this checklist helps you in getting the PI-TCPResponse Interface up and running. Users who are not familiar with PI interfaces should return to this section after reading the rest of this manual in detail.

You should follow the steps in the order listed below.

  1. Install the PI-SDK. Verify this installation by running the AboutPI-SDK.exe program and clicking on Connect.
  2. If necessary, obtain and install Microsoft Windows Installer.
  3. Install the Interface itself by running pitcpresp.msi.
  4. Install the Interface as a Windows NT service by running the command file installPITCPRespService.bat.
  5. Choose a point source for use by the Interface.
  6. Configure PI points.

For most cases, the InstrumentTag specifies the device.

Location1 is the interface identification number.

Location2 indicates the service.

Location3 should be 0.

Location4 specifies the scan class (and hence the scan frequency).

Location5 is used for debugging.

Exdesc specifies the trigger point for trigger-based inputs.

  1. If desired, configure interface performance points.
  2. If desired, configure an I/O Rate point.
  3. Edit the startup command file (pitcpresp.bat).
  4. Confirm the settings of the clock on the computer on which the Interface runs.
  5. Set up security on the PI Universal Data Server so that it accepts data sent by the Interface.
  6. With PI Buffer Server not running, run the Interface interactively.
  7. Verify that data are correctly being written to the PI Universal Data Server.
  8. Stop the interactive execution of the Interface.
  9. If the Interface runs on a PI-API node, set the Shutdown attribute of configured PI points to 0.
  10. Start PI Buffer Server.
  11. Run the Interface as a Windows NT service.
  12. Verify that data are correctly being written to the PI Universal Data Server.
  13. Confirm that the Interface re-starts after a complete machine shutdown and restart.

1

PI-TCPResponse Interface1

Interface Installation on Windows NT

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

The primary function of a PI Server node is to run the applications that compose the PI Universal Data Server. These applications archive data and provide data to client computers that request them. Thus, if PI interface programs are absent from the PI Server node, then PI Universal Data Server applications need not compete with these interface programs for this computer’s resources.

After you have installed and tested the Interface, you should enable the PI Buffer Server application. PI Buffer Server (also known as Bufserv) is a utility program distributed with the PI-API. It provides the capability to store and forward events to the PI Universal Data Server. The primary purpose of Bufserv is to allow continuous data collection when communications between the PI-API node and the PI Universal Data Server is lost. Communications will be lost when network problems exist, or when the PI Universal Data Server is shut down because of maintenance, upgrades, backups, or unexpected failures.

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

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