README rTPL Package

• Description
• Installation
• Supported Platforms
• Required Software
• Optional Software for Unix
• Other Requirements
• Online Documentation
• Sub Items of the Installation Directory
• Contact

The RTPL package (Remote Throughput, Ping Load) performs periodical network performance measurements tests between a set of workstations to view the network from a user's perspective. The performance measurements consist of round-trip and throughput measurements between a number of hosts. Optionally also UDP bandwidth kind of tests can be performed with the UDPmon package (Linux at Pentium processors only). By default all pairs in the hosts set are used, but it is also possible to skip host pairs from the tests. Also, the machine load of the participating workstations is measured. In this way performance loss can be related to heavy machine load. A remote or secure shell command is used to start the network performance measurements from a, so called, control host at each client or test host of the set. At the control host a Web based presentation of the results will be given.

The presentation of the results is Web based and dynamic: the net performance data are stored in ZIP compressed plain text files, which are accessible from a Web server. There are various files such that a user can be offered several views of the data, including several time based averages. The file data are read into the Web browser by a Java Applet. The HTML scripting language JavaScript is used to display the data in various tables. The Applet can also be used to present the data in plot form.

See the install.html file for installation instructions. There are interactive scripts for the setups at the control host and at the client hosts to guide you through the specification of the installation parameters.

The control host version of the RTPL package is only available for Unix platforms. However, the client side of the package is available for both Unix and Windows platforms. At Unix hosts, normally a secure or remote shell will be used to start from the control host the net performance tests at the client hosts. For Windows hosts a special Perl server / client combination is provided to start the net performance tests at the clients (there are secure or remote shell implementations available for Windows, but they are not very commonly used). Here the server part is running at the client hosts. It is waiting for requests from the client process, which is running at the control host, to start the net performance measurements. This server / client is also available for Unix hosts. At the Unix platform also a script has been add which checks if the server is running. It starts a server when this is not the case. Therefore, this script is suitable to be run from crontab.

At the Windows clients two servers should be run:

1. A server which executes the net performance measurements.
2. A server which restarts the netserver program when it did finish a throughput measurement. At the Windows platform no netserver process could be forked to start an independent process to handle a request to receive the generated traffic.

At Windows NT the SRVANY, available from the Windows NT Resource Kit, can be used to start both servers at system startup.

The threading support at Perl is not very good at the moment. However, for coming versions it is promised to be improved. Also the API will be changed. This implies that both servers are running now under Windows without Thread support. This makes them a bit sensitive to blocking during network problems.

Please note that the server, mentioned at point 1., uses at Unix fork() calls to treat the requests for performance tests at a client. Therefore, it is insensitive for network difficulties. The second server is not needed under Unix, because the netserver daemon already uses fork() calls to handle the net performance tests.

The following software packages should be installed:

• Perl 5.
• At the control host the Info-ZIP compress package should be installed.
• At the client hosts the Netperf tool should be installed. It is used to measure the throughput. See the download site for installation instructions. Note that the directory where the package is installed should be available from the PATH environment variable.

  One remark has to be made about the Netperf installation: the server program, netserver, uses a log or debug file. It is defined in the makefile of the installation by the LOG_FILE make variable. The default value of the log file is /tmp/netperf.debug. However, to make the netserver program accessible for more users at the same time it is better to use a relative path, for instance netperf.debug. The scripts from this package take care that the netserver program is started in an unique, hidden directory below the users home directory.

Optionally the following software can also be used:

• When desired the Nikhef variant of the ping program can be used in the place of the usual, system ping program. It should be installed in /usr/local/etc/ping which is the default installation path. The client setup script will ask you what ping program have to be used.
• For Pentium processors running Linux, the UDP bandwidth monitor from the UDPmon package, written by R.E. Hughes-Jones, the University of Manchester, can also be used. See the build instructions in the distribution. From this package the udp_bw_resp and udp_bw_mon programs should be installed at the client hosts. They should be available from the PATH environment variable.
• The multi-file monitor tool xtail can be installed to monitor the log files of the package at the control host. During the installation of the package at the control host xtail is automatically used when it can be reached from the PATH environment variable.

The requirements, listed below, should also be fulfilled to be able to run the package. In general the Unix platform is intended, when not explicitly mentioned.

• At the client hosts a "normal" user is sufficient and recommended to do the tests. It should be possible to start from the control host remote or secure shells for this user without interactive intervention, that is specification of a password. Alternatively the server&nbs;/ client, contained in this package, can be used. This is required for Windows. A tcsh or csh login shell for this user is preferable. In that case the definition of the user environment is easiest.
• To start the net performance tests periodically from the control host the test user should be allowed to run crontab jobs from that control host.
• At the control host a Web server can be used for the presentation of the results to the Web. In that case you should create a symbolic link somewhere from your public_html directory tree (or from somewhere else in the public HTML directories) to the html sub directory of the installed package root. Please note that the supplying or configuration of a Web server is not a part of the package installation procedure, because this package does not need server critical settings. We personally have good experiences with the Apache Web server in an Unix environment.

However, there are no limitations to use the browser oriented presentation of the results also at the file system of the control host. The HTML pages where the data are presented are transparent for Web server or file system presentation: no special services from the Web server are required.

In the distribution root, and / or from the installed hosts set, a.o. the following online documentation is available:

• The package manual.
  This manual contains more detailed information about this package.
• When you open the Web presentation of the network performance results for the first time an overview page is presented that gives an overview of the load, round-trip and throughput for all hosts at the last measurement time. This page contains at the top the following hyperlinks to HTML documentation:

  • "getting started"
    This document describes the main features a user may wish to know to become acquainted with this package.
  • "user guide"
    This document describes the currently displayed table.

• There are also man pages available for the scripts from this package.

Below a short description is given of the sub directories and files from this installation directory. During the installation most of these items will be copied to the appropriate destinations below the installed package root directory, where the appropriate setup parameters will be substituted in the installed package files.

• bin
  This directory contains the scripts which will be used at the network performance tests. Also some additional help scripts are found here.
• config
  This directory contains the make configuration files. Each file contains the configuration for a particular host setup. See the install.html file for more information.
• Crontab
  This directory contains the crontab file which will be used to start the network performance tests periodically. More information is given in the install.html file.
• html
  When installed this directory will be the root of the Web accessible HTML files and network performance result data files.
• INSTALL
  The installation help file.
• java
  The Java source, class files and Java Archive (JAR) file of the Applet. Only the JAR file will be copied to the installed HTML directory.
• log
  When installed this directory will contain the log files of the network performance test scripts.
• Makefile
  The make file which is used during the installation of the package for a particular hosts set.
• man
  This directory contains the man pages of the test scripts to install.
• my_html
  In this directory you can put HTML directory trees, describing the available sets of hosts. See the install.html file for more information.
• README
  The plain text version of this file.
• VERSIONS
  This file describes the main differences between the various versions.
• win_client
  This directory contains the Windows Client version from the package.
• clean_setup
  This setup script can be used to remove the directories and files from a particular hosts set from the installed package. More information is given in the install.html file.
• client_setup
  This setup script can be used to install this package for a particular hosts set at a client host. See the install.html file for more information.
• import_readme
  This is the README file for the installed Import package directory, where a download version of the Web files from this package for local, off-line usage can be found.
• make_archive
  This script makes a gzip compressed tar archive of the current installation directory which is also stored into this installation directory. The goal of this script is to expand the configuration settings which are required by the client test hosts to these hosts.
• root_readme
  This is the README file for the installed root package directory.
• setup
  This setup script can be used to install this package for a particular hosts set at the control host. More information is given in the install.html file.