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 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 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  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  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)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | USAGE | EXAMPLES | SEE ALSO | AUTHORS | BUGS

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

home | help