1: .TH IPERF 1 "October 2015" ESnet "User Manuals"
2: .SH NAME
3: iperf3 \- perform network throughput tests
4: .SH SYNOPSIS
5: .B iperf3 -s [
6: .I options
7: .B ]
8: .br
9: .B iperf3 -c
10: .I server
11: .B [
12: .I options
13: .B ]
14:
15: .SH DESCRIPTION
16: iperf3 is a tool for performing network throughput measurements. It can test
17: either TCP or UDP throughput. To perform an iperf3 test the user must
18: establish both a server and a client.
19:
20: .SH "GENERAL OPTIONS"
21: .TP
22: .BR -p ", " --port " \fIn\fR"
23: set server port to listen on/connect to to \fIn\fR (default 5201)
24: .TP
25: .BR -f ", " --format " "
26: [kmKM] format to report: Kbits, Mbits, KBytes, MBytes
27: .TP
28: .BR -i ", " --interval " \fIn\fR"
29: pause \fIn\fR seconds between periodic bandwidth reports;
30: default is 1, use 0 to disable
31: .TP
32: .BR -F ", " --file " \fIname\fR"
33: client-side: read from the file and write to the network, instead
34: of using random data;
35: server-side: read from the network and write to the file, instead
36: of throwing the data away
37: .TP
38: .BR -A ", " --affinity " \fIn/n,m\fR"
39: Set the CPU affinity, if possible (Linux and FreeBSD only).
40: On both the client and server you can set the local affinity by using
41: the \fIn\fR form of this argument (where \fIn\fR is a CPU number).
42: In addition, on the client side you can override the server's
43: affinity for just that one test, using the \fIn,m\fR form of
44: argument.
45: Note that when using this feature, a process will only be bound
46: to a single CPU (as opposed to a set containing potentialy multiple
47: CPUs).
48: .TP
49: .BR -B ", " --bind " \fIhost\fR"
50: bind to a specific interface
51: .TP
52: .BR -V ", " --verbose " "
53: give more detailed output
54: .TP
55: .BR -J ", " --json " "
56: output in JSON format
57: .TP
58: .BR --logfile " \fIfile\fR"
59: send output to a log file.
60: .TP
61: .BR -d ", " --debug " "
62: emit debugging output.
63: Primarily (perhaps exclusively) of use to developers.
64: .TP
65: .BR -v ", " --version " "
66: show version information and quit
67: .TP
68: .BR -h ", " --help " "
69: show a help synopsis
70:
71: .SH "SERVER SPECIFIC OPTIONS"
72: .TP
73: .BR -s ", " --server " "
74: run in server mode
75: .TP
76: .BR -D ", " --daemon " "
77: run the server in background as a daemon
78: .TP
79: .BR -I ", " --pidfile " \fIfile\fR"
80: write a file with the process ID, most useful when running as a daemon.
81: .TP
82: .BR -1 ", " --one-off
83: handle one client connection, then exit.
84:
85: .SH "CLIENT SPECIFIC OPTIONS"
86: .TP
87: .BR -c ", " --client " \fIhost\fR"
88: run in client mode, connecting to the specified server
89: .TP
90: .BR --sctp
91: use SCTP rather than TCP (FreeBSD and Linux)
92: .TP
93: .BR -u ", " --udp
94: use UDP rather than TCP
95: .TP
96: .BR -b ", " --bandwidth " \fIn\fR[KM]"
97: set target bandwidth to \fIn\fR bits/sec (default 1 Mbit/sec for UDP, unlimited for TCP).
98: If there are multiple streams (\-P flag), the bandwidth limit is applied
99: separately to each stream.
100: You can also add a '/' and a number to the bandwidth specifier.
101: This is called "burst mode".
102: It will send the given number of packets without pausing, even if that
103: temporarily exceeds the specified bandwidth limit.
104: Setting the target bandwidth to 0 will disable bandwidth limits
105: (particularly useful for UDP tests).
106: On platforms supporting the \fCSO_MAX_PACING_RATE\fR socket option
107: (currently only Linux), fair-queueing socket-level pacing, implemented in
108: the kernel, will be used.
109: On other platforms, iperf3 will implement its own rate control.
110: .TP
111: .BR --no-fq-socket-pacing
112: disable the use of fair-queueing based socket-level pacing with the -b
113: option, and rely on iperf3's internal rate control.
114: .TP
115: .BR -t ", " --time " \fIn\fR"
116: time in seconds to transmit for (default 10 secs)
117: .TP
118: .BR -n ", " --bytes " \fIn\fR[KM]"
119: number of bytes to transmit (instead of \-t)
120: .TP
121: .BR -k ", " --blockcount " \fIn\fR[KM]"
122: number of blocks (packets) to transmit (instead of \-t or \-n)
123: .TP
124: .BR -l ", " --length " \fIn\fR[KM]"
125: length of buffer to read or write (default 128 KB for TCP, 8KB for UDP)
126: .TP
127: .BR --cport " \fIport\fR"
128: bind data streams to a specific client port (for TCP and UDP only,
129: default is to use an ephemeral port)
130: .TP
131: .BR -P ", " --parallel " \fIn\fR"
132: number of parallel client streams to run
133: .TP
134: .BR -R ", " --reverse
135: run in reverse mode (server sends, client receives)
136: .TP
137: .BR -w ", " --window " \fIn\fR[KM]"
138: window size / socket buffer size (this gets sent to the server and used on that side too)
139: .TP
140: .BR -M ", " --set-mss " \fIn\fR"
141: set TCP/SCTP maximum segment size (MTU - 40 bytes)
142: .TP
143: .BR -N ", " --no-delay " "
144: set TCP/SCTP no delay, disabling Nagle's Algorithm
145: .TP
146: .BR -4 ", " --version4 " "
147: only use IPv4
148: .TP
149: .BR -6 ", " --version6 " "
150: only use IPv6
151: .TP
152: .BR -S ", " --tos " \fIn\fR"
153: set the IP 'type of service'
154: .TP
155: .BR -L ", " --flowlabel " \fIn\fR"
156: set the IPv6 flow label (currently only supported on Linux)
157: .TP
158: .BR -X ", " --xbind " \fIname\fR"
159: Bind SCTP associations to a specific subset of links using sctp_bindx(3).
160: The \fB--B\fR flag will be ignored if this flag is specified.
161: Normally SCTP will include the protocol addresses of all active links
162: on the local host when setting up an association. Specifying at least
163: one \fB--X\fR name will disable this behaviour.
164: This flag must be specified for each link to be included in the
165: association, and is supported for both iperf servers and clients
166: (the latter are supported by passing the first \fB--X\fR argument to bind(2)).
167: Hostnames are accepted as arguments and are resolved using
168: getaddrinfo(3).
169: If the \fB--4\fR or \fB--6\fR flags are specified, names
170: which do not resolve to addresses within the
171: specified protocol family will be ignored.
172: .TP
173: .BR --nstreams " \fIn\fR"
174: Set number of SCTP streams.
175: .TP
176: .BR -Z ", " --zerocopy " "
177: Use a "zero copy" method of sending data, such as sendfile(2),
178: instead of the usual write(2).
179: .TP
180: .BR -O ", " --omit " \fIn\fR"
181: Omit the first n seconds of the test, to skip past the TCP slow-start
182: period.
183: .TP
184: .BR -T ", " --title " \fIstr\fR"
185: Prefix every output line with this string.
186: .TP
187: .BR -C ", " --congestion " \fIalgo\fR"
188: Set the congestion control algorithm (Linux and FreeBSD only). An
189: older
190: .B --linux-congestion
191: synonym for this flag is accepted but is deprecated.
192: .TP
193: .BR "--get-server-output"
194: Get the output from the server.
195: The output format is determined by the server (in particular, if the
196: server was invoked with the \fB--json\fR flag, the output will be in
197: JSON format, otherwise it will be in human-readable format).
198: If the client is run with \fB--json\fR, the server output is included
199: in a JSON object; otherwise it is appended at the bottom of the
200: human-readable output.
201:
202: .SH AUTHORS
203: A list of the contributors to iperf3 can be found within the
204: documentation located at
205: \fChttp://software.es.net/iperf/dev.html#authors\fR.
206:
207: .SH "SEE ALSO"
208: libiperf(3),
209: http://software.es.net/iperf
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>