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