mirror of
https://github.com/the-tcpdump-group/tcpdump.git
synced 2024-11-23 18:14:29 +08:00
Convert CONTRIBUTING to Markdown. [skip ci]
(cherry picked from commit af98bb4776)
This commit is contained in:
Denis Ovsienko
Francois-Xavier Le Bail
parent
ddcb6e6548
commit
3311d0ca63
2
.github/ISSUE_TEMPLATE
vendored
2
.github/ISSUE_TEMPLATE
vendored
@ -2,7 +2,7 @@ To report a security issue please send an e-mail to security@tcpdump.org.
|
||||
|
||||
To report bugs and other problems, contribute patches, request a
|
||||
feature, provide generic feedback etc please see the file
|
||||
CONTRIBUTING in the tcpdump source tree root.
|
||||
CONTRIBUTING.md in the tcpdump source tree root.
|
||||
|
||||
When reporting bugs and other problems, give tcpdump and libpcap version
|
||||
with 'tcpdump --version' or './tcpdump --version'
|
||||
|
||||
170
CONTRIBUTING
170
CONTRIBUTING
@ -1,170 +0,0 @@
|
||||
Some Information for Contributors
|
||||
---------------------------------
|
||||
Thank you for considering to make a contribution to tcpdump! Please use the
|
||||
guidelines below to achieve the best results and experience for everyone.
|
||||
|
||||
|
||||
How to report bugs and other problems
|
||||
-------------------------------------
|
||||
To report a security issue (segfault, buffer overflow, infinite loop, arbitrary
|
||||
code execution etc) please send an e-mail to security@tcpdump.org, do not use
|
||||
the bug tracker!
|
||||
|
||||
To report a non-security problem (failure to compile, incorrect output in the
|
||||
protocol printout, missing support for a particular protocol etc) please check
|
||||
first that it reproduces with the latest stable release of tcpdump and the latest
|
||||
stable release of libpcap. If it does, please check that the problem reproduces
|
||||
with the current git master branch of tcpdump and the current git master branch of
|
||||
libpcap. If it does (and it is not a security-related problem, otherwise see
|
||||
above), please navigate to https://github.com/the-tcpdump-group/tcpdump/issues
|
||||
and check if the problem has already been reported. If it has not, please open
|
||||
a new issue and provide the following details:
|
||||
|
||||
* tcpdump and libpcap version (tcpdump --version)
|
||||
* operating system name and version and any other details that may be relevant
|
||||
(uname -a, compiler name and version, CPU type etc.)
|
||||
* custom configure/CMake flags, if any
|
||||
* statement of the problem
|
||||
* steps to reproduce
|
||||
|
||||
Please note that if you know exactly how to solve the problem and the solution
|
||||
would not be too intrusive, it would be best to contribute some development time
|
||||
and to open a pull request instead as discussed below.
|
||||
|
||||
Still not sure how to do? Feel free to [subscribe](https://www.tcpdump.org/#mailing-lists)
|
||||
to the mailing list tcpdump-workers@lists.tcpdump.org and ask!
|
||||
|
||||
|
||||
How to add new code and to update existing code
|
||||
-----------------------------------------------
|
||||
|
||||
0) Check that there isn't a pull request already opened for the changes you
|
||||
intend to make.
|
||||
|
||||
1) Fork the Tcpdump repository on GitHub from
|
||||
https://github.com/the-tcpdump-group/tcpdump
|
||||
(See https://help.github.com/articles/fork-a-repo/)
|
||||
|
||||
2) The easiest way to test your changes on multiple operating systems and
|
||||
architectures is to let the upstream CI test your pull request (more on
|
||||
this below).
|
||||
|
||||
3) Setup your git working copy
|
||||
git clone https://github.com/<username>/tcpdump.git
|
||||
cd tcpdump
|
||||
git remote add upstream https://github.com/the-tcpdump-group/tcpdump
|
||||
git fetch upstream
|
||||
|
||||
4) Do a 'touch .devel' in your working directory.
|
||||
Currently, the effect is
|
||||
a) add (via configure, in Makefile) some warnings options ( -Wall
|
||||
-Wmissing-prototypes -Wstrict-prototypes, ...) to the compiler if it
|
||||
supports these options,
|
||||
b) have the Makefile support "make depend" and the configure script run it.
|
||||
|
||||
5) Configure and build
|
||||
./configure && make -s && make check
|
||||
|
||||
6) Add/update tests
|
||||
The tests directory contains regression tests of the dissection of captured
|
||||
packets. Those captured packets were saved running tcpdump with option "-w
|
||||
sample.pcap". Additional options, such as "-n", are used to create relevant
|
||||
and reproducible output; "-#" is used to indicate which particular packets
|
||||
have output that differs. The tests are run with the TZ environment
|
||||
variable set to GMT0, so that UTC, rather than the local time where the
|
||||
tests are being run, is used when "local time" values are printed. The
|
||||
actual test compares the current text output with the expected result
|
||||
(sample.out) saved from a previous version.
|
||||
|
||||
Any new/updated fields in a dissector must be present in a sample.pcap file
|
||||
and the corresponding output file.
|
||||
|
||||
Configuration is set in tests/TESTLIST.
|
||||
Each line in this file has the following format:
|
||||
test-name sample.pcap sample.out tcpdump-options
|
||||
|
||||
The sample.out file can be produced as follows:
|
||||
(cd tests && TZ=GMT0 ../tcpdump -# -n -r sample.pcap tcpdump-options > sample.out)
|
||||
|
||||
Or, for convenience, use "./update-test.sh test-name"
|
||||
|
||||
It is often useful to have test outputs with different verbosity levels
|
||||
(none, -v, -vv, -vvv, etc.) depending on the code.
|
||||
|
||||
7) Test with 'make check'
|
||||
Don't send a pull request if 'make check' gives failed tests.
|
||||
|
||||
8) Try to rebase your commits to keep the history simple.
|
||||
git rebase upstream/master
|
||||
(If the rebase fails and you cannot resolve, issue "git rebase --abort"
|
||||
and ask for help in the pull request comment.)
|
||||
|
||||
9) Once 100% happy, put your work into your forked repository.
|
||||
git push
|
||||
|
||||
10) Initiate and send a pull request
|
||||
(See https://help.github.com/articles/using-pull-requests/)
|
||||
This will trigger the upstream repository CI tests.
|
||||
|
||||
|
||||
Code style and generic remarks
|
||||
------------------------------
|
||||
a) A thorough reading of some other printers code is useful.
|
||||
|
||||
b) Put the normative reference if any as comments (RFC, etc.).
|
||||
|
||||
c) Put the format of packets/headers/options as comments if there is no
|
||||
published normative reference.
|
||||
|
||||
d) The printer may receive incomplete packet in the buffer, truncated at any
|
||||
random position, for example by capturing with '-s size' option.
|
||||
If your code reads and decodes every byte of the protocol packet, then to
|
||||
ensure proper and complete bounds checks it would be sufficient to read all
|
||||
packet data using the GET_*() macros, typically:
|
||||
GET_U_1(p)
|
||||
GET_S_1(p)
|
||||
GET_BE_U_n(p), n in { 2, 3, 4, 5, 6, 7, 8 }
|
||||
GET_BE_S_n(p), n in { 2, 3, 4, 5, 6, 7, 8 }
|
||||
If your code uses the macros above only on some packet data, then the gaps
|
||||
would have to be bounds-checked using the ND_TCHECK_*() macros:
|
||||
ND_TCHECK_n(p), n in { 1, 2, 3, 4, 5, 6, 7, 8, 16 }
|
||||
ND_TCHECK_SIZE(p)
|
||||
ND_TCHECK_LEN(p, l)
|
||||
For the ND_TCHECK_* macros (if not already done):
|
||||
Assign: ndo->ndo_protocol = "protocol";
|
||||
Define: ND_LONGJMP_FROM_TCHECK before including netdissect.h
|
||||
Make sure that the intersection of GET_*() and ND_TCHECK_*() is minimal,
|
||||
but at the same time their union covers all packet data in all cases.
|
||||
You can test the code via:
|
||||
sudo ./tcpdump -s snaplen [-v][v][...] -i lo # in a terminal
|
||||
sudo tcpreplay -i lo sample.pcap # in another terminal
|
||||
You should try several values for snaplen to do various truncation.
|
||||
|
||||
e) Do invalid packet checks in code: Think that your code can receive in input
|
||||
not only a valid packet but any arbitrary random sequence of octets (packet
|
||||
- built malformed originally by the sender or by a fuzz tester,
|
||||
- became corrupted in transit or for some other reason).
|
||||
Print with: nd_print_invalid(ndo); /* to print " (invalid)" */
|
||||
|
||||
f) Use 'struct tok' for indexed strings and print them with
|
||||
tok2str() or bittok2str() (for flags).
|
||||
|
||||
g) Avoid empty lines in output of printers.
|
||||
|
||||
h) A commit message must have:
|
||||
First line: Capitalized short summary in the imperative (70 chars or less)
|
||||
|
||||
Body: Detailed explanatory text, if necessary. Fold it to approximately
|
||||
72 characters. There must be an empty line separating the summary from
|
||||
the body.
|
||||
|
||||
i) Avoid non-ASCII characters in code and commit messages.
|
||||
|
||||
j) Use the style of the modified sources.
|
||||
|
||||
k) Don't mix declarations and code
|
||||
|
||||
l) Don't use // for comments
|
||||
Not all C compilers accept C++/C99 comments by default.
|
||||
|
||||
m) Avoid trailing tabs/spaces
|
||||
188
CONTRIBUTING.md
Normal file
188
CONTRIBUTING.md
Normal file
@ -0,0 +1,188 @@
|
||||
# Some Information for Contributors
|
||||
Thank you for considering to make a contribution to tcpdump! Please use the
|
||||
guidelines below to achieve the best results and experience for everyone.
|
||||
|
||||
## How to report bugs and other problems
|
||||
**To report a security issue (segfault, buffer overflow, infinite loop, arbitrary
|
||||
code execution etc) please send an e-mail to security@tcpdump.org, do not use
|
||||
the bug tracker!**
|
||||
|
||||
To report a non-security problem (failure to compile, incorrect output in the
|
||||
protocol printout, missing support for a particular protocol etc) please check
|
||||
first that it reproduces with the latest stable release of tcpdump and the latest
|
||||
stable release of libpcap. If it does, please check that the problem reproduces
|
||||
with the current git master branch of tcpdump and the current git master branch of
|
||||
libpcap. If it does (and it is not a security-related problem, otherwise see
|
||||
above), please navigate to the
|
||||
[bug tracker](https://github.com/the-tcpdump-group/tcpdump/issues)
|
||||
and check if the problem has already been reported. If it has not, please open
|
||||
a new issue and provide the following details:
|
||||
|
||||
* tcpdump and libpcap version (`tcpdump --version`)
|
||||
* operating system name and version and any other details that may be relevant
|
||||
(`uname -a`, compiler name and version, CPU type etc.)
|
||||
* custom `configure`/`cmake` flags, if any
|
||||
* statement of the problem
|
||||
* steps to reproduce
|
||||
|
||||
Please note that if you know exactly how to solve the problem and the solution
|
||||
would not be too intrusive, it would be best to contribute some development time
|
||||
and to open a pull request instead as discussed below.
|
||||
|
||||
Still not sure how to do? Feel free to
|
||||
[subscribe to the mailing list](https://www.tcpdump.org/#mailing-lists)
|
||||
and ask!
|
||||
|
||||
|
||||
## How to add new code and to update existing code
|
||||
|
||||
0) Check that there isn't a pull request already opened for the changes you
|
||||
intend to make.
|
||||
|
||||
1) [Fork](https://help.github.com/articles/fork-a-repo/) the Tcpdump
|
||||
[repository](https://github.com/the-tcpdump-group/tcpdump).
|
||||
|
||||
2) The easiest way to test your changes on multiple operating systems and
|
||||
architectures is to let the upstream CI test your pull request (more on
|
||||
this below).
|
||||
|
||||
3) Setup your git working copy
|
||||
```
|
||||
git clone https://github.com/<username>/tcpdump.git
|
||||
cd tcpdump
|
||||
git remote add upstream https://github.com/the-tcpdump-group/tcpdump
|
||||
git fetch upstream
|
||||
```
|
||||
|
||||
4) Do a `touch .devel` in your working directory.
|
||||
Currently, the effect is
|
||||
* add (via `configure`, in `Makefile`) some warnings options (`-Wall`,
|
||||
`-Wmissing-prototypes`, `-Wstrict-prototypes`, ...) to the compiler if it
|
||||
supports these options,
|
||||
* have the `Makefile` support `make depend` and the `configure` script run it.
|
||||
|
||||
5) Configure and build
|
||||
```
|
||||
./configure && make -s && make check
|
||||
```
|
||||
|
||||
6) Add/update tests
|
||||
The `tests` directory contains regression tests of the dissection of captured
|
||||
packets. Those captured packets were saved running tcpdump with option
|
||||
`-w sample.pcap`. Additional options, such as `-n`, are used to create relevant
|
||||
and reproducible output; `-#` is used to indicate which particular packets
|
||||
have output that differs. The tests are run with the `TZ` environment
|
||||
variable set to `GMT0`, so that UTC, rather than the local time where the
|
||||
tests are being run, is used when "local time" values are printed. The
|
||||
actual test compares the current text output with the expected result
|
||||
(`sample.out`) saved from a previous version.
|
||||
|
||||
Any new/updated fields in a dissector must be present in a `sample.pcap` file
|
||||
and the corresponding output file.
|
||||
|
||||
Configuration is set in `tests/TESTLIST`.
|
||||
Each line in this file has the following format:
|
||||
```
|
||||
test-name sample.pcap sample.out tcpdump-options
|
||||
```
|
||||
|
||||
The `sample.out` file can be produced as follows:
|
||||
```
|
||||
(cd tests && TZ=GMT0 ../tcpdump -# -n -r sample.pcap tcpdump-options > sample.out)
|
||||
```
|
||||
|
||||
Or, for convenience, use `./update-test.sh test-name`
|
||||
|
||||
It is often useful to have test outputs with different verbosity levels
|
||||
(none, `-v`, `-vv`, `-vvv`, etc.) depending on the code.
|
||||
|
||||
7) Test using `make check` (current build options) and `./build_matrix.sh`
|
||||
(a multitude of build options, build systems and compilers). If you can,
|
||||
test on more than one operating system. Don't send a pull request until
|
||||
all tests pass.
|
||||
|
||||
8) Try to rebase your commits to keep the history simple.
|
||||
```
|
||||
git fetch upstream
|
||||
git rebase upstream/master
|
||||
```
|
||||
(If the rebase fails and you cannot resolve, issue `git rebase --abort`
|
||||
and ask for help in the pull request comment.)
|
||||
|
||||
9) Once 100% happy, put your work into your forked repository using `git push`.
|
||||
|
||||
10) [Initiate and send](https://help.github.com/articles/using-pull-requests/)
|
||||
a pull request.
|
||||
This will trigger the upstream repository CI tests.
|
||||
|
||||
|
||||
## Code style and generic remarks
|
||||
* A thorough reading of some other printers code is useful.
|
||||
|
||||
* Put the normative reference if any as comments (RFC, etc.).
|
||||
|
||||
* Put the format of packets/headers/options as comments if there is no
|
||||
published normative reference.
|
||||
|
||||
* The printer may receive incomplete packet in the buffer, truncated at any
|
||||
random position, for example by capturing with `-s size` option.
|
||||
If your code reads and decodes every byte of the protocol packet, then to
|
||||
ensure proper and complete bounds checks it would be sufficient to read all
|
||||
packet data using the `GET_*()` macros, typically:
|
||||
```
|
||||
GET_U_1(p)
|
||||
GET_S_1(p)
|
||||
GET_BE_U_n(p), n in { 2, 3, 4, 5, 6, 7, 8 }
|
||||
GET_BE_S_n(p), n in { 2, 3, 4, 5, 6, 7, 8 }
|
||||
```
|
||||
If your code uses the macros above only on some packet data, then the gaps
|
||||
would have to be bounds-checked using the `ND_TCHECK_*()` macros:
|
||||
```
|
||||
ND_TCHECK_n(p), n in { 1, 2, 3, 4, 5, 6, 7, 8, 16 }
|
||||
ND_TCHECK_SIZE(p)
|
||||
ND_TCHECK_LEN(p, l)
|
||||
```
|
||||
For the `ND_TCHECK_*` macros (if not already done):
|
||||
* Assign: `ndo->ndo_protocol = "protocol";`
|
||||
* Define: `ND_LONGJMP_FROM_TCHECK` before including `netdissect.h`
|
||||
* Make sure that the intersection of `GET_*()` and `ND_TCHECK_*()` is minimal,
|
||||
but at the same time their union covers all packet data in all cases.
|
||||
|
||||
You can test the code via:
|
||||
```
|
||||
sudo ./tcpdump -s snaplen [-v][v][...] -i lo # in a terminal
|
||||
sudo tcpreplay -i lo sample.pcap # in another terminal
|
||||
```
|
||||
You should try several values for snaplen to do various truncation.
|
||||
|
||||
* Do invalid packet checks in code: Think that your code can receive in input
|
||||
not only a valid packet but any arbitrary random sequence of octets (packet
|
||||
* built malformed originally by the sender or by a fuzz tester,
|
||||
* became corrupted in transit or for some other reason).
|
||||
|
||||
Print with: `nd_print_invalid(ndo); /* to print " (invalid)" */`
|
||||
|
||||
* Use `struct tok` for indexed strings and print them with
|
||||
`tok2str()` or `bittok2str()` (for flags).
|
||||
|
||||
* Avoid empty lines in output of printers.
|
||||
|
||||
* A commit message must have:
|
||||
```
|
||||
First line: Capitalized short summary in the imperative (50 chars or less)
|
||||
|
||||
Body: Detailed explanatory text, if necessary. Fold it to approximately
|
||||
72 characters. There must be an empty line separating the summary from
|
||||
the body.
|
||||
```
|
||||
|
||||
* Avoid non-ASCII characters in code and commit messages.
|
||||
|
||||
* Use the style of the modified sources.
|
||||
|
||||
* Don't mix declarations and code.
|
||||
|
||||
* Don't use `//` for comments.
|
||||
Not all C compilers accept C++/C99 comments by default.
|
||||
|
||||
* Avoid trailing tabs/spaces
|
||||
@ -44,7 +44,7 @@ Please see [this file](README.md) for notes about tested platforms.
|
||||
## Description of files
|
||||
```
|
||||
CHANGES - description of differences between releases
|
||||
CONTRIBUTING - guidelines for contributing
|
||||
CONTRIBUTING.md - guidelines for contributing
|
||||
CREDITS - people that have helped tcpdump along
|
||||
INSTALL.md - this file
|
||||
LICENSE - the license under which tcpdump is distributed
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
|
||||
To report bugs and other problems, contribute patches, request a
|
||||
feature, provide generic feedback etc please see the
|
||||
[guidelines for contributing](CONTRIBUTING) in the tcpdump source tree root.
|
||||
[guidelines for contributing](CONTRIBUTING.md) in the tcpdump source tree root.
|
||||
|
||||
Anonymous Git is available via
|
||||
|
||||
|
||||
2
aclocal.m4
vendored
2
aclocal.m4
vendored
@ -857,7 +857,7 @@ AC_DEFUN(AC_LBL_LIBPCAP,
|
||||
AC_CHECK_FUNC(pcap_loop,,
|
||||
[
|
||||
AC_MSG_ERROR(
|
||||
[This is a bug, please follow the guidelines in CONTRIBUTING and include the
|
||||
[This is a bug, please follow the guidelines in CONTRIBUTING.md and include the
|
||||
config.log file in your report. If you have downloaded libpcap from
|
||||
tcpdump.org, and built it yourself, please also include the config.log
|
||||
file from the libpcap source directory, the Makefile from the libpcap
|
||||
|
||||
2
configure
vendored
2
configure
vendored
@ -6044,7 +6044,7 @@ if test "x$ac_cv_func_pcap_loop" = xyes; then :
|
||||
|
||||
else
|
||||
|
||||
as_fn_error $? "This is a bug, please follow the guidelines in CONTRIBUTING and include the
|
||||
as_fn_error $? "This is a bug, please follow the guidelines in CONTRIBUTING.md and include the
|
||||
config.log file in your report. If you have downloaded libpcap from
|
||||
tcpdump.org, and built it yourself, please also include the config.log
|
||||
file from the libpcap source directory, the Makefile from the libpcap
|
||||
|
||||
@ -2031,7 +2031,7 @@ To report a security issue please send an e-mail to \%security@tcpdump.org.
|
||||
.LP
|
||||
To report bugs and other problems, contribute patches, request a
|
||||
feature, provide generic feedback etc. please see the file
|
||||
.I CONTRIBUTING
|
||||
.I CONTRIBUTING.md
|
||||
in the tcpdump source tree root.
|
||||
.LP
|
||||
NIT doesn't let you watch your own outbound traffic, BPF will.
|
||||
|
||||
Loading…
Reference in New Issue
Block a user