• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Some Information for Contributors
2---------------------------------
3Thank you for considering to make a contribution to tcpdump! Please use the
4guidelines below to achieve the best results and experience for everyone.
5
6
7How to report bugs and other problems
8-------------------------------------
9To report a security issue (segfault, buffer overflow, infinite loop, arbitrary
10code execution etc) please send an e-mail to security@tcpdump.org, do not use
11the bug tracker!
12
13To report a non-security problem (failure to compile, incorrect output in the
14protocol printout, missing support for a particular protocol etc) please check
15first that it reproduces with the latest stable release of tcpdump and the latest
16stable release of libpcap. If it does, please check that the problem reproduces
17with the current git master branch of tcpdump and the current git master branch of
18libpcap. If it does (and it is not a security-related problem, otherwise see
19above), please navigate to https://github.com/the-tcpdump-group/tcpdump/issues
20and check if the problem has already been reported. If it has not, please open
21a new issue and provide the following details:
22
23* tcpdump and libpcap version (tcpdump --version)
24* operating system name and version and any other details that may be relevant
25  (uname -a, compiler name and version, CPU type etc.)
26* custom configure/CMake flags, if any
27* statement of the problem
28* steps to reproduce
29
30Please note that if you know exactly how to solve the problem and the solution
31would not be too intrusive, it would be best to contribute some development time
32and to open a pull request instead as discussed below.
33
34Still not sure how to do? Feel free to [subscribe](https://www.tcpdump.org/#mailing-lists)
35to the mailing list tcpdump-workers@lists.tcpdump.org and ask!
36
37
38How to add new code and to update existing code
39-----------------------------------------------
40
410) Check that there isn't a pull request already opened for the changes you
42   intend to make.
43
441) Fork the Tcpdump repository on GitHub from
45   https://github.com/the-tcpdump-group/tcpdump
46   (See https://help.github.com/articles/fork-a-repo/)
47
482) The easiest way to test your changes on multiple operating systems and
49   architectures is to let the upstream CI test your pull request (more on
50   this below).
51
523) Setup your git working copy
53   git clone https://github.com/<username>/tcpdump.git
54   cd tcpdump
55   git remote add upstream https://github.com/the-tcpdump-group/tcpdump
56   git fetch upstream
57
584) Do a 'touch .devel' in your working directory.
59   Currently, the effect is
60   a) add (via configure, in Makefile) some warnings options ( -Wall
61   -Wmissing-prototypes -Wstrict-prototypes, ...) to the compiler if it
62   supports these options,
63   b) have the Makefile support "make depend" and the configure script run it.
64
655) Configure and build
66   ./configure && make -s && make check
67
686) Add/update tests
69   The tests directory contains regression tests of the dissection of captured
70   packets.  Those captured packets were saved running tcpdump with option "-w
71   sample.pcap".  Additional options, such as "-n", are used to create relevant
72   and reproducible output; "-#" is used to indicate which particular packets
73   have output that differs.  The tests are run with the TZ environment
74   variable set to GMT0, so that UTC, rather than the local time where the
75   tests are being run, is used when "local time" values are printed.  The
76   actual test compares the current text output with the expected result
77   (sample.out) saved from a previous version.
78
79   Any new/updated fields in a dissector must be present in a sample.pcap file
80   and the corresponding output file.
81
82   Configuration is set in tests/TESTLIST.
83   Each line in this file has the following format:
84   test-name   sample.pcap   sample.out   tcpdump-options
85
86   The sample.out file can be produced as follows:
87   (cd tests && TZ=GMT0 ../tcpdump -# -n -r sample.pcap tcpdump-options > sample.out)
88
89   Or, for convenience, use "./update-test.sh test-name"
90
91   It is often useful to have test outputs with different verbosity levels
92   (none, -v, -vv, -vvv, etc.) depending on the code.
93
947) Test with 'make check'
95   Don't send a pull request if 'make check' gives failed tests.
96
978) Try to rebase your commits to keep the history simple.
98   git rebase upstream/master
99   (If the rebase fails and you cannot resolve, issue "git rebase --abort"
100   and ask for help in the pull request comment.)
101
1029) Once 100% happy, put your work into your forked repository.
103   git push
104
10510) Initiate and send a pull request
106    (See https://help.github.com/articles/using-pull-requests/)
107    This will trigger the upstream repository CI tests.
108
109
110Code style and generic remarks
111------------------------------
112a) A thorough reading of some other printers code is useful.
113
114b) Put the normative reference if any as comments (RFC, etc.).
115
116c) Put the format of packets/headers/options as comments if there is no
117   published normative reference.
118
119d) The printer may receive incomplete packet in the buffer, truncated at any
120   random position, for example by capturing with '-s size' option.
121   If your code reads and decodes every byte of the protocol packet, then to
122   ensure proper and complete bounds checks it would be sufficient to read all
123   packet data using the GET_*() macros, typically:
124    GET_U_1(p)
125    GET_S_1(p)
126    GET_BE_U_n(p), n in { 2, 3, 4, 5, 6, 7, 8 }
127    GET_BE_S_n(p), n in { 2, 3, 4, 5, 6, 7, 8 }
128   If your code uses the macros above only on some packet data, then the gaps
129   would have to be bounds-checked using the ND_TCHECK_*() macros:
130    ND_TCHECK_n(p), n in { 1, 2, 3, 4, 5, 6, 7, 8, 16 }
131    ND_TCHECK_SIZE(p)
132    ND_TCHECK_LEN(p, l)
133   For the ND_TCHECK_* macros (if not already done):
134     Assign: ndo->ndo_protocol = "protocol";
135     Define: ND_LONGJMP_FROM_TCHECK before including netdissect.h
136     Make sure that the intersection of GET_*() and ND_TCHECK_*() is minimal,
137     but at the same time their union covers all packet data in all cases.
138   You can test the code via:
139     sudo ./tcpdump -s snaplen [-v][v][...] -i lo # in a terminal
140     sudo tcpreplay -i lo sample.pcap             # in another terminal
141   You should try several values for snaplen to do various truncation.
142
143e) Do invalid packet checks in code: Think that your code can receive in input
144   not only a valid packet but any arbitrary random sequence of octets (packet
145   - built malformed originally by the sender or by a fuzz tester,
146   - became corrupted in transit or for some other reason).
147   Print with: nd_print_invalid(ndo);	/* to print " (invalid)" */
148
149f) Use 'struct tok' for indexed strings and print them with
150   tok2str() or bittok2str() (for flags).
151
152g) Avoid empty lines in output of printers.
153
154h) A commit message must have:
155   First line: Capitalized short summary in the imperative (70 chars or less)
156
157   Body: Detailed explanatory text, if necessary. Fold it to approximately
158   72 characters. There must be an empty line separating the summary from
159   the body.
160
161i) Avoid non-ASCII characters in code and commit messages.
162
163j) Use the style of the modified sources.
164
165k) Don't mix declarations and code
166
167l) Don't use // for comments
168   Not all C compilers accept C++/C99 comments by default.
169
170m) Avoid trailing tabs/spaces
171