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