nuttcp - network performance measurement tool
] [ -wb
-Rxmit_rate_limit [m|g] ]
[ -Txmit_timeout [m] ] host
] [ -wb
-Rxmit_rate_limit [m|g] ]
[ -Txmit_timeout [m] ] [
] [ > output
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
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
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:
- Print out a usage statement. Running nuttcp with no
arguments will also produce a usage statement.
- 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
- Indicates that this nuttcp is the transmitter. In
client/server mode, this means the server specified by the host
parameter is the receiver.
- Indicates that this nuttcp is the receiver. In
client/server mode, this means the server specified by the host
parameter is the transmitter.
- 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.
- 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).
- 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.
- 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.
- 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
- 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.
- 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.
- Use UDP for the data transfer instead of the default of
- 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"
- Sets the socket option to support COS. Either takes a dscp
value or with the t|T modifier it takes the full TOS field.
- 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.
- 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.
- 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.
- 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.
- 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
- 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
- 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.
- 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.
- 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.
- 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.
For now, consult the README file for basic usage guidelines.
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:
The authors can be reached at firstname.lastname@example.org.
Please send bug reports to email@example.com.