Annotation of embedaddon/iperf/docs/dev.rst, revision 1.1.1.1
1.1 misho 1: iperf3 Development
2: ==================
3:
4: The iperf3 project is hosted on GitHub at:
5:
6: http://github.com/esnet/iperf
7:
8: This site includes the source code repository, issue tracker, and
9: wiki.
10:
11: Mailing Lists
12: -------------
13:
14: The developer list for iperf3 is: iperf-dev@googlegroups.com.
15: Information on joining the mailing list can be found at:
16:
17: http://groups.google.com/group/iperf-dev
18:
19: There is, at the moment, no mailing list for user questions, although
20: a low volume of inquiries on the developer list is probably
21: acceptable. If necessary, a user-oriented mailing list might be
22: created in the future.
23:
24: Bug Reports
25: -----------
26:
27: Before submitting a bug report, try checking out the latest version of
28: the code, and confirm that it's not already fixed. Then submit to the
29: iperf3 issue tracker on GitHub:
30:
31: https://github.com/esnet/iperf/issues
32:
33: **Note:** Issues submitted to the old iperf3 issue tracker on Google
34: Code (or comments to existing issues on the Google Code issue tracker)
35: will be ignored.
36:
37: Changes from iperf 2.x
38: ----------------------
39:
40: New options (not necessarily complete, please refer to the manual page
41: for a complete list of iperf3 options)::
42:
43: -V, --verbose more detailed output than before
44: -J, --json output in JSON format
45: -Z, --zerocopy use a 'zero copy' sendfile() method of sending data
46: -O, --omit N omit the first n seconds (to ignore slowstart)
47: -T, --title str prefix every output line with this string
48: -F, --file name xmit/recv the specified file
49: -A, --affinity n/n,m set CPU affinity (Linux and FreeBSD only)
50: -k, --blockcount #[KMG] number of blocks (packets) to transmit (instead
51: of -t or -n)
52: -L, --flowlabel set IPv6 flow label (Linux only)
53:
54: Changed flags::
55:
56: -C, --linux-congestion set congestion control algorithm (Linux only)
57: (-Z in iperf2)
58:
59:
60: Deprecated flags (currently no plans to support)::
61:
62: -d, --dualtest Do a bidirectional test simultaneously
63: -r, --tradeoff Do a bidirectional test individually
64: -T, --ttl time-to-live, for multicast (default 1)
65: -x, --reportexclude [CDMSV] exclude C(connection) D(data) M(multicast)
66: S(settings) V(server) reports
67: -y, --reportstyle C report as a Comma-Separated Values
68:
69: Also deprecated is the ability to set the options via environment
70: variables.
71:
72: Known Issues
73: ------------
74:
75: The following problems are notable known issues, which are probably of
76: interest to a large fraction of users or have high impact for some
77: users, and for which issues have already been filed in the issue
78: tracker. These issues are either open (indicating no solution
79: currently exists) or closed with the notation that no further attempts
80: to solve the problem are currently being made:
81:
82: * UDP performance: Some problems have been noticed with iperf3 on the
83: ESnet 100G testbed at high UDP rates (above 10Gbps). The symptom is
84: that on any particular run of iperf3 the receiver reports a loss
85: rate of about 20%, regardless of the ``-b`` option used on the client
86: side. This problem appears not to be iperf3-specific, and may be
87: due to the placement of the iperf3 process on a CPU and its relation
88: to the inbound NIC. In some cases this problem can be mitigated by
89: an appropriate use of the CPU affinity (``-A``) option. (Issue #55)
90:
91: * Interval reports on high-loss networks: The way iperf3 is currently
92: implemented, the sender write command will block until the entire
93: block has been written. This means that it might take several
94: seconds to send a full block if the network has high loss, and the
95: interval reports will have widely varying interval times. A
96: solution is being discussed, but in the meantime a work around is to
97: try using a small block size, for example ``-l 4K``. (Issue #125,
98: a fix will be released in iperf 3.1)
99:
100: * The ``-Z`` flag sometimes causes the iperf3 client to hang on OSX.
101: (Issue #129)
102:
103: * When specifying the TCP buffer size using the ``-w`` flag on Linux,
104: the Linux kernel automatically doubles the value passed in to
105: compensate for overheads. (This can be observed by using
106: iperf3's ``--debug`` flag.) However, CWND does not actually ramp up
107: to the doubled value, but only to about 75% of the doubled
108: value. Some part of this behavior is documented in the tcp(7)
109: manual page. (Issue #145)
110:
111: * On some platforms (observed on at least one version of Ubuntu
112: Linux), it might be necessary to invoke ``ldconfig`` manually after
113: doing a ``make install`` before the ``iperf3`` executable can find
114: its shared library. (Issue #153)
115:
116: There are, of course, many other open and closed issues in the issue
117: tracker.
118:
119: Versioning
120: ----------
121:
122: iperf3 version numbers use (roughly) a `Semantic Versioning
123: <http://semver.org/>`_ scheme, in which version numbers consist of
124: three parts: *MAJOR.MINOR.PATCH*
125:
126: The developers increment the:
127:
128: * *MAJOR* version when making incompatible API changes,
129:
130: * *MINOR* version when adding functionality in a backwards-compatible manner, and
131:
132: * *PATCH* version when making backwards-compatible bug fixes.
133:
134: Release Engineering Checklist
135: -----------------------------
136:
137: 1. Update the ``README`` and ``RELEASE_NOTES`` files to be accurate. Make sure
138: that the "Known Issues" section of the ``README`` file is up to date.
139:
140: 2. Compose a release announcement. Most of the release announcement
141: can be written before tagging. Usually the previous version's
142: announcement can be used as a starting point.
143:
144: 3. Preferably starting from a clean source tree (be sure that ``git
145: status`` emits no output), make the changes necessary to produce
146: the new version, such as bumping version numbers::
147:
148: vi RELEASE_NOTES # update version number and release date
149: vi configure.ac # update version parameter in AC_INIT
150: vi src/iperf3.1 # update manpage revision date if needed
151: vi src/libiperf.3 # update manpage revision date if needed
152: git commit -a # commit changes to the local repository only
153: ./bootstrap.sh # regenerate configure script, etc.
154: git commit -a # commit changes to the local repository only
155:
156: # Assuming that $VERSION is the version number to be released...
157: ./make_release tag $VERSION # this creates a tag in the local repo
158: ./make_release tar $VERSION # create tarball and compute SHA256 hash
159:
160: These steps should be done on a platform with a relatively recent
161: version of autotools / libtools. Examples are MacOS / MacPorts or
162: FreeBSD. The versions of these tools in CentOS 6 are somewhat
163: older and probably should be avoided.
164:
165: The result will be a release artifact that should be used for
166: pre-testing.
167:
168: 4. Stage the tarball (and a file containing the SHA256 hash) to the
169: download site. Currently this is located on ``downloads.es.net``.
170:
171: 5. From another host, test the link in the release announcement by
172: downloading a fresh copy of the file and verifying the SHA256
173: checksum. Checking all other links in the release announcement is
174: strongly recommended as well.
175:
176: 6. Also verify (with file(1)) that the tarball is actually a gzipped
177: tarball.
178:
179: 7. For extra points, actually try downloading, compiling, and
180: smoke-testing the results of the tarball on all supported
181: platforms.
182:
183: 8. Plug the SHA256 checksum into the release announcement.
184:
185: 9. PGP-sign the release announcement text using ``gpg --clearsign``.
186: The signed announcement will be sent out in a subsequent emails,
187: but could also be archived. Decoupling the signing from emailing
188: allows a signed release announcement to be resent via email or sent
189: by other, non-email means.
190:
191: 10. At this point, the release can and should be considered
192: finalized. To commit the release-engineering-related changes to
193: GitHub and make them public, push them out thusly::
194:
195: git push # Push version changes
196: git push --tags # Push the new tag to the GitHub repo
197:
198: 11. Send the PGP-signed release announcement to the following
199: addresses. Remember to turn off signing in the MUA, if
200: applicable. Remember to check the source address when posting to
201: lists, as "closed" list will reject posting from all from
202: registered email addresses.
203:
204: * iperf-dev@googlegroups.com
205:
206: * iperf-users@lists.sourceforge.net
207:
208: * perfsonar-user@internet2.edu
209:
210: * perfsonar-developer@internet2.edu
211:
212: Note: Thunderbird sometimes mangles the PGP-signed release
213: announcement so that it does not verify correctly. This could be
214: due to Thunderbird trying to wrap the length of extremely long
215: lines (such as the SHA256 hash). Apple Mail and mutt seem to
216: handle this situation correctly. Testing the release announcement
217: sending process by sending a copy to oneself first and attempting
218: to verify the signature is highly encouraged.
219:
220: 12. Update the iperf3 Project News section of the documentation site
221: to announce the new release (see ``docs/news.rst`` and
222: ``docs/conf.py`` in the source tree) and deploy a new build of the
223: documentation to GitHub Pages.
224:
225: Code Authors
226: ------------
227:
228: The main authors of iperf3 are (in alphabetical order): Jon Dugan,
229: Seth Elliott, Bruce A. Mah, Jeff Poskanzer, Kaustubh Prabhu.
230: Additional code contributions have come from (also in alphabetical
231: order): Mark Ashley, Aaron Brown, Aeneas Jaißle, Susant Sahani,
232: Bruce Simpson, Brian Tierney.
233:
234: iperf3 contains some original code from iperf2. The authors of iperf2
235: are (in alphabetical order): Jon Dugan, John Estabrook, Jim Ferbuson,
236: Andrew Gallatin, Mark Gates, Kevin Gibbs, Stephen Hemminger, Nathan
237: Jones, Feng Qin, Gerrit Renker, Ajay Tirumala, Alex Warshavsky.
FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>
![[BACK]](/icons/cvsweb/back.gif){kind=icon}
Return to dev.rst CVS log ![[TXT]](/icons/cvsweb/text.gif){kind=icon}
![[DIR]](/icons/cvsweb/dir.gif){kind=icon}
Up to [ELWIX - Embedded LightWeight unIX -] / embedaddon / iperf / docs