• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# libpcap installation notes
2Libpcap can be built either with the configure script and `make`, or
3with CMake and any build system supported by CMake.
4
5To build libpcap with the configure script and `make`:
6
7* Run `./configure` (a shell script).  The configure script will
8determine your system attributes and generate an appropriate `Makefile`
9from `Makefile.in`.  The configure script has a number of options to
10control the configuration of libpcap; `./configure --help`` will show
11them.
12
13* Next, run `make`.  If everything goes well, you can
14`su` to root and run `make install`.  However, you need not install
15libpcap if you just want to build tcpdump; just make sure the tcpdump
16and libpcap directory trees have the same parent directory.
17
18To build libpcap with CMake and the build system of your choice, from
19the command line:
20
21* Create a build directory into which CMake will put the build files it
22generates; CMake does not work as well with builds done in the source
23code directory as does the configure script.  The build directory may be
24created as a subdirectory of the source directory or as a directory
25outside the source directory.
26
27* Change to the build directory and run CMake with the path from the
28build directory to the source directory as an argument.  The `-G` flag
29can be used to select the CMake "generator" appropriate for the build
30system you're using; various `-D` flags can be used to control the
31configuration of libpcap.
32
33* Run the build tool.  If everything goes well, you can `su` to root and
34run the build tool with the `install` target.  Building tcpdump from a
35libpcap in a build directory is not supported.
36
37An `uninstall` target is supported with both `./configure` and CMake.
38
39***DO NOT*** run the build as root; there is no need to do so, running
40anything as root that doesn't need to be run as root increases the risk
41of damaging your system, and running the build as root will put files in
42the build directory that are owned by root and that probably cannot be
43overwritten, removed, or replaced except by root, which could cause
44permission errors in subsequent builds.
45
46If configure says:
47
48    configure: warning: cannot determine packet capture interface
49    configure: warning: (see INSTALL.md file for more info)
50
51or CMake says:
52
53    cannot determine packet capture interface
54
55    (see the INSTALL.md file for more info)
56
57then your system either does not support packet capture or your system
58does support packet capture but libpcap does not support that
59particular type. (If you have HP-UX, see below.) If your system uses a
60packet capture not supported by libpcap, please send us patches; don't
61forget to include an autoconf fragment suitable for use in
62`configure.ac`.
63
64It is possible to override the default packet capture type with the
65`--with-pcap`` option to `./configure` or the `-DPCAP_TYPE` option to
66CMake, although the circumstances where this works are limited.  One
67possible reason to do that would be to force a supported packet capture
68type in the case where the configure or CMake scripts fails to detect
69it.
70
71You will need a C99 compiler to build libpcap. The configure script
72will abort if your compiler is not C99 compliant. If this happens, use
73the generally available GNU C compiler (GCC) or Clang.
74
75You will need either Flex 2.5.31 or later, or a version of Lex
76compatible with it (if any exist), to build libpcap.  The configure
77script will abort if there isn't any such program; CMake fails if Flex
78or Lex cannot be found, but doesn't ensure that it's compatible with
79Flex 2.5.31 or later.  If you have an older version of Flex, or don't
80have a compatible version of Lex, the current version of Flex is
81available [here](https://github.com/westes/flex).
82
83You will need either Bison, Berkeley YACC, or a version of YACC
84compatible with them (if any exist), to build libpcap.  The configure
85script will abort if there isn't any such program; CMake fails if Bison
86or some form of YACC cannot be found, but doesn't ensure that it's
87compatible with Bison or Berkeley YACC.  If you don't have any such
88program, the current version of Bison can be found
89[here](https://ftp.gnu.org/gnu/bison/) and the current version of
90Berkeley YACC can be found [here](https://invisible-island.net/byacc/).
91
92Sometimes the stock C compiler does not interact well with Flex and
93Bison. The list of problems includes undefined references for alloca(3).
94You can get around this by installing GCC.
95
96## Linux specifics
97On Linux, libpcap will not work if the kernel does not have the packet
98socket option enabled; see [this file](doc/README.linux) for more
99information.
100
101## Solaris specifics
102If you use the SPARCompiler, you must be careful to not use the
103`/usr/ucb/cc` interface. If you do, you will get bogus warnings and
104perhaps errors. Either make sure your path has `/opt/SUNWspro/bin`
105before `/usr/ucb` or else:
106
107    setenv CC /opt/SUNWspro/bin/cc
108
109before running configure. (You might have to do a `make distclean`
110if you already ran `configure` once).
111
112See [this file](doc/README.solaris.md) for more up to date
113Solaris-related information.
114
115## HP-UX specifics
116If you use HP-UX, you must have at least version 9 and either the
117version of `cc` that supports C99 (`cc -AC99`) or else use the GNU C
118compiler. You must also buy the optional streams package. If you don't
119have:
120
121    /usr/include/sys/dlpi.h
122    /usr/include/sys/dlpi_ext.h
123
124then you don't have the streams package. In addition, we believe you
125need to install the "9.X LAN and DLPI drivers cumulative" patch
126(PHNE_6855) to make the version 9 DLPI work with libpcap.
127
128The DLPI streams package is standard starting with HP-UX 10.
129
130The HP implementation of DLPI is a little bit eccentric. Unlike
131Solaris, you must attach `/dev/dlpi` instead of the specific `/dev/*`
132network pseudo device entry in order to capture packets. The PPA is
133based on the ifnet "index" number. Under HP-UX 9, it is necessary to
134read `/dev/kmem` and the kernel symbol file (`/hp-ux`). Under HP-UX 10,
135DLPI can provide information for determining the PPA. It does not seem
136to be possible to trace the loopback interface. Unlike other DLPI
137implementations, PHYS implies MULTI and SAP and you get an error if you
138try to enable more than one promiscuous mode at a time.
139
140It is impossible to capture outbound packets on HP-UX 9.  To do so on
141HP-UX 10, you will, apparently, need a late "LAN products cumulative
142patch" (at one point, it was claimed that this would be PHNE_18173 for
143s700/10.20; at another point, it was claimed that the required patches
144were PHNE_20892, PHNE_20725 and PHCO_10947, or newer patches), and to do
145so on HP-UX 11 you will, apparently, need the latest lancommon/DLPI
146patches and the latest driver patch for the interface(s) in use on HP-UX
14711 (at one point, it was claimed that patches PHNE_19766, PHNE_19826,
148PHNE_20008, and PHNE_20735 did the trick).
149
150Furthermore, on HP-UX 10, you will need to turn on a kernel switch by
151doing
152
153	echo 'lanc_outbound_promisc_flag/W 1' | adb -w /stand/vmunix /dev/mem
154
155You would have to arrange that this happens on reboots; the right way to
156do that would probably be to put it into an executable script file
157`/sbin/init.d/outbound_promisc` and making
158`/sbin/rc2.d/S350outbound_promisc` a symbolic link to that script.
159
160Finally, testing shows that there can't be more than one simultaneous
161DLPI user per network interface.
162
163See [this file](doc/README.hpux) for more information specific to HP-UX.
164
165## AIX specifics
166See [this file](doc/README.aix) for information on installing libpcap and
167configuring your system to be able to support libpcap.
168
169## other specifics
170If you are trying to do packet capture with a FORE ATM card, you may or
171may not be able to. They usually only release their driver in object
172code so unless their driver supports packet capture, there's not much
173libpcap can do.
174
175If you get an error like:
176
177    tcpdump: recv_ack: bind error 0x???
178
179when using DLPI, look for the DL_ERROR_ACK error return values, usually
180in `/usr/include/sys/dlpi.h`, and find the corresponding value.
181
182## Description of files
183	CHANGES		    - description of differences between releases
184	ChmodBPF/*	    - macOS startup item to set ownership and permissions on /dev/bpf*
185	CMakeLists.txt	    - CMake file
186	CONTRIBUTING.md	    - guidelines for contributing
187	CREDITS		    - people that have helped libpcap along
188	INSTALL.md	    - this file
189	LICENSE		    - the license under which tcpdump is distributed
190	Makefile.in	    - compilation rules (input to the configure script)
191	README.md	    - description of distribution
192	doc/README.aix	    - notes on using libpcap on AIX
193	doc/README.dag	    - notes on using libpcap to capture on Endace DAG devices
194	doc/README.hpux	    - notes on using libpcap on HP-UX
195	doc/README.linux    - notes on using libpcap on Linux
196	doc/README.macos    - notes on using libpcap on macOS
197	doc/README.septel   - notes on using libpcap to capture on Intel/Septel devices
198	doc/README.sita	    - notes on using libpcap to capture on SITA devices
199	doc/README.solaris.md - notes on using libpcap on Solaris
200	doc/README.Win32.md - notes on using libpcap on Win32 systems (with Npcap)
201	VERSION		    - version of this release
202	aclocal.m4	    - autoconf macros
203	arcnet.h	    - ARCNET definitions
204	atmuni31.h	    - ATM Q.2931 definitions
205	bpf_dump.c	    - BPF program printing routines
206	bpf_filter.c	    - BPF filtering routines
207	bpf_image.c	    - BPF disassembly routine
208	config.guess	    - autoconf support
209	config.h.in	    - autoconf input
210	config.sub	    - autoconf support
211	configure	    - configure script (run this first)
212	configure.ac	    - configure script source
213	dlpisubs.c	    - DLPI-related functions for pcap-dlpi.c and pcap-libdlpi.c
214	dlpisubs.h	    - DLPI-related function declarations
215	etherent.c	    - /etc/ethers support routines
216	ethertype.h	    - Ethernet protocol types and names definitions
217	fad-getad.c	    - pcap_findalldevs() for systems with getifaddrs()
218	fad-gifc.c	    - pcap_findalldevs() for systems with only SIOCGIFLIST
219	fad-glifc.c	    - pcap_findalldevs() for systems with SIOCGLIFCONF
220	testprogs/filtertest.c      - test program for BPF compiler
221	testprogs/findalldevstest.c - test program for pcap_findalldevs()
222	gencode.c	    - BPF code generation routines
223	gencode.h	    - BPF code generation definitions
224	grammar.y	    - filter string grammar
225	ieee80211.h	    - 802.11 definitions
226	install-sh	    - BSD style install script
227	lbl/os-*.h	    - OS-dependent defines and prototypes
228	llc.h		    - 802.2 LLC SAP definitions
229	missing/*	    - replacements for missing library functions
230	mkdep		    - construct Makefile dependency list
231	msdos/*		    - drivers for MS-DOS capture support
232	nametoaddr.c	    - hostname to address routines
233	nlpid.h		    - OSI network layer protocol identifier definitions
234	optimize.c	    - BPF optimization routines
235	pcap/bluetooth.h    - public definition of DLT_BLUETOOTH_HCI_H4_WITH_PHDR header
236	pcap/bpf.h	    - BPF definitions
237	pcap/namedb.h	    - public libpcap name database definitions
238	pcap/pcap.h	    - public libpcap definitions
239	pcap/sll.h	    - public definitions of DLT_LINUX_SLL and DLT_LINUX_SLL2 headers
240	pcap/usb.h	    - public definition of DLT_USB header
241	pcap-bpf.c	    - BSD Packet Filter support
242	pcap-bpf.h	    - header for backwards compatibility
243	pcap-bt-linux.c	    - Bluetooth capture support for Linux
244	pcap-bt-linux.h	    - Bluetooth capture support for Linux
245	pcap-dag.c	    - Endace DAG device capture support
246	pcap-dag.h	    - Endace DAG device capture support
247	pcap-dlpi.c	    - Data Link Provider Interface support
248	pcap-dos.c	    - MS-DOS capture support
249	pcap-dos.h	    - headers for MS-DOS capture support
250	pcap-enet.c	    - enet support
251	pcap-int.h	    - internal libpcap definitions
252	pcap-libdlpi.c	    - Data Link Provider Interface support for systems with libdlpi
253	pcap-linux.c	    - Linux packet socket support
254	pcap-namedb.h	    - header for backwards compatibility
255	pcap-nit.c	    - SunOS Network Interface Tap support
256	pcap-npf.c	    - Npcap capture support
257	pcap-null.c	    - dummy monitor support (allows offline use of libpcap)
258	pcap-pf.c	    - Ultrix and Digital/Tru64 UNIX Packet Filter support
259	pcap-septel.c       - Intel/Septel device capture support
260	pcap-septel.h       - Intel/Septel device capture support
261	pcap-sita.c	    - SITA device capture support
262	pcap-sita.h	    - SITA device capture support
263	pcap-sita.html	    - SITA device capture documentation
264	pcap-snit.c	    - SunOS 4.x STREAMS-based Network Interface Tap support
265	pcap-snoop.c	    - IRIX Snoop network monitoring support
266	pcap-usb-linux.c    - USB capture support for Linux
267	pcap-usb-linux.h    - USB capture support for Linux
268	pcap.3pcap	    - manual entry for the library
269	pcap.c		    - pcap utility routines
270	pcap.h		    - header for backwards compatibility
271	pcap_*.3pcap	    - manual entries for library functions
272	pcap-filter.manmisc.in   - manual entry for filter syntax
273	pcap-linktype.manmisc.in - manual entry for link-layer header types
274	ppp.h		    - Point to Point Protocol definitions
275	savefile.c	    - offline support
276	scanner.l	    - filter string scanner
277	sunatmpos.h	    - definitions for SunATM capturing
278