NUTTCP(8)                     Under Construction                     NUTTCP(8)



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 buf‐
       fers from a source system across an interconnecting network to a desti‐
       nation  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 pro‐
       vides additional useful information related to the data  transfer  such
       as user, system, and wall-clock time, transmitter and receiver CPU uti‐
       lization, 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 perfor‐
       mance 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 abil‐
       ity to set the maximum segment size or TOS/DSCP bits.  nuttcp  is  con‐
       tinuing  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  trans‐
       mitter 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 advan‐
       tages, including being more robust, allowing multiple simultaneous con‐
       nections,  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 transmit‐
       ter/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  stan‐
       dard  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"  ver‐
              bose  output  is used (but not when using the default brief out‐
              put).  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 ini‐
              tiated 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 stan‐
              dard 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  buf‐
              fers  (for  "nuttcp  -t"),  or to write its data out to standard
              output (for "nuttcp -r").  The "-s" option is disabled for secu‐
              rity 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 trans‐
              mitter/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  parame‐
              ter  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 help‐
              ful,  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 win‐
              dow 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 buf‐
              fer size and the receiver will also set the TCP send socket buf‐
              fer size.  Under normal circumstances, this should never be nec‐
              essary.  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  speci‐
              fying 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  pro‐
              cessors.   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  imple‐
              mented, 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 proces‐
              sor 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.



nuttcp-v8.1.4                   3 February 2007                      NUTTCP(8)
