Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
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
       buffers from a source system across an  interconnecting	network	 to  a
       destination  system,  either transferring data for a specified time in-
       terval, 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	trans-
       fer 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 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 de-
       sired 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 de-
       fault, the nuttcp server	listens	for commands on	port 5000, and the ac-
       tual 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  re-
       ceiver.	 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  us-
       ing  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 re-
	      ceiver 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  re-
	      moved 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 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  al-
	      ways 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  re-
	      ceive 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 So-
	      laris 2.8	systems	would not properly set the TCP window size un-
	      less 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 de-
	      termine if there is any advantage	to running on multiple proces-
	      sors.   This  is	especially  simple  to	do  when  running   in
	      client/server  mode  when	 the  server  is  started from the in-
	      etd/xinetd daemon.  When running	multiple  nuttcp  commands  in
	      parallel,	the "-T" transmitter timeout option may	be used	to in-
	      sure  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)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=nuttcp&sektion=8&manpath=FreeBSD+Ports+14.3.quarterly>

home | help