NPAD/pathdiag Installation Instructions

Installation instructions for the NPAD pathdiag server

Version 1.5.6

Prerequisites

A fairly fast, preferably Gigabit-attached *Linux* server.
A working development environment including a C compiler and a recent version of Python.
If you want plots of the test data (strongly recommended), you need to install gnuplot and the python-gnuplot library.
(e.g.: apt-get install gnuplot python-gnuplot )
Web100 must be installed and properly tuned.
- The Web100 kernel patch version must be 2.5.5 or later (Linux 2.6.13 or later).
- The Web100 userland must be 1.5 or later.
- BIC and other experimental congestion control must be off
  (echo reno > /proc/sys/net/ipv4/tcp_congestion_control).
- Sufficient TCP buffer space for the largest pipe you want to test
  (see http://www.psc.edu/index.php/tcp-performance-tuning).
If things go wrong, see PROBLEMS below.

To tell if Web100 has been properly set up, run this script:
```
python -c "import Web100; Web100.Web100Agent(); print('Success.')"
```
If this does not print “Success.” then the NPAD tools WILL NOT WORK. You must get Web100 set up correctly first.

Instructions

Much of these instructions can be cut and pasted into a bash shell.

The current source setup is as follows:

npad-1.5.6/               - Configuration and common resources napd-1.5.6/pathdiag/      - The pathdiag tool npad-1.5.6/diag_server/   - The diagnostic client/server framework

Pick a location to manage the sources. This will be the parent of the build dir, such that future release will just “drop in”.
```
SRC=/usr/src cd $SRC
```

Unpack the source:

tar xzvf npad-1.5.6.tar.gz cd npad-1.5.6

Copy over your old config
NB: When upgrading from an older version, check RELEASENOTES.txt for specific information about any compatibility issues.
1. If you have a previously set up installation (or if you are upgrading from a previous version), you may want to copy your custom configuration. Copy config.xml from the previously installed location (by default, this will be in $SRC/npad-dist//), or from the previous source tree, to your current build directory.
2. If you have a site-customized server form (e.g. a modified template_diag_form.html), copy this file to your current build directory, though if you are upgrading, be sure to check for changes in our most recent template_diag_form.html you may want to merge.
  If you do not have a customized form, you can create one by editing template_diag_form.html in place. Certain critical sections are included with %%keyword%% directives processed by the config script. You should keep all of these in place somewhere within the file, probably in their default order. Most customizations should be to the “look and feel” of the page.
  
  The form should work as-is for most installations.
Run the config script
```
./config.py
```
You will be prompted with on-line help for each config option. If you have already run config.py and would like to change your configuration, run
```
./config.py -p 
```
Build:
```
make
```
You can confirm that the libraries are correctly installed and searched by displaying the help:
```
./pathdiag/pathdiag.py --help 
```
If this does not display pathdiag help the NPAD tools WILL NOT WORK. See BUILD PROBLEMS below.
Install:
```
make install 
```
Depending on the permissions for your installation directories, you may need to become root before running make install.

Note that the server will not run in the source area, you must do an install to properly assemble all of the components. You can run the server as yourself (it does not require root) if appropriately configured.
Start the server by hand. This can be done by running DiagServer.py in your chosen installation directory. By default:
```
$SRC/npad-dist/DiagServer.py 
```
Run tests.
Run a web browser on a machine that you want to test, and browse to the NPAD welcome page. Scroll down to the “The Test Form” section. It should have 2 fields labeled “Target RTT” and “Target rate”. Fill in the fields and click “Start test”. A log window will appear showing some log messages while the test runs. When it completes, another browser window will appear showing the test results. The results are saved in an HTML file on the server.

Hint: if something goes wrong with the tester, it is easier to use the command line client to capture output for debugging.
Set up the server to start at boot time.
There is a Sys V init script provided (‘npad’ in your build directory). On Sys V systems (most Linux distributions), you should be able to copy this to /etc/init.d/npad, and start the service with:
```
/etc/init.d/npad start
```
and set it up to automatically start/stop with your distribution’s init script management tools.

If this script does not work with your Linux distribution, you will need to determine the best way to start and stop the service, perhaps by creating your init script.
Please drop us a note at nettune@psc.edu, so we know that the server is up and running.

PROBLEMS

Build Problems

If pathdiag -help does not generate a usage message, it is failing to find all of the necessary libraries. This probably means that the system dynamic loader is not searching the default locations for user added libraries, such as web100. The easiest fix is to add the following to your login rc file (e.g. to .bashrc):

export LD_LIBRARY_PATH=/usr/local/lib

Problems on the “Run test” step

If the web applet showed no useful output (but -help worked) then try running the “c” command line version.

In either case if output includes messages something like:

Web100 setup error a 'web100_group *' is expected,                 'PySwigObject(xxxxxxx)' is received C/C++ variable 'gread'

Then the precompiled swig output included with the pathdiag sources is incompatible with the python run time on your system. There are 2 possible solutions:

Edit napd-1.5.6/pathdiag/Makefile to select a different SAVESWIG version, and start over with the build step.
Manually install swig on your system, then “make clean; make makeswig” in napd-1.5.6/pathdiag/Makefile, and start over with the build step.