Install instructions for the NPAD pathdiag server
Version 1.5.3.
Prerequisites:
1. A fairly fast, preferably Gigabit-attached *Linux* server.
2. A working development environment including a C compiler and a
recent version of Python.
3. 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 )
4. 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/networking/projects/tcptune/).
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.
Much of these instructions can be cut and pasted into a bash shell.
The current source setup is as follows:
npad-1.5.3/ - Configuration and common resources
napd-1.5.3/pathdiag/ - The pathdiag tool
npad-1.5.3/diag_server/ - The diagnostic client/server framework
1. 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
2. Unpack the source:
tar xzvf npad-1.5.3.tar.gz
cd npad-1.5.3
3. Copy over your old config
A. 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.
B. 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.
4. 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.
5. 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.
You must get the libraries and library paths (e.g. LD_LIBRARY_PATH) set
up correctly first.
It has been observed that incompatible version of swig sometimes cause
late run-time errors. If --help works but step 9 reports other errors,
look at the swig versions in the Makefile.
6. 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.
7. 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
9. 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 field-s 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.
11. 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.
12. Please drop us a note at nettune@psc.edu, so we know that the server is up
and running.