Traceroute Interface to the PI System
Traceroute
Interface to the PI System
Version 1.1.0.0
Revision C
How to Contact Us
|OSIsoft, Inc. |Worldwide Offices |
|777 Davis St., Suite 250 |OSIsoft Australia |
|San Leandro, CA 94577 USA |Perth, Australia |
| |Auckland, New Zealand |
|Telephone |OSI Software GmbH |
|(01) 510-297-5800 (main phone) |Altenstadt, Germany |
|(01) 510-357-8136 (fax) |OSI Software Asia Pte Ltd. |
|(01) 510-297-5828 (support phone) |Singapore |
| |OSIsoft Canada ULC |
|techsupport@ |Montreal, Canada |
| |OSIsoft, Inc. Representative Office |
|Houston, TX |Shanghai, People’s Republic of China |
|Johnson City, TN |OSIsoft Japan KK |
|Mayfield Heights, OH |Tokyo, Japan |
|Phoenix, AZ |OSIsoft Mexico S. De R.L. De C.V. |
|Savannah, GA |Mexico City, Mexico |
|Seattle, WA | |
|Yardley, PA | |
|Sales Outlets and Distributors |
|Brazil |South America/Caribbean |
|Middle East/North Africa |Southeast Asia |
|Republic of South Africa |South Korea |
|Russia/Central Asia |Taiwan |
| |
|WWW. |
|OSIsoft, Inc. is the owner of the following trademarks and registered trademarks: PI System, PI ProcessBook, Sequencia, |
|Sigmafine, gRecipe, sRecipe, and RLINK. All terms mentioned in this book that are known to be trademarks or service marks |
|have been appropriately capitalized. Any trademark that appears in this book that is not owned by OSIsoft, Inc. is the |
|property of its owner and use herein in no way indicates an endorsement, recommendation, or warranty of such party’s |
|products or any affiliation with such party of any kind. |
| |
|RESTRICTED RIGHTS LEGEND |
|Use, duplication, or disclosure by the Government is subject to restrictions as set forth in subparagraph (c)(1)(ii) of the |
|Rights in Technical Data and Computer Software clause at DFARS 252.227-7013 |
| |
|Unpublished – rights reserved under the copyright laws of the United States. |
| |
|© 2005-2007 OSIsoft, Inc. PI_TraceRt.doc |
Table of Contents
Introduction 1
Reference Manuals 1
Supported Features 1
Diagram of Hardware Connection 4
Principles of Operation 5
Installation Checklist 11
Interface Installation on Windows 13
Naming Conventions and Requirements 13
Interface Directories 14
PIHOME Directory Tree 14
Interface Installation Directory 14
Interface Installation Procedure 14
Installing Interface as a Windows Service 15
Installing Interface Service with PI Interface Configuration Utility 15
Installing Interface Service Manually 18
Using tracert 19
On Demand Traceroute 19
Digital States 21
PointSource 23
PI Point Configuration 25
Point Attributes 25
Tag 25
PointSource 25
PointType 26
Location1 26
Location2 26
Location3 26
Location4 27
Location5 27
InstrumentTag 27
ExDesc 28
Scan 30
Shutdown 30
Performance Point Configuration 33
I/O Rate Tag Configuration 35
Monitoring I/O Rates on the Interface Node 35
Configuring I/O Rate Tags with PI ICU (Windows) 35
Configuring I/O Rate Tags Manually 37
Configuring PI Point on the PI Server 37
Configuration on the Interface Node 37
Startup Command File 39
Configuring the Interface with PI ICU 39
tracert Interface Tab 41
Command-line Parameters 46
Sample PITraceRt.bat File 51
Interface Node Clock 53
Security 55
Windows 55
Starting / Stopping the Interface on Windows 57
Starting Interface as a Service 57
Stopping Interface Running as a Service 57
Buffering 59
Configuring Buffering with PI ICU (Windows) 60
Configuring Buffering Manually 63
Example piclient.ini File 65
Appendix A: Error and Informational Messages 67
Message Logs 67
Messages 67
System Errors and PI Errors 71
Appendix B: Using PI BatchView to View Traceroute Data 73
Appendix C: Using PI Batch Generator to Create Traceroute Batches 75
Revision History 79
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
• PI Server manuals
• PI API Installation manual
• UniInt Interface User Manual
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 |float16 / float32 / float64 / int16 / int32 / digital |
| |/ string |
|Sub-second Timestamps |No |
|Sub-second Scan Classes |No |
|Automatically Incorporates PI Point Attribute Changes |Yes |
|Exception Reporting |No |
|Outputs from PI |No |
|Inputs to PI: Scan-based / Unsolicited / Event Tags |Scan-based and Event tags. |
|Supports Questionable Bit |No |
|Supports Multi-character PointSource |Yes |
|Maximum Point Count |Unlimited |
|* Uses PI SDK |Yes |
|PINet String Support |No |
|* Source of Timestamps |The interface node |
|History Recovery |No |
|* UniInt-based |Yes |
|Disconnected Startup |No |
|* SetDeviceStatus |Yes |
|Failover |No |
|Vendor Software Required on PI Interface Node / PINet |No |
|Node | |
|Vendor Software Required on Foreign Device |No |
|Vendor Hardware Required |No |
|Additional PI Software Included with Interface |No |
|Device Point Types |N/A |
|Serial Based Interface |No |
* See paragraphs below for further explanation.
Platforms
The Interface is designed to run on the above mentioned Microsoft Windows operating systems and greater.
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 PI Module Database and the PI Batch Database.
Source of Timestamps
The source of all timestamps generated by the PI Traceroute Interface is 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 Interface sends data to the PI server.
UniInt-based
UniInt stands for Universal Interface. UniInt is not a separate product or file; it is an OSIsoft-developed template used by developers, and is integrated into many interfaces, including this interface. The purpose of UniInt is to keep a consistent feature set and behavior across as many of OSIsoft’s interfaces as possible. It also allows for the very rapid development of new interfaces. In any UniInt-based interface, the interface uses some of the UniInt-supplied configuration parameters and some interface-specific parameters. UniInt is constantly being upgraded with new options and features.
The UniInt Interface User Manual is a supplement to this manual.
SetDeviceStatus
The Interface is built with a version of UniInt that supports interface health points. The health point with the point attribute ExDesc = [UI_DEVSTAT], is used to represent the status of the source devices. The following events can be written into the point:
a) "Good" - the interface is properly communicating and reading data from the devices. If no data collection points have been defined, this indicates the interface has successfully started.
b) "3 | n devices(s) in error | Device1,...,DeviceN" - the interface has determined that the listed device(s) are offline. A device is considered offline when all traceroute operations to it have failed.
The event "2 | Connected / No Data | " is not used by this interface.
Note: This point only reports problems for devices that have scan-based points.
Please refer to the UniInt Interface User Manual for more information on how to configure health points.
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
[pic]
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 Interface Operation”
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, UNIX and Linux operating system typically include a command line tool called “traceroute” which implements the traceroute algorithm. Similarly the Windows operating system ships with a command line tool called “tracert” which also implements the traceroute algorithm. The next few paragraphs will detail the basics of the traceroute algorithm.
A traceroute program starts by constructing a probe packet with the Time To Live (TTL) field in the IP packet header set to 1. The probe is usually an Internet 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 Interface supports only ICMP and UDP probes). Once the probe is constructed it is sent out on the network, where it begins the journey to the traceroute destination specified in its IP header.
When a router receives an IP 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 1 reaches 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 source field of its IP header which the traceroute program records as the IP address of the first hop to the traceroute destination.
After receiving a “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 source 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 port unreachable” packet, if the probe is a UDP 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 but for the sake of simplicity 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 Interface Operation
The PI Traceroute Interface mimics 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 Interface fall 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 Interface tags 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 “latency” and “time” tags can be automatically created by the interface if missing. The following three tags are optional and can also be automatically created by the interface:
• 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.
The routepoint tag determines the scheduling of traceroutes and can be either event-based or scan-based.
Event-based routepoint tags are processed when the selected trigger tag receives a snapshot event.
Scan-based routepoint tags are scheduled according to the scan class 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, it starts to send 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). The following string values are also written to the routepoint tag to indicate the state of the traceroute:
• TR_START - indicates the start of a traceroute.
• TR_DONE - indicates the traceroute completed.
• TR_TIMEDOUT - indicates the traceroute exceeded the timeout value specified in the Location3 attribute of the routepoint tag. The interface also writes the digital state, I/O Timeout, to the latency, time, hops and retries tags instead of the value that would normally be written.
• TR_ERROR - indicates either the traceroute exceeded the maximum number of hops (which can be specified using a command-line parameter) or a “destination unreachable” response was received. The interface also writes the digital state, Bad Input, to the latency, time, hops and retries tags instead of the value that would normally be written.
For each traceroute, each hop in the routepoint tag is written with a timestamp that is one second after the previous value. This is an arbitrary time interval and doesn’t reflect the actual time at which the probe was received. Therefore the time between the value, TR_START, and one of the completion string values listed above, doesn’t provide the actual time taken to perform the traceroute. The actual time taken to perform the traceroute is provided by the time tag and is reflected in the timestamps of the “running” and “stopped” digital state values in the active tag.
Each event in the routepoint’s tag maintains a one to one mapping with an event in the latency tag based on the event’s timestamp. The events in the latency tag have values Li that represent the time it takes to receive a reply to a probe sent 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.
When total values are written to the detail tags, they are written using the timestamp of the TR_START value in the routepoint tag. This applies to the time tag and will also apply to the hops and retries tags when they are configured to store total values.
When incremental values are written to the detail tags, they are written using the timestamp of the corresponding value in the routepoint tag. This applies to the latency tag and will also apply to the hops and retries tags when they are configured to store incremental values.
Below is an example that compares running the “tracert” (fig. 1) utility in Windows to the data that the PI Traceroute Interface stores 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 sent to the corresponding hop and the last number is the IP address of the hop. The “tracert” utility has three latency columns because instead of sending only one probe for each TTL increment it sends three.
[pic]
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 B shows the latency in milliseconds for each hop stored in the “latency” tag, column D shows the IP address for each hop stored in the “routepoints” tag, and column F shows the total time it took for the traceroute to complete, stored in the “time” tag. Columns A, C, and E 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 earlier.
[pic]
Fig. 2
The last row of data, row 17, reveals that this is in fact a traceroute to the same destination used in executing the “tracert” utility shown in Figure 1. The careful observer will also notice that a few of the hops in the traceroute data generated by the PI Traceroute Interface are not the same as those recorded by the “tracert” utility. This is evidence of the dynamic nature of networks and in some situations is perfectly normal.
A user must create a traceroute base tag on the PI Server in order for the PI Traceroute Interface to collect traceroute data for a given network destination. The traceroute base tag configuration contains information on the traceroute to be executed such as:
1. The destination of the traceroute.
2. The rate at which the traceroutes should be executed (e.g., hourly).
3. The type protocol to use for the probe packets (UDP or ICMP).
In addition to storing traceroute parameters, the base tag is also responsible for storing the host name or IP address (depending on the tag configuration) between hops. The user needs to create only the base tag. All other required tags are created by the PI Traceroute Interface when it starts up if they do not already exist, unless the user specifically instructs the interface not to. These traceroute tags, including the base tag, should have the Compressing, ExcMin, ExcMax, ExcDev, and ExcDevPercent attributes set to 0. This is important for the correct operation of the traceroute interface. Every routepoint recorded during a traceroute must be recorded and all other traceroute tags should have events that correspond to each event in the routepoint tag (for example each routepoint has an associated latency, hop number, etc.); thus, it makes no sense to compress traceroute data.
The PI Traceroute Interface is also capable of executing traceroutes in what will be referred to as “spray mode.” In spray mode, as in normal mode, the interface sends a series of probes with increasing TTLs to the traceroute destination. The difference between “spray mode” and normal traceroute execution is that the interface does not wait for a reply to the first probe before sending the next. It simply sends a user specified number of packets out. It then waits for the replies to these packets.
Spray mode has advantages and disadvantages. It is usually a faster method of obtaining traceroute information since hops and latencies are calculated in parallel. However there is no way to know ahead of time how many packets to spray the destination with; therefore, a user must use his best judgment in determining how many packets to send out. If a user sends out too many packets it will result in residual and unnecessary traffic on the network. Also, if a user sends out too few packets the traceroute will never have a chance to complete successfully. We recommend that spray mode be used only to test routes that are expected to be relatively static and where any change at all in the route is cause for concern.
In addition to the tags used to store traceroute information, the PI Traceroute Interface uses the event framing capabilities of the PI Batch Database in the PI Server to store the start and end time of a traceroute. This allows a user with PI BatchView to overlay the results of multiple traceroutes and visually compare them. The ability to compare traceroutes visually makes it easier for users to distinguish between typical good traceroutes and those that display abnormalities.
For each traceroute base tag the interface creates a traceroute “batch” unit in the Module Database of the PI Server it connects to. This unit is used to create traceroute unit batches which contain information about the start and stop time of each traceroute executed. As with the time and active tags, these times reflect the actual time taken to complete the traceroute and may not match the timestamps written to the routepoint tag.
These start and stop times are utilized by client tools such as PI BatchView to frame the multitude of traceroutes generated and compare them to each other. Refer to Appendix B for more details.
Limitations of Traceroute with UDP
When using the UDP protocol to perform traceroutes, the interface uses a destination port of 33434 for the first probe and increments this value by one for each subsequent probe. If the destination device has an application listening on the destination port specified in the probe, a “destination port unreachable” ICMP packet will not be sent to the interface and, therefore, will cause the traceroute operation to timeout.
Multiple Network Cards
When the interface is running on a computer with multiple network interface cards (NICs) a single IP address is automatically selected during interface startup and used as the source IP address for all probes. To determine which IP address will be selected, open the Network Connections system folder, open the Advanced Settings dialog box and select the Adapters and Bindings tab. The first connection in the Connections list will be selected to provide the source IP address.
The source IP address can also be specified for the interface using a command-line parameter or it can be specified for a point using the ExDesc attribute.
Installation Checklist
For those users who are familiar with running PI data collection interface programs, this checklist helps get the Interface running. If not familiar with PI interfaces, return to this section after reading the rest of the manual in detail.
1. Install the PI-Interface Configuration Utility (which installs PI-SDK and PI-API)
2. Verify that PI-API has been installed.
3. Install the interface.
4. Test the connection between the interface node and the traceroute destinations using the Windows operating system “tracert” utility.
5. Define digital states.
Verify that the digital state set TracertStatus exists on the PI server if active tags will be used. This digital state set is created automatically when the interface starts for the first time. It can also be created manually by naming the digital state set TracertStatus and specifying the following states 0 for stopped, 1 for running.
6. Choose a point source.
7. Configure PI points.
Location1 is the interface instance.
Location2 specifies the retry timeout.
Location3 specifies the traceroute timeout.
Location4 is the scan class.
Location5 specifies the use of spray mode and how many packets to spray when greater than 0.
ExDesc specifies additional operating parameters for the traceroute e.g. the protocol to use.
InstrumentTag specifies the traceroute destination.
8. Configure the interface using the PI ICU utility or edit startup command file manually. It is recommended to use PI ICU whenever possible.
/host= defines the PI server to connect to.
9. Set interface node clock.
10. Set up security.
11. Test traceroute using the Windows “tracert” utility.
12. Start the interface without buffering.
13. Verify data.
14. Stop interface, start buffering, start interface.
Interface Installation on Windows
OSIsoft recommends that interfaces be installed on a PI Interface Nodes instead of directly on the PI Server node. A PI Interface Node is any node other than the PI Server node where the PI Application Programming Interface (PI API) has been installed (see the PI API manual). With this approach, the PI Server need not compete with interfaces for the machine’s resources. The primary function of the PI Server is to archive data and to service clients that request data.
After the interface has been installed and tested, Bufserv should be enabled on the PI Interface Node (once again, see the PI API manual). Bufserv is distributed with the
PI API. It is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when communication to the PI Server is lost. Communication will be lost when there are network problems or when the PI Server is shut down for maintenance, upgrades, backups, or unexpected failures.
In most cases, interfaces on PI Interface Nodes should be installed as automatic services. Services keep running after the user logs off. Automatic services automatically restart when the computer is restarted, which is useful in the event of a power failure.
The guidelines are different if an interface is installed on the PI Server node. In this case, the typical procedure is to install the PI Server as an automatic service and install the interface as an automatic service that depends on the PI Update Manager and PI Network Manager services. This typical scenario assumes that Bufserv is not enabled on the PI Server node. Bufserv can be enabled on the PI Server node so that interfaces on the PI Server node do not need to be started and stopped in conjunction with PI, but it is not standard practice to enable buffering on the PI Server node. See the UniInt Interface User Manual for special procedural information.
Naming Conventions and Requirements
In the installation procedure below, it is assumed that the name of the interface executable is PITraceRt.exe and that the startup command file is called PITraceRt.bat.
When Configuring 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, PITraceRt1.exe and PITraceRt1.bat would typically be used for interface number 1, PITraceRt2.exe and PITraceRt2.bat for interface number 2, and so on. When an interface is run as a service, the executable and the command file must have the same root name because the service looks for its command-line parameters in a file that has the same root name.
Interface Directories
PIHOME Directory Tree
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. A typical pipc.ini file contains the following lines:
[PIPC]
PIHOME=c:\pipc
The above lines define the \pipc directory as the root of the PIHOME directory tree on the C: drive. OSIsoft recommends using \pipc as the root directory name. The PIHOME directory does not need to be on the C: drive.
Interface Installation Directory
Place all copies of the interface into a single directory. The suggested directory is:
PIHOME\Interfaces\TraceRt\
Replace PIHOME with the corresponding entry in the pipc.ini file.
Interface Installation Procedure
The PI Traceroute Interface setup program uses the services of the Microsoft Windows Installer. Windows Installer is a standard part of Windows 2000 and greater operating systems. To install, run the TraceRt_x.x.x.x.exe installation kit.
Installing Interface as a Windows Service
The PI Traceroute Interface service can be created, preferably, with the PI Interface Configuration Utility, or can be created manually.
Installing Interface Service with PI Interface Configuration Utility
The PI Interface Configuration Utility provides a user interface for creating, editing, and deleting the interface service:
[pic]
Service Configuration
Service name
The Service name box shows the name of the current interface service. This service name is obtained from the interface executable.
ID
This is the service id used to distinguish multiple instances of the same interface using the same executable.
Display name
The Display Name text box shows the current Display Name of the interface service. If there is currently no service for the selected interface, the default Display Name is the service name with a “PI-” prefix. Users may specify a different Display Name. OSIsoft suggests that the prefix “PI-” be appended to the beginning of the interface to indicate that the service is part of the OSIsoft suite of products.
Log on as
The Log on as text box shows the current “Log on as” Windows User Account of the interface service. If the service is configured to use the Local System account, the Log on as text box will show “LocalSystem.” Users may specify a different Windows User account for the service to use.
Password
If a Windows User account is entered in the Log on as text box, then a password must be provided in the Password text box, unless the account requires no password.
Confirm password
If a password is entered in the Password text box, then it must be confirmed in the Confirm Password text box.
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 [pic] button. For example, if API Buffering is running, then “bufserv” should be selected from the list at the right and added to the list on the left. To remove a service from the list of dependencies, use the [pic] 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.
[pic] - Add Button
To add a dependency from the list of Installed services, select the dependency name, and click the Add button.
[pic] - Remove Button
To remove a selected dependency, highlight the service name in the Dependencies list, and click the Remove button.
The full name of the service selected in the Installed services list is displayed below the Installed services list box.
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 [pic] and a Stop button [pic]. 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.
[pic]
Installing Interface Service Manually
Help for installing the interface as a service is available at any time with the command:
PITraceRt.exe –help
Open a Windows command prompt window and change to the directory where the PITraceRt1.exe executable is located. Then, consult the following table to determine the appropriate service installation command.
|Windows Service Installation Commands on a PI Interface Node or a PI Server Node |
|with Bufserv implemented |
|Manual service |PITraceRt.exe –install –depend “tcpip bufserv” |
|Automatic service |PITraceRt.exe –install –auto –depend “tcpip bufserv” |
|*Automatic service with service|PITraceRt.exe –serviceid X –install –auto –depend “tcpip bufserv” |
|id | |
|Windows Service Installation Commands on a PI Interface Node or a PI Server Node |
|without Bufserv implemented |
|Manual service |PITraceRt.exe –install –depend tcpip |
|Automatic service |PITraceRt.exe –install –auto –depend tcpip |
|*Automatic service with service|PITraceRt.exe –serviceid X –install –auto –depend tcpip |
|id | |
*When specifying service id, the user must include an id number. It is suggested that this number correspond to the interface id (/id) parameter found in the interface .bat file.
Check the Microsoft Windows Services control panel to verify that the service was added successfully. The services control panel can be used at any time to change the interface from an automatic service to a manual service or vice versa.
Using tracert
Tracert is a good tool to use to verify data being collected by the PI Traceroute Interface. However, it is important to realize that the internet is a dynamic structure that is constantly changing so it is possible that running tracert against data collected from the PI Traceroute Interface may show some differences. In fact it is not at all uncommon to see different results while running tracert in two different windows or one right after the other. In general, the lower the number of hops between traceroute source and destination the more consistent the results will be. Please refer above to the section titled “Principles of Operation” for a side by side comparison of tracert and data collected by the PI Traceroute Interface.
On Demand Traceroute
The PI Traceroute Interface has the ability to use its internal code to run traceroutes without writing the data to PI. This is especially useful when a user needs immediate feedback from a particular network location and does not have to wait for the next scheduled traceroute. To run an on demand traceroute simple specify the /od= switch at the command line followed by the IP address or host name of the traceroute destination. For example:
PItraceRt /od=soda.berkeley.edu
or
PItraceRt /od=128.32.112.233
By default the UDP protocol is used for the traceroute probes. However it is possible to use ICMP probes with the /odtype switch. For example:
PItraceRt /od=cory.berkeley.edu /odtype=ICMP
Digital States
For more information regarding Digital States, refer to the PI Server documentation.
Digital State Sets
PI digital states are discrete values represented by strings. These strings are organized in PI as digital state sets. Each digital state set is a user-defined list of strings, enumerated from 0 to n to represent different values of discrete data. For more information about PI digital tags and editing digital state sets, see the PI Server manuals.
An interface point that contains discrete data can be stored in PI as a digital tag. A Digital tag associates discrete data with a digital state set, as specified by the user.
If the use of active tags is enabled through the /at command-line parameter the interface automatically creates the required digital state set. The digital state set created by the interface is called TracertStatus and contains the following states: 0 for stopped, 1 for running. If necessary it is acceptable to create this digital state manually.
System Digital State Set
Similar to digital state sets is the system digital state set. This set is used for all tags, regardless of type to indicate the state of a tag at a particular time. For example, if the interface receives bad data from an interface point, it writes the system digital state bad input to PI instead of a value. The system digital state set has many unused states that can be used by the interface and other PI clients.
PointSource
The PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For example, the string TR may be used to identify points that belong to the Traceroute Interface. To implement this, the PointSource attribute would be set to TR for every PI Point that is configured for the Traceroute Interface. Then, if /ps=TR is used on the startup command-line of the Traceroute Interface, the Interface will search the PI Point Database upon startup for every PI point that is configured with a PointSource of TR. Before an interface loads a point, the interface usually performs further checks by examining additional PI point attributes to determine whether a particular point is valid for the interface. For additional information, see the /ps parameter.
Case-sensitivity for PointSource Attribute
If the interface is running on a PINet node, use a capital letter (or a case-insensitive character such as a number, a question mark, etc.) for the PointSource attribute when defining points. For all other scenarios, the case of the PointSource is insignificant.
In all cases, the PointSource character that is supplied with the /ps command-line parameter is not case sensitive. That is, /ps=P and /ps=p are equivalent. It is only necessary to be careful with the case of the PointSource during point definition and only if the Interface will be running on a PINet node communicating to a PI Server.
Reserved Point Sources
Several subsystems and applications that ship with PI are associated with default PointSource characters. The Totalizer Subsystem uses the PointSource character T, the Alarm Subsystem uses G and @, Random uses R, RampSoak uses 9, and the Performance Equations Subsystem uses C. Do not use these PointSource characters or change the default point source characters for these applications. Also, if a PointSource character is not explicitly defined when creating a PI point; the point is assigned a default PointSource character of Lab (PI 3). Therefore, it would be confusing to use Lab as the PointSource character for an interface.
Note: Do not use a point source character that is already associated with another interface program. However it is acceptable to use the same point source for multiple instances of an interface.
PI Point Configuration
The PI point is the basic building block for controlling data flow to and from the PI Server. A single point is configured for each measurement value that needs to be archived.
As mentioned earlier in the section “Principles of Operation”, the PI Traceroute Interface requires the creation of a single “base tag” to configure a traceroute. The interface will automatically create the appropriate detail tags if specified to do so using the command-line parameters; otherwise the appropriate detail tags must also be created.
Point Attributes
Use the point attributes below to define the PI Point configuration for the Interface, including specifically what data to transfer.
Tag
A tag is a label or name for a point. For the routepoint, any tag name can be used in accordance with the normal PI point naming conventions.
Length
This interface uses the PI-SDK which provides a maximum length of 1023 for the Tag field.
However, when creating the base tag, the name is limited to 1000 characters or less. When the interface creates all other required tags, it uses the following naming conventions:
1. Tags that store the latency or round trip time of a probe start with the base tag name and have a suffix of _detail_latency.
2. Tags that store the total time a traceroute takes to complete start with the base tag name and have a suffix of _detail_time.
3. Tags that store the total number of hops it took to complete the traceroute start with the base tag name and have a suffix of _detail_hops.
4. Active tags start with the base tag name and have a suffix of _detail_active.
5. Tags that store the total number of retries that occurred during the traceroute start with the base tag name and have a suffix of _detail_retries.
These naming conventions specified above are also required if the tags are created manually.
PointSource
The PointSource is a unique, single or multi-character string that is used to identify the PI point as a point that belongs to a particular interface. For additional information, see the /ps command-line parameter and the “PointSource” section.
PointType
The base tag must be a string tag and is where the interface will store the host name or IP address (depending on the tag configuration) of the hops in the traceroute. Other required tags such as the latency tag and total execution time tag are automatically created by the interface with the appropriate PointType unless the user specifies not to create these points automatically. When points are created manually the user must use an appropriate PointType for each traceroute tag as specified in the list below:
1. latency tag: float16, float32, float64
2. time tag: float16, float32, float64
3. hops tag: int32
4. active tag: digital
5. retries tag: int32
Location1
Location1 indicates to which copy of the interface the point belongs. The value of this attribute must match the /id startup parameter.
Location2
This attribute in the routepoint tag specifies the retry timeout (in seconds) for each probe. It is ignored in the detail tags.
The retry timeout determines when to resend a probe for which no reply was received. The interface will continue to send retries at that interval until it receives a response, the traceroute completes, or the traceroute times out.
The retry timeout must be an integer greater than or equal to zero and less than or equal to one third of the timeout period, specified in Location3.
If this attribute is set to zero, the interface will not attempt to resend probes.
This attribute is ignored if the Interface is configured to operate in spray mode by specifying a value in Location5.
Location3
This attribute in the routepoint tag specifies the timeout period in seconds for a single traceroute. It is ignored in the detail tags.
The timeout period must be an integer greater than or equal to 10; however, if the command-line parameter /nsl is specified, this minimum is reduced to zero.
For scan-based tags, if this value is set to zero, a default value is assigned which is nine-tenths of the scan period. The Interface truncates this number if it has a fractional part. This value must also be less than the scan period of the point. The scan period is defined with the Location4 attribute and the /f command line parameter.
For event-based tags, if this value is set to zero, a default value of 30s is assigned.
Location4
Scan-based Inputs
For interfaces that support scan-based collection of data, Location4 defines the scan class for the PI point. The scan class determines the frequency at which input points are scanned for new values. For more information, see the description of the /f parameter in the section called “Startup Command File”.
The minimum scan class accepted by the interface is 20 seconds unless the /nsl command line parameter is specified.
Trigger-based Inputs
Location 4 should be set to zero for these points.
This attribute is ignored in the detail tags.
Location5
This attribute in the routepoint tag specifies the use of spray mode. It is ignored in the detail tags.
In spray mode the interface attempts to discover all routing points to the destination in parallel instead of in series. This is done by sending a wave of probe packets with increasing TTL (time to live) values. This differs from normal operation which does not send a probe packet with increased TTL until a response for the previous probe packet is received.
The default for this attribute is zero which means spray mode is disabled. A positive number indicates the number of probe packets to transmit simultaneously.
The advantage of spray mode is the discovery of the traceroute path in a shorter amount of time. However, there are also disadvantages to using spray mode. Both disadvantages stem from the fact that it is not possible to predict how many probes will be needed for a traceroute. Sending too many probes can result in superfluous network traffic. On a small scale this extra network traffic is trivial but on a larger scale it can contribute to overall network inefficiency. Sending too few packets will result in an incomplete traceroute.
Spray mode is recommended for network routes that are assumed to be static most of the time. For example, internal network routes where the number of total hops to the destination hardly ever varies or varies very slightly (by an extra hop). For these more static routes spray mode is a quicker more efficient way to determine whether of not the route is up and looks the way it is expected to.
InstrumentTag
This attribute in the routepoint tag specifies the traceroute destination. It is ignored in the detail tags.
The attribute accepts both IP addresses and resolvable host names. When host names are specified, the interface queries the DNS servers registered on the machine running the interface.
Length
This interface uses the PI-SDK which provides a maximum length of 1023 for the InstrumentTag field.
ExDesc
This attribute in the routepoint tag is used to specify additional operating parameters for the traceroute. It is ignored in the detail tags.
Each additional operating parameter is specified by a keyword-value pair i.e. =.
The values entered into the ExDesc attribute are case insensitive and are not positional. The only restriction is that each keyword-value pair is separated by a comma. A space can also be used as a separator; however, this is only provided for backwards compatibility.
Example: type=UDP, resolve=yes
Below is a description of each keyword that can be adjusted in the ExDesc attribute.
Type
The default protocol used for traceroutes probes is UDP but the use of ICMP probes can be configured by specifying the following in the ExDesc:
type=ICMP
Resolve
The default behavior for traceroutes is not to resolve IP addresses to hostnames but the interface can be configured to resolve IP addresses by specifying the following in the ExDesc:
resolve=YES
If the IP address is not resolvable then the interface will simply write the IP address to the routepoints tag.
ForceDNS
When IP addresses are resolved to hostnames, the default behavior is to use the operating system to perform the translation. The interface can also be configured to query the DNS servers registered on the machine running the interface by specifying the following in the ExDesc:
forcedns=YES
ResolveRate
The interface resolves hostnames specified in the InstrumentTag attribute of routepoint tags when they are first loaded. The interface can be configured to periodically refresh the resolved hostname by specifying the following in the ExDesc:
resolverate=#
The integer value represents the number of traceroutes performed between refreshes. For example, a value of one causes a refresh after each traceroute, a value of two causes a refresh every second traceroute and so on.
UnitPath
By default the interface creates traceroute “batch” units at the root level of the PI Module Database (MDB). This can create a lot of clutter at the root level of the MDB which can be a problem especially if the MDB is used to store data from other applications. However, the interface allows the user to specify a MDB hierarchy where he would like to store the traceroute “batch” units.
unitpath=module1\module2\module3
As seen from the above example, each module in the hierarchy is separated by a backslash. If any part of the module hierarchy does not exist it will be created by the interface. If the path is malformed or contains invalid characters the interface will log an error message and the tag will be rejected.
SourceIP
This allows the source IP address used in the probes to be specified. The source IP address must belong to the computer on which the interface is running and must be a valid IPv4 address. This keyword is only useful when running the interface on a computer with multiple NICs.
Trigger-based Inputs
For trigger-based input points, a separate trigger point must be configured. An input point is associated with a trigger point by entering a case-insensitive string in the extended descriptor (ExDesc) PI point attribute of the input point of the form:
keyword=trigger_tag_name
where keyword is replaced by “event” or “trig” and trigger_tag_name is replaced by the name of the trigger point. There should be no spaces in the string. UniInt automatically assumes that an input point is trigger-based instead of scan-based when the keyword=trigger_tag_name string is found in the extended descriptor attribute.
An input is triggered when a new value is sent to the Snapshot of the trigger point. The new value does not need to be different than the previous Snapshot value to trigger an input, but the timestamp of the new value must be greater than (more recent than) or equal to the timestamp of the previous value. This is different than the trigger mechanism for output points. For output points, the timestamp of the trigger value must be greater than (not greater than or equal to) the timestamp of the previous value.
Conditions can be placed on trigger events. Event conditions are specified in the extended descriptor as follows:
Event=‘trigger_tag_name’ event_condition
The trigger tag name must be in single quotes. For example,
Event=‘Sinuoid’ Anychange
will trigger on any event to the PI Tag sinusoid as long as the next event is different than the last event. The initial event is read from the snapshot.
The keywords in the following table can be used to specify trigger conditions.
|Event Condition |Description |
|Anychange |Trigger on any change as long as the value of the current event is different than the value of the|
| |previous event. System digital states also trigger events. For example, an event will be |
| |triggered on a value change from 0 to “Bad Input,” and an event will be triggered on a value |
| |change from “Bad Input” to 0. |
|Increment |Trigger on any increase in value. System digital states do not trigger events. For example, an |
| |event will be triggered on a value change from 0 to 1, but an event will not be triggered on a |
| |value change from “Pt Created” to 0. Likewise, an event will not be triggered on a value change |
| |from 0 to “Bad Input.” |
|Decrement |Trigger on any decrease in value. System digital states do not trigger events. For example, an |
| |event will be triggered on a value change from 1 to 0, but an event will not be triggered on a |
| |value change from “Pt Created” to 0. Likewise, an event will not be triggered on a value change |
| |from 0 to “Bad Input.” |
|Nonzero |Trigger on any non-zero value. Events are not triggered when a system digital state is written to|
| |the trigger tag. For example, an event is triggered on a value change from “Pt Created” to 1, but|
| |an event is not triggered on a value change from 1 to “Bad Input.” |
Length
The interface uses the PI-SDK which provides a maximum length of 1023 for the Extended Descriptor field.
Scan
The Scan attribute has the default value of 1, indicating that the Interface should collect data for the point. Setting the Scan attribute to 0 turns data collection off. If the Scan attribute is 0 when the interface starts, the Interface writes SCAN OFF to the point. If the user changes the Scan attribute from 1 to 0 while the interface is running, the Interface also writes SCAN OFF.
There is one other situation, which is independent of the Scan attribute, where UniInt will write SCAN OFF to a PI point. If a point that is currently loaded by the interface is edited so that the point is no longer valid for the interface, the point will be removed from the interface, and SCAN OFF will be written to the point. For example, if the PointSource of a PI point that is currently loaded by the interface is changed, the point will be removed from the interface and SCAN OFF will be written to the point.
Shutdown
The Shutdown attribute is 1 (true) by default. The default behavior of the PI Shutdown subsystem is to write the SHUTDOWN digital state to all PI points when PI is started. The timestamp that is used for the SHUTDOWN events is retrieved from a file that is updated by the Snapshot Subsystem. The timestamp is usually updated every 15 minutes, which means that the timestamp for the SHUTDOWN events will be accurate to within 15 minutes in the event of a power failure. For additional information on shutdown events, refer to PI Server manuals.
Note: The SHUTDOWN events that are written by the PI Shutdown subsystem are independent of the SHUTDOWN events that are written by the interface when the /stopstat=Shutdown command-line parameter is specified.
SHUTDOWN events can be disabled from being written to PI when PI 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 \PI\dat\Shutdown.dat file, as discussed in PI Server manuals.
Bufserv
It is undesirable to write shutdown events when Bufserv is being used. Bufserv is a utility program that provides the capability to store and forward events to a PI Server, allowing continuous data collection when the Server is down for maintenance, upgrades, backups, and unexpected failures. That is, when PI is shut down, Bufserv will continue to collect data for the interface, making it undesirable to write SHUTDOWN events to the PI points for this interface.
Performance Point Configuration
This Interface does not support Performance Points.
I/O Rate Tag Configuration
An I/O Rate tag measures the throughput of an Interface. In particular, the value of an I/O Rate point represents a 10-minute average of the total number of values per minute that the Interface sends to the PI Server. Because values are averaged over a 10-minute interval, the first calculated value is not written to the PI Server until 10 minutes after the Interface has started. The user can configure one I/O Rate tag for each copy of the Interface that is in use.
Monitoring I/O Rates on the Interface Node
For Windows nodes, the 10-minute rate averages (in events/minute) can be monitored with a client application such as PI ProcessBook.
Configuring I/O Rate Tags with PI ICU (Windows)
The PI Interface Configuration Utility (PI ICU) provides a user interface for creating and managing I/O Rate Tags.
[pic]
PI ICU currently allows for one I/O Rate tag to be configured for each copy of the interface that is in use. Some interfaces allow for multiple I/O Rate tags.
Enable IORates for this Interface
The Enable IORates for this interface check box enables or disables the I/O Rate point for the Interface. To disable the I/O Rate point, uncheck this box. To enable the I/O Rate point, check this box.
Event Counter
The Event Counter number correlates a point specified in the IORates.dat file with this Interface. This correlation results from the command line parameter
-ec=x
where x is the same number that is assigned to the point named in the IORates.dat file.
Tagname
The tag name listed under the Tagname column is the name of the I/O Rates point.
Tag Status
The Tag Status column indicates whether the I/O Rate point currently exists in PI Server. The possible states are:
• Created - This status indicates that the point exists in PI Server
• Not Created - This status indicates that the point does not yet exist in PI Server
• Deleted - This status indicates that the point has just been deleted
• Unknown - This status indicates that the PI ICU is not able to access PI Server
In File
The In File column indicates whether the I/O Rates point listed in the Tagname column and the event counter number listed in the Event Counter column are in the IORates.dat file. The possible states are:
• Yes - This status indicates that the I/O Rate point and the event counter number are in the IORates.dat file
• No - This status indicates that the I/O Rate point and the event counter number are not in the IORates.dat file
Snapshot
The Snapshot column holds the snapshot value of the I/O Rate tag, if the I/O Rate tag exists in PI. The Snapshot column is updated when the IORates/Status Tags tab is clicked, and when the Interface is first loaded.
Button Menu Options
Create
Create the suggested I/O Rates point with the tag name indicated in the Tagname column.
Delete
Delete the I/O Rate point listed in the Tagname column.
Reset
Change the value in the Tagname text box back to the default value.
Rename
Allow the user to specify a new name for the I/O Rate point listed in the Tagname column.
Add to File
Add the I/O Rate point and the event counter number to the IORates.dat file.
Search [pic]
Allow the user to search the PI Server a previously defined I/O Rate points.
Update Snapshot [pic]
Allow the user to refresh the snapshot value.
Configuring I/O Rate Tags Manually
There are two configuration steps.
1. Configuring the PI Point on the PI Server
2. Configuration on the Interface Node
Configuring PI Point on the PI Server
Create an I/O Rate Tag with the following point attribute values.
|Attribute |Value |
|PointSource |L |
|PointType |float32 |
|Compressing |0 |
|ExcDev |0 |
Configuration on the Interface Node
For the following examples, assume that the name of the PI tag is tracert001, and that the name of the I/O Rate on the home node is tracert001.
1. Edit/Create a file called IORates.dat in the PIHOME\dat directory. The PIHOME directory is defined either by the PIPCSHARE entry or the PIHOME entry in the pipc.ini file, which is located in the %windir% directory. If both are specified, the PIPCSHARE entry takes precedence.
Since the PIHOME directory is typically C:\PIPC, the full name of the IORates.dat file will typically be C:\PIPC\dat\IORates.dat.
Add a line in the IORates.dat file of the form:
tracert001, x
where tracert001 is the name of the I/O Rate Tag and x corresponds to the first instance of the /ec=x parameter in the startup command file. X can be any number between 2 and 34 or between 51 and 200, inclusive. To specify additional rate counters for additional copies of the interface, create additional I/O Rate tags and additional entries in the IORates.dat file. The event counter, /ec=x, should be unique for each copy of the interface.
2. Set the /ec=x parameter on the startup command file of the interface to match the event counter in the IORates.dat file.
The interface must be stopped and restarted in order for the I/O Rate tag to take effect. I/O Rates will not be written to the tag until 10 minutes after the interface is started.
Startup Command File
Command-line parameters can begin with a / or with a -. For example, the /ps=M and
–ps=M command-line parameters are equivalent.
For Windows, command file names have a .bat extension. The Windows continuation character (^) allows for the use of multiple lines for the startup command. The maximum length of each line is 1024 characters (1 kilobyte). The number of parameters is unlimited, and the maximum length of each parameter is 1024 characters.
The PI Interface Configuration Utility (PI ICU) provides a tool for configuring the Interface startup command file.
Configuring the Interface with PI ICU
Note: PI ICU requires PI 3.3 or greater.
The PI Interface Configuration Utility provides a graphical user interface for configuring PI interfaces. If the interface is configured by the PI ICU, the batch file of the interface (PITraceRt.bat) will be maintained by the PI ICU and all configuration changes will be kept in that file. The procedure below describes the necessary steps for using PI ICU to configure the PI Traceroute Interface.
From the PI ICU menu, select Interface, New Windows Interface Instance from EXE…, and then Browse to the appropriate executable. The executable file will be PITraceRT.exe. Then, choose a Host PI System, enter values for Point Source and change the Interface ID#, Service ID and optionally the Interface name as displayed in the ICU. A window such as the following results:
[pic]
“Interface name as displayed in the ICU (optional)” will have PI- pre-pended to this name and it will be the display name in the services menu.
Click on Add.
The dialog box shown below is then displayed.
[pic]
Note that in this example the Host PI System is localhost, which means that the interface will be configured to communicate with the local PI Server. However, to configure the interface to communicate with a remote PI Server, select ‘Connections…’ item from the PI ICU menu and make it the default server. If the remote node is not in the list of servers, it can be added.
Once the interface is added to the PI ICU, near the top of the main PI ICU screen, the Interface Type should be tracert. If not, use the drop-down box to change the Interface Type to be tracert.
Click on Apply to enable the PI ICU to manage this copy of the PI Traceroute Interface.
[pic]
The next step is to make selections in the interface-specific tab (i.e. “tracert”) that allows the startup parameters that are particular to the PI Traceroute Interface to be specified.
The tracert ICU control has 2 tabs. A yellow text box indicates that an invalid value has been entered, or that a required value has not been entered.
The next screenshot shows the General, Hops and tracert tab.
[pic]
Since the PI Traceroute interface is a UniInt-based interface, in some cases the user will need to make appropriate selections in the UniInt tab. This tab allows the user to access UniInt features through the PI ICU and to make changes to the behavior of the interface.
To set up the interface as a Windows Service, use the Service tab. This tab allows the interface to be configured to run as a service as well as to start and stop the interface. The interface can also be run interactively from the PI ICU. To do that go to menu, select the Interface item and then Start Interactive.
For more detailed information on how to use the above-mentioned and other PI ICU tabs and selections, please refer to the PI Interface Configuration Utility User Manual. In the next section we will describe the selections that are available from the tracert tab. After making any on the PI ICU GUI, press the Apply button to make these changes to the interface’s startup file.
tracert Interface Tab
Since the startup file of the PI Traceroute Interface is maintained automatically by PI ICU, it is recommended that the tracert tab is used to configure the interface specific startup parameters and instead of making changes to the file manually. The following is the description of interface configuration parameters used in the PI ICU Control and corresponding manual parameters.
General, Hops and Traceroute Tab
[pic]
Do not update batch database
This tells the interface not to update the PI Batch Database. The checkbox must be set in order for the interface to run against PI servers 3.2.x. It must also be checked if the PI Batch Generator Interface will be updating the PI Batch Database for the interface. In the latter scenario the “Maintain active tags” checkbox must be used as well. The command-line equivalent is /nb.
Thread count
This specifies the number of worker threads that service outgoing network traffic (send worker threads) and the number of worker threads that service incoming network traffic (receive worker threads). The command-line equivalent is /tc=n and is an optional parameter with a default value of 3.
Hops tag
This maintains a count of the total number of hops determined by a traceroute. When this is set equal to 0, hops tags are not used and this is the default behavior. The command-line equivalent is /hopstag=n and is an optional parameter.
Retries tag
This maintains a count of the number of times a probes were re-sent during the traceroute because they did not receive a reply. When this is set equal to 0, retries tags are not used and this is the default behavior. The command-line equivalent is /retrtag=n and is an optional parameter.
Maximum hops
This specifies the maximum number of hops for each traceroute between 10 and 255 inclusive. The command-line equivalent is /maxhops=n and is an optional parameter with a default value of 30.
On demand traceroute
This initiates an on demand traceroute. An on demand traceroute uses the PI Traceroute Interface code to execute a traceroute to a user specified destination without writing the results to the PI server. Instead, the results are displayed in the terminal window where the on demand traceroute and in the interface log file (pipc.log). The traceroute sends UDP protocol probes by default but can send ICMP protocols by using the “Protocol type” (ICMP) button. The command-line equivalent is /od=hostname; however, it is worth mentioning that the /od=hostname parameter require the use of the /ps and /sn parameters.
Protocol type
This specifies the protocol type of the probes sent by an on demand traceroute. The default is UDP. The command-line equivalent is /odtype=UDP or ICMP.
On Demand Resolve IP address
This specifies if resolved IP addresses are returned during on-demand traceroute to hostnames. The command-line equivalent is /odres.
On Demand Force DNS Server Lookup
This parameter is use with the /ODES command line parameter and specifies that DNS Servers are queried to resolve the IP addresses to hostnames for on-demand traceroutes. By querying the DNS Servers directly, it bypasses the local DNS cache. The command-line equivalent is /odforcedns.
Maintain active tags
This tells the interface to maintain active tags for each traceroute group. Active tags maintain the current state of the PI Traceroute Interface which can be either RUNNING or STOPPED. The command-line equivalent is /at.
Don’t create detail tags for base tags loaded
This tells the interface not to create any detail tags for the base tags which are loaded. The command-line equivalent is /dct.
No scan limit
This is an override parameter which instructs the interface to accept tags which are configured to use scan classes with time periods of less that 20 seconds. It also allows the user to configure tags with traceroute timeouts (specified in location 3) of less than 10 seconds. By default all tags that are configured to use a scan class of less than 20 seconds or a traceroute timeout of less than 10 seconds are rejected. The command-line equivalent is /nsl.
Source IP Address
This parameter is used to specify the source IP address used in the probes. The source IP address must belong to the computer on which the interface is running and must be a valid IPv4 address. This parameter is only useful when running the interface on a computer with multiple NICs. The command-line equivalent is /sourceip=a.b.c.d
Additional Parameters
In the space provided the user can enter any additional parameters that are not available through PI ICU.
Debug Tab
[pic]
Maximum debug settings
This specifies that the interface should use all possible debug levels. Checking this box will check all the individual settings. The command-line equivalent is /dbg=255 and is an optional parameter.
Default debug settings
This specifies that the interface is to use the default debug level for logging. Checking this box will uncheck any of the individual settings. The command-line equivalent is /dbg=0 and is the default setting.
Individual debug levels
These individual debug levels can be combined by checking the individual boxes. The combined value will be displayed in the Debug level: text box at the lower right. Informational messages from the different sections of the interface can be combined by adding the debug level values. See the section /dbg in the Command-line Parameters section for more information. The command-line equivalent is /dbg=n and is an optional parameter with a default value of 0.
Additional Parameters
In the space provided the user can enter any additional parameters that are not available through PI ICU.
Note: The UniInt Interface User Manual includes details about other command-line parameters, which may be useful.
Command-line Parameters
|Parameter |Description |
|/at |The /at parameter instructs the interface to maintain active tags for each traceroute |
|Optional |group. |
| |Active tags maintain the current state of the PI Traceroute Interface which can be |
| |either “RUNNING” or “STOPPED”. Active tags can be used in conjunction with the PI |
| |Batch Generator Interface to implement event framing for each traceroute run. Please |
| |refer to “Appendix C: Using PI Batch Generator to Create Traceroute Batches” for more |
| |information. |
|/dbg=# |The /dbg parameter specifies the debug output level. # is a number between 0 and 255 |
|Optional |which is computed as follows: |
| |0 specifies only critical error messages are logged. |
| |Add 1 to display warning messages. |
| |Add 2 to display traceroute state messages. These messages convey information about |
| |the current state of traceroutes. |
| |Add 4 to display traceroute map messages. These messages contain information about |
| |when traceroutes are created, scheduled, or deleted. |
| |Add 8 for network messages. These messages show when packets are sent on the network |
| |and when they are received. |
| |Add 16 for time messages. These messages display timing information such as when a |
| |traceroute starts and when it ends. |
| |Add 32 for batch messages. The interface will output messages when a batch is started |
| |and when it ends for a traceroute. |
| |Add 64 to display messages regarding packet abnormalities. |
| |Add 128 to display messages of failed batch operations. This debug level is actually |
| |enabled by default because of the critical nature of these errors. However, when |
| |connecting to a PI 3.2 server, which does not support the PI Batch Database, the |
| |interface will disable this debug level unless it is explicitly included using the |
| |/dbg parameter. This is by design in order to prevent the log file from overflowing |
| |with expected error messages. |
| |Note: During normal operations the debug level should be set to zero; otherwise a |
| |large number of messages may be written to the pipc.log file. |
|/dct |The /dct parameter instructs the interface not to automatically create detail tags for|
|Optional |a loaded base tag. This applies to all base tags loaded by the PI Traceroute |
| |Interface. |
|/ec=# |The first instance of the /ec parameter on the command-line is used to specify a |
|Optional |counter number, #, for an I/O Rate point. If the # is not specified, then the default |
| |event counter is 1. Also, if the /ec parameter is not specified at all, there is still|
| |a default event counter of 1 associated with the interface. If there is an I/O Rate |
| |point that is associated with an event counter of 1, each copy of the interface that |
| |is running without /ec=#explicitly defined will write to the same I/O Rate point. This|
| |means either explicitly defining an event counter other than 1 for each copy of the |
| |interface or not associating any I/O Rate points with event counter 1. Configuration |
| |of I/O Rate points is discussed in the section called “I/O Rate Tag Configuration.” |
| |For interfaces that run on Windows nodes, subsequent instances of the /ec parameter |
| |may be used by specific interfaces to keep track of various input or output |
| |operations. Subsequent instances of the /ec parameter can be of the form /ec*, where *|
| |is any ASCII character sequence. For example, /ecinput=10, /ecoutput=11, and /ec=12 |
| |are legitimate choices for the second, third, and fourth event counter strings. |
|/f=SS |The /f parameter defines the time period between scans in terms of hours (HH), minutes|
|or |(MM), and seconds (SS). The scans can be scheduled to occur at discrete moments in |
|/f=SS,SS |time with an optional time offset specified in terms of hours (hh), minutes (mm), and |
|or |seconds (ss). If HH and MM are omitted, then the time period that is specified is |
|/f=HH:MM:SS |assumed to be in seconds. |
|or |Each instance of the /f parameter on the command-line defines a scan class for the |
|/f=HH:MM:SS, |interface. There is no limit to the number of scan classes that can be defined. The |
|hh:mm:ss |first occurrence of the /f parameter on the command-line defines the first scan class |
| |of the interface; the second occurrence defines the second scan class, and so on. PI |
|Required for reading |Points are associated with a particular scan class via the Location4 PI Point |
|scan-based inputs |attribute. For example, all PI Points that have Location4 set to 1 will receive input |
| |values at the frequency defined by the first scan class. Similarly, all points that |
| |have Location4 set to 2 will receive input values at the frequency specified by the |
| |second scan class, and so on. |
| |Two scan classes are defined in the following example: |
| |/f=00:01:00,00:00:05 /f=00:00:07 |
| |or, equivalently: |
| |/f=60,5 /f=7 |
| |The first scan class has a scanning frequency of 1 minute with an offset of 5 seconds,|
| |and the second scan class has a scanning frequency of 7 seconds. When an offset is |
| |specified, the scans occur at discrete moments in time according to the formula: |
| |scan times = (reference time) + n(frequency) + offset |
| |where n is an integer and the reference time is midnight on the day that the interface|
| |was started. In the above example, frequency is 60 seconds and offset is 5 seconds for|
| |the first scan class. This means that if the interface was started at 05:06:06, the |
| |first scan would be at 05:06:10, the second scan would be at 05:07:10, and so on. |
| |Since no offset is specified for the second scan class, the absolute scan times are |
| |undefined. |
| |The definition of a scan class does not guarantee that the associated points will be |
| |scanned at the given frequency. If the interface is under a large load, then some |
| |scans may occur late or be skipped entirely. See the section called “Performance Point|
| |Configuration” for more information on skipped or missed scans. |
| |Wall Clock Scheduling |
| |Scan classes that strictly adhere to wall clock scheduling are now possible. This |
| |feature is available for interfaces that run on Windows and/or UNIX. Previously, wall |
| |clock scheduling was possible, but not across daylight saving time. For example, |
| |/f=24:00:00,08:00:00 corresponds to 1 scan a day starting at 8 AM. However, after a |
| |Daylight Saving Time change, the scan would occur either at 7 AM or 9 AM, depending |
| |upon the direction of the time shift. To schedule a scan once a day at 8 AM (even |
| |across daylight saving time), use /f=24:00:00,00:08:00,L. The ,L at the end of the |
| |scan class tells UniInt to use the new wall clock scheduling algorithm. |
|/hopstag=0 |The /hopstag parameter is used to specify the way the interface uses “hops” tags. Hops|
|or |tags maintain a count of the total number of hops found by a traceroute. |
|/hopstag=1 |When this parameter is set to 0 hops tags are not used. This is the default behavior. |
|or |If the parameter is set to 1 the total number of hops is written on completion of the |
|/hopstag=2 |traceroute. |
|Optional |If the parameter is set to 2 the hops tag is maintained as a counter that is |
| |incremented with each hop. |
|/host=host:port |The /host parameter is used to specify the PI Home node. Host is the IP address of |
|Required |the PI Sever node or the domain name of the PI Server node. Port is the port number |
| |for TCP/IP communication. The port is always 5450. It is recommended to explicitly |
| |define the host and port on the command-line with the /host parameter. Nevertheless, |
| |if either the host or port is not specified, the interface will attempt to use |
| |defaults. |
| |Examples: |
| |The interface is running on a PI Interface Node, the domain name of the PI home node |
| |is Marvin, and the IP address of Marvin is 206.79.198.30. Valid /host parameters would|
| |be: |
| |/host=marvin |
| |/host=marvin:5450 |
| |/host=206.79.198.30 |
| |/host=206.79.198.30:5450 |
|/id=x |The /id parameter is used to specify the interface identifier. |
|Required |The interface identifier is a string that is no longer than 9 characters in length. |
| |UniInt concatenates this string to the header that is used to identify error messages |
| |as belonging to a particular interface. See the section called “Appendix A: Error and |
| |Informational Messages” for more information. |
| |UniInt always uses the /id parameter in the fashion described above. This interface |
| |also uses the /id parameter to identify a particular interface copy number that |
| |corresponds to an integer value that is assigned to one of the Location code point |
| |attributes, most frequently Location1. For this interface, use only numeric characters|
| |in the identifier. For example, |
| |/id=1 |
|/maxhops=# |The /maxhops parameter specifies the maximum number of hops for each traceroute. # is |
|Optional |a number between 10 and 255 inclusive. |
| |The default value for this parameter is 30. |
|/nb |The /nb parameter tells the interface not to update the PI Batch Database. |
|Optional |The parameter must be set in order for the interface to run against PI servers 3.2.x |
| |or earlier. It must also be sent if the PI Batch Generator Interface will be updating |
| |the PI Batch Database for the interface. In the latter scenario the /at parameter must|
| |be used as well. |
| |If this parameter is omitted the interface will update the batch database. |
|/nsl |The /nsl parameter is used to specify no scan limits. This is an override parameter |
|Optional |which instructs the interface to accept tags which are configured to use scan classes |
| |with time periods of less than 20 seconds. It also allows the user to configure tags |
| |with traceroute timeouts (specified in location3) of less than 10 seconds. By default,|
| |tags that are configured to use a scan class of less than 20 seconds or a traceroute |
| |timeout of less than 10 seconds are rejected. |
|/od=a.b.c.d |The /od parameter is used to initiate an on-demand traceroute. |
|or |An on-demand traceroute uses the PI Traceroute Interface code to execute a traceroute |
|/od=hostname |to a user specified destination without writing the results to the PI server. Instead,|
|Optional |the results are displayed in the terminal window and in the interface log file |
| |(pipc.log). |
| |The traceroute sends UDP protocol probes by default but can send ICMP protocols by |
| |using the /odtype switch. |
|/odforcedns |The /odforcedns parameter is used with /odres and specifies that DNS servers are |
|Optional |queried to resolve the IP addresses to hostnames for on-demand traceroutes. By |
| |querying the DNS servers directly, it bypasses the local DNS cache. |
|/odres |The /odres parameter specifies that IP addresses returned during an on-demand |
|Optional |traceroute are resolved to hostnames. |
| |By default IP addresses are not resolved to host names during an on-demand |
| |traceroutes. |
|/odtype=UDP |The /odtype parameter specifies the protocol type of the probes sent by an on-demand |
|or |traceroute. |
|/odtype=ICMP |By default, the interface uses UDP probes. |
|Optional | |
|/ps=x |The /ps parameter specifies the point source for the interface. X is not case |
|Required |sensitive and can be any unique single or multiple character string. For example, |
| |/ps=P and /ps=p are equivalent. |
| |The point source that is assigned with the /ps parameter corresponds to the |
| |PointSource attribute of individual PI Points. The interface will attempt to load only|
| |those PI points with the appropriate point source. |
|/q |When the /q parameter is present, Snapshots and exceptions are queued before they are |
|Optional |sent to the PI Server node. |
| |Extended PI API mode behavior: |
| |The maximum queue size is close to 4000 bytes. The queue is flushed between scans if |
| |it is not filled. |
| |Non-Extended PI API mode behavior: |
| |The maximum queue size is 255 bytes for a PI Interface node. For example, if the |
| |interface is running on a UNIX node and is communicating to a PI Server, then the |
| |maximum queue size is 255. The queue is flushed between scans if it is not filled. |
| |When the /q parameter is specified in non-extended PI API mode, the PI API sends |
| |integer values as 16-bit integers instead of 32-bit integers. Therefore, integer |
| |points will be limited to values between 0 and 32767. Values higher than 32767 need to|
| |be sent to floating-point PI tags. |
|/retrtag=0 |The /retrtag parameter is used to specify the way the interface uses “retries” tags. |
|or |Retries tags maintain a count of the number of times probes were re-sent during the |
|/retrtag=1 |traceroute because a reply was not received. |
|or |When this parameter is set to 0 retries tags are not used. This is the default |
|/retrtag=2 |behavior. |
|Optional |If the parameter is set to 1 the total number of retries is written on completion of |
| |the traceroute. |
| |If the parameter is set to 2 the retries tag is maintained as a counter that is |
| |incremented with each hop. |
|/sn |When this parameter is specified, all exception reporting is disabled. |
|Required | |
|/sourceip=a.b.c.d |The /sourceip parameter is used to specify the source IP address used in the probes. |
|Optional |The source IP address must belong to the computer on which the interface is running |
| |and must be a valid IPv4 address. This parameter is only useful when running the |
| |interface on a computer with multiple NICs. |
|/stopstat |If the /stopstat parameter is present on the startup command line, then the |
|or |digital state Intf Shut will be written to each PI Point when the interface is |
|/stopstat= |stopped. |
|digstate |If /stopstat=digstate is present on the command line, then the digital state, |
|Default: |digstate, will be written to each PI Point when the interface is stopped. For a PI 3 |
|/stopstat= |Server, digstate must be in the system digital state table. |
|”Intf Shut” |If neither /stopstat nor /stopstat=digstate is specified on the command line, then no |
|Optional |digital states will be written when the interface is shut down. |
| |Examples: |
| |/stopstat=shutdown |
| |/stopstat=”Intf Shut” |
| |The entire digstate value should be enclosed within double quotes when there is a |
| |space in digstate. |
|/tc=# |The /tc parameter is used to specify the number of worker threads that service |
|Optional |outgoing network traffic (send worker threads) and the number of worker threads that |
| |service incoming network traffic (receive worker threads). For example, /tc=7 would |
| |create 7 send worker threads and 7 receive worker threads. |
| |# is a number between 1 and 10. |
| |If the /tc parameter is excluded the default parameter is 3. |
Sample PITraceRt.bat File
The following is an example file:
REM=======================================================================
REM
REM PITraceRt.bat
REM
REM Sample startup file for the PI Traceroute Interface to the
REM PI System
REM
REM=======================================================================
REM
REM OSIsoft strongly recommends using PI ICU to modify startup files.
REM
REM Sample command line
REM
.\pitracert.exe /sn /host=XXXXXX:5450 /ps=TR /id=1 /hopstag=2 /retrtag=2 /at /f=00:05:00,0 /f=00:10:00,0 /f=00:15:00,0
REM
REM End of PITraceRt.bat File
Interface Node Clock
Make sure that the time and time zone settings on the computer are correct. To confirm, run the Date/Time applet located in the Windows Control Panel. If the locale where the interface node resides observes Daylight Saving Time, check the box marked “Automatically adjust clock for daylight saving changes”. For example,
[pic]
In addition, make sure that the TZ environment variable is not defined. All of the currently defined environment variables can be viewed by opening a Command Prompt window and typing set. That is,
C:> set
Confirm that TZ is not in the resulting list. If it is, run the System applet of the Control Panel, click the Environment tab, and remove TZ from the list of environment variables.
Security
Windows
The PI Firewall Database and the PI Proxy Database must be configured so that the interface is allowed to write data to the PI Server. See “Modifying the Firewall Database” and “Modifying the Proxy Database” in the PI Server manuals.
Note that the Trust Database, which is maintained by the Base Subsystem, replaces the Proxy Database used prior to PI version 3.3. The Trust Database maintains all the functionality of the proxy mechanism while being more secure.
See “Trust Login Security” in the chapter “PI System Management” of the PI Universal Data Server System Management Guide.
If the interface cannot write data to the PI Server because it has insufficient privileges, a –10401 error will be reported in the pipc.log file. If the interface cannot send data to a PI2 Serve, it writes a –999 error. See the section “Appendix A: Error and Informational Messages” for additional information on error messaging.
PI Server v3.3 and Higher
Security configuration using piconfig
For PI Server v3.3 and higher, the following example demonstrates how to edit the PI Trust table:
C:\PI\adm> piconfig
@table pitrust
@mode create
@istr Trust,IPAddr,NetMask,PIUser
a_trust_name,192.168.100.11,255.255.255.255,piadmin
@quit
For the above,
Trust: An arbitrary name for the trust table entry; in the above example,
a_trust_name
IPAddr: the IP Address of the computer running the Interface; in the above example,
192.168.100.11
NetMask: the network mask; 255.255.255.255 specifies an exact match with IPAddr
PIUser: the PI user the Interface to be entrusted as; piadmin is usually an appropriate user
Security Configuring using Trust Editor
The Trust Editor plug-in for PI System Management Tools 3.x may also be used to edit the PI Trust table.
See the PI System Management chapter in the PI Server manual for more details on security configuration.
PI Server v3.2
For PI Server v3.2, the following example demonstrates how to edit the PI Proxy table:
C:\PI\adm> piconfig
@table pi_gen,piproxy
@mode create
@istr host,proxyaccount
piapimachine,piadmin
@quit
In place of piapimachine, put the name of the PI Interface node as it is seen by PI Server.
Starting / Stopping the Interface on Windows
This section describes starting and stopping the interface once it has been installed as a service. See the UniInt Interface User Manual to run the interface interactively.
[pic]
Starting Interface as a Service
If the interface was installed a service, it can be started from PI ICU, the services control panel or with the command:
PITraceRt.exe –start
To start the interface service with PI ICU, use the [pic] button on the PI ICU toolbar.
A message will inform the user of the status of the interface service. Even if the message indicates that the service has started successfully, double check through the Services control panel applet. Services may terminate immediately after startup for a variety of reasons, and one typical reason is that the service is not able to find the command-line parameters in the associated .bat file. Verify that the root name of the .bat file and the .exe file are the same, and that the .bat file and the .exe file are in the same directory. Further troubleshooting of services might require consulting the pipc.log file, Windows Event Viewer, or other sources of log messages. See the section “Appendix A: Error and Informational Messages,” for additional information.
Stopping Interface Running as a Service
If the interface was installed a service, it can be stopped at any time from PI ICU, the services control panel or with the command:
PITraceRt.exe –stop
The service can be removed by:
PITraceRt.exe –remove
To stop the interface service with PI ICU, use the [pic] button on the PI ICU toolbar.
Buffering
For complete information on buffering, please refer to the PI API Installation Instruction.
PI Interface Node buffering consists of a buffering process which runs continuously on the local node, a PI API library whose calls can send data to this buffering process, and a utility program for examining the state of buffering and controlling the buffering process.
Note: Change the Local Security Policy on Windows XP.
1. Open “Administrative Tools” from the control panel.
2. Open “Local Security Policy” from administrative tools.
3. Browse to “Security Options” under “Local Policies.”
4. Double click on “System Objects: Default owner for objects created by members of the Administrators group.”
5. Change the dropdown from “Object Creator” to “Administrators group.”
The behavior of Bufserv should now be the same on Windows XP as it was for Windows NT 4 and 2000.
If the PI buffer service is configured and running on the interface node, the PI Traceroute Interface will 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, the PI Traceroute Interface can be configured to 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 of three 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).
In the second mode of operation, the interface does not make any updates to the batch database and is configured by specifying the /nb command-line parameter.
In the third mode of operation, the interface does not update the batch database, but instead it maintains “active” tags to allow the PI Batch Generator interface to update batches and provide complete history recovery based on the active tags. This mode is configured by specifying both the /nb and /at command-line parameters. Please refer to the PI Batch Generator Interface User’s Manual for more details on batch recovery.
Configuring Buffering with PI ICU (Windows)
Buffering is enabled through the PI Interface Configuration Utility’s Tools>API Buffering… menu. Unless buffering is explicitly enabled, the PI API will not buffer data, sending data directly to the home node.
The API Buffering… dialog allows the user to view and configure the parameters associated with the PI API Buffering (bufserv) process. The user can start and stop the PI API Buffering process from the Service tab:
[pic]
Service Tab
The Service tab allows for some PI API Buffering service configuration. For further configuration changes, use the Services applet.
Service name
The Service name displays the name of the PI API Buffering Service.
Display name
The Display name displays the full name associated with the PI API Buffering service.
Log on as
Log on as indicates the Windows user account under which the PI API Buffering service is setup to start automatically on reboot, or manually.
Password
Password is the name of the password for the Windows user account entered in the Log on as: above.
Confirm password
Reenter the password to verify it has been typed correctly both times.
Dependencies
The Dependencies lists the Windows services on which the PI API Buffering service is dependent.
Dependent services
The Dependent services area lists the Windows services that depend on bufserv to function correctly.
Start / Stop Service
The Start / Stop buttons allow for the PI API Buffering service to be started and stopped. If the service is not created, this box will show Not Installed.
After a change is made to any of the settings on the Settings tab, the OK button must be clicked to save these settings, and then the service must be stopped and restarted for the changes to be picked up by bufserv.
Service Startup Type
The Startup Type indicates whether the PI API Buffering service is setup to start automatically on reboot or manually on reboot, or is disabled.
• If the Auto option is selected, the service will be installed to start automatically when the machine reboots.
• If the Manual option is selected, the interface service will not start on reboot, but will require someone to manually start the service.
• If the Disabled option is selected, the service will not start at all.
Generally, the PI API Buffering service is set to start automatically.
Create/Remove Service
The Create / Remove buttons allow for the creation or removal of the PI API Buffering service. Clicking the Create button will cause the service to be created using the Log on as and passwords given. Once the service is created the Start / Stop buttons will be activated.
Settings Tab
The Settings tab allows for configuration of the 7 configurable settings used by PI API Buffering. Default values are used if no other value is provided.
[pic]
Enable Buffering
Enable the PI API Buffering feature.
Maximum File Size
Maximum buffer file size in kilobytes before buffering fails and discards events. Default value is 100,000. Range is 1 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Send Rate
Send rate is the time to wait between sending up to MAXTRANSFEROBJS to the server (milliseconds). Default value is 100. Range is 0 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Primary Memory Buffer Size
Primary memory buffer size is the size in bytes of the Primary memory buffer. Default value is 32768. Range is 64 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Secondary Memory Buffer Size
Secondary memory buffer size is the size in bytes of the Secondary memory buffer. Default value is 32768. Range is 64 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Max Transfer Objects
Max transfer objects is the maximum number of events to send between each SENDRATE pause. Default value is 500. Range is 1 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Pause Rate
When buffers are empty the buffering process will wait for this number of seconds before attempting to send more data to the home node. Default value is 2. Range is 0 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Retry Rate
When the buffering process discovers the home node is unavailable it will wait this number of seconds before attempting to reconnect. Default value is 120. Range is 0 to 2,000,000.
The Use Default button places the default value into the text box. To keep this value, click the Apply button.
Max Theoretical Send Rate
This is the theoretical max send rate which is calculated like this:
max = MAXTRANSFEROBJS / SENDRATE * 1000
Default value is 5000. This value is automatically calculated for the user and can not be changed.
There are no additional steps needed to install buffering after installing the PI API. The delivered PI API library supports both buffered and un-buffered calls.
Configuring Buffering Manually
Buffering is enabled through the use of a configuration file, piclient.ini. Unless this file is modified to explicitly enable buffering, the PI API will not buffer data, sending data directly to the home node.
There are no additional steps needed to install buffering after installing the PI API. The delivered PI API library supports both buffered and un-buffered calls.
Note: When buffering is configured to be on, the bufserv process must be started before other programs using the PI API, so that these programs can access the shared buffering resources. Any program that makes a connection to a PI Server has this requirement even if it does not write to PI.
Configuration of buffering is achieved through entries in the piclient.ini file. The file is found in the .dat subdirectory of the PIHOME directory (typically c:\pipc\dat) under Windows. This file follows the conventions of Microsoft Windows initialization files with sections, keywords within sections, and values for keywords. All buffering settings are entered in a section called [APIBUFFER]. To modify settings, simply edit the piclient.ini file in a text editor (Notepad on Windows) to the desired values.
The following settings are available for buffering configuration:
|Keywords |Values |Default |Description |
|BUFFERING |0, 1 |0 |Turn off/on buffering. OFF = 0, ON = 1, |
|PAUSERATE |0 – 2,000,000 |2 |When buffers are empty the buffering process will |
| | | |wait for this long before attempting to send more |
| | | |data to the home node (seconds) |
|RETRYRATE |0 – 2,000,000 |120 |When the buffering process discovers the home node|
| | | |is unavailable it will wait this long before |
| | | |attempting to reconnect (seconds) |
|MAXFILESIZE |1 – 2,000,000 |100,000 |Maximum buffer file size before buffering fails |
| | | |and discards events. (Kbytes) |
|MAXTRANSFEROBJS |1 – 2,000,000 |500 |Maximum number of events to send between each |
| | | |SENDRATE pause. |
|BUF1SIZE |64 – 2,000,000 |32768 |Primary memory buffer size. (bytes) |
|BUF2SIZE |64 – 2,000,000 |32768 |Secondary memory buffer size. (bytes) |
|SENDRATE |0 – 2,000,000 |100 |The time to wait between sending up to |
| | | |MAXTRANSFEROBJS to the server (milliseconds) |
In addition to the [APIBUFFER] section, the [PISERVER] section may be used to define the default PI server and an optional time offset change that may occur between the client and server.
|Keywords |Values |Default |Description |
|PIHOMENODE |string |none |Windows default server is in pilogin.ini |
|DSTMISMATCH |0 – 2,000,000 |0 |The time that the server and client local time |
| | | |offset is allowed to jump. Typically, 3600 if the |
| | | |nodes are in time zones whose DST rules differ |
| | | |(seconds) |
Example piclient.ini File
On Windows, the default server information is stored in the pilogin.ini file so the piclient.ini would only have the [APIBUFFER] section. The BUFFERING=1 indicates that buffering is on. The MAXFILESIZE entry in Kbytes of 100000 allows up to 100 Megabytes of data storage. Do not use commas or other separators in the numeric entries. The retry rate is set to 600 seconds, meaning “Wait 10 minutes after losing a connection before retrying”.
On Windows a piclient.ini file might look like:
[APIBUFFER]
BUFFERING=1
MAXFILESIZE=100000
; The PI API connection routines have a 1 minute default timeout.
RETRYRATE=600
Appendix A:
Error and Informational Messages
A string NameID is pre-pended to error messages written to the message log. Name is a non-configurable 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 command-line.
Message Logs
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 retrieves points, messages are sent to the log if there are any problems with the configuration of the points.
• If the /db is used on the command-line, then various informational messages are written to the log file.
Messages
Below is a list of messages that are generated at the default debug level. Variables in the message are represented in italics.
"Error in icmp_traceroute2::NextState(): Could not recognize ICMP header type n."
Description: Generated during an ICMP traceroute when an ICMP packet is received with a header that is not consistent with a reply to a traceroute probe. n is the ICMP type specified by the header. In most cases the message is triggered by random ICMP junk picked up by the interface and can be safely ignored as the interface.
"Error in udp_traceroute2::NextState(): Could not recognize ICMP header type n."
Description: Same as above but generated by a UDP traceroute.
"Error in icmp_traceroute2::NextState(): Could not retrieve send time for seq num n"
Description: When a traceroute probe is sent into the network the current time is recorded in an array to compute latency when a reply to the probe is received. This error is generated if a reply to the probe is received but the corresponding entry in the array of send times cannot be found. This is a serious error and can indicate anything from memory to network corruption. n is the sequence number specified in the reply. In essence, this message indicates that the packet is a reply to the nth traceroute probe sent by the interface.
"Error in udp_traceroute2::NextState(): Could not retrieve send time for seq num n."
Description: Same as above but generated by a UDP traceroute.
"Error in udp_traceroute2::NextState(): Unacceptable packet."
Description: The reply packet received cannot be processed but in most cases the error can be ignored.
"Error in SendWorkerThreadPool::GetTask(): Hit max hop limit of n."
Description: The interface has a maximum number of hops it can record for individual traceroutes. This number is 30 by default but can be set higher or lower as necessary. If this message is a common occurrence specify a higher number of maximum hops with the /maxhops=n command line parameter.
"RecvWorkerThreadPool::TraverseWriteQ(): Failed."
Description: The interface failed to traverse the list of events that must be sent to PI. This is a generic error and can indicate a number of possible problems. It will most likely be followed by a more specific error. If not please contact OSIsoft technical support.
"Error in SendWorkerThreadPool::AddTask(): Failed."
Description: The interface failed to schedule a traceroute task. This is a serious error that most likely indicates an interface malfunction or bug. In the event that this error is encountered, please contact OSIsoft technical support.
"Error in setDevStruct(): scan class n rejected. The period must be greater than or equal to 20 seconds when the command-line parameter, /nsl, is not specified."
Description: A tag has been rejected because it uses a scan class with a period of less than twenty seconds and the command-line parameter, /nsl, has not been specified. n is the scan class in question.
"Error in validateTagParams(): get_scan_list_ex() returned NULL while validating tag str:n: for scan class m."
Description: The interface was not able to retrieve information for the scan class specified by the location4 attribute of the tag in question. This error indicates a serious problem with the interface. str is the tag name n is the point id and m is the scan class.
"Error in setDevStruct(): get_scan_list_ex() returned NULL while validating tag str:n: for scan class m."
Description: Same error message as above but generated by a different location of the program code.
"Send operation timed out while waiting for socket to be ready."
Description: The interface was not able to send a traceroute probe because the network resource was unavailable. This most likely indicates a network problem.
"Error in sendThreadProc(): While saving (sequence, time) pair."
Description: The interface was unable to save the probe sequence and the time the probe was sent (information used to calculate latency). This indicates a serious problem with the interface in the event that this error is encountered, please contact OSIsoft technical support.
"Error in initThreads(): RecvWorkerThreadPool() failed while allocating threadpool."
Description: The interface was not able to allocate resources for the thread pool responsible for processing replies to traceroute probes. This indicates a serious problem with the interface in the event that this error is encountered please contact OSIsoft technical support.
"Error in initThreads(): SendWorkerThreadPool() failed while allocating threadpool."
Description: The interface was not able to allocate resources for the thread pool responsible for generating traceroute probes. This indicates a serious problem with the interface in the event that this error is encountered please contact OSIsoft technical support.
"Error in initThreads(): _beginthreadex failed while initializing sendThreadProc: str"
Description: The interface could not allocate resources for the thread responsible for sending probes. This indicates a serious problem with the interface. str is a more specific error passed to the interface from the operating system. In the event that this error is encountered please contact OSIsoft technical support.
"Error in initThreads(): _beginthreadex failed while initializing recvThreadProc: str"
Description: The interface could not allocate resources for the thread responsible for receiving replies. This indicates a serious problem with the interface. str is a more specific error passed to the interface from the operating system. In the event that this error is encountered please contact OSIsoft technical support.
"Error in initOnDemandTracert(): dnsQuery(): Query to DNS server failed to resolve IP address to hostname."
Description: The interface could not resolve an IP address/host name supplied for an on-demand traceroute. This most likely indicates problems with the supplied IP address/host name, the network, or the destination machine. Use nslookup and tracert to troubleshoot the problem.
"Initializing on demand traceroute failed, exiting interface."
Description: The request for an on-demand traceroute failed. This is a generic error and by itself does not provide much information on the problem at hand. This error is usually preceded by a more specific one.
"Fatal error encountered while initializing network sockets."
Description: The interface was unable to initialize the network resources. This may indicate a network problem.
"Fatal error encountered while initializing interface threads."
Description: This is a generic message usually preceded by a more specific message indicating exactly which threads failed to initialize.
"Fatal error encountered while creating traceroute digital state set."
Description: The interface failed to create the digital state set required for the operation of its active tags. The name of this digital state set is TracertStatus. This can indicate a problem with the PI server. Use the digital state set editor in PI SMT3 to help troubleshoot this problem.
"Error in load_dev_structure(): update_group_list(): failed to update traceroute group list."
Description: This is a generic error that indicates a problem with a traceroute tag group. This error is typically followed by a more specific error that indicates what tag failed to pass validation and for what reason. Use the information provided by these more specific errors to double check the tag configuration of the traceroute tags.
"Error in load_dev_structure(): setDevStruct(): Failed setting developer structure for str (n); point REFUSED."
Description: This is a generic error that indicates a problem with the tag configuration. This error is typically preceded by a more specific message. str is the tag name and n is the point id.
"Error in load_dev_structure(): validateTagParams(): Failed to validate parameters for point: str (n); point REFUSED."
Description: This is a generic error that indicates a problem with the tag configuration. This error is typically preceded by a more specific message. str is the tag name and n is the point id.
"writeEvent(): Error allocating memory for new value for tag str (n)"
Description: This is a serious memory allocation error. The interface may need to be restarted. Make sure the system is not running out of memory resources. str is the tag name and n is the point id.
"Error in updateGroupList(): g_NT_TR_params.adddata(): n."
Description: The interface encountered a problem while creating a tag for a traceroute tag group. n is a pistatus error code.
"Error in updateGroupList(): g_NT_TR_params.get(): n."
Description: The interface could not retrieve tag information from one of its internal data structures. This indicates a serious problem with the interface. n is a pistatus error code. In the event that this error is encountered please contact OSIsoft technical support.
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 on Windows
On Windows and UNIX, descriptions of system and PI errors can be obtained with the pidiag utility:
Windows: \PI\adm\pidiag –e error_number
Appendix B:
Using PI BatchView to View Traceroute Data
OSIsoft, Inc. recommends the use of PI BatchView 3.0 or better to view data collected by the PI Traceroute Interface. BatchView allows users to view each traceroute executed by the PI Traceroute Interface as a PI Unit Batch. With PI Batchview, users can overlay the results of different traceroutes. This makes it easy to visually compare the results of different traceroutes which in turn makes it easy to spot problems. The user can also designate a traceroute that produces highly desirable results as the “golden batch” which can be used as a base of comparison for future traceroutes.
Below are two screenshots of PI Traceroute Interface data viewed with PI BatchView 3.0. Figure 1 is a screenshot of a single traceroute in BatchView. Notice how the bottom left hand quadrant of the BatchView display shows the Start and End time of the traceroute and under the product field the traceroute destination is displayed. The top right quadrant is the Batch Gantt chart. It shows the entire traceroute as a single cohesive unit. Below that is a trend that displays the batch data. If the cursor is dragged to the 4th unit on the X axis of the graph, the IP address of the hop, the latency associated with it, and the total time it took to complete the traceroute (see Fig. 2) are displayed. Finally, the PIUnitBatch Search at the top left allows the user to search for batches. Notice how all Unit Batch IDs start with “tr-.” The next set of digits up to the second “-” is the PointID of the traceroute base tag name. The last set of digits is the time the batch started in Coordinated Universal Time (UTC for Universal Time, Coordinated) which is the number of seconds since Jan 1, 1970.
[pic]
Fig 1.
[pic]
Fig. 2
Figure 3 is an example of overlaying two traceroutes from the same base tag. Overlaying the batches makes it easy to spot differences as well as similarities.
[pic]
Fig. 3
Appendix C:
Using PI Batch Generator to Create Traceroute Batches
With the help of the PI Batch Generator Configuration Plug-in for PI SMT3, configuring the PI Batch Generator to generate UnitBatches based on traceroute active tags is a relatively simple task. The PI Traceroute Interface requires the command line parameters /nb and /at be present so the PI Batch Generator can create Unit Batches for traceroutes. The /nb parameter ensures that the PI Traceroute Interface does not create its own Unit Batches that might conflict with the Unit Batches created by the PI Batch Generator Interface. The /at parameter instructs the interface to create and maintain active tags which signal when a traceroute starts and stops. If the interface is started with the /dct command line parameter, which instructs the interface not to automatically create tags, then the active tag must be created manually. The following attributes must be configured to create an active tag manually:
1. Tag – Must consist of the base tag name appended by “_detail_active”
2. PointType – Must be set to “digital”
3. DigitalSet – Must be set to “TracertStatus”
4. PointSource – Must be set to the PointSource specified by the /ps= argument in the interface startup command parameters.
5. Location1 – Must be set to the number specified by the /id= switch in the interface startup command parameters.
6. Location4 – Must be set to one of the scan classes specified by the /f= parameters in the interface startup command parameters.
The first step in configuring the PI Batch Generator to create Unit Batches for the PI Traceroute Interface is to start PI SMT3. Once SMT3 is started, connect to the server running PI Batch Generator and the PI Traceroute Interface by checking the box next to the server name under the PI Servers list. Then under “System Management Plug-ins” navigate to “Interfaces->Batch Generator Configuration”. If “Batch Generator Configuration” is not present then the PI Batch Generator Interface probably needs to be installed. Please refer to the PI Batch Generator Interface manual for information on how to install the PI Batch Generator Interface.
Once the PI Batch Generator Configuration Plug-in is started, select the MDB (Module Database) View tab. Now select a PI Unit that will be associated with the Unit Batches. Select an existing PI Unit (this could have been built by the PI Traceroute Interface) or create a new PI Unit. If the interface is started at least once without the /nb switch, the interface automatically creates a Unit for all base tags loaded by the interface. These PI Units adhere to a strict naming convention that consists of the characters “tr-“ concatenated with the point id of the base tag. A tag’s point id may be discerned by using a point editing tool like the PI SMT Tag Configurator or PI Datalink 3.x or better.
To manually create PI Units simply select the module in the Module Database, right click and select “Add New PIModule”. Name the module. Once it is created, right click on it and select “Convert to PIUnit”.
Highlight the selected PI Unit and then select the “PIUnitBatches” tab to the left of the MDB tree (Fig. 1). In the field labeled “Active Point” enter the full name of the active point or click on the button with ellipses “…” to search for the tag on the server (Fig. 2). Make sure that “step” is selected under “ActivePoint Behavior”. Save the changes by clicking the floppy disk icon on top of the MDB tree. Now, register the Unit by selecting the icon immediately to the right which looks like a reactor with a checked box. At this point if the PI Batch Generator is started then it will be generating Unit Batches for that traceroute.
[pic]
Fig. 1
[pic]
Fig. 2
The “PIUnitBatches” configuration tab offers other options for configuring the Unit Batch ID and Product Name. These tags can be defined to make the batch information stored more meaningful; however, the PI Traceroute Interface does not provide tags to generate this data. For more information on those options please refer to the PI Batch Generator documentation.
Revision History
|Date |Author |Comments |
|8-Mar-05 |DAmiri |First draft. |
|8-Sep-05 |DAmiri |Completed section on interface messages |
|21-Nov-05 |DAmiri |Several small fixes, added section on using PI Traceroute |
| | |Interface with PIbagen |
|29-Nov-05 |MKelly |Added screenshots for the ICU Section. Fixed the headers and |
| | |footers, updated TOC. |
|15-Feb-06 |Janelle |Version 1.0.0.0 Rev A: alphabetized the command line parameters |
| | |table, fixed headers and footers to correspond with correct |
| | |section names, updated the How to Contact Us page, and fixed |
| | |spelling and grammatical errors. |
|3-Mar-06 |DAmiri |Version 1.0.0.0 Rev B: made clarifications throughout the manual |
| | |for readability. |
|21-Mar-06 |MKelly |Version 1.0.0.0 Rev C: Fixed ICU control section description for |
| | |/dbg maximum value, the same was done for the command line |
| | |parameters section, the sample batch file and the errors and |
| | |information message section. Corrected part number in Support |
| | |Features table. |
|21-Mar-06 |Janelle |Version 1.0.0.0 Rev D: Updated manual to latest standards |
| | |(Security, Interface Node Clock, PI Point Configuration) |
|23-Mar-06 |MKelly |Version 1.0.0.0 Rev E: Made several formatting changes, corrected |
| | |spelling etc. |
|23-Mar-06 |Janelle |Version 1.0.0.0 Rev F: changed the sample point source from |
| | |reserved point source “g” to “TR”. |
|28-Aug-06 |Dario |Version 1.0.1.0 Rev A: first draft. |
|18-Jun-07 |PChow |Version 1.1.0.0 Rev A: Updated to skeleton 2.5.5. |
| | |Moved details in “History Recovery” to “Buffering” and clarified |
| | |the modes of operation. |
| | |Updated “Principles of Operation” to clarify the tags that can be |
| | |automatically created by the interface and to include a |
| | |description of the start and end strings for the routepoint tag. |
| | |Updated “On Demand Traceroute”. |
| | |Updated the introduction to “PI Point Configuration”. |
| | |Updated the description of “Tag”, “Location2”, “Location3”, |
| | |“Location4”, “Location5” and “InstrumentTag”. |
| | |Updated the description of “ExDesc” to include trigger based |
| | |inputs and new keywords. |
| | |Updated “Performance Point Configuration” to state the interface |
| | |does not support performance points. |
| | |Clarified the definition of default values in “Command-line |
| | |Parameters” and added new parameters. |
| | |Removed non-third person references. |
|31-Jul-07 |Janelle |Version 1.1.0.0, Revision B: updated hardware diagram, updated ICU|
| | |control screen shots |
|3-Aug-2007 |MKelly |Version 1.1.0.0, Revision C: Resized screenshots to fit within |
| | |margins also update several other ICU screenshots. Updated the |
| | |Table of Contents. |
-----------------------
Service installed or uninstalled
Status of the Interface Service
Status of the ICU
................
................
In order to avoid copyright disputes, this page is only a partial summary.
To fulfill the demand for quickly locating and searching documents.
It is intelligent file search solution for home and business.
Related searches
- why the school system is bad
- is the education system broken
- the school system is broken
- the education system is failing
- why the education system is good
- changing the school system essay
- the college system is broken
- calculator with the pi button
- how to cleanse the lymphatic system naturally
- the planets of the solar system song
- the organs in the circulatory system include
- label the conduction system of the heart