104 lines
3.8 KiB
Plaintext
104 lines
3.8 KiB
Plaintext
|
Some Information for Contributors
|
||
|
|
---------------------------------
|
||
|
|
You want to contribute to Tcpdump, Thanks!
|
||
|
|
Please, read these lines.
|
||
|
|
|
||
|
|
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 optional Travis-CI build
|
||
|
|
You can setup a travis build for your fork. So, you can test your changes
|
||
|
|
on Linux and OSX before sending pull requests.
|
||
|
|
(See http://docs.travis-ci.com/user/getting-started/)
|
||
|
|
|
||
|
|
3) Clone your repository
|
||
|
|
git clone https://github.com/<username>/tcpdump.git
|
||
|
|
|
||
|
|
4) Do a 'touch .devel' in your working directory.
|
||
|
|
Currently, the effect is
|
||
|
|
a) add (via configure, in Makefile) some warnings options ( -Wall
|
||
|
|
-Wmissing-prototypes -Wstrict-prototypes, ...) to the compiler if it
|
||
|
|
supports these options,
|
||
|
|
b) have the Makefile support "make depend" and the configure script run it.
|
||
|
|
|
||
|
|
5) Configure and build
|
||
|
|
./configure && make -s && make check
|
||
|
|
|
||
|
|
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.
|
||
|
|
|
||
|
|
Any new/updated fields in a dissector must be present in a sample.pcap file
|
||
|
|
and the corresponding output file.
|
||
|
|
|
||
|
|
Configuration is set in tests/TESTLIST.
|
||
|
|
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)
|
||
|
|
|
||
|
|
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)
|
||
|
|
|
||
|
|
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 useful.
|
||
|
|
|
||
|
|
b) Put the normative reference if any as comments (RFC, etc.).
|
||
|
|
|
||
|
|
c) Put the format of packets/headers/options as comments.
|
||
|
|
|
||
|
|
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]";
|
||
|
|
Define a label: trunc
|
||
|
|
Print with: ND_PRINT((ndo, "%s", tstr));
|
||
|
|
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
|
||
|
|
You should try several values for snaplen to do various truncation.
|
||
|
|
|
||
|
|
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)" */
|
||
|
|
|
||
|
|
f) Use 'struct tok' for indexed strings and print them with
|
||
|
|
tok2str() or bittok2str() (for flags).
|
||
|
|
|
||
|
|
g) Avoid empty lines in output of printers.
|
||
|
|
|
||
|
|
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 it to approximately
|
||
|
|
72 characters. There must be an empty line separating the summary from
|
||
|
|
the body.
|
||
|
|
|
||
|
|
i) Avoid non-ASCII characters in code and commit messages.
|
||
|
|
|
||
|
|
j) Use the style of the modified sources.
|
||
|
|
|
||
|
|
k) Don't mix declarations and code
|
||
|
|
|
||
|
|
l) Don't use // for comments
|
||
|
|
Not all C compilers accept C++/C99 comments by default.
|
||
|
|
|
||
|
|
m) Avoid trailing tabs/spaces
|