nuttcp - network performance measurement tool
nuttcp -h
nuttcp -V
nuttcp -t [ -bdDsuv ]
[ -cdscp_value ]
[ -lbuffer_len ]
[ -nnum_bufs ]
[ -wwindow_size ]
[ -wsserver_window ]
[ -wb ]
[ -pdata_port ]
[ -Pcontrol_port ]
[ -Nnum_streams ]
[ -Rxmit_rate_limit [m|g] ]
[ -Txmit_timeout [m] ] host [
< input ]
nuttcp -r [ -bBdsuv ]
[ -cdscp_value ]
[ -lbuffer_len ]
[ -nnum_bufs ]
[ -wwindow_size ]
[ -wsserver_window ]
[ -wb ]
[ -pdata_port ]
[ -Pcontrol_port ]
[ -Nnum_streams ]
[ -Rxmit_rate_limit [m|g] ]
[ -Txmit_timeout [m] ] [
host ] [ > output ]
nuttcp -S [ -Pcontrol_port ]
nuttcp -1 [ -Pcontrol_port ]
nuttcp is a network performance measurement tool intended for use
by network and system managers. Its most basic usage is to determine the raw
TCP (or UDP) network layer throughput by transferring memory buffers from a
source system across an interconnecting network to a destination system,
either transferring data for a specified time interval, or alternatively
transferring a specified number of bytes. In addition to reporting the
achieved network throughput in Mbps, nuttcp also provides additional useful
information related to the data transfer such as user, system, and
wall-clock time, transmitter and receiver CPU utilization, and loss
percentage (for UDP transfers).
nuttcp is based on nttcp, which in turn was an enhancement by
someone at Silicon Graphics (SGI) on the original ttcp, which was written by
Mike Muuss at BRL sometime before December 1984, to compare the performance
of TCP stacks by U.C. Berkeley and BBN to help DARPA decide which version to
place in the first BSD Unix release. nuttcp has several useful features
beyond those of the basic ttcp/nttcp, such as a server mode, rate limiting,
multiple parallel streams, and timer based usage. More recent changes
include IPv6 support, IPv4 multicast, and the ability to set the maximum
segment size or TOS/DSCP bits. nuttcp is continuing to evolve to meet new
requirements that arise and to add desired new features. nuttcp has been
successfully built and run on a variety of Solaris, SGI, and PPC/X86 Linux
systems, and should probably work fine on most flavors of Unix. It has also
been used successfully on various versions of the Windows operating
system.
There are two basic modes of operation for nuttcp. The original or
classic mode is the transmitter/receiver mode, which is also the way the
original ttcp and nttcp worked. In this mode, a receiver is first initiated
on the destination host using "nuttcp -r", and then a transmitter
must be started on the source host using "nuttcp -t". This mode is
somewhat deprecated and is no longer recommended for general use. The
preferred and recommended mode of operation for nuttcp is the new
client/server mode. With this mode, a server is first started on one system
using "nuttcp -S" (or "nuttcp -1"), and then a client
may either transmit data to (using "nuttcp -t") or receive data
from (using "nuttcp -r") the server system. All the information
provided by nuttcp is reported by the client, including the information from
the server, thus providing a full snapshot of both the transmitter and
receiver ends of the data transfer.
The server may be started by a normal, non-privileged user by
issuing either a "nuttcp -S" or a "nuttcp -1" command.
However, the optimal and recommended method of running a server is to run
"nuttcp -S" via the inetd/xinetd daemon. This method has several
significant advantages, including being more robust, allowing multiple
simultaneous connections, and providing for access control over who is
allowed to use the nuttcp server via the hosts.allow (and hosts.deny) file.
By default, the nuttcp server listens for commands on port 5000, and the
actual nuttcp data transfers take place on port 5001.
The host parameter must be specified for the transmitter,
and provides the host name or IP address of the receiver. In classic
transmitter/receiver mode, the host parameter may not be specified
for the receiver. In client/server mode, when the client is the receiver,
the host parameter specifies the host name or IP address of the
transmitter (server).
Normally, a nuttcp data transfer is memory-to-memory. However, by
using the "-s" option, it is possible to also perform
memory-to-disk, disk-to-memory, and disk-to-disk data transfers. Using the
"-s" option with the transmitter will cause nuttcp to read its
data from the standard input instead of using a prefabricated memory buffer,
while using the "-s" option on the receiver causes nuttcp to write
its data to standard output. All these types of data transfers are possible
with the classic transmitter/receiver mode. For security reasons, the
"-s" option is disabled on the server, so it is not possible to
access the disk on the server side of a data transfer.
The allowed options to nuttcp are:
- -h
- Print out a usage statement. Running nuttcp with no arguments will also
produce a usage statement.
- -V
- Prints the nuttcp version number. The nuttcp version is also printed as
part of the normal nuttcp output when the "-v" verbose output is
used (but not when using the default brief output). In client/server mode,
the version number of both the client and server is identified.
- -t
- Indicates that this nuttcp is the transmitter. In client/server mode, this
means the server specified by the host parameter is the
receiver.
- -r
- Indicates that this nuttcp is the receiver. In client/server mode, this
means the server specified by the host parameter is the
transmitter.
- -S
- Indicates that this nuttcp is the server. The only option that may be
specified to the server is the "-P" option, which allows one to
change the control port used by the server, but only when the server is
started by a normal, non-privileged user. When the server is initiated by
inetd/xinetd, the server control port should be specified in the
services file.
- -1
- Basically the same as the "-S" option, but indicates a one-shot
server, i.e. the server exits after the first data transfer initiated by a
client. The "-1" option should only be used when the server is
started by a normal, non-privileged user. This option will probably rarely
need to be used, but can be useful for a quick test and eliminates the
possibilty of leaving a non-access controlled nuttcp server running on the
system (which can happen when using the "-S" option and
forgetting to kill the nuttcp server after finishing a series of
tests).
- -b
- Produce brief one-line output, which includes the amount of data
transferred in MB (1024**2 bytes), the time interval in seconds, the TCP
(or UDP) network throughput in Mbps (millions of bits per second), the
transmitter and/or receiver CPU utilization, and for UDP data transfers
also outputs the loss percentage. In client/server mode, most of the
printed statistics are from the viewpoint of the receiver. This is the
default output format.
- -B
- This option is only valid for the receiver, and forces the receiver to
read a full buffer (as specified by the "-l" buffer length
option) from the network. It is mainly intended to be used with the
"-s" option to only output full buffers to standard output (e.g.
for use with tar). It is also implicitly set whenever the number of
streams as specified by the "-N" option is greater than 1. This
option is not passed to the server.
- -d
- For TCP data transfers, sets the SO_DEBUG option on the data socket. This
option is not passed to the server. It is a rarely used option which may
possibly be removed or renamed in a future version of nuttcp.
- -D
- This option is only valid for the transmitter, and only for TCP data
transfers, in which case it sets the TCP_NODELAY option on the data
socket, which turns off the Nagle algorithm causing data packets to be
sent as soon as possible without introducing any unnecessary delays. This
option is not passed to the server. It is a rarely used option which may
possibly be removed or renamed in a future version of nuttcp.
- -s
- Setting the "-s" option causes nuttcp to either read its data
from standard input rather than using prefabricated memory buffers (for
"nuttcp -t"), or to write its data out to standard output (for
"nuttcp -r"). The "-s" option is disabled for security
reasons on the server.
- -u
- Use UDP for the data transfer instead of the default of TCP.
- -v
- Verbose output that provides some additional information related to the
data transfer. In client/server mode, the server is always verbose
(implicit "-v" option), but the client controls the extent and
type of output via the "-v" and "-b" options.
- -cdscp_value
- Sets the socket option to support COS. Either takes a dscp value or with
the t|T modifier it takes the full TOS field.
- -lbuffer_len
- Length of the network write/read buffer in bytes for the
transmitter/receiver. It defaults to 64 KB (65536) for TCP data transfers
and to 8 KB (8192) for UDP. For client/server mode, it sets both the
client and server buffer lengths.
- -nnum_bufs
- Specifies the number of source buffers written to the network (default is
unlimited), and is ignored by the receiver. For client/server mode, if the
client issues a "nuttcp -r" command making it the receiver, this
parameter is passed to the server since the server is the transmitter in
this case. This parameter is also ignored if the "-s" parameter
is specified to the transmitter.
- -wwindow_size
- Indicates the window size in KB of the transmitter (for "nuttcp
-t") or receiver (for "nuttcp -r"). Actually, to be
technically correct, it sets the sender or receiver TCP socket buffer
size, which then effectively sets the window size. For client/server mode,
both the transmitter and receiver window sizes are set. The default window
size is architecture and system dependent. Note recent Linux systems, out
of a misguided desire to be helpful, double whatever window size is
actually specified by the user (this is not a bug with nuttcp but a
bug/feature of the Linux kernel). Also, with these Linux systems, the
actual window size that's used on the intervening network, as observed
with tcpdump, is greater than the requested window size, but less than the
doubled value set by Linux.
- -wsserver_window
- For client/server mode, the "-ws" option provides a mechanism
for setting a different window size on the server than the client window
size as specified with the "-w" option.
- -wb
- Normally, to conserve memory, the transmitter only sets the TCP send
socket buffer size and the receiver only sets the TCP receive socket
buffer size. However, if the "-wb" option is used, the
transmitter will also set the TCP receive socket buffer size and the
receiver will also set the TCP send socket buffer size. Under normal
circumstances, this should never be necessary. This option was implemented
because certain early braindead Solaris 2.8 systems would not properly set
the TCP window size unless both the TCP send and receive socket buffer
sizes were set (later Solaris 2.8 systems have corrected this deficiency).
Thus the 'b' in this option can stand either for "braindead" or
"both".
- -pdata_port
- Port number used for the data connection, which defaults to port 5001. If
multiple streams are specified with the "-N" option, the
"-p" option specifies the starting port number for the data
connection. For example, if four streams are specified using the default
data connection port number, nuttcp will use ports 5001, 5002, 5003, and
5004 for the four TCP (or UDP) connections used to perform the data
transfer.
- -Pcontrol_port
- For client/server mode, specifies the port number used for the control
connection between the client and server, and defaults to port 5000. On
the server side, the "-P" option should only be used when the
server is started manually by the user. If the server is started by
inetd/xinetd (the preferred method), the control connection must be
specified by adding a nuttcp entry to the services file.
- -Nnum_streams
- Species the number of parallel TCP (or UDP) data streams to be used for
the data transfer, with the default being a single data stream. The
maximum number of parallel data streams that can be used is 128. If the
number of streams is greater than one, the "-B" option is
implicitly set. The current implementation does not fork off separate
processes for each data stream, so specifying multiple streams on an SMP
machine will not take advantage of its multiple processors. Of course it
is always possible to run multiple nuttcp commands in parallel on an SMP
system to determine if there is any advantage to running on multiple
processors. This is especially simple to do when running in client/server
mode when the server is started from the inetd/xinetd daemon. When running
multiple nuttcp commands in parallel, the "-T" transmitter
timeout option may be used to insure that all the nuttcp commands finish
at approximately the same time.
- -Rxmit_rate_limit[m|g]
- The transmitter rate limit throttles the speed at which the transmitter
sends data to the network, and by default is in Kbps, although the 'm' or
'g' suffix may be used to specify Mbps or Gbps. This option may be used
with either TCP or UDP data streams. Because of the way this option is
currently implemented, it will consume all the available CPU on the
transmitter side of the connection so the "%TX" stats are not
meaningful when using the rate limit option. By default the rate limit is
applied to the average rate of the data transfer in real time, and not in
CPU time, so if nuttcp is switched out of the processor for any reason,
when it is switched back in, it is possible that the instantaneous rate
may momentarily exceed the specified value. There is an 'i' qualifier to
the rate limit option (specified as "-Ri") that will restrict
the instantaneous rate at any given point in time to the specified value,
although in this case the final rate reported by nuttcp may be less than
the specified value since nuttcp won't attempt to catch up if other
processes gain control of the CPU. The default is no rate limit. Note
another way to throttle the throughput of TCP data streams is to reduce
the window size.
- -Txmit_time_limit[m]
- Limits the amount of time that the transmitter will send data to the
specified number of seconds, or number of minutes if the 'm' suffix is
used. Normally a data transfer will either specify a fixed amount of data
to send using the "-n" option, or a fixed period of time to send
using the "-T" option. However, if both the "-n" and
"-T" options are used, the data transfer will be stopped by
whichever option takes affect first. The default is a 10 second time limit
for the data transfer.
Under Construction
For now, consult the README file for basic usage guidelines.
Under Construction
For now, see the examples.txt file for some examples of using
nuttcp.
Developed by Bill Fink based on nttcp which in turn was an
enhancement of the original ttcp developed by Mike Muuss at BRL. IPv6
capability and some other fixes and enhancements contributed by Rob Scott.
Many useful suggestions and testing performed by Phil Dykstra and
others.
The current version is available via anonymous ftp from:
ftp://ftp.lcp.nrl.navy.mil/pub/nuttcp/
The authors can be reached at nuttcp@lcp.nrl.navy.mil.
Please send bug reports to nuttcp-bugs@lcp.nrl.navy.mil.