This file describes the installation procedure of a network test monitor from
the RTPL network performance package. See the file
readme.html for a description of this
package, for the required software, and for the sub items contained in the
installation directory. The section
"Online Documentation" in the
readme.html file gives an overview of the
available online documentation.
The control part of this package is only available for Unix. However, there also
is a Windows client version available. See the
"Supported Platforms" section in
the readme.html file for more
information. The installation of the Windows client version is described in the
"Installation Windows Client" section at
the end of this file.
this font is used.both fonts are also used
correspondingly.
To be able to install this package the gzip compressed
tar archive should be unpacked in an arbitrary installation
directory using for instance the following command line:
% gunzip -c RTPL-Version.tar.gz | tar xfv -
Please note that the installation directory
InstallRoot/RTPL-Version will not be
used by the installed package.
Basicly the steps described below are required to install the RTPL package. In the section "Installation in Detail" these installation steps are explained in more detail. The step number hyperlinks are referring to the section "Installation in Detail" and vice versa.
| 1. | Let the client test hosts, where the network performance tests should be
performed, allow remote or secure shells from the control host without the
need to specify a password.
Alternatively the |
||||
| 2. | Install the
Netperf
package at the client test hosts for the throughput tests when it is not
yet available. Use a relative path for the log file. See also the
readme.html file. |
||||
| 3. | Optionally install the UDP bandwidth monitor from the UDPmon package. The usage of this package can be selected during the configuration in step 4. | ||||
| 4. | Run the setup script contained in the installation directory to
install this package at the control host. You are requested to supply the
appropriate parameters. The first parameter is the name of the used hosts
configuration: HostsConfig. |
||||
| 5. | Run the make_archive script, contained in the installation
directory, to make a gzip compressed tar archive
named RTPL-Version.tar.gz within the installation
directory. This archive also contains the configuration you defined in
step 4 with the setup
script. |
||||
| 6. | Copy the archive created in step 5 to each of the client test hosts to an arbitrary installation directory and unpack it. | ||||
| 7. | Run the client_setup script at each of the client test hosts.
You are requested to supply the appropriate parameters. As configuration
name you should specify the same name of the hosts configuration as
specified in step 4:
HostsConfig.
When the Net Test Server / Client is used,
take care that the |
||||
| 8. | Check the correct functioning of the script which performs the measurements
at the control host by typing the following command lines at the control
hosts in a shell where X Windows client displays are allowed:
with:
If no X displays are allowed you should type these commands in two separate terminal (emulator) sessions. |
||||
| 9. | Let crontab starts periodically the net performance tests by
typing the following command line:
% crontab RTPLRoot/crontab/crontab_input_HostsExt
|
||||
| 10. | The Web presentation of the results is now available in the URL:
file:RTPLRoot/html/HostsBaseDir/table/net_data.html
|
||||
That is all to install the setup for a particular hosts configuration. Please note that the installation at the client hosts (step 5 - 7) is only required when the package was not yet installed at that host, so there is no need for re-installation at the clients when you want to change some configuration parameters.
See also the section "Defining the User Environment" how to setup the user environment and the section "Online Documentation" where to obtain information a.o. about the Web presentation of the results.
The steps described below are required to install the RTPL package. See also the section "Installation in Short" for a more basic description. The step number hyperlinks are referring to the section "Installation in Short" and vice versa.
| 1. | To be able to start the net performance tests at the client test hosts by
means of a remote or secure shell from the control host, it is required that
these shells could be started without any user-interaction. That is: without
the need to specify a password
Below the steps required to use remote or secure shells without password
specification are explained for some commonly used shells. Please note that
in all cases the system management should allow this usage. More information
you can find in the corresponding
Alternatively, in the place of a remote or secure shell the
|
||||
| 2. | Install the
Netperf
package at each of the client test hosts when it is not yet installed. This
tool is used to execute the throughput measurements. Use a relative path for
the log file. See also the
readme.html file.
After installation the
Netperf
directory should be added to the |
||||
| 3. | Optionally install the UDP bandwidth monitor from the
UDPmon package written by
R.E. Hughes-Jones, the University of Manchester. 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
PATH environment variable.
The UDPmon package is only available for Pentium processors running Linux. Therefore, the usage of this package can be selected during the configuration in step 4. |
||||
| 4. | Run the Perl setup script contained in the installation
directory to install this package at the control host. It is assumed here
that the Perl path /usr/bin/perl exists. When this is not the
case you should start the script using perl setup. When
this script is started a help message is given in the pager of your system.
See this help message for a description of the special characters which can
be used. You can suppress the listing of the help message by starting the
installation script with setup -n. See the section
"Setup Scripts" for more information
about this script.
When your system management installed one of the available
Perl You are requested to supply the appropriate parameters. The first parameter you should supply is the name of the used hosts configuration you want to install. In the sequel we will denote this with the variable name HostsConfig. You can supply a new hosts configurations or edit an existing one. In the first situation you have to supply all parameters. In the second situation you can supply only the parameters you want to change and to skip the other parameters. Some parameters have a default answer; others you have to specify explicitly. To make the selection of parameters to skip more easy, the remaining parameters are divided in several, so called, parameter groups: when all parameters in a group are defined you are allowed to skip this group and go to the next one. If not you are requested to specify the undefined parameter(s). Below the available parameter groups are listed. When required some remarks about a parameter from the group are made. More information can always be obtained interactively. The groups are:
After all parameters are specified, a configuration file entitled
Hereafter the configuration is build using the |
||||
| 5. | Run the make_archive script contained in this directory to make
a gzip compresses tar archive named
RTPL-Version.tar.gz within the installation
directory. This archive also contains the configuration you defined in
step 4 with the setup script.
Therefore it is required to recreate an installation archive. |
||||
| 6. | Copy the archive created in step 5 to each of the client test hosts to an arbitrary installation directory and unpack it. | ||||
| 7. | Run the client_setup script at each of the client test hosts
which is also situated in the installation directory. You are requested to
specify the following parameters:
See the section "Setup Scripts" for more information about the setup scripts.
When the |
||||
| 8. | Check the correct functioning of the script which performs the measurements
at the control host by typing the following command lines at the control
host in a shell where X Windows client displays are allowed:
with:
The first script follows the growing of the log file in a new XTerm terminal
emulator. When selected
If no X displays are allowed you should type these commands in two separate terminal (emulator) sessions. Before running these commands it is a good idea to check if the remote or secure shells from the control host to the client test hosts are functioning properly. |
||||
| 9. | Let crontab starts periodically the net performance tests by
typing the following command line:
% crontab RTPLRoot/crontab/crontab_input_HostsExt
When you are already using a
It is not such a good idea to change the measurement period by editing the
|
||||
| 10. | The Web presentation of the results is now available in
file:RTPLRoot/html/HostsBaseDir/table/net_data.html
A Web server may be used to view the data remotely. See the section "Access from a Web Server" for more information. See also the section "Online Documentation" where to obtain information a.o. about the Web presentation of the results. | ||||
For a correct functioning of the test scripts, both at the control host and at
the client test hosts it is required that the user environment should be defined
correctly. One should realise that the shells started by crontab at
the control host and by the remote or secure shells at the client test hosts are
no login shells. Therefore, the usual login startup files are not read
by these shells. This implies that your environment should be defined in
$HOME/.cshrc for the (t)csh shell or in
$HOME/.bashrc for the bash shell. When this situation
should conflict too much with your current environment, please consider to
create separate test users at the control and client hosts. When possible, this
always is a good strategy.
Below we will treat the situation at the control host and at the client hosts in
more detail. There also is explained what to do when your shell does not possess
startup files such as sh and ksh.
RTPLRoot/bin
should be added to the PATH environment variable.
At the control host crontab is used to start the script which
starts the tests at the client test hosts and which stores the results. At
all systems crontab is using /bin/sh to spawn
programs, so in principle no shell startup resource files are read here at
all!
However, the measurement script is a csh script. This implies
for users with a (t)csh login shell that
$HOME/.cshrc is automaticly read and the environment is defined
properly.
Bash users my change the line in the crontab file
such that a bash shell is forced to be used and
$HOME/.bashrc will be read:
0[,30] * * * * bash -c RTPLRoot/bin/net_test_local RTPLRoot/log/net_test_local.cron 2>&1
Users with other shells can do the same trick. However, in the place of
bash they can also use csh
(... csh -c ...), but they should also create
the proper startup file: $HOME/.bashrc or
$HOME/.cshrc.
RTPLRoot/bin should be added to the
PATH environment variable.
Here a remote or secure shell is used to run the measurement script. Your
usual login shell is used, but not as login shell. For
(t)csh (bash) users a proper creation
of the startup files $HOME/.cshrc ($HOME/.bashrc)
is sufficient.
Users of other shells should force a usage of the csh
(alternatively bash) shell for the
(Perl) scripts
start_netserver and host_net_test which are used
at the client hosts by specifying the following commands (alternatively you
can place them in a shell script):
% cd RTPLRoot/bin | ||
% mv start_netserver start_netserver.perl |
||
% mv host_net_test host_net_test.perl |
||
% echo '#! /bin/csh' |
> |
start_net_server |
% echo '' |
>> |
start_net_server |
% echo 'exec start_netserver.perl $*' |
>> |
start_net_server |
% echo '#! /bin/csh' |
> |
host_net_test |
% echo '' |
>> |
host_net_test |
% echo 'exec host_net_test.perl $*' |
>> |
host_net_test |
% chmod +x start_net_server host_net_test |
||
When desired /bin/csh may be replaced by /bin/bash
or /usr/local/bin/bash, depending from your Unix flavour when
you want to use a bash startup script.
After a re-installation of the package at the client hosts you will have to repeat these commands.
When the HTML pages of the package should be accessible from a Web server, a
symbolic link from the root directory of the HTML files,
RTPLRoot/html, or from one of its sub directories, to a
directory accessible from a Web server has to be created with for instance the
following command line:
% ln -s RTPLRoot/html $HOME/public_html/rtpl
Please note that the Web server should be configured such that access with a
symbolic link is allowed. For the
Apache Web server this implies that in the
configuration file access.conf the Options directive
should contain the option FollowSymLinks for the home
directory tree. Consult the Apache documentation for more information.
No Web server dependent functionality, like for instance CGI-Bin
programs, is used. Therefore the Web oriented part of the package is
transparent for access from a Web server or from a file system.
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:
There are also man pages available for the scripts from this package.
At each client host the resource file $HOME/.host_net_test_rsc can
be used for specific options for the client network performance measurement
script host_net_test. For instance this possibility is used by the
client setup script client_setup to use the
Nikhef ping program
specific for that client.
In this section the setup script which is used to install the
package for a hosts configuration at the control host and the
client_setup script which is used to install the package at the
client test hosts are treated here in more detail.
Both scripts are prompting you to answer some questions. When your system
management installed one of the available
Perl Term::ReadLine packages you
can use line editing in the same way as you are used to do in your shell or
MS-DOS prompt.
The scripts are requesting you for some parameters to supply. When a script is
opened a help message is displayed using the pager specified in the
PAGER environment variable. The more pager is used
when it is undefined. When the Standard Output is not a Terminal TYpe no pager
is used, but the help message is printed to Standard Output and the setup will
be exited when the help message is printed. This makes it possible for instance
to store the help message to file or to print it.
When a default answer exists for a particular question it will be listed at the end of the question between square brackets "[...]". If you supply an empty answer, or an answer which contains only white spaces when a default answer is available, the default answer will be used and the prompt "Using default: Answer" is listed. When there is no default answer available the question is repeated until you did specify a non-empty answer.
The setup scripts contain the following types of questions:
y'
and 'n' or a
navigation character. A default value is always
available.
setup script). In general
several parameters have to be specified for each array element. Default
values may be defined. In contradiction to the previous types there are
sometimes empty arrays allowed here. Also the usual
navigation characters are allowed to which some
extra parameters are add to: select, add, delete
or edit elements from the array of parameters.
In the setup scripts it always is allowed to go to the previous question. An already given answer will be stored and will be used as default answer when this question is reentered again. It also is allowed to go to the next answer, but only when a default answer exists. In that case this answer will be used.
In the setup script named setup the parameters are divided in
several so called parameter groups. When you want to change an existing
configuration this makes it more easier to skip parameters you do not want to
change. Equivalently to the previous paragraph you always can go to the previous
group. However, you can only go to the next group when all parameters in the
group are defined. When there are undefined parameters when you want to go to
the next group you are left at the first undefined parameter to specify a value
for it after a diagnostic message is printed which parameter is still undefined.
During the specification of the parameters in a group you are also allowed to go
one level up, but again only when all parameters are defined. Otherwise you are
left again by the undefined parameter.
'?' |
: | Print help information about the current directive (group). | |
'?p' |
: | Display the help with the default pager. | |
'=' |
: | List the current directive value or the current directive values within a group. | |
'=p' |
: | List the directive value(s) with the default pager. | |
'!' |
: | Run the system command following this character. | |
'<' |
: | Go to the previous directive (group). | |
'>' |
: | Go to the next directive at the directive level when the previous and the current directives are defined. Go to the next group at the group level when all directives within the group are defined. | |
'^' |
: | Go to the directive group level but only when all directives within the group are defined. | |
Additionally for parameter arrays there are the special characters listed below to select, add, delete or edit elements from the array of parameters. The variable I = 1, ..., denotes an index from an element from the array of parameters.
':Ia' |
: | Add new parameters after index I. | |
':Ii' |
: | Insert new parameters before I. | |
':Ie' |
: | Specify the parameters of I. | |
':Id' |
: | Delete the parameters of I. | |
':Ib,Ied' |
: | Delete the parameters from Ib to and including Ie. | |
':q' |
: | Quit the addition of parameters. | |
In all situations when Control-D is pressed the setup will exit.
After the parameters are specified you are confirmed to build the configuration at the control or client host. If you does not confirm this question you again requested to specify the configuration directives.
It is also possible to install the package without using the setup scripts. In
that case you have to edit the configuration files by hand. After that the
make program should be run to install the package. The advantage is
that there are some additional features available, which cannot be used from the
setup scripts. However, these features are seldom needed. See the comment
headers in configuration file template config/config.mk for a
description of all possible features. Running make by hand also
allows more targets than by using the setup scripts. See the comment header from
the Makefile in the installation directory for a description of all
possible targets.
Below we will give a short description of the installation procedure
for a hosts configuration
| 1. | Allow remote shells from the control host at the client test hosts as described above. | ||
| 2. | Install the Netperf package at the client test hosts as described above. | ||
| 3. | Copy the configuration template config/config.mk to the
configuration file for the corresponding hosts set, when non-existing
and edit the hosts set configuration file to define the required
|
||
| 4. | Install the package for the hosts set at the control host by typing
The possible targets are described in the comment header of the
|
||
| 5. | Make a gzip compressed tar archive named
RTPL-Version.tar.gz, which also contains the hosts
set configuration file, within this installation directory by specifying the
command line:
% make tar_gzip_archive
|
||
| 6. | Copy the new archive to the client hosts. | ||
| 7. | Install the package at each of the client hosts by running
% make client
|
||
| 8. | When required set client specific options in
$HOME/.host_net_test_rsc, for instance to use the
Nikhef ping program. See
man host_net_test for the corresponding option. |
||
| 9. | Check the correct functioning of the script and start the
crontab job as described above. |
||
In general the net performance commands are started at the client test hosts by the control host using a remote or secure shell command. Alternatively, it is also possible to use a server / client combination, provided by this package. In fact, for Windows clients this is the only possibility. See also the section "Installation Windows Client". Two Perl scripts are provided here:
net_test_com_server
However at the Windows platform, it is for
Perl more difficult to start a separate
process (only an experimental fork() emulator is available),
while for all platforms the thread support at
Perl is not very good. This implies that
the net_test_com_server server at the Windows platform is
always a single process. This makes the block chance somewhat larger during
poor network connections.
Because this script should run under Unix and all Windows platforms, no user authentication is implemented, but only host access limitation: the access to this script can be limited to one or more control hosts, when desired. See also below in this section. This server only allows the execution of the net performance scripts residing in the same directory as this server script.
rem_net_test_com
When these server / client scripts are used, it is required that
periodically there is checked if the net_test_com_server at a
client is running. It should be started when this is not the case. At Unix
platforms the script start_net_test_com_server can be used to
perform these periodic checks, for instance with a crontab job.
Suppose that the network performance tests are started each hour by the control
script. When all participating hosts have synchronised clocks (NTP), a crontab
job at a client host could look like:
59 * * * * RTPLRoot/bin/start_net_test_com_server >RTPLRoot/log/start_net_test_com_server.cron 2>&1So, just before the net performance tests are executed, there is checked at the client test host if the server is running.
Copy also the file
RTPLRoot/lib/sample-net_test_com_server.conf to the
configuration file RTPLRoot/lib/net_test_com_server.conf
and set the allow_host directive to the control host to limit the
access only from this host.
The Windows client can be installed with the following steps:
win_client.zip at the location where you would like to install
this package. At that position a folder win_client will be
created.
win_client\lib\sample-net_test_com_server.conf
to the configuration file
win_client\lib\net_test_com_server.conf
and substitute the local hostname and IP address, specified in the
allow_host directives by the hostname and IP address of the
control host. In this way access to the
Perl server will be limited to the control
host.
Standard Output and Error will be send to the log file:
win_client\log\net_test_com_server
Win_Clien\bin folder at the client host with the command line:
perl net_test_com_server.pl -config_file ..\lib\net_test_com_server.conf
You may specify some more options or configuration directives. Type
perl net_test_com_server.pl -help for a usage message.
netserver command when it is finished from the
Win_Clien\bin folder with the command line:
perl loop_test_netserver.pl
You may specify some options and also a configuration file. Type
perl loop_test_netserver.pl -help for a usage message.
At Windows NT, the scripts started at
steps 3.
and 4. can also be run as system server,
using the SRVANY package, available from the
Windows NT Resource Kit.
If you encounter any problems, please contact me.
| Hans Blom |
| jblom@science.uva.nl |