-*- nroff -*-

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

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., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

netpipe.1
Created: Mon Jun 15 1998 by Guy Helmer

NetPIPE - network protocol independent performance evaluator NPtcp [\c -A buffer_alignment\c ] [\c -a \c ] [\c -b TCP_buffer_size\c ] [\c -h host_name\c ] [\c -i increment\c ] [\c -l starting_msg_size\c ] [\c -O buffer_offset\c ] [\c -o output_filename\c ] [\c -P \c ] [\c -p port\c ] [\c -r \c ] [\c -s \c ] [\c -t \c ] [\c -u ending_msg_size\c ]

NPmpi [\c -A buffer_alignment\c ] [\c -a \c ] [\c -i increment\c ] [\c -l starting_msg_size\c ] [\c -O buffer_offset\c ] [\c -o output_filename\c ] [\c -P \c ] [\c -s \c ] [\c -u ending_msg_size\c ]

NPpvm [\c -A buffer_alignment\c ] [\c -a \c ] [\c -i increment\c ] [\c -l starting_msg_size\c ] [\c -O buffer_offset\c ] [\c -o output_filename\c ] [\c -P \c ] [\c -r \c ] [\c -s \c ] [\c -t \c ] [\c -u ending_msg_size\c ]

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:

NetPIPE is provided with interfaces for TCP, MPI, and PVM, but TCP is the most commonly used interface for general network testing purposes. It should be easy to write new interfaces for other reliable protocols based on the examples provided by the TCP, MPI and PVM interfaces.

Typical use for TCP involves running the TCP NetPIPE receiver on one system with the command

.Ex NPtcp -r .Ee

and running the TCP NetPIPE transmitter on another system with the command

.Ex NPtcp -h receiver_hostname -o output_filename -P -t .Ee

If any options are used that modify the test protocol, including -i, -l, -p, -s, and -u, those parameters must be used on both the transmitter and the receiver, or the test will not run properly.

Typical use for PVM first requires starting PVM with the command

.Ex pvm .Ee

and adding a second machine with the PVM command

.Ex add othermachine .Ee

(then exit the PVM command line interface). Then run the PVM NetPIPE receiver on one system with the command

.Ex NPpvm -r .Ee

and run the TCP NetPIPE transmitter on the other system with the command

.Ex NPpvm -t -o output_filename -P .Ee

If any options are used that modify the test protocol, including -i, -l, -p, -s, and -u, those parameters must be used on both the transmitter and the receiver, or the test will not run properly.

Use of the MPI interface for NetPIPE depends on the MPI implementation used. For the Argonne MPICH implementation using the p4 device (for a cluster of individual systems interconnected using TCP/IP), create a file that contains the hostnames of the two systems you want to include in the test, with one hostname on each line of the file (assume the file is named "machines.p4"). Then, use the command

.Ex mpirun -machinefile machines.p4 -np 2 NPmpi -o output_filename -P .Ee

to start the test. MPICH will start an NPmpi process on each of the two selected machines and the test will begin.

NetPIPE tests network performance by sending a number of messages at each block size, starting from the lower bound on message size. NetPIPE increments the message size until the upper bound on message size is reached or the time to transmit a block exceeds one second, which ever occurs first.

NetPIPE\c \'s output file may be graphed with a program such as gnuplot(1) to view the results of the test. NetPIPE\c \'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 time versus bits per second. Sample gnuplot(1) commands for such a graph would be

.Ex set logscale x .Ee

.Ex plot "NetPIPE.out" using 1:2 .Ee

The more traditional throughput versus block size graph can be created by graphing bytes versus bits per second. Sample gnuplot(1) commands for such a graph would be

.Ex set logscale x .Ee

.Ex plot "NetPIPE.out" using 4:2 .Ee

-A alignment Align buffers to the given boundary. For example, a value of 4 would align buffers to 4-byte (word) boundaries.

-a Specify asynchronous receive (a.k.a. preposted receive), if the underlying protocol supports it.

-b buffer_size [TCP only] Set send and receive TCP buffer sizes.

-h hostname [TCP transmitter only] Specify name of host to which to connect.

-i increment Specify increment step size (default is an exponentially increasing increment).

-l start_msg_size Specify the starting message size. The test will start with messages of this size and increment, either exponentially or with an increment specified by the -i flag, until a block requires more than one second to transmit or the ending message size specified by the -u flag is reached, which ever occurs first.

-O buffer_offset Specify offset of buffers from alignment. For example, specifying an alignment of 4 (with -A) and an offset of 1 would align buffers to the first byte after a word boundary.

-o output_filename Specify output filename. By default, the output filename is NetPIPE.out .

-P Print results on screen during execution of the test. By default, NetPIPE is silent during execution of the test.

-p port_number [TCP only] Specify TCP port number to which to connect (for the transmitter) or the port on which to listen for connections (for the receiver).

-r [TCP only] This process is a TCP receiver.

-s Set streaming mode: data is only transmitted in one direction. By default, the transmitter measures the time taken as each data block is sent from the transmitter to the receiver and back, then divides the round-trip time by two to obtain the time taken by the message to travel in each direction. In streaming mode, the receiver measures the time required to receive the message and sends the measured time back to the transmitter for posting to the output file.

-t [TCP only] This process is a TCP transmitter.

-u ending_msg_size Specify the ending message size. By default, the test will end when the time to transmit a block exceeds one second. If -u is specified, the test will end when either the test time exceeds one second or the ending message size is reached, which ever occurs first.

NetPIPE.out Default output file for NetPIPE . Overridden by the -o option.

Quinn Snell <snell@cs.byu.edu>, Guy Helmer <ghelmer@scl.ameslab.gov>, and others.

Clark Dorman <dorman@s3i.com> contributed the PVM interface.

Information about NetPIPE can be found on the World Wide Web at http://www.scl.ameslab.gov/netpipe/.

By nature, NetPIPE will use as much of the network bandwidth as possible. Other users of the network may notice the effect.