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