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

FreeBSD Manual Pages

  
 
  

home | help
IPERF3(1)			 User Manuals			     IPERF3(1)

NAME
       iperf3 -	perform	network	throughput tests

SYNOPSIS
       iperf3 -s [ options ]
       iperf3 -c server	[ options ]

DESCRIPTION
       iperf3  is  a  tool for performing network throughput measurements.  It
       can test	TCP, UDP, or SCTP throughput.  To perform an iperf3  test  the
       user must establish both	a server and a client.

       The  iperf3  executable	contains both client and server	functionality.
       An iperf3 server	can be started using either of the -s or --server com-
       mand-line parameters, for example:

	      iperf3 -s

	      iperf3 --server

       Note  that  many	 iperf3	 parameters  have  both	 short	(-s)  and long
       (--server) forms.  In this section we will generally use	the short form
       of  command-line	 flags,	 unless	only the long form of a	flag is	avail-
       able.

       By default, the iperf3 server listens on	TCP port 5201 for  connections
       from  an	iperf3 client.	A custom port can be specified by using	the -p
       flag, for example:

	      iperf3 -s	-p 5002

       After the server	is started, it will listen for connections from	iperf3
       clients	(in  other words, the iperf3 program run in client mode).  The
       client mode can be started using	the -c command-line option, which also
       requires	a host to which	iperf3 should connect.	The host can by	speci-
       fied by hostname, IPv4 literal, or IPv6 literal:

	      iperf3 -c	iperf3.example.com

	      iperf3 -c	192.0.2.1

	      iperf3 -c	2001:db8::1

       If the iperf3 server is running on a non-default	TCP  port,  that  port
       number needs to be specified on the client as well:

	      iperf3 -c	iperf3.example.com -p 5002

       The initial TCP connection is used to exchange test parameters, control
       the start and end of the	test, and to exchange test results.   This  is
       sometimes  referred  to	as  the	"control connection".  The actual test
       data is sent over a separate TCP	connection, as a separate flow of  UDP
       packets,	or as an independent SCTP connection, depending	on what	proto-
       col was specified by the	client.

       Normally, the test data is sent from the	client to the server, and mea-
       sures  the  upload  speed  of the client.  Measuring the	download speed
       from the	server can be done by specifying the -R	flag  on  the  client.
       This causes data	to be sent from	the server to the client.

	      iperf3 -c	iperf3.example.com -p 5202 -R

       Results	are displayed on both the client and server.  There will be at
       least one line of output	per measurement	interval (by  default  a  mea-
       surement	 interval lasts	for one	second,	but this can be	changed	by the
       -i option).  Each line of output	includes (at least) the	time since the
       start  of  the test, amount of data transfered during the interval, and
       the average bitrate over	that interval.	Note that the values for  each
       measurement  interval  are taken	from the point of view of the endpoint
       process emitting	that output (in	other words, the output	on the	client
       shows the measurement interval data for the client.

       At  the	end of the test	is a set of statistics that shows (at least as
       much as possible) a summary of the test as seen by both the sender  and
       the  receiver,  with  lines tagged accordingly.	Recall that by default
       the client is the sender	and the	server is the  receiver,  although  as
       indicated above,	use of the -R flag will	reverse	these roles.

       The  client  can	be made	to retrieve the	server-side output for a given
       test by specifying the --get-server-output flag.

       Either the client or the	server can produce its output in a JSON	struc-
       ture,  useful for integration with other	programs, by passing it	the -J
       flag.  Because the contents of the JSON structure  are  only  competely
       known after the test has	finished, no JSON output will be emitted until
       the end of the test.

       iperf3 has a (overly) large set of command-line	options	 that  can  be
       used  to	 set the parameters of a test.	They are given in the "GENERAL
       OPTIONS"	section	of the manual page below, as  well  as	summarized  in
       iperf3's	help output, which can be viewed by running iperf3 with	the -h
       flag.

GENERAL	OPTIONS
       -p, --port n
	      set server port to listen	on/connect to to n (default 5201)

       -f, --format
	      [kmgtKMGT]   format to report: Kbits/Mbits/Gbits/Tbits

       -i, --interval n
	      pause n seconds between periodic throughput reports; default  is
	      1, use 0 to disable

       -F, --file name
	      Use  a  file  as	the source (on the sender) or sink (on the re-
	      ceiver) of data, rather than  just  generating  random  data  or
	      throwing	it  away.  This	feature	is used	for finding whether or
	      not the storage subsystem	is the bottleneck for file  transfers.
	      It  does not turn	iperf3 into a file transfer tool.  The length,
	      attributes, and in some cases contents of	the received file  may
	      not match	those of the original file.

       -A, --affinity n/n,m
	      Set  the CPU affinity, if	possible (Linux	and FreeBSD only).  On
	      both the client and server you can set the local affinity	by us-
	      ing  the	n form of this argument	(where n is a CPU number).  In
	      addition,	on the client  side  you  can  override	 the  server's
	      affinity for just	that one test, using the n,m form of argument.
	      Note that	when using this	feature, a process will	only be	 bound
	      to  a single CPU (as opposed to a	set containing potentialy mul-
	      tiple CPUs).

       -B, --bind host
	      bind to a	specific interface. If the host	 has  multiple	inter-
	      faces, it	will use the first interface by	default.

       -V, --verbose
	      give more	detailed output

       -J, --json
	      output in	JSON format

       --logfile file
	      send output to a log file.

       --forceflush
	      force  flushing output at	every interval.	 Used to avoid buffer-
	      ing when sending output to pipe.

       -d, --debug
	      emit debugging output.  Primarily	(perhaps exclusively)  of  use
	      to developers.

       -v, --version
	      show version information and quit

       -h, --help
	      show a help synopsis

SERVER SPECIFIC	OPTIONS
       -s, --server
	      run in server mode

       -D, --daemon
	      run the server in	background as a	daemon

       -I, --pidfile file
	      write  a file with the process ID, most useful when running as a
	      daemon.

       -1, --one-off
	      handle one client	connection, then exit.

       --rsa-private-key-path file
	      path to the RSA private key (not password-protected) used	to de-
	      crypt  authentication credentials	from the client	(if built with
	      OpenSSL support).

       --authorized-users-path file
	      path to the configuration	file containing	authorized users  cre-
	      dentials	to  run	 iperf	tests (if built	with OpenSSL support).
	      The file is a comma separated list  of  usernames	 and  password
	      hashes;  more  information  on  the structure of the file	can be
	      found in the EXAMPLES section.

CLIENT SPECIFIC	OPTIONS
       -c, --client host
	      run in client mode, connecting to	the specified server.  By  de-
	      fault,  a	 test  consists	of sending data	from the client	to the
	      server, unless the -R flag is specified.

       --sctp use SCTP rather than TCP (FreeBSD	and Linux)

       -u, --udp
	      use UDP rather than TCP

       --connect-timeout n
	      set timeout for establishing the initial control	connection  to
	      the  server, in milliseconds.  The default behavior is the oper-
	      ating system's timeout for TCP connection	 establishment.	  Pro-
	      viding  a	 shorter value may speed up detection of a down	iperf3
	      server.

       -b, --bitrate n[KM]
	      set target bitrate to n bits/sec (default	1  Mbit/sec  for  UDP,
	      unlimited	 for  TCP/SCTP).   If  there  are multiple streams (-P
	      flag), the  throughput  limit  is	 applied  separately  to  each
	      stream.	You  can  also	add  a '/' and a number	to the bitrate
	      specifier.  This is called "burst	mode".	It will	send the given
	      number  of packets without pausing, even if that temporarily ex-
	      ceeds the	specified throughput limit.  Setting  the  target  bi-
	      trate  to	0 will disable bitrate limits (particularly useful for
	      UDP tests).  This	throughput limit is implemented	internally in-
	      side  iperf3,  and  is available on all platforms.  Compare with
	      the --fq-rate flag.  This	option replaces	the --bandwidth	 flag,
	      which is now deprecated but (at least for	now) still accepted.

       --pacing-timer n[KMG]
	      set  pacing  timer  interval  in	microseconds (default 1000 mi-
	      croseconds, or 1 ms).  This controls  iperf3's  internal	pacing
	      timer  for  the -b/--bitrate option.  The	timer fires at the in-
	      terval set by this parameter.   Smaller  values  of  the	pacing
	      timer  parameter	smooth	out the	traffic	emitted	by iperf3, but
	      potentially at the cost of  performance  due  to	more  frequent
	      timer processing.

       --fq-rate n[KM]
	      Set a rate to be used with fair-queueing based socket-level pac-
	      ing, in bits per second.	This pacing (if	specified) will	be  in
	      addition	to any pacing due to iperf3's internal throughput pac-
	      ing (-b/--bitrate	flag), and both	can be specified for the  same
	      test.   Only  available  on platforms supporting the SO_MAX_PAC-
	      ING_RATE socket option (currently	only Linux).  The  default  is
	      no fair-queueing based pacing.

       --no-fq-socket-pacing
	      This option is deprecated	and will be removed.  It is equivalent
	      to specifying --fq-rate=0.

       -t, --time n
	      time in seconds to transmit for (default 10 secs)

       -n, --bytes n[KM]
	      number of	bytes to transmit (instead of -t)

       -k, --blockcount	n[KM]
	      number of	blocks (packets) to transmit (instead of -t or -n)

       -l, --length n[KM]
	      length of	buffer to read or write.  For TCP tests,  the  default
	      value is 128KB.  In the case of UDP, iperf3 tries	to dynamically
	      determine	a reasonable sending size based	on the	path  MTU;  if
	      that  cannot be determined it uses 1460 bytes as a sending size.
	      For SCTP tests, the default size is 64KB.

       --cport port
	      bind data	streams	to a specific client port  (for	 TCP  and  UDP
	      only, default is to use an ephemeral port)

       -P, --parallel n
	      number  of  parallel  client streams to run. Note	that iperf3 is
	      single threaded, so if you are CPU bound,	this  will  not	 yield
	      higher throughput.

       -R, --reverse
	      reverse  the  direction of a test, so that the server sends data
	      to the client

       -w, --window n[KM]
	      window size / socket buffer size (this gets sent to  the	server
	      and used on that side too)

       -M, --set-mss n
	      set TCP/SCTP maximum segment size	(MTU - 40 bytes)

       -N, --no-delay
	      set TCP/SCTP no delay, disabling Nagle's Algorithm

       -4, --version4
	      only use IPv4

       -6, --version6
	      only use IPv6

       -S, --tos n
	      set the IP type of service

       --dscp dscp
	      set  the IP DSCP bits.  Both numeric and symbolic	values are ac-
	      cepted.

       -L, --flowlabel n
	      set the IPv6 flow	label (currently only supported	on Linux)

       -X, --xbind name
	      Bind SCTP	associations to	 a  specific  subset  of  links	 using
	      sctp_bindx(3).   The  --B	 flag  will be ignored if this flag is
	      specified.  Normally SCTP	will include the protocol addresses of
	      all  active  links on the	local host when	setting	up an associa-
	      tion. Specifying at least	one --X	name will disable this	behav-
	      iour.   This flag	must be	specified for each link	to be included
	      in the association, and is supported for both iperf servers  and
	      clients (the latter are supported	by passing the first --X argu-
	      ment to bind(2)).	 Hostnames are accepted	as arguments  and  are
	      resolved	using  getaddrinfo(3).	 If  the  --4 or --6 flags are
	      specified, names which do	not resolve to	addresses  within  the
	      specified	protocol family	will be	ignored.

       --nstreams n
	      Set number of SCTP streams.

       -Z, --zerocopy
	      Use  a  "zero copy" method of sending data, such as sendfile(2),
	      instead of the usual write(2).

       -O, --omit n
	      Omit the first n seconds of the test, to skip past the TCP slow-
	      start period.

       -T, --title str
	      Prefix every output line with this string.

       -C, --congestion	algo
	      Set  the	congestion control algorithm (Linux and	FreeBSD	only).
	      An older --linux-congestion synonym for this  flag  is  accepted
	      but is deprecated.

       --get-server-output
	      Get the output from the server.  The output format is determined
	      by the server (in	particular, if the server was invoked with the
	      --json  flag,  the  output  will be in JSON format, otherwise it
	      will be in human-readable	format).  If the client	 is  run  with
	      --json,  the  server output is included in a JSON	object;	other-
	      wise it is appended at the bottom	of the human-readable output.

       --username username
	      username to use for authentication to the	iperf server (if built
	      with OpenSSL support).  The password will	be prompted for	inter-
	      actively when the	test is	run.

       --rsa-public-key-path file
	      path to the RSA public key used to encrypt  authentication  cre-
	      dentials (if built with OpenSSL support)

EXAMPLES
   Authentication - RSA	Keypair
       The authentication feature of requires an RSA public keypair.  The pub-
       lic key is used to encrypt the authentication token containing the user
       credentials,  while  the	private	key is used to decrypt the authentica-
       tion token.  An example of a set	of  UNIX/Linux	commands  to  generate
       correct keypair follows:

	    > openssl genrsa -des3 -out	private.pem 2048
	    > openssl rsa -in private.pem -outform PEM -pubout -out public.pem
	    > openssl rsa -in private.pem -out private_not_protected.pem -out-
	    form PEM

       After these commands, the public	key will be contained in the file pub-
       lic.pem	and  the  private  key	will  be  contained  in	 the file pri-
       vate_not_protected.pem.

   Authentication - Authorized users configuration file
       A simple	plaintext file must be provided	to the iperf3 server in	 order
       to  specify the authorized user credentials.  The file is a simple list
       of comma-separated pairs	of a username  and  a  corresponding  password
       hash.   The password hash is a SHA256 hash of the string	"{$user}$pass-
       word".  The file	can also contain commented lines (starting with	the  #
       character).   An	example	of commands to generate	the password hash on a
       UNIX/Linux system is given below:

	    > S_USER=mario S_PASSWD=rossi
	    > echo -n "{$S_USER}$S_PASSWD" | sha256sum | awk '{	print $1 }'

       An example of a password	file (with an entry corresponding to the above
       username	and password) is given below:
	    > cat credentials.csv
	    # file format: username,sha256
	    mario,bf7a49a846d44b454a5d11e7ac-
	    faf13d138bbe0b7483aa3e050879700572709b

AUTHORS
       A list of the contributors to iperf3 can	be found within	the documenta-
       tion located at http://software.es.net/iperf/dev.html#authors.

SEE ALSO
       libiperf(3), http://software.es.net/iperf

ESnet				   June	2017			     IPERF3(1)

NAME | SYNOPSIS | DESCRIPTION | GENERAL OPTIONS | SERVER SPECIFIC OPTIONS | CLIENT SPECIFIC OPTIONS | EXAMPLES | AUTHORS | SEE ALSO

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

home | help