Provided by: nttcp_1.47-13build1_amd64 
NAME
nttcp - new test TCP program
SYNOPSIS
nttcp [ local options ] partner-host [ partner-host ] ... [ remote options ]
DESCRIPTION
The nttcp program measures the transferrate (and other numbers) on a TCP, UDP or UDP
multicast connection. To use nttcp you have to provide the executable on the local
machine and on a partner machine. On the partner machine simply start nttcp with the
option -i. Started this way, nttcp is waiting for connections from other nttcps. On the
local host simply call nttcp with the name of the partner host. It will contact the nttcp
started on the partner machine and initiate the transfer. On default the program transfers
2048 buffers of 4KByte length (a total of 8 MByte) to the partner host. On both sides the
performance will be measured and the findings (both, remote and local) are reported on the
local side. You may change nearly every parameter of the transmission via commandline
options, even what and how results are printed.
OPTIONS
-r defines the receive transfer direction; data is sent from the partner host to the
local host.
-t defines the transmit transfer direction; data is sent from the local host to the
partner host. This is the default direction.
-T Print a title line.
-u Use the UDP protocol instead of TCP (which is the default).
-g Gap time in microseconds between packets. This delay is implemented via the timeout
parameter of select(2) and a loop with gettimeofday(2). The accuracy of this value
is misleading. Most machines will not be able to delay exactly the given amount.
The code will try its best to achieve the desired delay. For TCP connections this
option does only implement a delay between the write(2) system calls. It does not
really delay between the real output on the physical device.
-v Give more and verbose output; only useful for debugging purposes.
-D Set the TCP_NODELAY option on the transmitting socket. With this option set, the
socket does not buffer any write requests.
-f format string
Specify your own output format. See OUTPUT.
-n number of buffers
The given number of buffers will be written to the transmitting socket. It
defaults to 2048.
-l length of buffer
The given length defines the size of one buffer written to the transmitting socket.
Defaults to 4096.
-x fixed length of data
The given length defines the amount of data that will be transfered. Subsequent
specified -l or -n options will adapt the corresponding other value so that the
number of buffers and the length of buffer multiplies to the given fixed length.
-w number of kilo bytes
Defines the buffer size of the transmitting and receiving socket. This is system
dependant; usally it is 16K.
-c If this option is present, the receiving side will compare the bytes received with
the pattern used by the sending side. At most the first 100 differences will be
reported. If the transmission is via TCP, a uniq pattern for the whole transmission
is generated. For UDP the same pattern for each paket is used. You can force a
stream pattern with the -s switch; but if one paket is lost, all subsequent packets
contain patterns not expected and will be reported as different. Since every byte
is numbered, this can be used to detect the first packet lost during the
transmission.
BUT be aware: if there is a difference, this option may lead to packet-losses on
UDP transmissions or to degration in performance, since the preparation of the
output is simple-minded and uses a lot of CPU time.
-s Forces the generation of a stream pattern if UPD packet data is compared. See -c
switch.
-S seed string
give any string to initialize the pattern generator. By default this seed has the
value 'This is a simple init string'. This enforces the -c option.
-pport number
On default the partner host will listen on port 5037. This can be overwritten with
this option.
-i If you have no root access on the partner host, or do not want hacking with inetd,
this option directs nttcp to behave as a daemon, waiting for connections and
spawning off child processes by itself as inetd would do it otherwise.
-Rnumber of getpid() calls
This option does not transmit any data, but calls the given number of times
getpid(2) and calculates the number of calls per second. This is a measure for the
speed of the machine and the system call interface.
-mmulticast IP:port
This option is used to force sending to the specified multicast address and port.
This option enforces the -u and-t switch.AlsoseeMULTICASTlaterinthisdocument.
OUTPUT
The output of the program consists of two lines of numbers; or more lines if used in
transmitting to more than one machine (multicasting). The first line for the measures of
the local host the other line for the measure of the partner host. This is also indicated
with the first characters beeing a 'l' respective 'r'. If the -T flag was given, also a
Title line is given. The default format of the outout looks like this:
Bytes Real s CPU s Real-MBit/s CPU-MBit/s Calls Real-C/s CPU-C/s
l 8388608 7.51 0.25 8.7307 259.8676 2048 272.83 8120.86
r 8388608 7.55 0.95 8.6804 68.9853 3831 507.42 4032.63
The timing and rate values marked with 'CPU' use the sum of system and user time only.
Real timing and rate values are computed using the time from the begin to the end of the
transmission.
It is possible to specify another form of the output. This is done similiar to the format
strings of printf(3s). The conversion characters of printf(3s) are replaced with the
following tags. Each tag is preceded by '%' as in printf(3s). Between the '%' character
and the tag there are width and precision specifications allowed as with printf(3s). Two
types of values are printed integers and floats. For these types the conversion letters
'd' respective 'f' of printf(3s) are used.
l prints the buffer length in bytes. Integer value.
n prints the buffer count. Integer value.
c prints the number of calls. Integer value.
rt prints the real time in s. Float value.
rbr prints the real bit rate in MBit/s. Float value.
rcr prints the real call rate in calls/s. Float value.
ct prints the cpu time in s. Float value.
cbr prints the cpu bit rate in MBit/s. Float value.
ccr prints the cpu call rate in calls/s. Float value.
The default format is produced with the following format string:
"%9b%8.2rt%8.2ct%12.4rbr%12.4cbr%8c%10.2rcr%10.2ccr"
INSTALLATION
To make most convenient use of this program, it can be installed on the partner machine,
so that inetd(8) can start it. To accomplish this, two files have to be edited:
/etc/inetd.conf and /etc/services.
The respective lines may look like this:
inetd.conf:
ttcp stream tcp nowait nobody /usr/local/etc/nttcp nttcp
services:
ttcp 5037/tcp # to measure tcp transfer rates
After these changes have been made, the inetd(8) process has to be notified via a HUP
signal (or killed and restarted on older versions of unix).
MULTICASTING
Beginning with version 1.4 there is support generating multicast traffic. You even needn't
set any option, but simply specify more than one partner host. This mode is restricted to
sending packets from the local host to the partner hosts. And of course works only on
machines that have a multicast enabled IP stack. Tested is this feature on Solaris2.6,
HPUX-10 and HPUX-11 and Irix 6.2. Also FreeBSD-2.2.6 compiled with option MROUTING works.
But be aware what this means to your networking environment. Most ethernet switches for
example handle multicast traffic as broadcast. This way you will flood your complete
network with these packets.
ENVIRONMENT
The are two environment variables NTTCP_LOC_OPT and NTTCP_REM_OPT that can be used to
preset the local options and remote options respectivly. They take the same format as the
commandline does. Commandline options override those settings from the environment.
SECURITY
Under security considerations, the inetd-mode of operation is NOT suggested. Hosts
configured to start nttcp this way, are very open to denial-of-service attacks. If you are
concerned about this issue, you should consider either the use of tcpwrapper or simply not
install nttcp this way.
Also be sure to run nttcp as non-root when started via inetd(8). I have taken some care to
avoid buffer-overrun prone coding. But the source is too big now to be sure in all corners
of the code.
You may also consider not to provide general access to this programm. It may easily be
used to flood your network with lots of traffic. This may be used to launch or support
denial-of-service attacks.
WARNING
There are a lot of pitfalls in explaining unexpected measures. Be sure to get a thorough
understanding of your network and the devices used and installed. Also it is extremly
helpful to have a deep understanding of the things that happen in your machine and
operating system. A short example shows what is meant here: If you see packet losses on
UDP transfers, it may be, that the packets are lost on the sending host! For today
machines it is easy to produce packets much faster than a 10MBit ethernet can swallow it,
so they may be dropped on the UDP stack of the operating system. This depends on the
implementation of your IP stack. So, to be sure, use a second machine, and snoop or
tcpdump the traffic in question, to be sure what happens on the medium.
BUGS
Any program without bugs?
SEE ALSO
inetd(8).
HISTORY
This program was written to ease the measurement of TCP transfer rates in a network of
unix workstations. It is based on the ttcp.c program, which was (I suppose) posted to
comp.sources.misc. This man-page describes version 1.4.
AUTHOR
Elmar Bartel
Fakultaet fuer Informatik,
Technische Universitaet Muenchen.
bartel@informatik.tu-muenchen.de
5 Oct 1998 nttcp(1)