IPERF(1)                                   User Manuals                                  IPERF(1)

NAME
       iperf - perform network throughput tests

SYNOPSIS
       iperf -s [ options ]

       iperf -c server [ options ]

       iperf -u -s [ options ]

       iperf -u -c server [ options ]

DESCRIPTION
       iperf is a tool for performing network throughput measurements.  It can test either TCP or
       UDP throughput.  To perform an iperf test the user must establish both a server  (to  dis-
       card traffic) and a client (to generate traffic).

GENERAL OPTIONS
       -b, --bandwidth
              set the target bandwidth (and optional standard devation where supported)

       -e, --enhanced
              Display  enhanced output in reports otherwise use legacy report (ver 2.0.5) format-
              ting (see notes)

       -f, --format
              [abkmgBKMG]   format to report: adaptive, bits, Bytes, Kbits, Mbits, Gbits, KBytes,
              MBytes, GBytes (see NOTES for more)

       -h, --help
              print a help synopsis

       -i, --interval n
              pause n seconds between periodic bandwidth reports

       -l, --len n[kmKM]
              set  read/write  buffer  size (TCP) or length (UDP) to n (TCP default 128K, UDP de-
              fault 1470)

           --l2checks
              perform layer 2 length checks on received UDP packets (requires systems  that  sup-
              port packet sockets, e.g. Linux)

       -m, --print_mss
              print TCP maximum segment size (MTU - TCP/IP header)

       -o, --output filename
              output the report or error message to this specified file

       -p, --port n
              set server port to listen on/connect to to n (default 5001)

       -u, --udp
              use UDP rather than TCP

           --udp-counters-64bit
              use 64 bit UDP sequence numbers

       -w, --window n[kmKM]
              TCP window size (socket buffer size)

       -z, --realtime
              Request realtime scheduler, if supported.

       -B, --bind host
              bind to host, ip address or multicast address and optional port (see notes)

       -C, --compatibility
              for use with older versions does not sent extra msgs

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

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

       -v, --version
              print version information and quit

       -x, --reportexclude [CDMSV]
              exclude C(connection) D(data) M(multicast) S(settings) V(server) reports

       -y, --reportstyle C|c
              if set to C or c report results as CSV (comma separated values)

SERVER SPECIFIC OPTIONS
       -b, --bandwidth n[kmgKMG]
              set target read rate to n bits/sec. TCP only for the server.

       -s, --server
              run in server mode

           --udp-histogram[=binwidth[u],bincount,[lowerci],[upperci]]
              output  UDP  latency histograms, bin width (default 1 millisecond, append u for mi-
              croseconds,) bincount is total bins (default 1000), ci is confidence  interval  be-
              tween 0-100% (default lower 5%, upper 95%)

       -B, --bind ip | ip%device
              bind src ip addr and optional src device for receiving

       -D, --daemon
              run the server as a daemon.  On Windows this will also install the IPerfService.

       -H, --ssm-host host
              Set the source host (ip addr) per SSM multicast, i.e. the S of the S,G

       -R, --remove
              remove the IPerfService (Windows only).

       -U, --single_udp
              run in single threaded UDP mode

       -V, --ipv6_domain
              Enable  IPv6 reception by setting the domain and socket to AF_INET6 (Can receive on
              both IPv4 and IPv6)

CLIENT SPECIFIC OPTIONS
       -b, --bandwidth n[kmgKMG] | npps
              set target bandwidth to n bits/sec (default 1 Mbit/sec) or n packets per sec.  This
              may be used with TCP or UDP.  For variable loads use format mean,standard deviation

       -c, --client host
              run in client mode, connecting to host

       -d, --dualtest
              Do a bidirectional test simultaneously

           --incr-dstip
              increment the destination ip address when using the parallel (-P) option

           --ipg n
              set  the  interpacket  gap  to  n  (units  of  milliseconds)  for packets within an
              isochronous frame (burst), requires --isochronous

           --isochronous[=fps:mean,stdev]
              send isochronous traffic with frequency frames per second and load defined by  mean
              and standard deviation using a log normal distribution, defaults to 60:20m,0

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

       -r, --tradeoff
              Do a bidirectional test individually

       -t, --time n
              time  in seconds to listen for new traffic connections, receive traffic or transmit
              traffic (Defaults: transmit is 10 secs while listen and receive are indefinite)

           --tx-sync n
              set the tx-sync interval to n (units of seconds) for synchronized packet writes

       -B, --bind ip | ip:port | ipv6 -V | [ipv6]:port -V
              bind src ip addr and optional port as the source of traffic (see notes)

       -F, --fileinput name
              input the data to be transmitted from a file

       -I, --stdin
              input the data to be transmitted from stdin

       -L, --listenport n
              port to receive bidirectional tests back on

       -P, --parallel n
              number of parallel client threads to run

       -R, --reverse
              reverse the traffic flow after header exchange, useful for  testing  through  fire-
              walls

       -S, --tos
              set the socket's IP_TOS (byte) field

       -T, --ttl n
              time-to-live,  for  multicast  (default 1) -V, --ipv6_domain Set the domain to IPv6
              (send packets over IPv6)

       -X, --peerdetect
              run server version detection prior to traffic.

       -Z, --linux-congestion algo
              set TCP congestion control algorithm (Linux only)

ENVIRONMENT
       TCP_WINDOW_SIZE
              Controls the size of TCP buffers.

NOTES
       Some numeric options support format characters per '<value>c' (e.g. 10M) where the c  for-
       mat  characters are k,m,g,K,M,G.  Lowercase format characters are 10^3 based and uppercase
       are 2^n based, e.g. 1k = 1000, 1K = 1024, 1m = 1,000,000 and 1M = 1,048,576

       The -b option supports variable offered loads through the <mean>,<standard deviation> for-
       mat,  e.g.  -b  100m,10m on the client.  The distribution used is log normal.  Similar for
       the isochronous option.

       The -e or --enhanced latency output on the UDP servers assumes the clients'  and  servers'
       system  clocks  are  synchronized.  Network Time Protocol (NTP) or Precision Time Protocol
       (PTP) are commonly used for this.  The reference clock(s) or oscillator's error will  also
       affect the accuracy of UDP latency measurements.

       The -B option affects the bind() system call.  This is typically used to bind to a partic-
       ular IP address. Only packets destined to that IP  address  will  be  received  while  any
       transmitted  packets  will carry that IP address as their source. The bind() does not con-
       trol anything about the routing of transmitted packets. So, for example, if the IP address
       of  eth0  is used for -B and the routing table for the destination IP address (per -c) re-
       solves the output interface to be eth1, then the host will send the packet out device eth1
       with  the  source  IP address of eth0.  To affect the physical output interface (e.g. dual
       homed systems) the host's routing table(s) need to be configured,  e.g.  configure  policy
       routing per each -B source address.

DIAGNOSTICS
       This section needs to be filled in.

BUGS
       See https://sourceforge.net/p/iperf2/tickets/

AUTHORS
       Iperf2,  based  from  iperf  (originally written by Mark Gates and Alex Warshavsky), has a
       goal of maintenance with some feature enhancement.  Other contributions  from  Ajay  Tiru-
       mala,  Jim  Ferguson, Jon Dugan <jdugan at x1024 dot net>, Feng Qin, Kevin Gibbs, John Es-
       tabrook <jestabro at ncsa.uiuc.edu>, Andrew Gallatin <gallatin at gmail.com>, Stephen Hem-
       minger <shemminger at linux-foundation.org>, Tim Auckland, Robert J. McMahon <rjmcmahon at
       rjmcmahon.com>

SEE ALSO
       http://sourceforge.net/projects/iperf2/

NLANR/DAST                                  APRIL 2008                                   IPERF(1)

Usage: iperf [-s|-c host] [options]
       iperf [-h|--help] [-v|--version]

Client/Server:
  -b, --bandwidth #[kmgKMG | pps]  bandwidth to send at in bits/sec or packets per second
  -e, --enhancedreports    use enhanced reporting giving more tcp/udp and traffic information
  -f, --format    [kmgKMG]   format to report: Kbits, Mbits, KBytes, MBytes
  -i, --interval  #        seconds between periodic bandwidth reports
  -l, --len       #[kmKM]    length of buffer in bytes to read or write (Defaults: TCP=128K, v4 UDP=1470, v6 UDP=1450)
  -m, --print_mss          print TCP maximum segment size (MTU - TCP/IP header)
  -o, --output    <filename> output the report or error message to this specified file
  -p, --port      #        server port to listen on/connect to
  -u, --udp                use UDP rather than TCP
      --udp-counters-64bit use 64 bit sequence numbers with UDP
  -w, --window    #[KM]    TCP window size (socket buffer size)
  -z, --realtime           request realtime scheduler
  -B, --bind <host>[:<port>][%<dev>] bind to <host>, ip addr (including multicast address) and optional port and device
  -C, --compatibility      for use with older versions does not sent extra msgs
  -M, --mss       #        set TCP maximum segment size (MTU - 40 bytes)
  -N, --nodelay            set TCP no delay, disabling Nagle's Algorithm
  -S, --tos       #        set the socket's IP_TOS (byte) field

Server specific:
  -s, --server             run in server mode
  -t, --time      #        time in seconds to listen for new connections as well as to receive traffic (default not set)
      --udp-histogram #,#  enable UDP latency histogram(s) with bin width and count, e.g. 1,1000=1(ms),1000(bins)
  -B, --bind <ip>[%<dev>]  bind to multicast address and optional device
  -H, --ssm-host <ip>      set the SSM source, use with -B for (S,G) 
  -U, --single_udp         run in single threaded UDP mode
  -D, --daemon             run the server as a daemon
  -V, --ipv6_domain        Enable IPv6 reception by setting the domain and socket to AF_INET6 (Can receive on both IPv4 and IPv6)

Client specific:
  -c, --client    <host>   run in client mode, connecting to <host>
  -d, --dualtest           Do a bidirectional test simultaneously
      --ipg                set the the interpacket gap (milliseconds) for packets within an isochronous frame
      --isochronous <frames-per-second>:<mean>,<stddev> send traffic in bursts (frames - emulate video traffic)
  -n, --num       #[kmgKMG]    number of bytes to transmit (instead of -t)
  -r, --tradeoff           Do a bidirectional test individually
  -t, --time      #        time in seconds to transmit for (default 10 secs)
  -B, --bind [<ip> | <ip:port>] bind ip (and optional port) from which to source traffic
  -F, --fileinput <name>   input the data to be transmitted from a file
  -I, --stdin              input the data to be transmitted from stdin
  -L, --listenport #       port to receive bidirectional tests back on
  -P, --parallel  #        number of parallel client threads to run
  -R, --reverse            reverse the test (client receives, server sends)
  -T, --ttl       #        time-to-live, for multicast (default 1)
  -V, --ipv6_domain        Set the domain to IPv6 (send packets over IPv6)
  -X, --peer-detect        perform server version detection and version exchange
  -Z, --linux-congestion <algo>  set TCP congestion control algorithm (Linux only)

Miscellaneous:
  -x, --reportexclude [CDMSV]   exclude C(connection) D(data) M(multicast) S(settings) V(server) reports
  -y, --reportstyle C      report as a Comma-Separated Values
  -h, --help               print this message and quit
  -v, --version            print version information and quit

[kmgKMG] Indicates options that support a k,m,g,K,M or G suffix
Lowercase format characters are 10^3 based and uppercase are 2^n based
(e.g. 1k = 1000, 1K = 1024, 1m = 1,000,000 and 1M = 1,048,576)

The TCP window size option can be set by the environment variable
TCP_WINDOW_SIZE. Most other options can be set by an environment variable
IPERF_<long option name>, such as IPERF_BANDWIDTH.

Source at <http://sourceforge.net/projects/iperf2/>
Report bugs to <iperf-users@lists.sourceforge.net>