tests: add regression tests for Follow TCP Stream
[metze/wireshark/wip.git] / INSTALL
1 See also https://wiki.wireshark.org/Development.
2
3 Installation
4 ============
5
6 These are installation instructions for Unix and Unix-like systems
7 that can run the "configure" script in this same directory. These
8 are not the installation instructions for Windows systems; see
9 README.windows for those instructions.
10
11 0. This is software.  Beware.
12
13 1. If you wish to build Wireshark, make sure you have the Qt and GLib
14    development packages installed. Try running
15    'pkg-config glib-2.0 --modversion' to see if you have GLib 2.x
16    installed.  Then try running 'pkg-config Qt5Widgets --modversion'
17    to see if you have Qt installed. Wireshark needs version 4.8 or above
18    of Qt, although 5.2 and above are strongly recommended. It needs
19    version 2.22.0 or above of glib-2.0.  If you need to install or
20    re-install GLIB, you can find the packages at:
21
22         https://www.gtk.org
23
24    You can find Qt at:
25
26         https://www.qt.io/download
27
28    If you installed Qt or GLib from binary packages, you may have to
29    install corresponding "development" packages; there may be separate
30    "user's" and "developer's" packages, with the former not including
31    header files and the like.  For example, Red Hat users will need to
32    install a "glib2-devel" .rpm.
33
34 2. If you wish to build TShark, the line-mode version of Wireshark,
35    make sure you have GLib installed.  See note #1 above for instructions
36    on checking if you have GLib installed.
37
38 3. If you want to capture packets, make sure you have libpcap
39    installed.  The latest "official" version can be found at
40
41         http://www.tcpdump.org .
42
43    If you installed libpcap from a binary package, you may have to
44    install a "development" package; for example, there's
45    apparently a "libpcap0" Debian package, but it just includes a
46    shared library, a copyright notice, changelog files, and a
47    README.md file - you also need to install a "libpcap-dev" package
48    to get header files, a non-shared library, and the man page.
49    Similarly, Red Hat users will need to install a "libpcap-devel"
50    .rpm to go along with the "libpcap" .rpm.
51
52 4. Building Wireshark requires Perl (specifically the pod2man program)
53    so that the documentation can be built.
54
55 5. Building Wireshark requires Python.
56
57 6. Create a build directory separate from the source directory. It can
58    be anywhere, but you might run into issues if the path contains
59    spaces.
60
61 7. Run 'cmake <options> <path/to/the/wireshark/sources>' in your build
62    directory. Running 'cmake -LH <path/to/the/wireshark/sources>'
63    displays a complete list of options. The "Tool Reference" section of
64    Developer's Guide contains general instructions for using CMake. Some
65    of the Wireshark-specific options are as follows:
66
67     -G Ninja
68         CMake supports many different build systems, including UNIX
69         Make, MSBuild, and Ninja. UNIX Make is the default, but Ninja
70         tends to be faster.
71
72     -DBUILD_wireshark=OFF
73         By default CMake tries to find the Qt libraries so Wireshark,
74         the GUI packet analyzer, can be built.  You can disable the
75         build of the GUI version of Wireshark with this switch.
76
77     -DBUILD_tshark=OFF
78         By default the line-mode packet analyzer, TShark, is built.
79         Use this switch to avoid building it.
80
81     -DBUILD_editcap=OFF
82         By default the capture-file editing program is built.
83         Use this switch to avoid building it.
84
85     -DBUILD_capinfos=OFF
86         By default the capture-file statistics reporting pogram
87         is built. Use this switch to avoid building it.
88
89     -DBUILD_captype=OFF
90         By default the capture-type reporting pogram is built. Use this
91         switch to avoid building it.
92
93     -DBUILD_mergecap=OFF
94         By default the capture-file merging program is built.
95         Use this switch to avoid building it.
96
97     -DBUILD_reordercap=OFF
98         By default the capture-file reordering program is built.
99         Use this switch to avoid building it.
100
101     -DBUILD_text2pcap=OFF
102         By default the hex-dump-to-capture file conversion program
103         is built. Use this switch to avoid building it.
104
105     -DBUILD_dftest=OFF
106         By default the display-filter-compiler test program is built.
107         Use this switch to avoid building it.
108
109     -DBUILD_randpkt=OFF
110         By default the program which creates random packet-capture files
111         is built. Use this switch to avoid building it.
112
113     -DBUILD_dumpcap=OFF
114         By default the network traffic capture program is built.
115         Use this switch to avoid building it.
116
117     -DBUILD_rawshark=OFF
118         By default the program used to dump and analyze raw libpcap data
119         is built. Use this switch to avoid building it.
120
121     -DDUMPCAP_INSTALL_OPTION=suid
122     -DDUMPCAP_INSTALL_OPTION=capabilities
123         Wireshark and TShark rely on dumpcap for packet capture. Setting
124         this flag to "suid" installs dumpcap with setuid root
125         permissions, which lets any user on the system capture live
126         traffic. If this is not desired, you can restrict dumpcap's
127         permissions so that only a single user or group can run it and
128         set the "capabilities" flag.
129
130         Running Wireshark or TShark as root is not recommended.
131
132     -DENABLE_CAP=OFF
133         By default, if 'cmake' finds libcap (the POSIX capabilities
134         library) dumpcap will be built so that if it is installed setuid
135         root, it will attempt to retain CAP_NET_RAW and CAP_NET_ADMIN
136         before dropping root privileges. Use this option to disable this
137         behavior.
138
139     -DENABLE_PCAP=OFF
140         If you choose to build a packet analyzer that can analyze
141         capture files but cannot capture packets on its own, but you
142         *do* have libpcap installed, or if you are trying to build
143         Wireshark on a system that doesn't have libpcap installed (in
144         which case you have no choice but to build a version that can
145         analyze capture files but cannot capture packets on its own),
146         use -DENABLE_PCAP=OFF to avoid using libpcap.
147
148     -DENABLE_ZLIB=OFF
149         By default, if 'configure' finds zlib (a.k.a, libz), the
150         wiretap library will be built so that it can read compressed
151         capture files. If you have zlib but do not wish to build
152         it into the wiretap library, used by Wireshark, TShark, and
153         the capture-file utilities that come in this package, use
154         this switch.
155
156     -DENABLE_PLUGINS=OFF
157         By default, if your system can support run-time loadable modules,
158         the packet analyzers are build with support for plugins.
159         Use this switch to build packet analyzers without plugin support.
160
161 8. After running 'cmake', you will see a summary of some
162    of the options you chose. Ensure that the summary reflects
163    what you want. If it doesn't, re-run 'cmake' with new options.
164
165 9. Run 'make', or 'ninja' if you chose to create Ninja build files.
166    Hopefully, you won't run into any problems.
167
168 10. Run './run/wireshark' or './run/tshark' or ./run/dumpcap, and make sure things are
169    working. You must have root privileges in order to capture live data.
170
171 11./a. Run 'make install'.  If you're running a system that supports
172    the RPM packaging systems you can run
173
174         make rpm-package
175
176    or
177
178         ninja rpm-package
179
180    to make an installable package for your system. The installation path
181    defaults to /usr/local, so you'll probably want to pass
182    -DCMAKE_INSTALL_PREFIX=/usr to CMake.
183
184 11/b. If you 're running a system that supports APT (Debian/Ubuntu/etc.)
185    run
186
187         dpkg-buildpackage -us -uc -rfakeroot
188
189    in the source directory right after extracting of checking out
190    Wireshark's source code. (You don't have to run configure/make/etc.
191    prior to running dpkg-buildpackage)
192
193
194 If you have trouble with the build or installation process, you can
195 find assistance on the wireshark-users and wireshark-dev mailing lists (see
196 http://www.wireshark.org/lists/ for details) or the Wireshark Q&A site:
197 https://ask.wireshark.org .