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 bytes.  In addition
31       to  reporting the achieved network throughput in Mbps, nuttcp also pro‐
32       vides additional useful information related to the data  transfer  such
33       as user, system, and wall-clock time, transmitter and receiver CPU uti‐
34       lization, 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       More recent changes include IPv6 support, IPv4 multicast, and the abil‐
44       ity to set the maximum segment size or TOS/DSCP bits.  nuttcp  is  con‐
45       tinuing  to  evolve  to  meet  new  requirements  that arise and to add
46       desired new features.  nuttcp has been successfully built and run on  a
47       variety of Solaris, SGI, and PPC/X86 Linux systems, and should probably
48       work fine on most flavors of Unix.  It has also been used  successfully
49       on various versions of the Windows operating system.
50
51       There  are  two  basic  modes of operation for nuttcp.  The original or
52       classic mode is the transmitter/receiver mode, which is  also  the  way
53       the  original ttcp and nttcp worked.  In this mode, a receiver is first
54       initiated on the destination host using "nuttcp -r", and then a  trans‐
55       mitter must be started on the source host using "nuttcp -t".  This mode
56       is somewhat deprecated and is no longer recommended  for  general  use.
57       The  preferred  and recommended mode of operation for nuttcp is the new
58       client/server mode.  With this mode, a server is first started  on  one
59       system using "nuttcp -S" (or "nuttcp -1"), and then a client may either
60       transmit data to (using  "nuttcp  -t")  or  receive  data  from  (using
61       "nuttcp -r") the server system.  All the information provided by nuttcp
62       is reported by the client, including the information from  the  server,
63       thus  providing  a  full  snapshot of both the transmitter and receiver
64       ends of the data transfer.
65
66       The server may be started by a normal, non-privileged user  by  issuing
67       either  a  "nuttcp  -S" or a "nuttcp -1" command.  However, the optimal
68       and recommended method of running a server is to run  "nuttcp  -S"  via
69       the  inetd/xinetd  daemon.   This method has several significant advan‐
70       tages, including being more robust, allowing multiple simultaneous con‐
71       nections,  and  providing for access control over who is allowed to use
72       the nuttcp server  via  the  hosts.allow  (and  hosts.deny)  file.   By
73       default,  the  nuttcp server listens for commands on port 5000, and the
74       actual nuttcp data transfers take place on port 5001.
75
76       The host parameter must be specified for the transmitter, and  provides
77       the  host  name  or  IP  address of the receiver.  In classic transmit‐
78       ter/receiver mode, the host parameter may  not  be  specified  for  the
79       receiver.   In client/server mode, when the client is the receiver, the
80       host parameter specifies the host name or IP address of the transmitter
81       (server).
82
83       Normally,  a  nuttcp  data  transfer  is memory-to-memory.  However, by
84       using the "-s" option, it is possible to also  perform  memory-to-disk,
85       disk-to-memory, and disk-to-disk data transfers.  Using the "-s" option
86       with the transmitter will cause nuttcp to read its data from the  stan‐
87       dard  input instead of using a prefabricated memory buffer, while using
88       the "-s" option on the receiver causes nuttcp  to  write  its  data  to
89       standard  output.   All these types of data transfers are possible with
90       the classic transmitter/receiver mode.  For security reasons, the  "-s"
91       option  is  disabled on the server, so it is not possible to access the
92       disk on the server side of a data transfer.
93
94       The allowed options to nuttcp are:
95

OPTIONS

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

USAGE

294       Under Construction
295
296       For now, consult the README file for basic usage guidelines.
297

EXAMPLES

299       Under Construction
300
301       For now, see the examples.txt file for some examples of using nuttcp.
302

SEE ALSO

304       ping(8),   traceroute(8),   tracepath(8),   pathchar(8),    netstat(1),
305       mtrace(8)
306

AUTHORS

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

BUGS

320       Please send bug reports to nuttcp-bugs@lcp.nrl.navy.mil.
321
322
323
324nuttcp-v6.1.2                   3 February 2007                      NUTTCP(8)
Impressum