"Fossies" - the Fresh Open Source Software Archive

Member "tcpdump-4.99.1/./CONTRIBUTING" (7 Jun 2021, 7322 Bytes) of package /linux/misc/tcpdump-4.99.1.tar.gz:


As a special service "Fossies" has tried to format the requested text file into HTML format (style: standard) with prefixed line numbers. Alternatively you can here view or download the uninterpreted source code file.

    1 Some Information for Contributors
    2 ---------------------------------
    3 Thank you for considering to make a contribution to tcpdump! Please use the
    4 guidelines below to achieve the best results and experience for everyone.
    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@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 * custom configure/CMake flags, if any
   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 to open a pull request instead as discussed below.
   33 
   34 Still not sure how to do? Feel free to [subscribe](https://www.tcpdump.org/#mailing-lists)
   35 to the mailing list tcpdump-workers@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) 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 
   52 3) 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 
   58 4) 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 
   65 5) Configure and build
   66    ./configure && make -s && make check
   67 
   68 6) 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 
   94 7) Test with 'make check'
   95    Don't send a pull request if 'make check' gives failed tests.
   96 
   97 8) 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 
  102 9) Once 100% happy, put your work into your forked repository.
  103    git push
  104 
  105 10) 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 
  110 Code style and generic remarks
  111 ------------------------------
  112 a) A thorough reading of some other printers code is useful.
  113 
  114 b) Put the normative reference if any as comments (RFC, etc.).
  115 
  116 c) Put the format of packets/headers/options as comments if there is no
  117    published normative reference.
  118 
  119 d) 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 
  143 e) 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 
  149 f) Use 'struct tok' for indexed strings and print them with
  150    tok2str() or bittok2str() (for flags).
  151 
  152 g) Avoid empty lines in output of printers.
  153 
  154 h) 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 
  161 i) Avoid non-ASCII characters in code and commit messages.
  162 
  163 j) Use the style of the modified sources.
  164 
  165 k) Don't mix declarations and code
  166 
  167 l) Don't use // for comments
  168    Not all C compilers accept C++/C99 comments by default.
  169 
  170 m) Avoid trailing tabs/spaces