NAME
nuttcp - network performance measurement tool
SYNOPSIS
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 ]
DESCRIPTION
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:
OPTIONS
-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.
USAGE
Under Construction
For now, consult the README file for basic usage guidelines.
EXAMPLES
Under Construction
For now, see the examples.txt file for some examples of using nuttcp.
SEE ALSO
ping(8), traceroute(8), tracepath(8), pathchar(8), netstat(1),
mtrace(8)
AUTHORS
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.
BUGS
Please send bug reports to nuttcp-bugs@lcp.nrl.navy.mil.