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