NetPIPE Network Protocol Independent Performance Evaluator, Java Version 1.0
Copyright 1997, 1998 Iowa State University Research Foundation, Inc.

$Id: README,v 1.4 1998/10/28 14:51:28 ghelmer Exp $

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation.  You should have received a copy of the
GNU General Public License along with this program; if not, write to the
Free Software Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

Getting NetPIPE
---------------

The NetPIPE implementation in Java can be found at:

ftp://ftp.scl.ameslab.gov/pub/netpipe-Java-1.0.tar.gz

The source code for NetPIPE 1.0 is provided as a gzipped tar archive,
which can be uncompressed with "gunzip netpipe-Java-1.0.tar.gz"
(or "gzip -d netpipe-1.0.tar.gz"), and then extracted from the
uncompressed archive with the command "tar xvf netpipe-1.0.tar".
If you do not have the gzip program, it can be obtained as:

ftp://prep.ai.mit.edu/pub/gnu/gzip-1.2.4.tar

Similarly, the NetPIPE implementation in C can be found at:

ftp://ftp.scl.ameslab.gov/pub/netpipe/netpipe-2.3.tar.gz

The instructions that follow apply to the Java implementation of
NetPIPE.  Due to differences in the protocol, the TCP version of
NetPIPE in C (prior to version 2.3) does not interoperate with the
Java implementation of NetPIPE.

What is NetPIPE?
----------------

NetPIPE is a protocol independent performance tool that encapsulates
the best of ttcp and netperf and visually represents the network
performance under a variety of conditions. By taking the end-to-end
application view of a network, NetPIPE clearly shows the overhead
associated with different protocol layers. Netpipe answers such
questions as: how soon will a given data block of size k arrive at its
destination? Which network and protocol will transmit size k blocks
the fastest? What is a given network's effective maximum throughput
and saturation level?  Does there exist a block size k for which the
throughput is maximized? How much communication overhead is due to the
network communication protocol layer(s)? How quickly will a small (< 1
kbyte) control message arrive, and which network and protocol are best
for this purpose?

For a paper fully describing NetPIPE and sample investigation of
network performance issues using NetPIPE, see
http://www.scl.ameslab.gov/netpipe/paper/full.html.

About Java NetPIPE
------------------

This Java version of NetPIPE is a nearly exact implementation of the C
version of NetPIPE, with these exceptions:

* Command line usage: The protocol implementation must be specified on
  the command line.

* NetPIPE-Java's TCP protocol was different from NetPIPE's
  implementation in C, although this has been fixed in the C
  implementation of NetPIPE at version 2.2 (the synchronization,
  repeat count, and timestamp messages were changed to reflect
  sanity).

* The only protocol interface implemented is TCP using the Java Core
  API Socket class.

A caveat: simple tests with Java NetPIPE on an SGI Indy testing the
localhost (loopback) interface show that the Java implementation has
latency roughly five times that of the C implementation, and the peak
performance of the Java version achieves roughly 60% of the
performance of the C version.

How to Use Java NetPIPE
-----------------------

NetPIPE is provided with a protocol-specific implementation for TCP
(using the Java Core API Socket class).  It should be easy to write
new implementations for other protocols based on the example of the
TCP implementation.

Java NetPIPE requires a Java compiler and Java Core API 1.0 or newer.

Review the provided Makefile and make any desired changes.

Compile Java NetPIPE by using the command "make".

To test TCP, run a NetPIPE receiver on one computer by issuing the
command "java Netpipe TCP -r".  Run a NetPIPE sender on another
computer by issuing the command "java Netpipe TCP -t -h <receiver's
address> -o <output file>" and any other options as appropriate:

	Generic NetPIPE flags:
	----------------------
	a: asynchronous receive (a.k.a. preposted receive)
		This option currently has no effect on TCP

	i: specify increment step size, e.g. "-i 64"
		Default is exponential increment calculated at runtime

	l: lower bound (start value for block size), e.g. "-l 1"

	o: specify output filename, e.g. "-o output.txt"
		Default output file name is "netpipe.out" if -o
		is not specified

	P: print real-time results on stdout

	s: stream option
		If this option is used, it must be specified on both
		the sending and receiving processes

	u: upper bound (stop value for block size), e.g. "-u 1048576"

	TCP-specific flags:
	-------------------
	h: specify hostname, e.g. "-h mumblehost"

	p: specify port, e.g. "-p 5150"

	r: receiver

	t: transmitter

(The default output file is "netpipe.out"; the -o option overrides the
default value.)

NetPIPE's output file contains five columns: time to transfer the block,
bits per second, bits in block, bytes in block, and variance.  These
columns may be graphed to represent and compare the network's
performance.  For example, the "network signature" graph can be
created by graphing the time column versus the bits per second column
(see the NetPIPE report at the URL above for the details why this
graph is important and how to interpret it).  The more traditional
"throughput versus block size" graph can be created by
graphing the bytes column versus the bits per second column.

See http://www.scl.ameslab.gov/Projects/ClusterCookbook/nprun.html for
a detailed tutorial on running NetPIPE and graphing the results.

Help
----

NetPIPE is currently maintained by Guy Helmer.  Email
"ghelmer@scl.ameslab.gov" or call 515-294-9469 for help or
suggestions.

Acknowledgments
---------------

The Format class is provided courtesy of Gary Cornell and Cay
S. Horstmann, authors of the Core Java book and CD-ROM.  Used by
permission as stated in the copyright and license as stated in the
comments in the source file Format.java.

Changes
-------

version 1.0 (9/25/1998)
    * Updated README

version 1.0beta (2/19/1998)
    * Initial release