1IPERF(1)                         User Manuals                         IPERF(1)
2
3
4

NAME

6       iperf  -  perform  network traffic tests using network sockets. Metrics
7       include throughput and latency.
8

SYNOPSIS

10       iperf -s [options]
11
12       iperf -c server [options]
13
14       iperf -u -s [options]
15
16       iperf -u -c server [options]
17
18

DESCRIPTION

20       iperf 2 is a testing tool which performs network  traffic  measurements
21       using  network  sockets.  The  performance  metrics  supported  include
22       throughput and latency. Iperf can use both TCP and UDP sockets (or pro‐
23       tocols.)  It  supports  unidirectional,  full  duplex (same socket) and
24       bidirectional traffic,  and  supports  multiple,  simultaneous  traffic
25       streams. It supports multicast traffic including source specific multi‐
26       cast (SSM) joins. Its multi-threaded design  allows  for  peak  perfor‐
27       mance. Metrics displayed help to characterize host to host network per‐
28       formance. Note: Setting the enhanced (-e) option provides all available
29       metrics.
30
31       The user must establish both a both a server (to receive traffic) and a
32       client (to generate and send traffic) for a test to occur.  The  client
33       and  server  typically are on different hosts or computers but need not
34       be.
35

GENERAL OPTIONS

37       -b, --bandwidth
38              set the target bandwidth and  optional  standard  deviation  per
39              <mean>,[<stdev>] (See NOTES for suffixes)
40
41       -e, --enhanced
42              Display  enhanced  output in reports otherwise use legacy report
43              (ver 2.0.5) formatting (see NOTES)
44
45       -f, --format [abkmgBKMG]
46              format to report: adaptive, bits, Bytes,  Kbits,  Mbits,  Gbits,
47              KBytes, MBytes, GBytes (see NOTES for more)
48
49       -h, --help
50              print a help synopsis
51
52           --hide-ips
53              obscure  ip  addresses in output (useful when wanting to publish
54              results and not display the full ip addresses. v4 only)
55
56       -i, --interval < t | f >
57              sample or display interval reports every t seconds (default)  or
58              every  frame  or burst, i.e. if f is used then the interval will
59              be each frame or burst. The frame interval reporting is  experi‐
60              mental.   Also suggest a compile with fast-sampling, i.e. ./con‐
61              figure --enable-fastsampling
62
63       -l, --len n[kmKM]
64              set read/write buffer size (TCP) or length (UDP) to n  (TCP  de‐
65              fault 128K, UDP default 1470)
66
67           --l2checks
68              perform  layer 2 length checks on received UDP packets (requires
69              systems that support packet sockets, e.g. Linux)
70
71       -m, --print_mss
72              print TCP maximum segment size (MTU - TCP/IP header)
73
74           --NUM_REPORT_STRUCTS <count>
75              Override the default shared  memory  size  between  the  traffic
76              thread(s)  and  reporter  thread in order to mitigate mutex lock
77              contentions. The default value of 5000 should be sufficient  for
78              1Gb/s networks. Increase this upon seeing the Warning message of
79              reporter thread too slow. If the  Warning  message  isn't  seen,
80              then  increasing  this  won't have any significant effect (other
81              than to use some additional memory.)
82
83       -o, --output filename
84              output the report or error message to this specified file
85
86           --permit-key [=<value>]
87              Set a key value that must match for the server to accept traffic
88              on  a  connection. If the option is given without a value on the
89              server a key value will be autogenerated and  displayed  in  its
90              initial  settings  report.  The lifetime of the key is set using
91              --permit-key-timeout and defaults to twenty seconds.  The  value
92              is  required  on clients. The value will also be used as part of
93              the transfer id in reports. The option set on the client but not
94              the  server  will  also  cause the server to reject the client's
95              traffic. TCP only, no UDP support.
96
97       -p, --port m[-n]
98              set client or server port(s) to send or listen on per m (default
99              5001)  w/optional  port  range  per m-n (e.g. -p 6002-6008) (see
100              NOTES)
101
102           --sum-dstip
103              sum traffic threads based upon the destination IP  address  (de‐
104              fault is source ip address)
105
106           --sum-only
107              set  the output to sum reports only. Useful for -P at large val‐
108              ues
109
110       -t, --time n
111              time in seconds to listen for new traffic  connections,  receive
112              traffic or send traffic
113
114       -u, --udp
115              use UDP rather than TCP
116
117       -w, --window n[kmKM]
118              TCP window size (socket buffer size)
119
120       -z, --realtime
121              Request real-time scheduler, if supported.
122
123       -B, --bind host[:port][%dev]
124              bind  to host, ip address or multicast address, optional port or
125              device (see NOTES)
126
127       -C, --compatibility
128              for use with older versions does not sent extra msgs
129
130       -M, --mss n
131              set TCP maximum segment size (MTU - 40 bytes)
132
133       -N, --nodelay
134              set TCP no delay, disabling Nagle's Algorithm
135
136       -v, --version
137              print version information and quit
138
139       -x, --reportexclude [CDMSV]
140              exclude C(connection) D(data) M(multicast) S(settings) V(server)
141              reports
142
143       -y, --reportstyle C|c
144              if set to C or c report results as CSV (comma separated values)
145
146       -Z, --tcp-congestion
147              Set  the default congestion-control algorithm to be used for new
148              connections. Platforms must support setsockopt's TCP_CONGESTION.
149              (Notes: See sysctl and tcp_allowed_congestion_control for avail‐
150              able options. May require root privileges.)
151

SERVER SPECIFIC OPTIONS

153       -1, --singleclient
154              set the server to process only one client at a time
155
156       -b, --bandwidth n[kmgKMG]
157              set target read rate to n bits/sec. TCP only for the server.
158
159       -s, --server
160              run in server mode
161
162           --histograms[=binwidth[u],bincount,[lowerci],[upperci]]
163              enable latency histograms for udp packets (-u), for  tcp  writes
164              (with --trip-times), or for either udp or tcp with --isochronous
165              clients. The binning can be modified. Bin widths (default 1 mil‐
166              lisecond,  append  u  for microseconds, m for milliseconds) bin‐
167              count is total bins (default 1000), ci  is  confidence  interval
168              between 0-100% (default lower 5%, upper 95%, 3 stdev 99.7%)
169
170           --permit-key [=<value>]
171              Set a key value that must match for the server to accept traffic
172              from a client (also set with --permit-key.) The server will  au‐
173              togenerate  a globally unique key when the option is given with‐
174              out a value. This value will be displayed in the  server's  ini‐
175              tial  settings  report.  The  lifetime  of  the key is set using
176              --permit-key-timeout and defaults to twenty seconds.  TCP  only,
177              no UDP support.
178
179           --permit-key-timeout <value>
180              Set  the  lifetime  of the permit key in seconds. Defaults to 20
181              seconds if not set. A value of zero will disable the timer.
182
183           --tcp-rx-window-clamp n[kmKM]
184              Set the socket option of TCP_WINDOW_CLAMP, units is bytes.
185
186       -t, --time n
187              time in seconds to listen for new traffic connections and/or re‐
188              ceive traffic (defaults to infinite)
189
190       -B, --bind ip | ip%device
191              bind src ip addr and optional src device for receiving
192
193       -D, --daemon
194              run  the server as a daemon. On Windows this will run the speci‐
195              fied command-line under the IPerfService, installing the service
196              if  necessary.  Note the service is not configured to auto-start
197              or restart - if you need a self-starting service you  will  need
198              to create an init script or use Windows "sc" commands.
199
200       -H, --ssm-host host
201              Set  the  source host (ip addr) per SSM multicast, i.e. the S of
202              the S,G
203
204       -R, --remove
205              remove the IPerfService (Windows only).
206
207       -U, --single_udp
208              run in single threaded UDP mode
209
210       -V, --ipv6_domain
211              Enable IPv6 reception  by  setting  the  domain  and  socket  to
212              AF_INET6 (Can receive on both IPv4 and IPv6)
213

CLIENT SPECIFIC OPTIONS

215       -b, --bandwidth n[kmgKMG][,n[kmgKMG]] | n[kmgKMG]pps
216              set  target  bandwidth  to  n bits/sec (default 1 Mbit/sec) or n
217              packets per sec. This may be used with TCP or  UDP.  Optionally,
218              for variable loads, use format of  mean,standard deviation
219
220       -c, --client host | host%device
221              run  in client mode, connecting to host  where the optional %dev
222              will SO_BINDTODEVICE that output interface  (requires  root  and
223              see NOTES)
224
225           --burst-period[=n]
226              Set  the burst period in seconds. Defaults to one second. (Note:
227              assumed use case is low duty cycle traffic bursts)
228
229           --burst-size[=n]
230              Set the burst size in bytes. Defaults  to  1M  if  no  value  is
231              given.
232
233           --connect-only[=n]
234              only  perform a TCP connect (or 3WHS) without any data transfer,
235              useful to measure TCP connect() times. Optional value  of  n  is
236              the  total  number of connects to do (zero is run forever.) Note
237              that -i will rate limit the connects where -P will create bursts
238              and -t will end the client and hence end its connect attempts.
239
240           --connect-retries[= n]
241              number of times to retry a TCP connect at the application level.
242              See operating system information on the details of  TCP  connect
243              related settings.
244
245       -d, --dualtest
246              Do  a  bidirectional  test simultaneous test using two unidirec‐
247              tional sockets
248
249           --fq-rate n[kmgKMG]
250              Set a rate to be used with fair-queueing based socket-level pac‐
251              ing,  in  bytes  or bits per second. Only available on platforms
252              supporting the SO_MAX_PACING_RATE socket option. (Note: Here the
253              suffixes  indicate bytes/sec or bits/sec per use of uppercase or
254              lowercase, respectively)
255
256           --full-duplex
257              run a full duplex test, i.e. traffic in both  transmit  and  re‐
258              ceive directions using the same socket
259
260           --histograms[=binwidth[u],bincount,[lowerci],[upperci]]
261              enable  select()/write()  histograms  with --tcp-write-prefetch.
262              The binning can be modified. Bin widths (default  100  microsec‐
263              onds, append u for microseconds, m for milliseconds) bincount is
264              total bins (default 10000), ci is  confidence  interval  between
265              0-100% (default lower 5%, upper 95%, 3 stdev 99.7%)
266
267           --incr-dstip
268              increment  the  destination  ip  address when using the parallel
269              (-P) option
270
271           --incr-dstport
272              increment the destination port when using the parallel (-P)  op‐
273              tion
274
275           --incr-srcip
276              increment the source ip address when using the parallel (-P) op‐
277              tion
278
279           --ipg n
280              set the inter-packet gap to n (units of seconds) for packets  or
281              within a frame/burst when --isochronous is set
282
283           --isochronous[=fps:mean,stdev]
284              send  isochronous  traffic  with frequency frames per second and
285              load defined by mean and standard deviation using a  log  normal
286              distribution, defaults to 60:20m,0. (Note: Here the suffixes in‐
287              dicate bytes/sec or bits/sec per use of uppercase or  lowercase,
288              respectively.  Also  the  p suffix is supported to set the burst
289              size in packets, e.g. isochronous=2:25p will send two 25  packet
290              bursts every second, or one 25 packet burst every 0.5 seconds.)
291
292           --local-only[=1|0]
293              Set  1  to  limit traffic to the local network only (through the
294              use of SO_DONTROUTE) set to zero otherwise with  optional  over‐
295              ride of compile time default (see configure --default-localonly)
296
297           --near-congestion[=n]
298              Enable TCP write rate limiting per the sampled RTT. The delay is
299              applied after the -l number of bytes  have  completed.  The  op‐
300              tional  value  is the multiplier to the RTT and defines the time
301              delay. This value defaults to 0.5 if it is not set. Values  less
302              than  1  are supported but the value cannot be negative. This is
303              an experimental feature. It is not likely stable  on  live  net‐
304              works. Suggested use is over controlled test networks.
305
306           --no-connect-sync
307              By  default,  parallel  traffic  threads (per -P greater than 1)
308              will synchronize after their TCP  connects  and  prior  to  each
309              sending  traffic, i.e. all the threads first complete (or error)
310              the TCP 3WHS before any traffic thread will start sending.  This
311              option  disables  that  synchronization  such  that each traffic
312              thread will start sending immediately after completing its  suc‐
313              cessful connect.
314
315           --no-udp-fin
316              Don't  perform  the  UDP  final  server to client exchange which
317              means there won't be a final  server  report  displayed  on  the
318              client.  All packets per the test will be from the client to the
319              server and no packets should be sent  in  the  other  direction.
320              It's  highly  suggested that -t be set on the server if this op‐
321              tion is being used.  This is because  there  will  be  only  one
322              trigger  ending  packet  sent  from client to server and if it's
323              lost then the server will continue to run. (Requires ver  2.0.14
324              or better)
325
326       -n, --num n[kmKM]
327              number of bytes to transmit (instead of -t)
328
329           --permit-key [=<value>]
330              Set  a  key  value  that must match the server's value (also set
331              with --permit-key) in order for the  server  to  accept  traffic
332              from the client. TCP only, no UDP support.
333
334       -r, --tradeoff
335              Do  a  bidirectional  test individually - client-to-server, fol‐
336              lowed by a reversed test, server-to-client
337
338           --tcp-write-prefetch n[kmKM]
339              Set TCP_NOTSENT_LOWAT on the socket and use event  based  writes
340              per select() on the socket.
341
342       -t, --time n|0
343              time  in seconds to transmit traffic, use zero for infinite (de‐
344              fault is 10 secs)
345
346           --trip-times
347              enable the measurement of end to end  write  to  read  latencies
348              (client and server clocks must be synchronized)
349
350           --txdelay-time
351              time  in seconds to hold back or delay after the TCP connect and
352              prior to the socket writes. For UDP it's the delay  between  the
353              traffic thread starting and the first write.
354
355           --txstart-time n.n
356              set  the  txstart-time  to  n.n  using unix or epoch time format
357              (supports microsecond resolution, e.g 1536014418.123456) An  ex‐
358              ample to delay one second using command substitution is iperf -c
359              192.168.1.10 --txstart-time $(expr $(date +%s) + 1).$(date +%N)
360
361       -B, --bind ip | ip:port | ipv6 -V | [ipv6]:port -V
362              bind src ip addr and optional port as the source of traffic (see
363              NOTES)
364
365       -F, --fileinput name
366              input the data to be transmitted from a file
367
368       -I, --stdin
369              input the data to be transmitted from stdin
370
371       -L, --listenport n
372              port to receive bidirectional tests back on
373
374       -P, --parallel n
375              number of parallel client threads to run
376
377       -R, --reverse
378              reverse  the traffic flow (useful for testing through firewalls,
379              see NOTES)
380
381       -S, --tos
382              set the socket's IP_TOS (byte) field
383
384       -T, --ttl n
385              time-to-live, for multicast (default 1)  -V,  --ipv6_domain  Set
386              the domain to IPv6 (send packets over IPv6)
387
388       -X, --peerdetect
389              run peer version detection prior to traffic.
390
391       -Z, --linux-congestion algo
392              set TCP congestion control algorithm (Linux only)
393

EXAMPLES

395       TCP tests (client)
396
397       iperf -c <host> -e -i 1
398       ------------------------------------------------------------
399       Client connecting to <host>, TCP port 5001 with pid 5149
400       Write buffer size:  128 KByte
401       TCP window size:  340 KByte (default)
402       ------------------------------------------------------------
403       [   3]  local  45.56.85.133 port 49960 connected with 45.33.58.123 port
404       5001 (ct=3.23 ms)
405       [  ID]  Interval         Transfer     Bandwidth        Write/Err   Rtry
406       Cwnd/RTT        NetPwr
407       [   3]  0.00-1.00  sec    126 MBytes  1.05 Gbits/sec  1006/0          0
408       56K/626 us  210636.47
409       [  3] 1.00-2.00 sec   138 MBytes   1.15  Gbits/sec   1100/0         299
410       483K/3884 us  37121.32
411       [   3]  2.00-3.00  sec    137 MBytes  1.15 Gbits/sec  1093/0         24
412       657K/5087 us  28162.31
413       [  3] 3.00-4.00 sec   126 MBytes   1.06  Gbits/sec   1010/0         284
414       294K/2528 us  52366.58
415       [   3]  4.00-5.00  sec    117  MBytes   980 Mbits/sec  935/0        373
416       487K/2025 us  60519.66
417       [  3] 5.00-6.00 sec   144 MBytes   1.20  Gbits/sec   1149/0           2
418       644K/3570 us  42185.36
419       [   3]  6.00-7.00  sec    126 MBytes  1.06 Gbits/sec  1011/0        112
420       582K/5281 us  25092.56
421       [  3] 7.00-8.00 sec   110  MBytes    922  Mbits/sec   879/0          56
422       279K/1957 us  58871.89
423       [   3]  8.00-9.00  sec    127 MBytes  1.06 Gbits/sec  1014/0         46
424       483K/3372 us  39414.89
425       [  3] 9.00-10.00 sec   132 MBytes  1.11  Gbits/sec   1054/0           0
426       654K/3380 us  40872.75
427       [   3]  0.00-10.00 sec  1.25 GBytes  1.07 Gbits/sec  10251/0       1196
428       -1K/3170 us  42382.03
429
430
431       where (per -e,)
432              ct= TCP connect time (or three way handshake time 3WHS)
433              Write/Err Total number of successful socket writes. Total number
434              of non-fatal socket write errors
435              Rtry Total number of TCP retries
436              Cwnd/RTT  (*nix  only) TCP congestion window and round trip time
437              (sampled where NA indicates no value)
438              NetPwr (*nix only) Network power defined as (throughput / RTT)
439
440
441       TCP tests (server)
442
443       iperf -s -e -i 1 -l 8K
444       ------------------------------------------------------------
445       Server listening on TCP port 5001 with pid 13430
446       Read buffer size: 8.00 KByte
447       TCP window size: 85.3 KByte (default)
448       ------------------------------------------------------------
449       [  4] local 45.33.58.123 port 5001  connected  with  45.56.85.133  port
450       49960
451       [     ID]    Interval           Transfer       Bandwidth          Reads
452       Dist(bin=1.0K)
453       [    4]   0.00-1.00   sec     124   MBytes    1.04   Gbits/sec    22249
454       798:2637:2061:767:2165:1563:589:11669
455       [    4]   1.00-2.00   sec     136   MBytes    1.14   Gbits/sec    24780
456       946:3227:2227:790:2427:1888:641:12634
457       [    4]   2.00-3.00   sec     137   MBytes    1.15   Gbits/sec    24484
458       1047:2686:2218:810:2195:1819:728:12981
459       [    4]   3.00-4.00   sec     126   MBytes    1.06   Gbits/sec    20812
460       863:1353:1546:614:1712:1298:547:12879
461       [    4]   4.00-5.00   sec     117   MBytes     984   Mbits/sec    20266
462       769:1886:1828:589:1866:1350:476:11502
463       [    4]   5.00-6.00   sec     143   MBytes    1.20   Gbits/sec    24603
464       1066:1925:2139:822:2237:1827:744:13843
465       [    4]   6.00-7.00   sec     126   MBytes    1.06   Gbits/sec    22635
466       834:2464:2249:724:2269:1646:608:11841
467       [    4]   7.00-8.00   sec     110   MBytes     921   Mbits/sec    21107
468       842:2437:2747:592:2871:1903:496:9219
469       [    4]   8.00-9.00   sec     126   MBytes    1.06   Gbits/sec    22804
470       1038:1784:2639:656:2738:1927:573:11449
471       [    4]   9.00-10.00   sec     133   MBytes    1.11   Gbits/sec   23091
472       1088:1654:2105:710:2333:1928:723:12550
473       [   4]  0.00-10.02   sec    1.25   GBytes    1.07   Gbits/sec    227306
474       9316:22088:21792:7096:22893:17193:6138:120790
475
476       where (per -e,)
477              Reads Total number of socket reads
478              Dist(bin=size)  Eight bin histogram of the socket reads returned
479              byte count. Bin width is set per size. Bins are separated  by  a
480              colon. In the example, the bins are 0-1K, 1K-2K, .., 7K-8K.
481
482
483       TCP tests (server with --trip-times on client) iperf -s -i 1 -w 4M
484       ------------------------------------------------------------
485       Server listening on TCP port 5001
486       TCP window size: 8.00 MByte (WARNING: requested 4.00 MByte)
487       ------------------------------------------------------------
488       [   4] local 192.168.1.4%eth0 port 5001 connected with 192.168.1.7 port
489       44798 (trip-times) (MSS=1448) (peer 2.0.14-alpha)
490       [  ID]   Interval          Transfer      Bandwidth      Burst   Latency
491       avg/min/max/stdev (cnt/size) inP NetPwr  Reads=Dist
492       [      4]     0.00-1.00    sec     19.0    MBytes      159    Mbits/sec
493       52.314/10.238/117.155/19.779  ms   (151/131717)   1.05   MByte   380.19
494       781=306:253:129:48:18:15:8:4
495       [      4]     1.00-2.00    sec     20.0    MBytes      168    Mbits/sec
496       53.863/21.264/79.252/12.277   ms   (160/131080)   1.08   MByte   389.38
497       771=294:236:126:60:18:24:10:3
498       [      4]     2.00-3.00    sec     18.2    MBytes      153    Mbits/sec
499       58.718/22.000/137.944/20.397  ms   (146/130964)   1.06   MByte   325.64
500       732=299:231:98:52:18:19:10:5
501       [    4]   3.00-4.00   sec    19.7   MBytes     165  Mbits/sec   50.448/
502       8.921/82.728/14.627    ms    (158/130588)      997     KByte     409.00
503       780=300:255:121:58:15:18:7:6
504       [      4]     4.00-5.00    sec     18.8    MBytes      158    Mbits/sec
505       53.826/11.169/115.316/15.541  ms   (150/131420)   1.02   MByte   366.24
506       761=302:226:134:52:22:17:7:1
507       [      4]     5.00-6.00    sec     19.5    MBytes      164    Mbits/sec
508       50.943/11.922/76.134/14.053   ms   (156/131276)   1.03   MByte   402.00
509       759=273:246:149:45:16:18:4:8
510       [      4]     6.00-7.00    sec     18.5    MBytes      155    Mbits/sec
511       57.643/10.039/127.850/18.950  ms   (148/130926)   1.05   MByte   336.16
512       710=262:228:133:37:16:20:8:6
513       [      4]     7.00-8.00    sec     19.6    MBytes      165    Mbits/sec
514       52.498/12.900/77.045/12.979   ms   (157/131003)   1.00   MByte   391.78
515       742=288:200:135:68:16:23:4:8
516       [    4]   8.00-9.00   sec    18.0   MBytes     151  Mbits/sec   58.370/
517       8.026/150.243/21.445    ms    (144/131255)    1.06     MByte     323.81
518       716=268:241:108:51:20:17:8:3
519       [      4]    9.00-10.00    sec     18.4    MBytes      154    Mbits/sec
520       56.112/12.419/79.790/13.668   ms   (147/131194)   1.05   MByte   343.70
521       822=330:303:120:26:16:14:9:4
522       [     4]    10.00-10.06    sec     1.03    MBytes      146    Mbits/sec
523       69.880/45.175/78.754/10.823   ms   (9/119632)   1.74    MByte    260.40
524       62=26:30:5:1:0:0:0:0
525       [    4]   0.00-10.06   sec     191   MBytes    159  Mbits/sec   54.183/
526       8.026/150.243/16.781    ms    (1526/131072)    1.03    MByte     366.98
527       7636=2948:2449:1258:498:175:185:75:48
528
529       where (per -e,)
530              Burst Latency One way TCP write() to read() latency in mean/min‐
531              imum/maximum/standard  deviation  format  (Note:  requires   the
532              client's and server's system clocks to be synchronized to a com‐
533              mon reference, e.g. using precision time  protocol  PTP.  A  GPS
534              disciplined OCXO is a recommended reference.)
535              cnt  Number  of completed bursts received and used for the burst
536              latency calculations
537              size Average burst size in bytes (computed average and  estimate
538              only)
539              inP  inP,  short for in progress, is the average number of bytes
540              in progress or in flight. This is  taken  from  the  application
541              level  write to read perspective. Note this is a mean value. The
542              parenthesis value is the standard deviation from the mean.  (Re‐
543              quires --trip-times on client. See Little's law in NOTES.)
544              NetPwr Network power defined as (throughput / one way latency)
545
546
547       TCP  tests  (with  one  way delay sync check -X and --trip-times on the
548       client)
549
550       iperf -c 192.168.1.4 -X -e --trip-times -i 1 -t 2
551       ------------------------------------------------------------
552       Client connecting to 192.168.1.4, TCP  port  5001  with  pid  16762  (1
553       flows)
554       Write buffer size: 131072 Byte
555       TCP window size: 85.0 KByte (default)
556       ------------------------------------------------------------
557       [    1]    Clock   sync   check   (ms):   RTT/Half=(3.361/1.680)   OWD-
558       send/ack/asym=(2.246/1.115/1.131)
559       [  1] local 192.168.1.1%ap0 port 47466 connected with 192.168.1.4  port
560       5001 (MSS=1448) (trip-times) (sock=3) (peer 2.1.4-master)
561       [  ID]  Interval         Transfer     Bandwidth        Write/Err   Rtry
562       Cwnd/RTT        NetPwr
563       [  1] 0.00-1.00 sec   9.50  MBytes   79.7  Mbits/sec   77/0           0
564       2309K/113914 us  87
565       [   1]  1.00-2.00  sec   7.12  MBytes   59.8 Mbits/sec  57/0          0
566       2492K/126113 us  59
567       [  1] 2.00-2.42  sec    128  KBytes   2.47  Mbits/sec   2/0           0
568       2492K/126113 us  2
569       [   1]  0.00-2.42  sec   16.8  MBytes  58.0 Mbits/sec  136/0          0
570       2492K/126113 us  57
571
572
573       UDP tests (client)
574
575       iperf -c <host> -e -i 1 -u -b 10m
576       ------------------------------------------------------------
577       Client connecting to <host>, UDP port 5001 with pid 5169
578       Sending 1470 byte datagrams, IPG target: 1176.00 us (kalman adjust)
579       UDP buffer size:  208 KByte (default)
580       ------------------------------------------------------------
581       [  3] local 45.56.85.133 port 32943 connected  with  45.33.58.123  port
582       5001
583       [ ID] Interval        Transfer     Bandwidth      Write/Err  PPS
584       [  3] 0.00-1.00 sec  1.19 MBytes  10.0 Mbits/sec  852/0      851 pps
585       [  3] 1.00-2.00 sec  1.19 MBytes  10.0 Mbits/sec  850/0      850 pps
586       [  3] 2.00-3.00 sec  1.19 MBytes  10.0 Mbits/sec  850/0      850 pps
587       [  3] 3.00-4.00 sec  1.19 MBytes  10.0 Mbits/sec  851/0      850 pps
588       [  3] 4.00-5.00 sec  1.19 MBytes  10.0 Mbits/sec  850/0      850 pps
589       [  3] 5.00-6.00 sec  1.19 MBytes  10.0 Mbits/sec  850/0      850 pps
590       [  3] 6.00-7.00 sec  1.19 MBytes  10.0 Mbits/sec  851/0      850 pps
591       [  3] 7.00-8.00 sec  1.19 MBytes  10.0 Mbits/sec  850/0      850 pps
592       [  3] 8.00-9.00 sec  1.19 MBytes  10.0 Mbits/sec  851/0      850 pps
593       [  3] 0.00-10.00 sec  11.9 MBytes  10.0 Mbits/sec  8504/0      850 pps
594       [  3] Sent 8504 datagrams
595       [  3] Server Report:
596       [  3] 0.00-10.00 sec  11.9 MBytes  10.0 Mbits/sec   0.047 ms    0/ 8504
597       (0%)  0.537/ 0.392/23.657/ 0.497 ms  850 pps  2329.37
598
599       where (per -e,)
600              Write/Err Total number of successful socket writes. Total number
601              of non-fatal socket write errors
602              PPS Transmit packet rate in packets per second
603
604
605       UDP tests (server) iperf -s -i 1 -w 4M -u
606       ------------------------------------------------------------
607       Server listening on UDP port 5001
608       Receiving 1470 byte datagrams
609       UDP buffer size: 8.00 MByte (WARNING: requested 4.00 MByte)
610       ------------------------------------------------------------
611       [  3] local 192.168.1.4 port 5001 connected with 192.168.1.1 port 60027
612       (WARN: winsize=8.00 MByte  req=4.00  MByte)  (trip-times)  (0.0)  (peer
613       2.0.14-alpha)
614       [ ID] Interval        Transfer     Bandwidth        Jitter   Lost/Total
615       Latency avg/min/max/stdev PPS  inP NetPwr
616       [  3] 0.00-1.00 sec  44.5 MBytes   373 Mbits/sec   0.071 ms 52198/83938
617       (62%) 75.185/ 2.367/85.189/14.430 ms 31854 pps 3.64 MByte 620.58
618       [    3]   1.00-2.00   sec   44.8  MBytes    376  Mbits/sec    0.015  ms
619       59549/143701 (41%) 79.609/75.603/85.757/ 1.454 ms 31954 pps 3.56  MByte
620       590.04
621       [    3]   2.00-3.00   sec   44.5  MBytes    373  Mbits/sec    0.017  ms
622       59494/202975 (29%) 80.006/75.951/88.198/ 1.638 ms 31733 pps 3.56  MByte
623       583.07
624       [    3]   3.00-4.00   sec   44.5  MBytes    373  Mbits/sec    0.019  ms
625       59586/262562 (23%) 79.939/75.667/83.857/ 1.145 ms 31767 pps 3.56  MByte
626       583.57
627       [    3]   4.00-5.00   sec   44.5  MBytes    373  Mbits/sec    0.081  ms
628       59612/322196 (19%) 79.882/75.400/86.618/ 1.666 ms 31755 pps 3.55  MByte
629       584.40
630       [    3]   5.00-6.00   sec   44.7  MBytes    375  Mbits/sec    0.064  ms
631       59571/381918 (16%) 79.767/75.571/85.339/ 1.556 ms 31879 pps 3.56  MByte
632       588.02
633       [    3]   6.00-7.00   sec   44.6  MBytes    374  Mbits/sec    0.041  ms
634       58990/440820 (13%) 79.722/75.662/85.938/ 1.087 ms 31820 pps 3.58  MByte
635       586.73
636       [    3]   7.00-8.00   sec   44.7  MBytes    375  Mbits/sec    0.027  ms
637       59679/500548 (12%) 79.745/75.704/84.731/ 1.094 ms 31869 pps 3.55  MByte
638       587.46
639       [    3]   8.00-9.00   sec   44.3  MBytes    371  Mbits/sec    0.078  ms
640       59230/559499 (11%) 80.346/75.514/94.293/ 2.858 ms 31590 pps 3.58  MByte
641       577.97
642       [    3]   9.00-10.00  sec   44.4  MBytes    373  Mbits/sec    0.073  ms
643       58782/618394 (9.5%) 79.125/75.511/93.638/ 1.643 ms 31702 pps 3.55 MByte
644       588.99
645       [    3]  10.00-10.08  sec   3.53  MBytes    367  Mbits/sec    0.129  ms
646       6026/595236 (1%) 94.967/80.709/99.685/ 3.560 ms 31107  pps  3.58  MByte
647       483.12
648       [    3]   0.00-10.08  sec    449  MBytes    374  Mbits/sec    0.129  ms
649       592717/913046 (65%) 79.453/ 2.367/99.685/ 5.200  ms  31776  pps  (null)
650       587.91
651
652
653       where (per -e,)
654              Latency  End to end latency in mean/minimum/maximum/standard de‐
655              viation format (Note: requires the client's and server's  system
656              clocks to be synchronized to a common reference, e.g. using pre‐
657              cision time protocol PTP. A GPS disciplined  OCXO  is  a  recom‐
658              mended reference.)
659              PPS Received packet rate in packets per second
660              inP  inP,  short for in progress, is the average number of bytes
661              in progress or in flight. This  is  taken  from  an  application
662              write to read perspective. (Requires --trip-times on client. See
663              Little's law in NOTES.)
664              NetPwr Network power defined as (throughput / latency)
665
666
667       Isochronous UDP tests (client)
668
669       iperf -c 192.168.100.33 -u -e -i 1 --isochronous=60:100m,10m --realtime
670       ------------------------------------------------------------
671       Client connecting to 192.168.100.33, UDP port 5001 with pid 14971
672       UDP isochronous: 60 frames/sec mean= 100  Mbit/s,  stddev=10.0  Mbit/s,
673       Period/IPG=16.67/0.005 ms
674       UDP buffer size:  208 KByte (default)
675       ------------------------------------------------------------
676       [   3]  local  192.168.100.76  port 42928 connected with 192.168.100.33
677       port 5001
678       [  ID]  Interval         Transfer      Bandwidth       Write/Err    PPS
679       frames:tx/missed/slips
680       [   3]  0.00-1.00 sec  12.0 MBytes   101 Mbits/sec  8615/0     8493 pps
681       62/0/0
682       [  3] 1.00-2.00 sec  12.0 MBytes   100 Mbits/sec  8556/0      8557  pps
683       60/0/0
684       [   3]  2.00-3.00 sec  12.0 MBytes   101 Mbits/sec  8586/0     8586 pps
685       60/0/0
686       [  3] 3.00-4.00 sec  12.1 MBytes   102 Mbits/sec  8687/0      8687  pps
687       60/0/0
688       [   3]  4.00-5.00 sec  11.8 MBytes  99.2 Mbits/sec  8468/0     8468 pps
689       60/0/0
690       [  3] 5.00-6.00 sec  11.9 MBytes  99.8 Mbits/sec  8519/0      8520  pps
691       60/0/0
692       [   3]  6.00-7.00 sec  12.1 MBytes   102 Mbits/sec  8694/0     8694 pps
693       60/0/0
694       [  3] 7.00-8.00 sec  12.1 MBytes   102 Mbits/sec  8692/0      8692  pps
695       60/0/0
696       [   3]  8.00-9.00 sec  11.9 MBytes   100 Mbits/sec  8537/0     8537 pps
697       60/0/0
698       [  3] 9.00-10.00 sec  11.8 MBytes  99.0 Mbits/sec  8450/0     8450  pps
699       60/0/0
700       [  3] 0.00-10.01 sec   120 MBytes   100 Mbits/sec  85867/0     8574 pps
701       602/0/0
702       [  3] Sent 85867 datagrams
703       [  3] Server Report:
704       [  3] 0.00-9.98 sec   120 MBytes   101 Mbits/sec   0.009 ms   196/85867
705       (0.23%)  0.665/ 0.083/ 1.318/ 0.174 ms 8605 pps  18903.85
706
707       where (per -e,)
708              frames:tx/missed/slips  Total  number  of  isochronous frames or
709              bursts. Total number of frame ids  not  sent.  Total  number  of
710              frame slips
711
712
713       Isochronous UDP tests (server)
714
715       iperf -s -e -u --udp-histogram=100u,2000 --realtime
716       ------------------------------------------------------------
717       Server listening on UDP port 5001 with pid 5175
718       Receiving 1470 byte datagrams
719       UDP buffer size:  208 KByte (default)
720       ------------------------------------------------------------
721       [  3] local 192.168.100.33 port 5001 connected with 192.168.100.76 port
722       42928 isoch (peer 2.0.13-alpha)
723       [ ID] Interval        Transfer     Bandwidth        Jitter   Lost/Total
724       Latency avg/min/max/stdev PPS  NetPwr  Frames/Lost
725       [   3] 0.00-9.98 sec   120 MBytes   101 Mbits/sec   0.010 ms  196/85867
726       (0.23%)  0.665/ 0.083/ 1.318/ 0.284 ms 8585 pps  18903.85  601/1
727       [            3]           0.00-9.98           sec            T8(f)-PDF:
728       bin(w=100us):cnt(85671)=1:2,2:844,3:10034,4:8493,5:8967,6:8733,7:8823,8:9023,9:8901,10:8816,11:7730,12:4563,13:741,14:1
729       (5.00/95.00%=3/12,Outliers=0,obl/obu=0/0)
730       [            3]           0.00-9.98           sec            F8(f)-PDF:
731       bin(w=100us):cnt(598)=15:2,16:1,17:27,18:68,19:125,20:136,21:103,22:83,23:22,24:23,25:5,26:3
732       (5.00/95.00%=17/24,Outliers=0,obl/obu=0/0)
733
734
735       where, Frames/lost Total number of frames (or bursts)  received.  Total
736              number of bursts lost or error-ed
737              T8-PDF(f) Latency histogram for packets
738              F8-PDF(f) Latency histogram for frames
739
740
741

ENVIRONMENT

743       Note:  The environment variable option settings haven't been maintained
744              well.  See the source code if these are of interest.
745

NOTES

747       Numeric options: Some numeric options  support  format  characters  per
748       '<value>c'  (e.g.  10M)  where the c format characters are k,m,g,K,M,G.
749       Lowercase format characters are 10^3 based and uppercase are 2^n based,
750       e.g. 1k = 1000, 1K = 1024, 1m = 1,000,000 and 1M = 1,048,576
751
752       Rate  limiting:  The -b option supports read and write rate limiting at
753       the application level.  The -b option on the client also supports vari‐
754       able offered loads through the <mean>,<standard deviation> format, e.g.
755       -b 100m,10m. The distribution used  is  log  normal.  Similar  for  the
756       isochronous  option. The -b on the server rate limits the reads. Socket
757       based pacing is also supported using the --fq-rate  long  option.  This
758       will work with the --reverse and --full-duplex options as well.
759
760       Synchronized   clocks:  The  --trip-times  option  indicates  that  the
761       client's and server's clocks are synchronized to  a  common  reference.
762       Network  Time  Protocol (NTP) or Precision Time Protocol (PTP) are com‐
763       monly used for this. The reference clock(s) error and the  synchroniza‐
764       tion  protocols will affect the accuracy of any end to end latency mea‐
765       surements.
766
767       Binding is done at the logical level (ip address or layer 3) using  the
768       -B  option  and  at the device (or layer 2) level using the percent (%)
769       separator for both the client and the server. On the client, the -B op‐
770       tion  affects  the  bind(2) system call, and will set the source ip ad‐
771       dress and the source port, e.g. iperf -c <host> -B  192.168.100.2:6002.
772       This controls the packet's source values but not routing.  These can be
773       confusing in that a route or device lookup may not be that of  the  de‐
774       vice with the configured source IP.  So, for example, if the IP address
775       of eth0 is used for -B and the routing table for the destination IP ad‐
776       dress resolves the output interface to be eth1, then the host will send
777       the packet out device eth1 while using the source IP address of eth0 in
778       the  packet.   To affect the physical output interface (e.g. dual homed
779       systems) either use -c <host>%<dev> (requires root) which bypasses this
780       host route table lookup, or configure policy routing per each -B source
781       address and set  the  output  interface  appropriately  in  the  policy
782       routes.  On  the  server or receive, only packets destined to -B IP ad‐
783       dress will be received. It's also useful for  multicast.  For  example,
784       iperf  -s  -B 224.0.0.1%eth0 will only accept ip multicast packets with
785       dest ip 224.0.0.1 that are received on the eth0 interface, while  iperf
786       -s  -B  224.0.0.1 will receive those packets on any interface, Finally,
787       the  device  specifier  is  required  for  v6   link-local,   e.g.   -c
788       [v6addr]%<dev> -V, to select the output interface.
789
790       Reverse,  full-duplex,  dualtest  (-d) and tradeoff (-r): The --reverse
791       (-R) and --full-duplex options can be confusing when  compared  to  the
792       older options of --dualtest (-d) and --tradeoff (-r). The newer options
793       of --reverse and --full-duplex only open one socket and read and  write
794       to the same socket descriptor, i.e. use the socket in full duplex mode.
795       The older -d and -r open second sockets in the opposite  direction  and
796       do  not use a socket in full duplex mode. Note that full duplex applies
797       to the socket and not to the network devices and that full duplex sock‐
798       ets  are supported by the operating systems regardless if an underlying
799       network supports full duplex transmission  and  reception.   It's  sug‐
800       gested  to use --reverse if you want to test through a NAT firewall (or
801       -R on non-windows systems). This applies role reversal of the test  af‐
802       ter  opening  the  full duplex socket.  (Note: Firewall piercing may be
803       required to use -d and -r if a NAT gateway is in the path.)
804
805       Also, the --reverse -b <rate> setting behaves differently for  TCP  and
806       UDP.  For  TCP  it will rate limit the read side, i.e. the iperf client
807       (role reversed to act as a server) reading from the full duplex socket.
808       This  will  in  turn  flow control the reverse traffic per standard TCP
809       congestion control. The --reverse -b <rate> will be applied on transmit
810       (i.e.  the server role reversed to act as a client) for UDP since there
811       is no flow control with UDP. There is no option to directly rate  limit
812       the writes with TCP testing when using --reverse.
813
814       TCP Connect times: The TCP connect time (or three way handshake) can be
815       seen on the iperf client when the -e (--enhanced) option is  set.  Look
816       for  the  ct=<value>  in  the  connected  message,  e.g.in  '[ 3] local
817       192.168.1.4 port 48736 connected with 192.168.1.1  port  5001  (ct=1.84
818       ms)' shows the 3WHS took 1.84 milliseconds.
819
820       Port-range  Port  ranges  are supported using the hyphen notation, e.g.
821       6001-6009. This will cause multiple threads, one per  port,  on  either
822       the listener/server or the client. The user needs to take care that the
823       ports in the port range are available and not already in  use  per  the
824       operating  system.  The -P is supported on the client and will apply to
825       each destination port within the port range. Finally, this can be  used
826       for a workaround for Windows UDP and -P > 1 as Windows doesn't dispatch
827       UDP per a server's connect and the quintuple.
828
829       Packet per second (pps) calculation The packets per second  calculation
830       is  done  as  a derivative, i.e. number of packets divided by time. The
831       time is taken from the previous last packet to the current last packet.
832       It is not the sample interval time. The last packet can land at differ‐
833       ent times within an interval.  This means that pps  does  not  have  to
834       match rx bytes divided by the sample interval.  Also, with --trip-times
835       set, the packet time on receive is set by the sender's  write  time  so
836       pps indicates the end to end pps with --trip-times. The RX pps calcula‐
837       tion is receive side only when -e is set and --trip-times is not set.
838
839       Little's Law in queuing theory is a theorem that determines the average
840       number of items (L) in a stationary queuing system based on the average
841       waiting time (W) of an item within a system and the average  number  of
842       items arriving at the system per unit of time (lambda). Mathematically,
843       it's L = lambda * W. As used here, the units  are  bytes.  The  arrival
844       rate is taken from the writes.
845
846       Network  power: The network power (NetPwr) metric is experimental. It's
847       a convenience function defined as throughput/delay.  For TCP transmits,
848       the delay is the sampled RTT times.  For TCP receives, the delay is the
849       write to read latency.  For UDP  the  delay  is  the  end/end  latency.
850       Don't  confuse  this  with  the  physics definition of power (delta en‐
851       ergy/delta time) but more of a measure of a desirable property  divided
852       by  an  undesirable  property. Also note, one must use -i interval with
853       TCP to get this as that's what sets the RTT sampling rate.  The  metric
854       is scaled to assist with human readability.
855
856       Multicast:  Iperf 2 supports multicast with a couple of caveats. First,
857       multicast streams cannot take advantage of the -P  option.  The  server
858       will serialize multicast streams. Also, it's highly encouraged to use a
859       -t on a server that will be used for multicast clients. That is because
860       the  single  end  of  traffic packet sent from client to server may get
861       lost and there are no redundant end of traffic packets.  Setting -t  on
862       the  server will kill the server thread in the event this packet is in‐
863       deed lost.
864
865       Fast Sampling: Use ./configure --enable-fastsampling and  then  compile
866       from  source  to  enable four digit (e.g. 1.0000) precision in reports'
867       timestamps. Useful for sub-millisecond sampling.
868

DIAGNOSTICS

870       Use ./configure --enable-thread-debug and then compile from  source  to
871       enable both asserts and advanced debugging of the tool itself.
872

BUGS

874       See https://sourceforge.net/p/iperf2/tickets/
875

AUTHORS

877       Iperf2,  based  from  iperf  (originally written by Mark Gates and Alex
878       Warshavsky), has a goal of maintenance with some  feature  enhancement.
879       Other contributions from Ajay Tirumala, Jim Ferguson, Jon Dugan <jdugan
880       at x1024 dot net>, Feng Qin, Kevin Gibbs, John Estabrook  <jestabro  at
881       ncsa.uiuc.edu>,  Andrew  Gallatin <gallatin at gmail.com>, Stephen Hem‐
882       minger <shemminger at linux-foundation.org>, Tim Auckland <tim.auckland
883       at gmail.com>, Robert J. McMahon <rjmcmahon at rjmcmahon.com>
884

SEE ALSO

886       accept(2),bind(2),close(2),connect(2),fcntl(2),getpeername(2),getsock‐
887       name(2),getsockopt(2),listen(2),read(2),recv(2),select(2),send(2),set‐
888       sockopt(2),shutdown(2),write(2),ip(7),socket(7),tcp(7),udp(7)
889
890       Source code at http://sourceforge.net/projects/iperf2/
891
892       "Unix  Network  Programming,  Volume 1: The Sockets Networking API (3rd
893       Edition) 3rd Edition" by W. Richard Stevens (Author), Bill Fenner  (Au‐
894       thor), Andrew M. Rudoff (Author)
895
896
897
898NLANR/DAST                         July 2021                          IPERF(1)
Impressum