contrib/libpcap/INSTALL.md

   1 # libpcap installation notes
   2 Libpcap can be built either with the configure script and `make`, or
   3 with CMake and any build system supported by CMake.
   4
   5 To build libpcap with the configure script and `make`:
   6
   7 * Run `./configure` (a shell script).  The configure script will
   8 determine your system attributes and generate an appropriate `Makefile`
   9 from `Makefile.in`.  The configure script has a number of options to
  10 control the configuration of libpcap; `./configure --help`` will show
  11 them.
  12
  13 * Next, run `make`.  If everything goes well, you can
  14 `su` to root and run `make install`.  However, you need not install
  15 libpcap if you just want to build tcpdump; just make sure the tcpdump
  16 and libpcap directory trees have the same parent directory.
  17
  18 To build libpcap with CMake and the build system of your choice, from
  19 the command line:
  20
  21 * Create a build directory into which CMake will put the build files it
  22 generates; CMake does not work as well with builds done in the source
  23 code directory as does the configure script.  The build directory may be
  24 created as a subdirectory of the source directory or as a directory
  25 outside the source directory.
  26
  27 * Change to the build directory and run CMake with the path from the
  28 build directory to the source directory as an argument.  The `-G` flag
  29 can be used to select the CMake "generator" appropriate for the build
  30 system you're using; various `-D` flags can be used to control the
  31 configuration of libpcap.
  32
  33 * Run the build tool.  If everything goes well, you can `su` to root and
  34 run the build tool with the `install` target.  Building tcpdump from a
  35 libpcap in a build directory is not supported.
  36
  37 An `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
  40 anything as root that doesn't need to be run as root increases the risk
  41 of damaging your system, and running the build as root will put files in
  42 the build directory that are owned by root and that probably cannot be
  43 overwritten, removed, or replaced except by root, which could cause
  44 permission errors in subsequent builds.
  45
  46 If configure says:
  47
  48     configure: warning: cannot determine packet capture interface
  49     configure: warning: (see INSTALL.md file for more info)
  50
  51 or CMake says:
  52
  53     cannot determine packet capture interface
  54
  55     (see the INSTALL.md file for more info)
  56
  57 then your system either does not support packet capture or your system
  58 does support packet capture but libpcap does not support that
  59 particular type. (If you have HP-UX, see below.) If your system uses a
  60 packet capture not supported by libpcap, please send us patches; don't
  61 forget to include an autoconf fragment suitable for use in
  62 `configure.ac`.
  63
  64 It is possible to override the default packet capture type with the
  65 `--with-pcap`` option to `./configure` or the `-DPCAP_TYPE` option to
  66 CMake, although the circumstances where this works are limited.  One
  67 possible reason to do that would be to force a supported packet capture
  68 type in the case where the configure or CMake scripts fails to detect
  69 it.
  70
  71 You will need a C99 compiler to build libpcap. The configure script
  72 will abort if your compiler is not C99 compliant. If this happens, use
  73 the generally available GNU C compiler (GCC) or Clang.
  74
  75 You will need either Flex 2.5.31 or later, or a version of Lex
  76 compatible with it (if any exist), to build libpcap.  The configure
  77 script will abort if there isn't any such program; CMake fails if Flex
  78 or Lex cannot be found, but doesn't ensure that it's compatible with
  79 Flex 2.5.31 or later.  If you have an older version of Flex, or don't
  80 have a compatible version of Lex, the current version of Flex is
  81 available [here](https://github.com/westes/flex).
  82
  83 You will need either Bison, Berkeley YACC, or a version of YACC
  84 compatible with them (if any exist), to build libpcap.  The configure
  85 script will abort if there isn't any such program; CMake fails if Bison
  86 or some form of YACC cannot be found, but doesn't ensure that it's
  87 compatible with Bison or Berkeley YACC.  If you don't have any such
  88 program, the current version of Bison can be found
  89 [here](https://ftp.gnu.org/gnu/bison/) and the current version of
  90 Berkeley YACC can be found [here](https://invisible-island.net/byacc/).
  91
  92 Sometimes the stock C compiler does not interact well with Flex and
  93 Bison. The list of problems includes undefined references for alloca(3).
  94 You can get around this by installing GCC.
  95
  96 ## Linux specifics
  97 On Linux, libpcap will not work if the kernel does not have the packet
  98 socket option enabled; see [this file](doc/README.linux) for more
  99 information.
 100
 101 ## Solaris specifics
 102 If 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
 104 perhaps errors. Either make sure your path has `/opt/SUNWspro/bin`
 105 before `/usr/ucb` or else:
 106
 107     setenv CC /opt/SUNWspro/bin/cc
 108
 109 before running configure. (You might have to do a `make distclean`
 110 if you already ran `configure` once).
 111
 112 See [this file](doc/README.solaris.md) for more up to date
 113 Solaris-related information.
 114
 115 ## HP-UX specifics
 116 If you use HP-UX, you must have at least version 9 and either the
 117 version of `cc` that supports C99 (`cc -AC99`) or else use the GNU C
 118 compiler. You must also buy the optional streams package. If you don't
 119 have:
 120
 121     /usr/include/sys/dlpi.h
 122     /usr/include/sys/dlpi_ext.h
 123
 124 then you don't have the streams package. In addition, we believe you
 125 need to install the "9.X LAN and DLPI drivers cumulative" patch
 126 (PHNE_6855) to make the version 9 DLPI work with libpcap.
 127
 128 The DLPI streams package is standard starting with HP-UX 10.
 129
 130 The HP implementation of DLPI is a little bit eccentric. Unlike
 131 Solaris, you must attach `/dev/dlpi` instead of the specific `/dev/*`
 132 network pseudo device entry in order to capture packets. The PPA is
 133 based on the ifnet "index" number. Under HP-UX 9, it is necessary to
 134 read `/dev/kmem` and the kernel symbol file (`/hp-ux`). Under HP-UX 10,
 135 DLPI can provide information for determining the PPA. It does not seem
 136 to be possible to trace the loopback interface. Unlike other DLPI
 137 implementations, PHYS implies MULTI and SAP and you get an error if you
 138 try to enable more than one promiscuous mode at a time.
 139
 140 It is impossible to capture outbound packets on HP-UX 9.  To do so on
 141 HP-UX 10, you will, apparently, need a late "LAN products cumulative
 142 patch" (at one point, it was claimed that this would be PHNE_18173 for
 143 s700/10.20; at another point, it was claimed that the required patches
 144 were PHNE_20892, PHNE_20725 and PHCO_10947, or newer patches), and to do
 145 so on HP-UX 11 you will, apparently, need the latest lancommon/DLPI
 146 patches and the latest driver patch for the interface(s) in use on HP-UX
 147 11 (at one point, it was claimed that patches PHNE_19766, PHNE_19826,
 148 PHNE_20008, and PHNE_20735 did the trick).
 149
 150 Furthermore, on HP-UX 10, you will need to turn on a kernel switch by
 151 doing
 152
 153         echo 'lanc_outbound_promisc_flag/W 1' | adb -w /stand/vmunix /dev/mem
 154
 155 You would have to arrange that this happens on reboots; the right way to
 156 do 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
 160 Finally, testing shows that there can't be more than one simultaneous
 161 DLPI user per network interface.
 162
 163 See [this file](doc/README.hpux) for more information specific to HP-UX.
 164
 165 ## AIX specifics
 166 See [this file](doc/README.aix) for information on installing libpcap and
 167 configuring your system to be able to support libpcap.
 168
 169 ## other specifics
 170 If you are trying to do packet capture with a FORE ATM card, you may or
 171 may not be able to. They usually only release their driver in object
 172 code so unless their driver supports packet capture, there's not much
 173 libpcap can do.
 174
 175 If you get an error like:
 176
 177     tcpdump: recv_ack: bind error 0x???
 178
 179 when using DLPI, look for the DL_ERROR_ACK error return values, usually
 180 in `/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