summaryrefslogtreecommitdiffstats
path: root/man/iperf.1
blob: 8ca13435e92b474a8f23e7bcf4e5f7788c876a5a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
.TH IPERF 1 "February 2023" NLANR/DAST "User Manuals"
.SH NAME
iperf \- perform network traffic tests using network sockets. Metrics include throughput and latency or link capacity and responsiveness.
.SH SYNOPSIS
.BI "iperf -s [" options ]

.BI "iperf -c " server " [" options ]

.BI "iperf -u -s [" options ]

.BI "iperf -u -c "  server " [" options ]

.SH DESCRIPTION
.LP
iperf 2 is a testing tool which performs network traffic measurements using network sockets. The performance
metrics supported include throughput and latency (or link capacity and responsiveness.) Latency measurements include
both one way delay (OWD) and round trip times (RTTs.) Iperf can use both TCP and UDP sockets (or
protocols.) It supports unidirectional, full duplex (same socket) and bidirectional traffic, and supports
multiple, simultaneous traffic streams. It supports multicast traffic including source specific
multicast (SSM) joins. Its multi-threaded design allows for peak performance. Metrics displayed help to
characterize host to host network performance. Setting the enhanced (-e) option provides all
available metrics. Note: the metrics are at the socket level reads and writes. They do
not include the overhead associated with lower level protocol layer headers.
.LP
The user must establish both a server (to receive traffic)
and a client (to generate and send traffic) for a test to occur.
The client and server typically are on different hosts or
computers but need not be.
.SH "GENERAL OPTIONS"
.TP
.BR -b ", " --bandwidth " "
set the target bandwidth and optional standard deviation per
\fI<mean>\fR,\fI[<stdev>]\fR (See NOTES for suffixes)
.TP
.BR -e ", " --enhanced " "
Display enhanced output in reports otherwise use legacy report (ver
2.0.5) formatting (see NOTES)
.TP
.BR -f ", " --format " " [abkmgBKMG]
format to report: adaptive, bits, Bytes, Kbits, Mbits, Gbits, KBytes,
MBytes, GBytes (see NOTES for more)
.TP
.BR -h ", " --help " "
print a help synopsis
.TP
.BR "    --hide-ips "
obscure ip addresses in output (useful when wanting to publish results and not display the full ip addresses. v4 only)
.TP
.BR -i ", " --interval " < \fIt\fR | f >"
sample or display interval reports every \fIt\fR seconds (default) or every frame or burst, i.e. if f is used then the interval will be each frame or burst. The frame interval reporting is experimental.  Also suggest a compile with fast-sampling, i.e. ./configure --enable-fastsampling
.TP
.BR -l ", " --len " \fIn\fR[kmKM]"
set read/write buffer size (TCP) or length (UDP) to \fIn\fR (TCP default 128K, UDP default 1470)
.TP
.BR "    --l2checks "
perform layer 2 length checks on received UDP packets (requires systems that support packet sockets, e.g. Linux)
.TP
.BR -m ", " --print_mss " "
print TCP maximum segment size
.TP
.BR "    --NUM_REPORT_STRUCTS " \fI<count>\fR
Override the default shared memory size between the traffic thread(s) and reporter thread in order to mitigate mutex lock contentions. The default value of 5000 should be sufficient for 1Gb/s networks. Increase this upon seeing the Warning message of reporter thread too slow. If the Warning message isn't seen, then increasing this won't have any significant effect (other than to use some additional memory.)
.TP
.BR -o ", " --output " \fIfilename\fR"
output the report or error message to this specified file
.TP
.BR "    --permit-key [=" \fI<value>\fR "]"
Set a key value that must match for the server to accept traffic on a connection. If the option is given without a value on the server a key value will be autogenerated and displayed in its initial settings report. The lifetime of the key is set using --permit-key-timeout and defaults to twenty seconds. The value is required on clients. The value will also be used as part of the transfer id in reports. The option set on the client but not the server will also cause the server to reject the client's traffic. TCP only, no UDP support.
.TP
.BR -p ", " --port " \fIm\fR[-\fIn\fR]"
set client or server port(s) to send or listen on per \fIm\fR (default 5001) w/optional port range per m-n (e.g. -p 6002-6008) (see NOTES)
.TP
.BR "    --sum-dstip"
sum traffic threads based upon the destination IP address (default is source ip address)
.TP
.BR "    --sum-only "
set the output to sum reports only. Useful for -P at large values
.TP
.BR -t ", " --time " \fIn\fR"
time in seconds to listen for new traffic connections, receive traffic or send traffic
.TP
.BR -u ", " --udp " "
use UDP rather than TCP
.TP
.BR "    --utc"
use coordinated universal time (UTC) when outputting time (otherwise use local time)
.TP
.BR -w ", " --window " \fIn\fR[kmKM]"
TCP window size (socket buffer size)
.TP
.BR -z ", " --realtime " "
Request real-time scheduler, if supported.
.TP
.BR -B ", " --bind " \fIhost\fR[:\fIport\fR][%\fIdev\fR]"
bind to \fIhost\fR, ip address or multicast address, optional port or device (see NOTES)
.TP
.BR -C ", " --compatibility " "
for use with older versions does not sent extra msgs
.TP
.BR -M ", " --mss " \fIn\fR"
set TCP maximum segment size using TCP_MAXSEG
.TP
.BR -N ", " --nodelay " "
set TCP no delay, disabling Nagle's Algorithm
.TP
.BR -v ", " --version " "
print version information and quit
.TP
.BR -x ", " --reportexclude " [CDMSV]"
exclude C(connection) D(data) M(multicast) S(settings) V(server) reports
.TP
.BR -y ", " --reportstyle " C|c"
if set to C or c report results as CSV (comma separated values)
.TP
.BR -Z ", " --tcp-congestion " "
Set the default congestion-control algorithm to be used for new connections. Platforms must support setsockopt's TCP_CONGESTION. (Notes: See sysctl and tcp_allowed_congestion_control for available options. May require root privileges.)
.SH "SERVER SPECIFIC OPTIONS"
.TP
.BR -1 ", " --singleclient " "
set the server to process only one client at a time
.TP
.BR -b ", " --bandwidth " \fIn\fR[kmgKMG]"
set target read rate to \fIn\fR bits/sec. TCP only for the server.
.TP
.BR -s ", " --server " "
run in server mode
.TP
.BR "    --histograms[="\fIbinwidth\fR[u],\fIbincount\fR,[\fIlowerci\fR],[\fIupperci\fR] "]"
enable latency histograms for udp packets (-u), for tcp writes (with --trip-times), or for either udp or tcp with --isochronous clients, or for --bounceback. The binning can be modified. Bin widths (default 1 millisecond, append u for microseconds, m for milliseconds) bincount is total bins (default 1000), ci is confidence interval between 0-100% (default lower 5%, upper 95%, 3 stdev 99.7%)
.TP
.BR "    --jitter-histograms[=" \fI<binwidth>\fR "]"
enable jitter histograms for udp packets (-u). Optional value is the bin width where units are microseconds and defaults to 100 usecs
.TP
.BR "    --permit-key [=" \fI<value>\fR "]"
Set a key value that must match for the server to accept traffic from a client (also set with --permit-key.) The server will auto-generate a globally unique key when the option is given without a value. This value will be displayed in the server's initial settings report. The lifetime of the key is set using --permit-key-timeout and defaults to twenty seconds. TCP only, no UDP support.
.TP
.BR "    --permit-key-timeout " \fI<value>\fR
Set the lifetime of the permit key in seconds. Defaults to 20 seconds if not set. A value of zero will disable the timer.
.TP
.BR "    --tap-dev " \fI<dev>\fR
Set the receive interface to the TAP device as specified.
.TP
.BR "    --tcp-rx-window-clamp "  \fIn\fR[kmKM]
Set the socket option of TCP_WINDOW_CLAMP, units is bytes.
.TP
.BR -t ", " --time " \fIn\fR"
time in seconds to listen for new traffic connections and/or receive traffic (defaults to infinite)
.TP
.BR "    --tos-override "  \fI<val>\fR
set the socket's IP_TOS value for reverse or full duplex traffic. Supported in versions 2.1.5 or greater. Previous versions won't set IP_TOS on reverse traffic. See NOTES for values.
.TP
.BR -B ", " --bind " \fIip\fR | \fIip\fR%\fIdevice\fR"
bind src ip addr and optional src device for receiving
.TP
.BR -D ", " --daemon " "
run the server as a daemon. On Windows this will run the specified
command-line under the IPerfService, installing the service if
necessary. Note the service is not configured to auto-start or
restart - if you need a self-starting service you will need to create
an init script or use Windows "sc" commands.
.TP
.BR -H ", " --ssm-host " \fIhost\fR"
Set the source host (ip addr) per SSM multicast, i.e. the S of the S,G
.TP
.BR -R ", " --remove " "
remove the IPerfService (Windows only).
.TP
.BR -U ", " --single_udp " "
run in single threaded UDP mode
.TP
.BR -V ", " --ipv6_domain " "
Enable IPv6 reception by setting the domain and socket to AF_INET6 (Can receive on both IPv4 and IPv6)
.SH "CLIENT SPECIFIC OPTIONS"
.TP
.BR -b ", " --bandwidth " \fIn\fR[kmgKMG][,\fIn\fR[kmgKMG]] | \fIn\fR\fR[kmgKMG]pps"
set target bandwidth to \fIn\fR bits/sec (default 1 Mbit/sec) or
\fIn\fR packets per sec. This may be used with TCP or UDP. Optionally, for variable loads, use format of  mean,standard deviation
.TP
.BR "    --bounceback[=" \fIn\fR "]"
run a TCP bounceback or rps test with optional number writes in a burst per value of n. The default is ten writes every period and the default period is one second (Note: set size with -l or --len which defaults to 100 bytes)
.TP
.BR "    --bounceback-hold " \fIn\fR
request the server to insert a delay of n milliseconds between its read and write (default is no delay)
.TP
.BR "    --bounceback-period[=" \fIn\fR "]"
request the client schedule its send(s) every n seconds (default is one second, use zero value for immediate or continuous back to back)
.TP
.BR "    --bounceback-no-quickack "
request the server not set the TCP_QUICKACK socket option (disabling TCP ACK delays) during a bounceback test (see NOTES)
.TP
.BR "    --bounceback-txdelay " \fIn\fR
request the client to delay n seconds between the start of the working load and the bounceback traffic (default is no delay)
.TP
.BR "    --burst-period " \fIn\fR
Set the burst period in seconds. Defaults to one second. (Note: assumed use case is low duty cycle traffic bursts)
.TP
.BR "    --burst-size " \fIn\fR
Set the burst size in bytes. Defaults to 1M if no value is given.
.BR -c ", " --client " \fI\fIhost\fR | \fIhost\fR%\fIdevice\fR"
run in client mode, connecting to \fIhost\fR  where the optional %dev will SO_BINDTODEVICE that output interface (requires root and see NOTES)
.TP
.TP
.BR "    --connect-only[=" \fIn\fR "]"
only perform a TCP connect (or 3WHS) without any data transfer, useful to measure TCP connect() times. Optional value of n is the total number of connects to do (zero is run forever.) Note that -i will rate limit the connects where -P will create bursts and -t will end the client and hence end its connect attempts.
.TP
.BR "    --connect-retries[= " \fIn\fR "]"
number of times to retry a TCP connect at the application level.  See operating system information on the details of TCP connect related settings.
.TP
.BR -d ", " --dualtest " "
Do a bidirectional test simultaneous test using two unidirectional sockets
.TP
.BR "    --fq-rate n[kmgKMG]"
Set a rate to be used with fair-queuing based socket-level pacing, in bytes or bits per second. Only available on platforms supporting the SO_MAX_PACING_RATE socket option. (Note: Here the suffixes indicate bytes/sec or bits/sec per use of uppercase or lowercase, respectively)
.TP
.BR "    --full-duplex"
run a full duplex test, i.e. traffic in both transmit and receive directions using the \fBsame socket\fR
.TP
.BR "    --histograms[="\fIbinwidth\fR[u],\fIbincount\fR,[\fIlowerci\fR],[\fIupperci\fR] "]"
enable select()/write() histograms with --tcp-write-times or --bounceback (these options are mutually exclusive.) The binning can be modified. Bin widths (default 100 microseconds, append u for microseconds, m for milliseconds) bincount is total bins (default 10000), ci is confidence interval between 0-100% (default lower 5%, upper 95%, 3 stdev 99.7%)
.TP
.BR "    --incr-dstip"
increment the destination ip address when using the parallel (-P) or port range option
.TP
.BR "    --incr-dstport"
increment the destination port when using the parallel (-P) or port range option
.TP
.BR "    --incr-srcip"
increment the source ip address when using the parallel (-P) or port range option
.TP
.BR "    --incr-srcport"
increment the source ip address when using the parallel (-P) or port range option, requires -B to set the src port
.TP
.BR "    --ipg "\fIn\fR
set the inter-packet gap to \fIn\fR (units of seconds) for packets or within a frame/burst when --isochronous is set
.TP
.BR "    --isochronous[=" \fIfps\fR:\fImean\fR,\fIstdev\fR "]"
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. (Note: Here the suffixes indicate bytes/sec or bits/sec per use of uppercase or lowercase, respectively. Also the p suffix is supported to set the burst size in packets, e.g. isochronous=2:25p will send two 25 packet bursts every second, or one 25 packet burst every 0.5 seconds.)
.TP
.BR "    --local-only[=\fI1\fR|\fI0\fR]"
Set 1 to limit traffic to the local network only (through the use of SO_DONTROUTE) set to zero otherwise with optional override of compile time default (see configure --default-localonly)
.TP
.BR "    --near-congestion[=\fIn\fR]"
Enable TCP write rate limiting per the sampled RTT. The delay is applied after the -l number of bytes have completed. The optional value is the multiplier to the RTT and defines the time delay. This value defaults to 0.5 if it is not set. Values less than 1 are supported but the value cannot be negative. This is an experimental feature. It is not likely stable on live networks. Suggested use is over controlled test networks.
.TP
.BR "    --no-connect-sync "
By default, parallel traffic threads (per -P greater than 1) will synchronize after their TCP connects and prior to each sending traffic, i.e. all the threads first complete (or error) the TCP 3WHS before any traffic thread will start sending. This option disables that synchronization such that each traffic thread will start sending immediately after completing its successful connect.
.TP
.BR "    --no-udp-fin "
Don't perform the UDP final server to client exchange which means there won't be a final server report displayed on the client. All packets per the test will be from the client to the server and no packets should be sent in the other direction.
.B It's highly suggested that -t be set on the server if this option is being used.
This is because there will be
.B only one trigger ending packet
sent from client to server and if it's lost then the server will continue to run. (Requires ver 2.0.14 or better)
.TP
.BR -n ", " --num " \fIn\fR[kmKM]"
number of bytes to transmit (instead of -t)
.TP
.BR "    --permit-key [=" \fI<value>\fR "]"
Set a key value that must match the server's value (also set with --permit-key) in order for the server to accept traffic from the client. TCP only, no UDP support.
.TP
.BR -r ", " --tradeoff " "
Do a bidirectional test individually - client-to-server, followed by
a reversed test, server-to-client
.TP
.BR "    --tcp-quickack "
Set TCP_QUICKACK on the socket
.TP
.BR "    --tcp-write-prefetch " \fIn\fR[kmKM]
Set TCP_NOTSENT_LOWAT on the socket and use event based writes per select() on the socket.
.TP
.BR "    --tcp-write-times "
Measure the socket write times
.TP
.BR -t ", " --time " \fIn\fR" | "\fI0\fR"
time in seconds to transmit traffic, use zero for infinite (default is 10 secs)
.TP
.BR "    --trip-times "
enable the measurement of end to end write to read latencies (client and server clocks must be synchronized.) See notes about tcp-write-prefetch being enabled.
.TP
.BR "    --txdelay-time "
time in seconds to hold back or delay after the TCP connect and prior to the socket writes. For UDP it's the delay between the traffic thread starting and the first write.
.TP
.BR "    --txstart-time "\fIn\fR.\fIn\fR
set the txstart-time to \fIn\fR.\fIn\fR using unix or epoch time format (supports microsecond resolution, e.g 1536014418.123456) An example to delay one second using command substitution is iperf -c 192.168.1.10 --txstart-time $(expr $(date +%s) + 1).$(date +%N)
.TP
.BR -B ", " --bind " \fIip\fR | \fIip\fR:\fIport\fR | \fIipv6 -V\fR | \fI[ipv6]\fR:\fIport -V\fR"
bind src ip addr and optional port as the source of traffic (see NOTES)
.TP
.BR -F ", " --fileinput " \fIname\fR"
input the data to be transmitted from a file
.TP
.BR -I ", " --stdin " "
input the data to be transmitted from stdin
.TP
.BR -L ", " --listenport " \fIn\fR"
port to receive bidirectional tests back on
.TP
.BR -P ", " --parallel " \fIn\fR"
number of parallel client threads to run
.TP
.BR -R ", " --reverse " "
reverse the traffic flow (useful for testing through firewalls, see NOTES)
.TP
.BR -S ", " --tos " \fI<val>\fR"
set the socket's IP_TOS value. Versions 2.1.5 or greater will reflect this tos setting back with --reverse or --full-duplex option. (Previous versions won't set tos on the reverse traffic.) Note: use server side --tos-override to override. See NOTES for values.
.TP
.BR -T ", " --ttl " \fIn\fR"
time-to-live, for multicast (default 1)
.TP
.BR "    --working-load[="\fBup|down|bidir][\fR,\fIn\fR\fB]\fR
request a concurrent working load, currently TCP stream(s), defaults to full duplex (or bidir) unless the \fBup\fR or \fBdown\fR option is provided. The number of TCP streams defaults to 1 and can be changed via the n value, e.g. \fB--working-load=down,4\fR will use four TCP streams from server to the client as the working load. The IP ToS will be BE (0x0) for working load traffic.
.TP
.BR -V ", " --ipv6_domain " "
Set the domain to IPv6 (send packets over IPv6)
.TP
.BR -X ", " --peerdetect " "
run peer version detection prior to traffic.
.TP
.BR -Z ", " --linux-congestion " \fIalgo\fR"
set TCP congestion control algorithm (Linux only)
.SH EXAMPLES

.B TCP tests (client)

.B iperf -c <host> -e -i 1
.br
------------------------------------------------------------
.br
Client connecting to <host>, TCP port 5001 with pid 5149
.br
Write buffer size:  128 KByte
.br
TCP window size:  340 KByte (default)
.br
------------------------------------------------------------
.br
[  3] local 45.56.85.133 port 49960 connected with 45.33.58.123 port 5001 (ct=3.23 ms)
.br
[ ID] Interval        Transfer    Bandwidth       Write/Err  Rtry     Cwnd/RTT        NetPwr
.br
[  3] 0.00-1.00 sec   126 MBytes  1.05 Gbits/sec  1006/0          0       56K/626 us  210636.47
.br
[  3] 1.00-2.00 sec   138 MBytes  1.15 Gbits/sec  1100/0        299      483K/3884 us  37121.32
.br
[  3] 2.00-3.00 sec   137 MBytes  1.15 Gbits/sec  1093/0         24      657K/5087 us  28162.31
.br
[  3] 3.00-4.00 sec   126 MBytes  1.06 Gbits/sec  1010/0        284      294K/2528 us  52366.58
.br
[  3] 4.00-5.00 sec   117 MBytes   980 Mbits/sec  935/0        373      487K/2025 us  60519.66
.br
[  3] 5.00-6.00 sec   144 MBytes  1.20 Gbits/sec  1149/0          2      644K/3570 us  42185.36
.br
[  3] 6.00-7.00 sec   126 MBytes  1.06 Gbits/sec  1011/0        112      582K/5281 us  25092.56
.br
[  3] 7.00-8.00 sec   110 MBytes   922 Mbits/sec  879/0         56      279K/1957 us  58871.89
.br
[  3] 8.00-9.00 sec   127 MBytes  1.06 Gbits/sec  1014/0         46      483K/3372 us  39414.89
.br
[  3] 9.00-10.00 sec   132 MBytes  1.11 Gbits/sec  1054/0          0      654K/3380 us  40872.75
.br
[  3] 0.00-10.00 sec  1.25 GBytes  1.07 Gbits/sec  10251/0       1196       -1K/3170 us  42382.03

.TP
.B where (per -e,)
.B ct=
TCP connect time (or three way handshake time 3WHS)
.br
.B Write/Err
Total number of successful socket writes. Total number of non-fatal socket write errors
.br
.B Rtry
Total number of TCP retries
.br
.B Cwnd/RTT (*nix only)
TCP congestion window and round trip time (sampled where NA indicates no value)
.br
.B NetPwr (*nix only)
Network power defined as (throughput / RTT)

.PP

.B iperf -c host.doamin.com -i 1 --bounceback --permit-key=mytest --hide-ips
.br
------------------------------------------------------------
.br
Client connecting to (**hidden**), TCP port 5001
.br
Bursting:  100 Byte writes 10 times every 1.00 second(s)
.br
Bounce-back test (size= 100 Byte) (server hold req=0 usecs)
.br
TCP window size: 16.0 KByte (default)
.br
------------------------------------------------------------
.br
[mytest(1)] local *.*.*.96 port 38044 connected with *.*.*.123 port 5001 (bb len/hold=100/0) (icwnd/mss/irtt=14/1448/10605)
.br
[ ID] Interval        Transfer    Bandwidth         BB cnt=avg/min/max/stdev         Rtry  Cwnd/RTT    RPS
.br
[mytest(1)] 0.00-1.00 sec  1.95 KBytes  16.0 Kbits/sec    10=11.949/9.662/19.597/3.127 ms    0   14K/10930 us    83 rps
.br
[mytest(1)] 1.00-2.00 sec  1.95 KBytes  16.0 Kbits/sec    10=10.004/9.651/10.322/0.232 ms    0   14K/10244 us    99 rps
.br
[mytest(1)] 2.00-3.00 sec  1.95 KBytes  16.0 Kbits/sec    10=10.582/9.720/14.831/1.573 ms    0   14K/10352 us    94 rps
.br
[mytest(1)] 3.00-4.00 sec  1.95 KBytes  16.0 Kbits/sec    10=11.303/9.940/15.114/2.026 ms    0   14K/10832 us    88 rps
.br
[mytest(1)] 4.00-5.00 sec  1.95 KBytes  16.0 Kbits/sec    10=11.148/9.671/14.803/1.837 ms    0   14K/10858 us    89 rps
.br
[mytest(1)] 5.00-6.00 sec  1.95 KBytes  16.0 Kbits/sec    10=10.207/9.695/10.729/0.356 ms    0   14K/10390 us    97 rps
.br
[mytest(1)] 6.00-7.00 sec  1.95 KBytes  16.0 Kbits/sec    10=10.871/9.770/14.387/1.547 ms    0   14K/10660 us    91 rps
.br
[mytest(1)] 7.00-8.00 sec  1.95 KBytes  16.0 Kbits/sec    10=11.224/9.760/14.993/1.837 ms    0   14K/11027 us    89 rps
.br
[mytest(1)] 8.00-9.00 sec  1.95 KBytes  16.0 Kbits/sec    10=10.719/9.887/14.553/1.455 ms    0   14K/10620 us    93 rps
.br
[mytest(1)] 9.00-10.00 sec  1.95 KBytes  16.0 Kbits/sec    10=10.775/9.689/14.746/1.562 ms    0   14K/10596 us    92 rps
.br
[mytest(1)] 0.00-10.02 sec  19.5 KBytes  16.0 Kbits/sec    100=10.878/9.651/19.597/1.743 ms    0   14K/11676 us    91 rps
.br
[  1] 0.00-10.02 sec BB8(f)-PDF: bin(w=100us):cnt(100)=97:5,98:8,99:10,100:8,101:12,102:10,103:6,104:7,105:2,106:2,107:3,108:3,109:2,110:1,114:1,115:1,118:1,120:2,121:1,124:1,125:1,128:1,140:1,143:1,144:1,146:2,148:1,149:2,150:1,151:1,152:1,196:1 (5.00/95.00/99.7%=97/149/196,Outliers=0,obl/obu=0/0)
.br

.TP
.B where
.B BB cnt=avg/min/max/stdev
Count of bouncebacks, average time, minimum time, maximum time, standard deviation units of ms
.br
.B Rtry
Total number of TCP retries
.br
.B Cwnd/RTT (*nix only)
TCP congestion window and round trip time (sampled where NA indicates no value)
.br
.B RPS
Responses per second

.PP

.B TCP tests (server)

.B
iperf -s -e -i 1 -l 8K
.br
------------------------------------------------------------
.br
Server listening on TCP port 5001 with pid 13430
.br
Read buffer size: 8.00 KByte
.br
TCP window size: 85.3 KByte (default)
.br
------------------------------------------------------------
.br
[  4] local 45.33.58.123 port 5001 connected with 45.56.85.133 port 49960
.br
[ ID] Interval        Transfer    Bandwidth       Reads   Dist(bin=1.0K)
.br
[  4] 0.00-1.00 sec   124 MBytes  1.04 Gbits/sec  22249    798:2637:2061:767:2165:1563:589:11669
.br
[  4] 1.00-2.00 sec   136 MBytes  1.14 Gbits/sec  24780    946:3227:2227:790:2427:1888:641:12634
.br
[  4] 2.00-3.00 sec   137 MBytes  1.15 Gbits/sec  24484    1047:2686:2218:810:2195:1819:728:12981
.br
[  4] 3.00-4.00 sec   126 MBytes  1.06 Gbits/sec  20812    863:1353:1546:614:1712:1298:547:12879
.br
[  4] 4.00-5.00 sec   117 MBytes   984 Mbits/sec  20266    769:1886:1828:589:1866:1350:476:11502
.br
[  4] 5.00-6.00 sec   143 MBytes  1.20 Gbits/sec  24603    1066:1925:2139:822:2237:1827:744:13843
.br
[  4] 6.00-7.00 sec   126 MBytes  1.06 Gbits/sec  22635    834:2464:2249:724:2269:1646:608:11841
.br
[  4] 7.00-8.00 sec   110 MBytes   921 Mbits/sec  21107    842:2437:2747:592:2871:1903:496:9219
.br
[  4] 8.00-9.00 sec   126 MBytes  1.06 Gbits/sec  22804    1038:1784:2639:656:2738:1927:573:11449
.br
[  4] 9.00-10.00 sec   133 MBytes  1.11 Gbits/sec  23091    1088:1654:2105:710:2333:1928:723:12550
.br
[  4] 0.00-10.02 sec  1.25 GBytes  1.07 Gbits/sec  227306    9316:22088:21792:7096:22893:17193:6138:120790
.br
.TP
.B where (per -e,)
.B Reads
Total number of socket reads
.br
.B Dist(bin=size)
Eight bin histogram of the socket reads returned byte count. Bin
width is set per size. Bins are separated by a colon. In the
example, the bins are 0-1K, 1K-2K, .., 7K-8K.

.PP

.B TCP tests (server with --trip-times on client)
.B
iperf -s -i 1 -w 4M
.br
------------------------------------------------------------
.br
Server listening on TCP port 5001
.br
TCP window size: 8.00 MByte (WARNING: requested 4.00 MByte)
.br
------------------------------------------------------------
.br
[  4] local 192.168.1.4%eth0 port 5001 connected with 192.168.1.7 port 44798 (trip-times) (MSS=1448) (peer 2.0.14-alpha)
.br
[ ID] Interval        Transfer    Bandwidth    Burst Latency avg/min/max/stdev (cnt/size) inP NetPwr  Reads=Dist
.br
[  4] 0.00-1.00 sec  19.0 MBytes   159 Mbits/sec  52.314/10.238/117.155/19.779 ms (151/131717) 1.05 MByte 380.19  781=306:253:129:48:18:15:8:4
.br
[  4] 1.00-2.00 sec  20.0 MBytes   168 Mbits/sec  53.863/21.264/79.252/12.277 ms (160/131080) 1.08 MByte 389.38  771=294:236:126:60:18:24:10:3
.br
[  4] 2.00-3.00 sec  18.2 MBytes   153 Mbits/sec  58.718/22.000/137.944/20.397 ms (146/130964) 1.06 MByte 325.64  732=299:231:98:52:18:19:10:5
.br
[  4] 3.00-4.00 sec  19.7 MBytes   165 Mbits/sec  50.448/ 8.921/82.728/14.627 ms (158/130588)  997 KByte 409.00  780=300:255:121:58:15:18:7:6
.br
[  4] 4.00-5.00 sec  18.8 MBytes   158 Mbits/sec  53.826/11.169/115.316/15.541 ms (150/131420) 1.02 MByte 366.24  761=302:226:134:52:22:17:7:1
.br
[  4] 5.00-6.00 sec  19.5 MBytes   164 Mbits/sec  50.943/11.922/76.134/14.053 ms (156/131276) 1.03 MByte 402.00  759=273:246:149:45:16:18:4:8
.br
[  4] 6.00-7.00 sec  18.5 MBytes   155 Mbits/sec  57.643/10.039/127.850/18.950 ms (148/130926) 1.05 MByte 336.16  710=262:228:133:37:16:20:8:6
.br
[  4] 7.00-8.00 sec  19.6 MBytes   165 Mbits/sec  52.498/12.900/77.045/12.979 ms (157/131003) 1.00 MByte 391.78  742=288:200:135:68:16:23:4:8
.br
[  4] 8.00-9.00 sec  18.0 MBytes   151 Mbits/sec  58.370/ 8.026/150.243/21.445 ms (144/131255) 1.06 MByte 323.81  716=268:241:108:51:20:17:8:3
.br
[  4] 9.00-10.00 sec  18.4 MBytes   154 Mbits/sec  56.112/12.419/79.790/13.668 ms (147/131194) 1.05 MByte 343.70  822=330:303:120:26:16:14:9:4
.br
[  4] 10.00-10.06 sec  1.03 MBytes   146 Mbits/sec  69.880/45.175/78.754/10.823 ms (9/119632) 1.74 MByte 260.40  62=26:30:5:1:0:0:0:0
.br
[  4] 0.00-10.06 sec   191 MBytes   159 Mbits/sec  54.183/ 8.026/150.243/16.781 ms (1526/131072) 1.03 MByte 366.98  7636=2948:2449:1258:498:175:185:75:48
.TP
.B where (per -e,)
.B Burst Latency
One way TCP write() to read() latency in mean/minimum/maximum/standard deviation format
(Note: requires the client's and server's system clocks to be
synchronized to a common reference, e.g. using precision time protocol
PTP. A GPS disciplined OCXO is a recommended reference.)
.br
.B cnt
Number of completed bursts received and used for the burst latency calculations
.br
.B size
Average burst size in bytes (computed average and estimate only)
.br
.B inP
inP, short for in progress, is the average number of bytes in progress or in flight. This is taken from the application level write to read perspective. Note this is
a mean value. The parenthesis value is the standard deviation from the mean.  (Requires --trip-times on client. See Little's law in NOTES.)
.br
.B NetPwr
Network power defined as (throughput / one way latency)

.PP

.B TCP tests (with one way delay sync check -X and --trip-times on the client)

.B iperf -c 192.168.1.4 -X -e --trip-times -i 1  -t 2
.br
------------------------------------------------------------
.br
Client connecting to 192.168.1.4, TCP port 5001 with pid 16762 (1 flows)
.br
Write buffer size: 131072 Byte
.br
TCP window size: 85.0 KByte (default)
.br
------------------------------------------------------------
.br
.B [  1] Clock sync check (ms): RTT/Half=(3.361/1.680) OWD-send/ack/asym=(2.246/1.115/1.131)
.br
[  1] local 192.168.1.1%ap0 port 47466 connected with 192.168.1.4 port 5001 (MSS=1448) (trip-times) (sock=3) (peer 2.1.4-master)
.br
[ ID] Interval        Transfer    Bandwidth       Write/Err  Rtry     Cwnd/RTT        NetPwr
.br
[  1] 0.00-1.00 sec  9.50 MBytes  79.7 Mbits/sec  77/0          0     2309K/113914 us  87
.br
[  1] 1.00-2.00 sec  7.12 MBytes  59.8 Mbits/sec  57/0          0     2492K/126113 us  59
.br
[  1] 2.00-2.42 sec   128 KBytes  2.47 Mbits/sec  2/0          0     2492K/126113 us  2
.br
[  1] 0.00-2.42 sec  16.8 MBytes  58.0 Mbits/sec  136/0          0     2492K/126113 us  57
.br

.PP

.B UDP tests (client)

.B iperf -c <host> -e -i 1 -u -b 10m
.br
------------------------------------------------------------
.br
Client connecting to <host>, UDP port 5001 with pid 5169
.br
Sending 1470 byte datagrams, IPG target: 1176.00 us (kalman adjust)
.br
UDP buffer size:  208 KByte (default)
.br
------------------------------------------------------------
.br
[  3] local 45.56.85.133 port 32943 connected with 45.33.58.123 port 5001
.br
[ ID] Interval        Transfer     Bandwidth      Write/Err  PPS
.br
[  3] 0.00-1.00 sec  1.19 MBytes  10.0 Mbits/sec  852/0      851 pps
.br
[  3] 1.00-2.00 sec  1.19 MBytes  10.0 Mbits/sec  850/0      850 pps
.br
[  3] 2.00-3.00 sec  1.19 MBytes  10.0 Mbits/sec  850/0      850 pps
.br
[  3] 3.00-4.00 sec  1.19 MBytes  10.0 Mbits/sec  851/0      850 pps
.br
[  3] 4.00-5.00 sec  1.19 MBytes  10.0 Mbits/sec  850/0      850 pps
.br
[  3] 5.00-6.00 sec  1.19 MBytes  10.0 Mbits/sec  850/0      850 pps
.br
[  3] 6.00-7.00 sec  1.19 MBytes  10.0 Mbits/sec  851/0      850 pps
.br
[  3] 7.00-8.00 sec  1.19 MBytes  10.0 Mbits/sec  850/0      850 pps
.br
[  3] 8.00-9.00 sec  1.19 MBytes  10.0 Mbits/sec  851/0      850 pps
.br
[  3] 0.00-10.00 sec  11.9 MBytes  10.0 Mbits/sec  8504/0      850 pps
.br
[  3] Sent 8504 datagrams
.br
[  3] Server Report:
.br
[  3] 0.00-10.00 sec  11.9 MBytes  10.0 Mbits/sec   0.047 ms    0/ 8504 (0%)  0.537/ 0.392/23.657/ 0.497 ms  850 pps  2329.37
.br
.TP
.B where (per -e,)
.B Write/Err
Total number of successful socket writes. Total number of non-fatal socket write errors
.br
.B PPS
Transmit packet rate in packets per second

.PP

.B UDP tests (server)
.B iperf -s -i 1 -w 4M -u
.br
------------------------------------------------------------
.br
Server listening on UDP port 5001
.br
Receiving 1470 byte datagrams
.br
UDP buffer size: 8.00 MByte (WARNING: requested 4.00 MByte)
.br
------------------------------------------------------------
.br
[  3] local 192.168.1.4 port 5001 connected with 192.168.1.1 port 60027 (WARN: winsize=8.00 MByte req=4.00 MByte) (trip-times) (0.0) (peer 2.0.14-alpha)
.br
[ ID] Interval        Transfer     Bandwidth        Jitter   Lost/Total  Latency avg/min/max/stdev PPS  inP NetPwr
.br
[  3] 0.00-1.00 sec  44.5 MBytes   373 Mbits/sec   0.071 ms 52198/83938 (62%) 75.185/ 2.367/85.189/14.430 ms 31854 pps 3.64 MByte 620.58
.br
[  3] 1.00-2.00 sec  44.8 MBytes   376 Mbits/sec   0.015 ms 59549/143701 (41%) 79.609/75.603/85.757/ 1.454 ms 31954 pps 3.56 MByte 590.04
.br
[  3] 2.00-3.00 sec  44.5 MBytes   373 Mbits/sec   0.017 ms 59494/202975 (29%) 80.006/75.951/88.198/ 1.638 ms 31733 pps 3.56 MByte 583.07
.br
[  3] 3.00-4.00 sec  44.5 MBytes   373 Mbits/sec   0.019 ms 59586/262562 (23%) 79.939/75.667/83.857/ 1.145 ms 31767 pps 3.56 MByte 583.57
.br
[  3] 4.00-5.00 sec  44.5 MBytes   373 Mbits/sec   0.081 ms 59612/322196 (19%) 79.882/75.400/86.618/ 1.666 ms 31755 pps 3.55 MByte 584.40
.br
[  3] 5.00-6.00 sec  44.7 MBytes   375 Mbits/sec   0.064 ms 59571/381918 (16%) 79.767/75.571/85.339/ 1.556 ms 31879 pps 3.56 MByte 588.02
.br
[  3] 6.00-7.00 sec  44.6 MBytes   374 Mbits/sec   0.041 ms 58990/440820 (13%) 79.722/75.662/85.938/ 1.087 ms 31820 pps 3.58 MByte 586.73
.br
[  3] 7.00-8.00 sec  44.7 MBytes   375 Mbits/sec   0.027 ms 59679/500548 (12%) 79.745/75.704/84.731/ 1.094 ms 31869 pps 3.55 MByte 587.46
.br
[  3] 8.00-9.00 sec  44.3 MBytes   371 Mbits/sec   0.078 ms 59230/559499 (11%) 80.346/75.514/94.293/ 2.858 ms 31590 pps 3.58 MByte 577.97
.br
[  3] 9.00-10.00 sec  44.4 MBytes   373 Mbits/sec   0.073 ms 58782/618394 (9.5%) 79.125/75.511/93.638/ 1.643 ms 31702 pps 3.55 MByte 588.99
.br
[  3] 10.00-10.08 sec  3.53 MBytes   367 Mbits/sec   0.129 ms 6026/595236 (1%) 94.967/80.709/99.685/ 3.560 ms 31107 pps 3.58 MByte 483.12
.br
[  3] 0.00-10.08 sec   449 MBytes   374 Mbits/sec   0.129 ms 592717/913046 (65%) 79.453/ 2.367/99.685/ 5.200 ms 31776 pps (null) 587.91
.br

.TP
.B where (per -e,)
.B Latency
End to end latency in mean/minimum/maximum/standard deviation format
(Note: requires the client's and server's system clocks to be
synchronized to a common reference, e.g. using precision time protocol
PTP. A GPS disciplined OCXO is a recommended reference.)
.br
.B PPS
Received packet rate in packets per second
.br
.B inP
inP, short for in progress, is the average number of bytes in progress or in flight. This is taken from an application write to read perspective. (Requires --trip-times on client. See Little's law in NOTES.)
.br
.B NetPwr
Network power defined as (throughput / latency)

.PP

.B Isochronous UDP tests (client)

.B iperf -c 192.168.100.33 -u -e -i 1 --isochronous=60:100m,10m --realtime
.br
------------------------------------------------------------
.br
Client connecting to 192.168.100.33, UDP port 5001 with pid 14971
.br
UDP isochronous: 60 frames/sec mean= 100 Mbit/s, stddev=10.0 Mbit/s, Period/IPG=16.67/0.005 ms
.br
UDP buffer size:  208 KByte (default)
.br
------------------------------------------------------------
.br
[  3] local 192.168.100.76 port 42928 connected with 192.168.100.33 port 5001
.br
[ ID] Interval        Transfer     Bandwidth      Write/Err  PPS  frames:tx/missed/slips
.br
[  3] 0.00-1.00 sec  12.0 MBytes   101 Mbits/sec  8615/0     8493 pps   62/0/0
.br
[  3] 1.00-2.00 sec  12.0 MBytes   100 Mbits/sec  8556/0     8557 pps   60/0/0
.br
[  3] 2.00-3.00 sec  12.0 MBytes   101 Mbits/sec  8586/0     8586 pps   60/0/0
.br
[  3] 3.00-4.00 sec  12.1 MBytes   102 Mbits/sec  8687/0     8687 pps   60/0/0
.br
[  3] 4.00-5.00 sec  11.8 MBytes  99.2 Mbits/sec  8468/0     8468 pps   60/0/0
.br
[  3] 5.00-6.00 sec  11.9 MBytes  99.8 Mbits/sec  8519/0     8520 pps   60/0/0
.br
[  3] 6.00-7.00 sec  12.1 MBytes   102 Mbits/sec  8694/0     8694 pps   60/0/0
.br
[  3] 7.00-8.00 sec  12.1 MBytes   102 Mbits/sec  8692/0     8692 pps   60/0/0
.br
[  3] 8.00-9.00 sec  11.9 MBytes   100 Mbits/sec  8537/0     8537 pps   60/0/0
.br
[  3] 9.00-10.00 sec  11.8 MBytes  99.0 Mbits/sec  8450/0     8450 pps   60/0/0
.br
[  3] 0.00-10.01 sec   120 MBytes   100 Mbits/sec  85867/0     8574 pps  602/0/0
.br
[  3] Sent 85867 datagrams
.br
[  3] Server Report:
.br
[  3] 0.00-9.98 sec   120 MBytes   101 Mbits/sec   0.009 ms  196/85867 (0.23%)  0.665/ 0.083/ 1.318/ 0.174 ms 8605 pps  18903.85
.br
.TP
.B where (per -e,)
.B frames:tx/missed/slips
Total number of isochronous frames or bursts. Total number of frame ids not sent. Total number of frame slips

.PP

.B Isochronous UDP tests (server)

.B iperf -s -e -u --udp-histogram=100u,2000 --realtime
.br
------------------------------------------------------------
.br
Server listening on UDP port 5001 with pid 5175
.br
Receiving 1470 byte datagrams
.br
UDP buffer size:  208 KByte (default)
.br
------------------------------------------------------------
.br
[  3] local 192.168.100.33 port 5001 connected with 192.168.100.76 port 42928 isoch (peer 2.0.13-alpha)
.br
[ ID] Interval        Transfer     Bandwidth        Jitter   Lost/Total  Latency avg/min/max/stdev PPS  NetPwr  Frames/Lost
.br
[  3] 0.00-9.98 sec   120 MBytes   101 Mbits/sec   0.010 ms  196/85867 (0.23%)  0.665/ 0.083/ 1.318/ 0.284 ms 8585 pps  18903.85  601/1
.br
[  3] 0.00-9.98 sec T8(f)-PDF: 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 (5.00/95.00%=3/12,Outliers=0,obl/obu=0/0)
.br
[  3] 0.00-9.98 sec F8(f)-PDF: 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 (5.00/95.00%=17/24,Outliers=0,obl/obu=0/0)

.TP
.B where,
.B Frames/lost
Total number of frames (or bursts) received. Total number of bursts lost or error-ed
.br
.B
T8-PDF(f)
Latency histogram for packets
.br
.B F8-PDF(f)
Latency histogram for frames


.SH ENVIRONMENT
.TP
.B
Note:
The environment variable option settings haven't been maintained well.
See the source code if these are of interest.
.RE
.SH NOTES
.B Numeric options:
Some numeric options support format characters per '<value>\fIc\fR'
(e.g. 10M) where the \fIc\fR format 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
.P
.B Rate limiting:
The -b option supports read and write rate limiting at the application level.  The -b option
on the client also supports variable offered loads through the <mean>,<standard deviation> format, e.g.
-b 100m,10m. The distribution used is log normal. Similar for the isochronous
option. The -b on the server rate limits the reads. Socket based pacing is also
supported using the --fq-rate long option. This will work with the --reverse
and --full-duplex options as well.
.P
.B
IP tos:
Specifies the type-of-service or DSCP class for connections.  Accepted values are \fBaf11, af12, af13, af21,
af22, af23, af31, af32, af33, af41, af42, af43, cs0, cs1, cs2, cs3, cs4, cs5, cs6, cs7, ef, le, nqb, nqb2,
ac_be, ac_bk, ac_vi, ac_vo, lowdelay, throughput, reliability\fR, a numeric value, or none to use the operating system default.
The ac_xx values are the four access categories defined in WMM for Wi-Fi, and they are aliases for DSCP values that will be mapped
to the corresponding ACs under the assumption that the device uses the DSCP-to-UP mapping table specified in IETF RFC 8325.
.P
.B --trip-times
The --trip-times option enables many one way delay (OWD) metrics. Also note that using --trip-times on a TCP client
will cause --tcp-write-prefetch to be set to a small value if tcp-write-prefetch hasn't hasn't also been set. This is
done to reduce send side bloat latency (which is unrelated to network induced latency.) Set --tcp-write-prefetch
to zero to disable this (which will disable TCP_NOTSENT_LOWAT) and will allow for send side bloat.
.P
.B Synchronized clocks:
The --trip-times option indicates that the client's and server's clocks are synchronized to a common reference.
Network Time Protocol (NTP) or Precision Time Protocol (PTP) are commonly used for
this. The reference clock(s) error and the synchronization protocols will affect
the accuracy of any end to end latency measurements.
.P
.B Histograms and non-parametric statistics:
The --histograms option provides the raw data where nothing is averaged. This is useful for non-parametric
distributions, e.g. latency. The standard output does use the central limit theorem to produce average,
minimum, maximum and variation. This loses information when the underlining distribution is not Gaussian.
Histograms are supported so this information is made available.
.P
.B Histogram output interpretation:
Below is an example bounceback histogram and how to interpret it

.br
[  1] 0.00-5.10 sec BB8-PDF:
.br
bin(w=100us):cnt(50)=35:1,37:1,39:1,40:3,41:4,42:1,43:1,52:1,57:1,65:1,68:1,69:1,70:1,72:2,74:1,75:5,78:1,79:2,80:4,81:3,82:1,83:1,88:2,90:2,92:1,94:1,117:1,126:1,369:1,1000:1,1922:1,3710:1 (5.00/95.00/99.7%=39/1000/3710,Outliers=4,obl/obu=0/0)
.TP
.B where,
.B [  1]
The traffic thread number
.br
.B 0.00-5.10 sec
The time interval of the histogram
.br
.B BB8-PDF
BB8 is the histogram name and the PDF indicates a histogram raw output
.br
.B bin(w=100us)
provides the bin width. The bin width of this histogram is 100 microseconds
.br
.B cnt(50)
provides the total number of samples in the histogram. There are 50 samples in this histogram
.br
.B 35:1
provides the bin no then the number of samples in that bin. Bin 35 with bin width 100us is 3.4 ms - 3.5 ms and there was one sample that landed there
.br
.B 5.00/95.00/99.7%=39/1000/3710
provides the bin confidence intervals (per the integrated cumulative distribution function.) 5% landed in 3.9 ms or better (recall bin number multiplies by bin width.) 95% landed in 10 ms or better. 99.7% or 3 standards of deviation landed in 37.1 ms or better
.br
.B Outliers=4
provides the outlier count, similar to 3IQR (3 times the inter quartile range) but uses 10% and 90% for inner & outer fence post, then 3 times that for outlier detection.
.br
.B obl/obu=0/0
out of bounds lower and out of bands upper, provides the number of samples that could not be binned because the value landed outside of all possible bins

.P
.B
Binding
is done at the logical level of port and ip address (or layer 3) using the -B option
and a colon as the separator between port and the ip addr. Binding at the
device (or layer 2) level requires the percent (%) as the delimiter (for both the client and the server.)
An example for src port and ip address is -B 192.168.1.1:6001. To \fBbind the src port only\fR and
let the operating system choose the source ip address use 0.0.0.0, e.g.
\fB-B 0.0.0.0:6001\fR. On the client, the -B option affects the \fBbind\fR(2)
system call, and will set the source ip address and the source port, e.g. iperf -c <host>
-B 192.168.100.2:6002. This controls the packet's source values but not routing.
These can be confusing in that a route or device lookup may not
be that of the device with the configured source IP.
So, for example, if the IP address of eth0 is used for -B and the
routing table for the destination IP address resolves
the output interface to be eth1, then the host will send the packet
out device eth1 while using the source IP address of eth0 in the packet.
To affect the physical output interface (e.g. dual homed systems) either use
-c <host>%<dev> (requires root) which bypasses this host route table lookup,
or configure policy routing per each -B source address and set the
output interface appropriately in the policy routes. On the server or receive,
only packets destined to -B IP address will be received. It's also useful
for multicast. For example, iperf -s -B 224.0.0.1\fB%eth0\fR
will only accept ip multicast packets with dest ip 224.0.0.1 that are
received on the eth0 interface, while iperf -s -B 224.0.0.1 will
receive those packets on any interface,
Finally, the device specifier is required for v6 link-local,
e.g. -c [v6addr]%<dev> -V, to select the output interface.
.P
.B Reverse, full-duplex, dualtest (-d) and tradeoff (-r):
The \fB--reverse\fR (-R) and \fB--full-duplex\fR options can be confusing when compared to the
older options of \fB--dualtest (-d)\fR and \fB--tradeoff (-r)\fR. The newer options of \fB--reverse\fR and \fB--full-duplex\fR only
open one socket and read and write to the \fBsame socket descriptor\fR, i.e. use the socket in full duplex mode.  The older -d and -r open
second sockets in the opposite direction and do not use a socket in full duplex mode. Note that full duplex applies to the socket
and not to the network devices and that full duplex sockets are supported by the
operating systems regardless if an underlying network supports full duplex transmission and reception.
It's \fBsuggested to use --reverse\fR if you
want to \fBtest through a NAT firewall\fR (or -R on non-windows systems). This applies
role reversal of the test after opening the full duplex socket.  (Note: Firewall piercing may be required to use -d and -r
if a NAT gateway is in the path.)
.P
Also, the --reverse -b <rate> setting behaves differently for TCP and UDP. For
TCP it will rate limit the read side, i.e. the iperf client
(role reversed to act as a server) reading from the full duplex socket.
This will in turn flow control the reverse traffic per standard TCP
congestion control. The --reverse -b <rate> will be applied on
transmit (i.e. the server role reversed to act as a client) for UDP
since there is no flow control with UDP. There is no option to
directly rate limit the writes with TCP testing when using --reverse.
.P
.B Bounceback
The bounceback test allows one to measure network responsiveness (which, in this test, is an inverse of latency.)
The units are responses per second or rps. Latency is merely delay in units of time. Latency metrics require one
to know the delay of what's being measured. For bounceback it's a client write to a server read followed by a server
write and then the client read. The original write is bounce backed. Iperf 2 sets up the socket with TCP_NODELAY
and possibly TCP_QUICKACK (unless disabled). The client sends a small write (which defaults to 100 bytes unless -l is set)
and issues a read waiting for the "bounceback" from the server. The server waits for a read and then
optionally delays before sending the payload back. This repeats until the traffic ends. Results
are shown in units of rps and time delays.
.P
The TCP_QUICKACK socket option will be enabled during bounceback tests when the bounceback-hold
is set to a non-zero value. The socket option is applied after every read() on the server
and before the hold delay call. It's also applied on the client. Use --bounceback-no-quickack
to have TCP run in default mode per the socket (which is most likely TCP_QUICKACK being off.)
.P
.B TCP Connect times:
The TCP connect time (or three way handshake) can be seen on the iperf
client when the -e (--enhanced) option is set. Look for the
ct=<value> in the connected message, e.g.in '[ 3] local 192.168.1.4
port 48736 connected with 192.168.1.1 port 5001 \fB(ct=1.84 ms)\fR'
shows the 3WHS took 1.84 milliseconds.
.P
.B Port-range
Port ranges are supported using the hyphen notation, e.g. 6001-6009. This will cause multiple threads, one per port, on either the listener/server or the client. The user needs to take care that the ports in the port range are available and not already in use per the operating system. The -P is supported on the client and will apply to each destination port within the port range.
Finally, this can be used for a workaround for Windows UDP and -P > 1 as Windows doesn't dispatch UDP per a server's connect and the quintuple.
.P
.B Packet per second (pps) calculation
The packets per second calculation is done as a derivative, i.e. number of packets divided by
time. The time is taken from the previous last packet to the current last packet. It is not
the sample interval time. The last packet can land at different times within an interval.
This means that pps does not have to match rx bytes divided by the sample interval.
Also, with --trip-times set, the packet time on receive is set by the sender's write
time so pps indicates the end to end pps with --trip-times. The RX pps calculation is receive
side only when -e is set and --trip-times is not set.
.P
\fBLittle's Law\fR in queuing theory is a theorem that determines the average number of items (L) in a stationary queuing system based on the average waiting time (W) of an item within a system and the average number of items arriving at the system per unit of time (lambda). Mathematically, it's L = lambda * W. As used here, the units are bytes. The arrival rate is taken from the writes.
.P
.B Network power:
The network power (NetPwr) metric is \fBexperimental\fR. It's a
convenience function defined as throughput/delay.
For TCP transmits, the delay is the sampled RTT times.
For TCP receives, the delay is the write to read latency.
For UDP the delay is the end/end latency.
Don't confuse this with the physics definition of power (delta
energy/delta time) but more of a measure of a desirable property
divided by an undesirable property. Also note, one must use -i
interval with TCP to get this as that's what sets the RTT sampling
rate. The metric is scaled to assist with human readability.
.P
.B Multicast:
Iperf 2 supports multicast with a couple of caveats. First, multicast streams cannot take advantage of the -P option. The server will serialize multicast streams. Also, it's highly encouraged to use a -t on a server that will be used for multicast clients. That is because the single end of traffic packet sent from client to server may get lost and there are no redundant end of traffic packets.  Setting -t on the server will kill the server thread in the event this packet is indeed lost.
.P
.B TCP_QUICKACK:
The TCP_QUICKACK socket option will be applied after every read() on the server such that TCP acks are sent immediately, rather than possibly delayed.
.P
.B Fast Sampling:
Use
.B ./configure --enable-fastsampling
and then compile from source to enable four digit (e.g. 1.0000) precision in reports' timestamps. Useful for sub-millisecond sampling.
.SH DIAGNOSTICS
Use
.B ./configure --enable-thread-debug
and then compile from source to enable both asserts and advanced debugging of the tool itself.
.SH BUGS
See https://sourceforge.net/p/iperf2/tickets/
.SH 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 Tirumala, Jim Ferguson, Jon Dugan <jdugan at x1024 dot net>,
Feng Qin,
Kevin Gibbs,
John Estabrook <jestabro at ncsa.uiuc.edu>,
Andrew Gallatin <gallatin at gmail.com>,
Stephen Hemminger <shemminger at linux-foundation.org>,
Tim Auckland <tim.auckland at gmail.com>,
Robert J. McMahon <rjmcmahon at rjmcmahon.com>
.SH "SEE ALSO"
.BR accept (2),  bind (2),  close (2), connect (2),  fcntl (2),  getpeername (2),  getsockname (2),  getsockopt (2),  listen (2),  read (2),  recv (2),  select (2),  send (2),  setsockopt (2),  shutdown (2),  write (2),  ip (7),  socket (7),  tcp (7),  udp (7)
.LP
Source code at http://sourceforge.net/projects/iperf2/
.LP
"Unix Network Programming, Volume 1: The Sockets Networking API (3rd Edition) 3rd Edition"
by W. Richard Stevens (Author), Bill Fenner (Author), Andrew M. Rudoff (Author)