1NUTTCP(8)                     Under Construction                     NUTTCP(8)
2
3
4

NAME

6       nuttcp - network performance measurement tool
7

SYNOPSIS

9       nuttcp -h
10       nuttcp -V
11       nuttcp -t [ -bdDsuv ] [ -cdscp_value ] [ -lbuffer_len ] [ -nnum_bufs ]
12                 [ -wwindow_size ] [ -wsserver_window ] [ -wb ]
13                 [ -pdata_port ] [ -Pcontrol_port ]
14                 [ -Nnum_streams ] [ -Rxmit_rate_limit [m|g] ]
15                 [ -Txmit_timeout [m] ] host [ < input ]
16       nuttcp -r [ -bBdsuv ] [ -cdscp_value ] [ -lbuffer_len ] [ -nnum_bufs ]
17                 [ -wwindow_size ] [ -wsserver_window ] [ -wb ]
18                 [ -pdata_port ] [ -Pcontrol_port ]
19                 [ -Nnum_streams ] [ -Rxmit_rate_limit [m|g] ]
20                 [ -Txmit_timeout [m] ] [ host ] [ > output ]
21       nuttcp -S [ -Pcontrol_port ]
22       nuttcp -1 [ -Pcontrol_port ]
23

DESCRIPTION

25       nuttcp  is  a  network performance measurement tool intended for use by
26       network and system managers.  Its most basic usage is to determine  the
27       raw  TCP  (or UDP) network layer throughput by transferring memory buf‐
28       fers from a source system across an interconnecting network to a desti‐
29       nation  system, either transferring data for a specified time interval,
30       or alternatively transferring a specified number of buffers.  In  addi‐
31       tion  to reporting the achieved network throughput in Mbps, nuttcp also
32       provides additional useful information related  to  the  data  transfer
33       such as user, system, and wall-clock time, transmitter and receiver CPU
34       utilization, and loss percentage (for UDP transfers).
35
36       nuttcp is based on nttcp, which in turn was an enhancement  by  someone
37       at  Silicon  Graphics  (SGI) on the original ttcp, which was written by
38       Mike Muuss at BRL sometime before December 1984, to compare the perfor‐
39       mance of TCP stacks by U.C. Berkeley and BBN to help DARPA decide which
40       version to place in the first BSD Unix  release.   nuttcp  has  several
41       useful  features beyond those of the basic ttcp/nttcp, such as a server
42       mode, rate limiting, multiple parallel streams, and timer based  usage.
43       nuttcp is also continuing to evolve to meet new requirements that arise
44       and to add desired new features.  nuttcp has been  successfully  tested
45       and  used  on a variety of Solaris, SGI, and PPC/X86 Linux systems, and
46       should probably work fine on most flavors of Unix.
47
48       There are two basic modes of operation for  nuttcp.   The  original  or
49       classic  mode  is  the transmitter/receiver mode, which is also the way
50       the original ttcp and nttcp worked.  In this mode, a receiver is  first
51       initiated  on the destination host using "nuttcp -r", and then a trans‐
52       mitter must be started on the source host using "nuttcp -t".  This mode
53       is  somewhat  deprecated  and is no longer recommended for general use.
54       The preferred and recommended mode of operation for nuttcp is  the  new
55       client/server  mode.   With this mode, a server is first started on one
56       system using "nuttcp -S" (or "nuttcp -1"), and then a client may either
57       transmit  data  to  (using  "nuttcp  -t")  or  receive data from (using
58       "nuttcp -r") the server system.  All the information provided by nuttcp
59       is  reported  by the client, including the information from the server,
60       thus providing a full snapshot of both  the  transmitter  and  receiver
61       ends of the data transfer.
62
63       The  server  may be started by a normal, non-privileged user by issuing
64       either a "nuttcp -S" or a "nuttcp -1" command.   However,  the  optimal
65       and  recommended  method  of running a server is to run "nuttcp -S" via
66       the inetd/xinetd daemon.  This method has  several  significant  advan‐
67       tages, including being more robust, allowing multiple simultaneous con‐
68       nections, and providing for access control over who is allowed  to  use
69       the  nuttcp  server  via  the  hosts.allow  (and  hosts.deny) file.  By
70       default, the nuttcp server listens for commands on port 5000,  and  the
71       actual nuttcp data transfers take place on port 5001.
72
73       The  host parameter must be specified for the transmitter, and provides
74       the host name or IP address of  the  receiver.   In  classic  transmit‐
75       ter/receiver  mode,  the  host  parameter  may not be specified for the
76       receiver.  In client/server mode, when the client is the receiver,  the
77       host parameter specifies the host name or IP address of the transmitter
78       (server).
79
80       Normally, a nuttcp data  transfer  is  memory-to-memory.   However,  by
81       using  the  "-s" option, it is possible to also perform memory-to-disk,
82       disk-to-memory, and disk-to-disk data transfers.  Using the "-s" option
83       with  the transmitter will cause nuttcp to read its data from the stan‐
84       dard input instead of using a prefabricated memory buffer, while  using
85       the  "-s"  option  on  the  receiver causes nuttcp to write its data to
86       standard output.  All these types of data transfers are  possible  with
87       the  classic transmitter/receiver mode.  For security reasons, the "-s"
88       option is disabled on the server, so it is not possible to  access  the
89       disk on the server side of a data transfer.
90
91       The allowed options to nuttcp are:
92

OPTIONS

94       -h     Print  out  a usage statement.  Running nuttcp with no arguments
95              will also produce a usage statement.
96
97       -V     Prints the nuttcp version number.  The nuttcp  version  is  also
98              printed  as  part of the normal nuttcp output when the "-v" ver‐
99              bose output is used (but not when using the default  brief  out‐
100              put).   In  client/server  mode,  the version number of both the
101              client and server is identified.
102
103       -t     Indicates that this nuttcp is the transmitter.  In client/server
104              mode,  this  means the server specified by the host parameter is
105              the receiver.
106
107       -r     Indicates that this nuttcp is the  receiver.   In  client/server
108              mode,  this  means the server specified by the host parameter is
109              the transmitter.
110
111       -S     Indicates that this nuttcp is the server.  The only option  that
112              may  be specified to the server is the "-P" option, which allows
113              one to change the control port used by the server, but only when
114              the  server  is  started by a normal, non-privileged user.  When
115              the server is initiated by inetd/xinetd, the server control port
116              should be specified in the services file.
117
118       -1     Basically  the same as the "-S" option, but indicates a one-shot
119              server, i.e. the server exits after the first data transfer ini‐
120              tiated  by  a  client.  The "-1" option should only be used when
121              the server is started by a normal,  non-privileged  user.   This
122              option  will  probably rarely need to be used, but can be useful
123              for a quick test and eliminates the possibilty of leaving a non-
124              access controlled nuttcp server running on the system (which can
125              happen when using the "-S" option and  forgetting  to  kill  the
126              nuttcp server after finishing a series of tests).
127
128       -b     Produce brief one-line output, which includes the amount of data
129              transferred in MB (1024**2 bytes), the time interval in seconds,
130              the  TCP  (or  UDP) network throughput in Mbps (millions of bits
131              per second), the transmitter and/or  receiver  CPU  utilization,
132              and for UDP data transfers also outputs the loss percentage.  In
133              client/server mode, most of the printed statistics are from  the
134              viewpoint of the receiver.  This is the default output format.
135
136       -B     This  option  is  only  valid  for  the receiver, and forces the
137              receiver to read a full buffer (as specified by the "-l"  buffer
138              length  option)  from  the network.  It is mainly intended to be
139              used with the "-s" option to only output full buffers  to  stan‐
140              dard  output (e.g. for use with tar).  It is also implicitly set
141              whenever the number of streams as specified by the  "-N"  option
142              is greater than 1.  This option is not passed to the server.
143
144       -d     For  TCP  data  transfers,  sets the SO_DEBUG option on the data
145              socket.  This option is not passed  to  the  server.   It  is  a
146              rarely used option which may possibly be removed or renamed in a
147              future version of nuttcp.
148
149       -D     This option is only valid for the transmitter, and only for  TCP
150              data  transfers, in which case it sets the TCP_NODELAY option on
151              the data socket, which turns off  the  Nagle  algorithm  causing
152              data  packets to be sent as soon as possible without introducing
153              any unnecessary delays.   This  option  is  not  passed  to  the
154              server.   It  is  a  rarely  used  option  which may possibly be
155              removed or renamed in a future version of nuttcp.
156
157       -s     Setting the "-s" option causes nuttcp to either  read  its  data
158              from  standard input rather than using prefabricated memory buf‐
159              fers (for "nuttcp -t"), or to write its  data  out  to  standard
160              output (for "nuttcp -r").  The "-s" option is disabled for secu‐
161              rity reasons on the server.
162
163       -u     Use UDP for the data transfer instead of the default of TCP.
164
165       -v     Verbose output that provides some additional information related
166              to  the  data  transfer.   In  client/server mode, the server is
167              always verbose (implicit "-v" option), but the  client  controls
168              the extent and type of output via the "-v" and "-b" options.
169
170       -cdscp_value
171              Sets  the  socket  option  to  support COS.  Either takes a dscp
172              value or with the t|T modifier it takes the full TOS field.
173
174       -lbuffer_len
175              Length of the network write/read buffer in bytes for the  trans‐
176              mitter/receiver.   It  defaults  to  64  KB (65536) for TCP data
177              transfers and to 8 KB (8192) for UDP.  For  client/server  mode,
178              it sets both the client and server buffer lengths.
179
180       -nnum_bufs
181              Specifies  the  number  of source buffers written to the network
182              (default is unlimited), and is ignored  by  the  receiver.   For
183              client/server  mode,  if the client issues a "nuttcp -r" command
184              making it the receiver, this parameter is passed to  the  server
185              since  the server is the transmitter in this case.  This parame‐
186              ter is also ignored if the "-s" parameter is  specified  to  the
187              transmitter.
188
189       -wwindow_size
190              Indicates  the window size in KB of the transmitter (for "nuttcp
191              -t") or receiver (for "nuttcp -r").  Actually, to be technically
192              correct,  it sets the sender or receiver TCP socket buffer size,
193              which then effectively sets the window size.  For  client/server
194              mode,  both  the  transmitter and receiver window sizes are set.
195              The default window size is architecture  and  system  dependent.
196              Note recent Linux systems, out of a misguided desire to be help‐
197              ful, double whatever window size is actually  specified  by  the
198              user  (this  is  not  a bug with nuttcp but a bug/feature of the
199              Linux kernel).  Also, with these Linux systems, the actual  win‐
200              dow  size  that's  used  on the intervening network, as observed
201              with tcpdump, is greater than the  requested  window  size,  but
202              less than the doubled value set by Linux.
203
204       -wsserver_window
205              For  client/server  mode,  the "-ws" option provides a mechanism
206              for setting a different window  size  on  the  server  than  the
207              client window size as specified with the "-w" option.
208
209       -wb    Normally,  to conserve memory, the transmitter only sets the TCP
210              send socket buffer size and  the  receiver  only  sets  the  TCP
211              receive  socket  buffer  size.   However, if the "-wb" option is
212              used, the transmitter will also set the TCP receive socket  buf‐
213              fer size and the receiver will also set the TCP send socket buf‐
214              fer size.  Under normal circumstances, this should never be nec‐
215              essary.   This  option  was  implemented  because  certain early
216              braindead Solaris 2.8 systems would not  properly  set  the  TCP
217              window  size  unless both the TCP send and receive socket buffer
218              sizes were set (later Solaris 2.8 systems  have  corrected  this
219              deficiency).   Thus  the 'b' in this option can stand either for
220              "braindead" or "both".
221
222       -pdata_port
223              Port number used for the data connection, which defaults to port
224              5001.   If  multiple streams are specified with the "-N" option,
225              the "-p" option specifies the starting port number for the  data
226              connection.   For  example,  if four streams are specified using
227              the default data connection port number, nuttcp will  use  ports
228              5001, 5002, 5003, and 5004 for the four TCP (or UDP) connections
229              used to perform the data transfer.
230
231       -Pcontrol_port
232              For client/server mode, specifies the port number used  for  the
233              control  connection  between the client and server, and defaults
234              to port 5000.  On the server side, the "-P" option  should  only
235              be used when the server is started manually by the user.  If the
236              server is started by inetd/xinetd (the  preferred  method),  the
237              control connection must be specified by adding a nuttcp entry to
238              the services file.
239
240       -Nnum_streams
241              Species the number of parallel TCP (or UDP) data streams  to  be
242              used for the data transfer, with the default being a single data
243              stream.  The maximum number of parallel data streams that can be
244              used  is 128.  If the number of streams is greater than one, the
245              "-B" option is implicitly set.  The current implementation  does
246              not  fork off separate processes for each data stream, so speci‐
247              fying multiple streams on an SMP machine will not take advantage
248              of  its multiple processors.  Of course it is always possible to
249              run multiple nuttcp commands in parallel on  an  SMP  system  to
250              determine  if there is any advantage to running on multiple pro‐
251              cessors.  This is  especially  simple  to  do  when  running  in
252              client/server   mode   when  the  server  is  started  from  the
253              inetd/xinetd daemon.  When running multiple nuttcp  commands  in
254              parallel,  the  "-T"  transmitter  timeout option may be used to
255              insure that all the nuttcp commands finish at approximately  the
256              same time.
257
258       -Rxmit_rate_limit[m|g]
259              The  transmitter  rate  limit  throttles  the speed at which the
260              transmitter sends data to the network,  and  by  default  is  in
261              Kbps, although the 'm' or 'g' suffix may be used to specify Mbps
262              or Gbps.  This option may be used with either TCP  or  UDP  data
263              streams.   Because  of  the  way this option is currently imple‐
264              mented, it will consume all the available CPU on the transmitter
265              side  of  the  connection  so the "%TX" stats are not meaningful
266              when using the rate limit option.  By default the rate limit  is
267              applied  to  the average rate of the data transfer in real time,
268              and not in CPU time, so if nuttcp is switched out of the proces‐
269              sor  for any reason, when it is switched back in, it is possible
270              that the instantaneous rate may momentarily exceed the specified
271              value.   There  is  an  'i'  qualifier  to the rate limit option
272              (specified as "-Ri") that will restrict the  instantaneous  rate
273              at  any  given point in time to the specified value, although in
274              this case the final rate reported by nuttcp may be less than the
275              specified  value since nuttcp won't attempt to catch up if other
276              processes gain control of the  CPU.   The  default  is  no  rate
277              limit.   Note another way to throttle the throughput of TCP data
278              streams is to reduce the window size.
279
280       -Txmit_time_limit[m]
281              Limits the amount of time that the transmitter will send data to
282              the specified number of seconds, or number of minutes if the 'm'
283              suffix is used.  Normally a data transfer will either specify  a
284              fixed  amount  of data to send using the "-n" option, or a fixed
285              period of time to send using the "-T" option.  However, if  both
286              the  "-n"  and  "-T" options are used, the data transfer will be
287              stopped by whichever option takes affect first.  The default  is
288              a 10 second time limit for the data transfer.
289

USAGE

291       Under Construction
292
293       For now, consult the README file for basic usage guidelines.
294

EXAMPLES

296       Under Construction
297
298       For now, see the examples.txt file for some examples of using nuttcp.
299

SEE ALSO

301       ping(8),    traceroute(8),   tracepath(8),   pathchar(8),   netstat(1),
302       mtrace(8)
303

AUTHORS

305       Developed by Bill Fink based on nttcp which in turn was an  enhancement
306       of  the  original ttcp developed by Mike Muuss at BRL.  IPv6 capability
307       and some other fixes and enhancements contributed by Rob  Scott.   Many
308       useful suggestions and testing performed by Phil Dykstra and others.
309
310       The current version is available via anonymous ftp from:
311
312              ftp://ftp.lcp.nrl.navy.mil/pub/nuttcp/
313
314       The authors can be reached at nuttcp@lcp.nrl.navy.mil.
315

BUGS

317       Please send bug reports to nuttcp-bugs@lcp.nrl.navy.mil.
318
319
320
321nuttcp-5.3.1                      6 June 2006                        NUTTCP(8)
Impressum