1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
|
Some Information for Contributors
---------------------------------
You want to contribute to Tcpdump, Thanks!
Please, read these lines.
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.)
* configure flags if any were used
* 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 open a pull request instead as discussed below.
Still not sure how to do? Feel free to [subscribe](http://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) Setup optional Travis CI build and AppVeyor builds
You can setup Travis CI and AppVeyor builds for your fork, so you can
test your changes on Linux, macOS, and Windows before sending pull
requests.
(See http://docs.travis-ci.com/user/getting-started/ for information
on setting up Travis CI; go to https://ci.appveyor.com/login and log
in with your GitHub account and select "NEW PROJECT" to set up an
AppVeyor build.)
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 sample.pcap files
We use tests directory to do regression tests on the dissection of captured
packets. Those captured packets were saved running tcpdump with option "-w
sample.pcap". Additional options like "-n" and "-t" are used to create
relevant and reproducible output. 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 build by:
(cd tests && ../tcpdump -n -t -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
This will trigger both Travis CI and AppVeyor builds.
10) Initiate and send a pull request
(See https://help.github.com/articles/using-pull-requests/)
Note that creating the pull request will cause your code to be
tested on Linux and macOS with Travis CI and on Windows with
AppVeyor.
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.
Thus use ND_TTEST, ND_TTEST_LEN, ND_TCHECK or ND_TCHECK_LEN for bound checking.
For ND_TCHECK_LEN:
Define : static const char tstr[] = " [|protocol]";
Define a label: trunc
Print with: ND_PRINT("%s", tstr);
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).
Print with: ND_PRINT("%s", istr); /* 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
|
