1 Some Information for Contributors 2 --------------------------------- 3 You want to contribute to Tcpdump, Thanks! 4 Please, read these lines. 5 6 7 How to report bugs and other problems 8 ------------------------------------- 9 To report a security issue (segfault, buffer overflow, infinite loop, arbitrary 10 code execution etc) please send an e-mail to security (a] tcpdump.org, do not use 11 the bug tracker! 12 13 To report a non-security problem (failure to compile, incorrect output in the 14 protocol printout, missing support for a particular protocol etc) please check 15 first that it reproduces with the latest stable release of tcpdump and the latest 16 stable release of libpcap. If it does, please check that the problem reproduces 17 with the current git master branch of tcpdump and the current git master branch of 18 libpcap. If it does (and it is not a security-related problem, otherwise see 19 above), please navigate to https://github.com/the-tcpdump-group/tcpdump/issues 20 and check if the problem has already been reported. If it has not, please open 21 a 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 * configure flags if any were used 27 * statement of the problem 28 * steps to reproduce 29 30 Please note that if you know exactly how to solve the problem and the solution 31 would not be too intrusive, it would be best to contribute some development time 32 and open a pull request instead as discussed below. 33 34 Still not sure how to do? Feel free to [subscribe](http://www.tcpdump.org/#mailing-lists) 35 to the mailing list tcpdump-workers (a] lists.tcpdump.org and ask! 36 37 38 How to add new code and to update existing code 39 ----------------------------------------------- 40 41 0) Check that there isn't a pull request already opened for the changes you 42 intend to make. 43 44 1) 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 48 2) Setup an optional Travis-CI build 49 You can setup a travis build for your fork. So, you can test your changes 50 on Linux and OSX before sending pull requests. 51 (See http://docs.travis-ci.com/user/getting-started/) 52 53 3) Setup your git working copy 54 git clone https://github.com/<username>/tcpdump.git 55 cd tcpdump 56 git remote add upstream https://github.com/the-tcpdump-group/tcpdump 57 git fetch upstream 58 59 4) Do a 'touch .devel' in your working directory. 60 Currently, the effect is 61 a) add (via configure, in Makefile) some warnings options ( -Wall 62 -Wmissing-prototypes -Wstrict-prototypes, ...) to the compiler if it 63 supports these options, 64 b) have the Makefile support "make depend" and the configure script run it. 65 66 5) Configure and build 67 ./configure && make -s && make check 68 69 6) Add/update sample.pcap files 70 We use tests directory to do regression tests on the dissection of captured 71 packets, by running tcpdump against a savefile sample.pcap, created with -w 72 option and comparing the results with a text file sample.out giving the 73 expected results. 74 75 Any new/updated fields in a dissector must be present in a sample.pcap file 76 and the corresponding output file. 77 78 Configuration is set in tests/TESTLIST. 79 Each line in this file has the following format: 80 test-name sample.pcap sample.out tcpdump-options 81 82 the sample.out file can be build by: 83 (cd tests && ../tcpdump -n -r sample.pcap tcpdump-options > sample.out) 84 85 It is often useful to have test outputs with different verbosity levels 86 (none, -v, -vv, -vvv, etc.) depending on the code. 87 88 7) Test with 'make check' 89 Don't send a pull request if 'make check' gives failed tests. 90 91 8) Try to rebase your commits to keep the history simple. 92 git rebase upstream/master 93 (If the rebase fails and you cannot resolve, issue "git rebase --abort" 94 and ask for help in the pull request comment.) 95 96 9) Once 100% happy, put your work into your forked repository. 97 git push 98 99 10) Initiate and send a pull request 100 (See https://help.github.com/articles/using-pull-requests/) 101 102 103 Code style and generic remarks 104 ------------------------------ 105 a) A thorough reading of some other printers code is useful. 106 107 b) Put the normative reference if any as comments (RFC, etc.). 108 109 c) Put the format of packets/headers/options as comments if there is no 110 published normative reference. 111 112 d) The printer may receive incomplete packet in the buffer, truncated at any 113 random position, for example by capturing with '-s size' option. 114 Thus use ND_TTEST, ND_TTEST2, ND_TCHECK or ND_TCHECK2 for bound checking. 115 For ND_TCHECK2: 116 Define : static const char tstr[] = " [|protocol]"; 117 Define a label: trunc 118 Print with: ND_PRINT((ndo, "%s", tstr)); 119 You can test the code via: 120 sudo ./tcpdump -s snaplen [-v][v][...] -i lo # in a terminal 121 sudo tcpreplay -i lo sample.pcap # in another terminal 122 You should try several values for snaplen to do various truncation. 123 124 e) Do invalid packet checks in code: Think that your code can receive in input 125 not only a valid packet but any arbitrary random sequence of octets (packet 126 - built malformed originally by the sender or by a fuzz tester, 127 - became corrupted in transit). 128 Print with: ND_PRINT((ndo, "%s", istr)); /* to print " (invalid)" */ 129 130 f) Use 'struct tok' for indexed strings and print them with 131 tok2str() or bittok2str() (for flags). 132 133 g) Avoid empty lines in output of printers. 134 135 h) A commit message must have: 136 First line: Capitalized short summary in the imperative (70 chars or less) 137 138 Body: Detailed explanatory text, if necessary. Fold it to approximately 139 72 characters. There must be an empty line separating the summary from 140 the body. 141 142 i) Avoid non-ASCII characters in code and commit messages. 143 144 j) Use the style of the modified sources. 145 146 k) Don't mix declarations and code 147 148 l) Don't use // for comments 149 Not all C compilers accept C++/C99 comments by default. 150 151 m) Avoid trailing tabs/spaces 152
