Provided by: nuttcp_6.1.2-4build1_amd64 bug

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.