-Some informations for Contributors
-----------------------------------
-Your want to contribute to Tcpdump, Thanks!
+Some Information for Contributors
+---------------------------------
+You want to contribute to Tcpdump, Thanks!
Please, read these lines.
+
+How to report bugs and other problems
+-------------------------------------
+To report a security issue (segfault, buffer overflow, infinite loop, arbitrary
+the bug tracker!
+
+To report a non-security problem (failure to compile, incorrect output in the
+protocol printout, missing support for a particular protocol etc) please check
+first that it reproduces with the latest stable release of tcpdump and the latest
+stable release of libpcap. If it does, please check that the problem reproduces
+with the current git master branch of tcpdump and the current git master branch of
+libpcap. If it does (and it is not a security-related problem, otherwise see
+above), please navigate to https://github.com/the-tcpdump-group/tcpdump/issues
+and check if the problem has already been reported. If it has not, please open
+a new issue and provide the following details:
+
+* tcpdump and libpcap version (tcpdump --version)
+* operating system name and version and any other details that may be relevant
+ (uname -a, compiler name and version, CPU type etc.)
+* configure flags if any were used
+* statement of the problem
+* steps to reproduce
+
+Please note that if you know exactly how to solve the problem and the solution
+would not be too intrusive, it would be best to contribute some development time
+and open a pull request instead as discussed below.
+
+Still not sure how to do? Feel free to [subscribe](https://www.tcpdump.org/#mailing-lists)
+
+
+How to add new code and to update existing code
+-----------------------------------------------
+
+0) Check that there isn't a pull request already opened for the changes you
+ intend to make.
+
1) Fork the Tcpdump repository on GitHub from
https://github.com/the-tcpdump-group/tcpdump
(See https://help.github.com/articles/fork-a-repo/)
-2) Setup an optionnal Travis-CI build
- You can setup a travis build for your fork. So, your can test your changes
- on Linux and OSX before sending pull requests.
- (See http://docs.travis-ci.com/user/getting-started/)
+2) Setup optional Travis CI build and AppVeyor builds
+ You can setup Travis CI and AppVeyor builds for your fork, so you can
+ test your changes on Linux, macOS, and Windows before sending pull
+ requests.
+ (See http://docs.travis-ci.com/user/getting-started/ for information
+ on setting up Travis CI; go to https://ci.appveyor.com/login and log
+ in with your GitHub account and select "NEW PROJECT" to set up an
+ AppVeyor build.)
-3) Clone your repository
+3) Setup your git working copy
git clone https://github.com/<username>/tcpdump.git
+ cd tcpdump
+ git remote add upstream https://github.com/the-tcpdump-group/tcpdump
+ git fetch upstream
4) Do a 'touch .devel' in your working directory.
Currently, the effect is
6) Add/update sample.pcap files
We use tests directory to do regression tests on the dissection of captured
- packets, by running tcpdump against a savefile sample.pcap, created with -w
- option and comparing the results with a text file sample.out giving the
- expected results.
+ packets. Those captured packets were saved running tcpdump with option "-w
+ sample.pcap". Additional options, such as "-n", are used to create relevant
+ and reproducible output; "-#" is used to indicate which particular packets
+ have output that differs. The tests are run with the TZ environment
+ variable set to GMT0, so that UTC, rather than the local time where the
+ tests are being run, is used when "local time" values are printed. The
+ actual test compares the current text output with the expected result
+ (sample.out) saved from a previous version.
Any new/updated fields in a dissector must be present in a sample.pcap file
and the corresponding output file.
Each line in this file has the following format:
test-name sample.pcap sample.out tcpdump-options
- the sample.out file can be build by:
- (cd tests && ../tcpdump -n -r sample.pcap tcpdump-options > sample.out)
+ The sample.out file can be build by:
+ (cd tests && TZ=GMT0 ../tcpdump -# -n -r sample.pcap tcpdump-options > sample.out)
+
+ Or, for convenience, use "./update-test.sh test-name"
It is often useful to have test outputs with different verbosity levels
(none, -v, -vv, -vvv, etc.) depending on the code.
7) Test with 'make check'
Don't send a pull request if 'make check' gives failed tests.
-8) Rebase your commits against upstream/master
- (To keep linearity)
+8) Try to rebase your commits to keep the history simple.
+ git rebase upstream/master
+ (If the rebase fails and you cannot resolve, issue "git rebase --abort"
+ and ask for help in the pull request comment.)
+
+9) Once 100% happy, put your work into your forked repository.
+ git push
+ This will trigger both Travis CI and AppVeyor builds.
+
+10) Initiate and send a pull request
+ (See https://help.github.com/articles/using-pull-requests/)
+ Note that creating the pull request will cause your code to be
+ tested on Linux and macOS with Travis CI and on Windows with
+ AppVeyor.
-9) Initiate and send a pull request
- (See https://help.github.com/articles/using-pull-requests/)
-Some remarks
-------------
-a) A thorough reading of some other printers code is usefull.
+Code style and generic remarks
+------------------------------
+a) A thorough reading of some other printers code is useful.
-b) Put the the normative reference if any as comments (RFC, etc.).
+b) Put the normative reference if any as comments (RFC, etc.).
-c) Put the the format of packets/headers/options as comments.
+c) Put the format of packets/headers/options as comments if there is no
+ published normative reference.
d) The printer may receive incomplete packet in the buffer, truncated at any
random position, for example by capturing with '-s size' option.
- Thus use ND_TTEST, ND_TTEST2, ND_TCHECK or ND_TCHECK2 for bound checking.
- For ND_TCHECK2:
- Define : static const char tstr[] = " [|protocol]";
+ Thus use, for bounds checking, one of the following macros (defined in
+ netdissect.h or extract.h):
+ ND_TCHECK_n(p), n in { 1, 2, 3, 4, 5, 6, 7, 8, 16 }
+ ND_TCHECK_SIZE(p)
+ ND_TCHECK_LEN(p, l)
+
+ ND_TTEST_n(p), n in { 1, 2, 3, 4, 5, 6, 7, 8, 16 }
+ ND_TTEST_SIZE(p)
+ ND_TTEST_LEN(p, l)
+
+ For the ND_TCHECK_* macros (if not already done):
+ Assign: ndo->ndo_protocol = "protocol";
Define a label: trunc
- Print with: ND_PRINT((ndo, "%s", tstr));
+ Print with: nd_print_trunc(ndo);
You can test the code via:
sudo ./tcpdump -s snaplen [-v][v][...] -i lo # in a terminal
sudo tcpreplay -i lo sample.pcap # in another terminal
e) Do invalid packet checks in code: Think that your code can receive in input
not only a valid packet but any arbitrary random sequence of octets (packet
- built malformed originally by the sender or by a fuzz tester,
- - became corrupted in transit).
- Print with: ND_PRINT((ndo, "%s", istr)); /* to print " (invalid)" */
+ - became corrupted in transit or for some other reason).
+ Print with: nd_print_invalid(ndo); /* to print " (invalid)" */
f) Use 'struct tok' for indexed strings and print them with
tok2str() or bittok2str() (for flags).
h) A commit message must have:
First line: Capitalized short summary in the imperative (70 chars or less)
- Body: Detailed explanatory text, if necessary. Fold up it to approximately
+ Body: Detailed explanatory text, if necessary. Fold it to approximately
72 characters. There must be an empty line separating the summary from
the body.
projects / tcpdump / blobdiff