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