CONTRIBUTING.md

   1 # Some Information for Contributors
   2 Thank you for considering to make a contribution to tcpdump! Please use the
   3 guidelines 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
   7 code execution etc) please send an e-mail to security@tcpdump.org, do not use
   8 the bug tracker!**
   9
  10 To report a non-security problem (failure to compile, incorrect output in the
  11 protocol printout, missing support for a particular protocol etc) please check
  12 first that it reproduces with the latest stable release of tcpdump and the latest
  13 stable release of libpcap. If it does, please check that the problem reproduces
  14 with the current git master branch of tcpdump and the current git master branch of
  15 libpcap. If it does (and it is not a security-related problem, otherwise see
  16 above), please navigate to the
  17 [bug tracker](https://github.com/the-tcpdump-group/tcpdump/issues)
  18 and check if the problem has already been reported. If it has not, please open
  19 a 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
  28 Please note that if you know exactly how to solve the problem and the solution
  29 would not be too intrusive, it would be best to contribute some development time
  30 and to open a pull request instead as discussed below.
  31
  32 Still not sure how to do? Feel free to
  33 [subscribe to the mailing list](https://www.tcpdump.org/#mailing-lists)
  34 and ask!
  35
  36
  37 ## How to add new code and to update existing code
  38
  39 0) Check that there isn't a pull request already opened for the changes you
  40    intend to make.
  41
  42 1) [Fork](https://help.github.com/articles/fork-a-repo/) the Tcpdump
  43    [repository](https://github.com/the-tcpdump-group/tcpdump).
  44
  45 2) 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
  49 3) 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
  57 4) 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
  64 5) Configure and build
  65    ```
  66    ./configure && make -s && make check
  67    ```
  68
  69 6) 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
  99 7) 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
 104 8) 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
 112 9) Once 100% happy, put your work into your forked repository using `git push`.
 113
 114 10) [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