The Tcpdump Group git mirrors - libpcap/blob - INSTALL.md

   1 # libpcap installation notes
   2
   3 Platform-specific notes:
   4 * [AIX](doc/README.aix)
   5 * [Haiku](doc/README.haiku.md)
   6 * [HP-UX](doc/README.hpux)
   7 * [GNU/Hurd](doc/README.hurd.md)
   8 * [GNU/Linux](doc/README.linux)
   9 * [macOS](doc/README.macos)
  10 * [Solaris and related OSes](doc/README.solaris.md)
  11 * [Windows](doc/README.windows.md)
  12
  13 Hardware-specific notes:
  14 * [Endace DAG](doc/README.dag.md)
  15 * [Myricom SNF](doc/README.snf.md)
  16
  17 Libpcap can be built either with the configure script and `make`, or
  18 with CMake and any build system supported by CMake.
  19
  20 To build libpcap with the configure script and `make`:
  21
  22 * If you build from a git clone rather than from a release archive,
  23 run `./autogen.sh` (a shell script). The autogen.sh script will
  24 build the `configure` and `config.h.in` files.
  25
  26 On some system, you may need to set the `AUTORECONF` variable, like:
  27 `AUTORECONF=autoreconf-2.69 ./autogen.sh`
  28 to select the `autoreconf` version you want to use.
  29
  30 * Run `./configure` (a shell script).  The configure script will
  31 determine your system attributes and generate an appropriate `Makefile`
  32 from `Makefile.in`.  The configure script has a number of options to
  33 control the configuration of libpcap; `./configure --help` will show
  34 them.
  35
  36 * Next, run `make`.  If everything goes well, you can
  37 `su` to root and run `make install`.  However, you need not install
  38 libpcap if you just want to build tcpdump; just make sure the tcpdump
  39 and libpcap directory trees have the same parent directory.
  40
  41 On OpenBSD, you may need to set, before the `make`, the `AUTOCONF_VERSION`
  42 variable like:
  43 `AUTOCONF_VERSION=2.69 make`
  44
  45 To build libpcap with CMake and the build system of your choice, from
  46 the command line:
  47
  48 * Create a build directory into which CMake will put the build files it
  49 generates; CMake does not work as well with builds done in the source
  50 code directory as does the configure script.  The build directory may be
  51 created as a subdirectory of the source directory or as a directory
  52 outside the source directory.
  53
  54 * Change to the build directory and run CMake with the path from the
  55 build directory to the source directory as an argument.  The `-G` flag
  56 can be used to select the CMake "generator" appropriate for the build
  57 system you're using; various `-D` flags can be used to control the
  58 configuration of libpcap.
  59
  60 * Run the build tool.  If everything goes well, you can `su` to root and
  61 run the build tool with the `install` target.  Building tcpdump from a
  62 libpcap in a build directory is not supported.
  63
  64 An `uninstall` target is supported with both `./configure` and CMake.
  65
  66 ***DO NOT*** run the build as root; there is no need to do so, running
  67 anything as root that doesn't need to be run as root increases the risk
  68 of damaging your system, and running the build as root will put files in
  69 the build directory that are owned by root and that probably cannot be
  70 overwritten, removed, or replaced except by root, which could cause
  71 permission errors in subsequent builds.
  72
  73 If configure says:
  74
  75     configure: warning: cannot determine packet capture interface
  76     configure: warning: (see INSTALL.md file for more info)
  77
  78 or CMake says:
  79
  80     cannot determine packet capture interface
  81
  82     (see the INSTALL.md file for more info)
  83
  84 then your system either does not support packet capture or your system
  85 does support packet capture but libpcap does not support that
  86 particular type.  If your system uses a
  87 packet capture not supported by libpcap, please send us patches; don't
  88 forget to include an autoconf fragment suitable for use in
  89 `configure.ac`.
  90
  91 It is possible to override the default packet capture type with the
  92 `--with-pcap` option to `./configure` or the `-DPCAP_TYPE` option to
  93 CMake, although the circumstances where this works are limited.  One
  94 possible reason to do that would be to force a supported packet capture
  95 type in the case where the configure or CMake scripts fails to detect
  96 it.
  97
  98 You will need a C99 compiler to build libpcap. The configure script
  99 will abort if your compiler is not C99 compliant. If this happens, use
 100 the generally available GNU C compiler (GCC) or Clang.
 101
 102 You will need either Flex 2.5.31 or later, or a version of Lex
 103 compatible with it (if any exist), to build libpcap.  The configure
 104 script will abort if there isn't any such program; CMake fails if Flex
 105 or Lex cannot be found, but doesn't ensure that it's compatible with
 106 Flex 2.5.31 or later.  If you have an older version of Flex, or don't
 107 have a compatible version of Lex, the current version of Flex is
 108 available [here](https://github.com/westes/flex).
 109
 110 You will need either Bison, Berkeley YACC, or a version of YACC
 111 compatible with them (if any exist), to build libpcap.  The configure
 112 script will abort if there isn't any such program; CMake fails if Bison
 113 or some form of YACC cannot be found, but doesn't ensure that it's
 114 compatible with Bison or Berkeley YACC.  If you don't have any such
 115 program, the current version of Bison can be found
 116 [here](https://ftp.gnu.org/gnu/bison/) and the current version of
 117 Berkeley YACC can be found [here](https://invisible-island.net/byacc/).
 118
 119 Sometimes the stock C compiler does not interact well with Flex and
 120 Bison. The list of problems includes undefined references for alloca(3).
 121 You can get around this by installing GCC.
 122
 123 ## Description of files
 124         CHANGES             - description of differences between releases
 125         ChmodBPF/*          - macOS startup item to set ownership and permissions on /dev/bpf*
 126         CMakeLists.txt      - CMake file
 127         CONTRIBUTING.md     - guidelines for contributing
 128         CREDITS             - people that have helped libpcap along
 129         INSTALL.md          - this file
 130         LICENSE             - the license under which libpcap is distributed
 131         Makefile.in         - compilation rules (input to the configure script)
 132         README.md           - description of distribution
 133         doc/README.aix      - notes on using libpcap on AIX
 134         doc/README.dag.md   - notes on using libpcap to capture on Endace DAG devices
 135         doc/README.haiku.md - notes on using libpcap on Haiku
 136         doc/README.hpux     - notes on using libpcap on HP-UX
 137         doc/README.hurd.md  - notes on using libpcap on GNU/Hurd
 138         doc/README.linux    - notes on using libpcap on Linux
 139         doc/README.macos    - notes on using libpcap on macOS
 140         doc/README.snf.md   - notes on using libpcap to capture on Myricom SNF devices
 141         doc/README.solaris.md - notes on using libpcap on Solaris
 142         doc/README.windows.md - notes on using libpcap on Windows systems (with Npcap)
 143         VERSION             - version of this release
 144         aclocal.m4          - autoconf macros
 145         autogen.sh          - build configure and config.h.in (run this first)
 146         bpf_dump.c          - BPF program printing routines
 147         bpf_filter.c        - BPF filtering routines
 148         bpf_image.c         - BPF disassembly routine
 149         charconv.c          - Windows Unicode routines
 150         charconv.h          - Windows Unicode prototypes
 151         config.guess        - autoconf support
 152         config.sub          - autoconf support
 153         configure.ac        - configure script source
 154         diag-control.h      - compiler diagnostics control macros
 155         dlpisubs.c          - DLPI-related functions for pcap-dlpi.c and pcap-libdlpi.c
 156         dlpisubs.h          - DLPI-related function declarations
 157         etherent.c          - /etc/ethers support routines
 158         extract.h           - Alignment definitions
 159         ethertype.h         - Ethernet protocol types and names definitions
 160         fad-getad.c         - pcap_findalldevs() for systems with getifaddrs()
 161         fad-gifc.c          - pcap_findalldevs() for systems with only SIOCGIFLIST
 162         fad-glifc.c         - pcap_findalldevs() for systems with SIOCGLIFCONF
 163         fmtutils.c          - error message formatting routines
 164         fmtutils.h          - error message formatting prototypes
 165         ftmacros.h          - feature test macros
 166         testprogs/TESTrun   - a script for "make check"
 167         testprogs/TESTlib.pm - TESTrun helper file
 168         testprogs/TESTmt.pm - TESTrun helper file
 169         testprogs/TESTst.pm - TESTrun helper file
 170         testprogs/filtertest.c      - test program for BPF compiler
 171         testprogs/findalldevstest.c - test program for pcap_findalldevs()
 172         gencode.c           - BPF code generation routines
 173         gencode.h           - BPF code generation definitions
 174         grammar.y           - filter string grammar
 175         ieee80211.h         - 802.11 definitions
 176         install-sh          - BSD style install script
 177         instrument-functions.c - functions instrumentation calls for entry/exit
 178         lbl/os-*.h          - OS-dependent defines and prototypes (if any)
 179         llc.h               - 802.2 LLC SAP definitions
 180         missing/*           - replacements for missing library functions
 181         mkdep               - construct Makefile dependency list
 182         nametoaddr.c        - hostname to address routines
 183         nametoaddr.h        - hostname to address prototypes
 184         optimize.c          - BPF optimization routines
 185         optimize.h          - BPF optimization prototypes
 186         pcap/bluetooth.h    - public definition of DLT_BLUETOOTH_HCI_H4_WITH_PHDR header
 187         pcap/bpf.h          - BPF definitions
 188         pcap/can_socketcan.h - SocketCAN header
 189         pcap/compiler-tests.h - compiler version comparison and other macros
 190         pcap/dlt.h          - Link-layer header type codes.
 191         pcap/funcattrs.h    - function attribute macros
 192         pcap/ipnet.h        - Solaris IPnet definitions
 193         pcap/namedb.h       - public libpcap name database definitions
 194         pcap/nflog.h        - NFLOG-related definitions
 195         pcap/pcap.h         - public libpcap definitions
 196         pcap/pcap-inttypes.h - header for OS-specific integer type includes
 197         pcap/sll.h          - public definitions of DLT_LINUX_SLL and DLT_LINUX_SLL2 headers
 198         pcap/socket.h       - IP sockets support for various OSes
 199         pcap/usb.h          - public definition of DLT_USB header
 200         pcap/vlan.h         - VLAN-specific definitions
 201         pcap-bpf.c          - BSD Packet Filter support
 202         pcap-bpf.h          - header for backwards compatibility
 203         pcap-bt-linux.c     - Bluetooth capture support for Linux
 204         pcap-bt-linux.h     - Bluetooth capture support for Linux
 205         pcap-bt-monitor-linux.c - Bluetooth monitor capture support for Linux
 206         pcap-bt-monitor-linux.h - Bluetooth monitor capture support for Linux
 207         pcap-common.c       - common code for pcap and pcapng files
 208         pcap-common.h       - common code for pcap and pcapng files
 209         pcap-dag.c          - Endace DAG device capture support
 210         pcap-dag.h          - Endace DAG device capture support
 211         pcap-dbus.c         - D-Bus capture support
 212         pcap-dbus.h         - D-Bus capture support
 213         pcap-dlpi.c         - Data Link Provider Interface support
 214         pcap-dpdk.c         - DPDK device support
 215         pcap-dpdk.h         - DPDK device support
 216         pcap-haiku.c        - Haiku capture support
 217         pcap-hurd.c         - GNU Hurd support
 218         pcap-int.h          - internal libpcap definitions
 219         pcap-libdlpi.c      - Data Link Provider Interface support for systems with libdlpi
 220         pcap-linux.c        - Linux packet socket support
 221         pcap-namedb.h       - header for backwards compatibility
 222         pcap-netfilter-linux.c - Linux netfilter support
 223         pcap-netfilter-linux.h - Linux netfilter support
 224         pcap-netmap.c       - netmap support
 225         pcap-netmap.h       - netmap support
 226         pcap-npf.c          - Npcap capture support
 227         pcap-null.c         - dummy monitor support (allows offline use of libpcap)
 228         pcap-rdmasniff.c    - RDMA/InfiniBand capture support
 229         pcap-rdmasniff.h    - RDMA/InfiniBand capture support
 230         pcap-rpcap.c        - RPCAP protocol capture support
 231         pcap-rpcap.h        - RPCAP protocol capture support
 232         pcap-snf.c          - Myricom SNF device capture support
 233         pcap-snf.h          - Myricom SNF device capture support
 234         pcap-types.h        - header for OS-specific type includes
 235         pcap-usb-linux.c    - USB capture support for Linux
 236         pcap-usb-linux.h    - USB capture support for Linux
 237         pcap-usb-linux-common.c - Linux USB common routines
 238         pcap-usb-linux-common.h - Linux USB common prototypes
 239         pcap-util.c         - common code for various files
 240         pcap-util.h         - common code for various files
 241         pcap.3pcap          - manual entry for the library
 242         pcap.c              - pcap utility routines
 243         pcap.h              - header for backwards compatibility
 244         pcap_*.3pcap        - manual entries for library functions
 245         pcap-filter.manmisc.in   - manual entry for filter syntax
 246         pcap-linktype.manmisc.in - manual entry for link-layer header types
 247         pflog.h             - header for DLT_PFLOG handling in filter code
 248         portability.h       - Portability declarations/definitions
 249         ppp.h               - Point to Point Protocol definitions
 250         rpcap-protocol.c    - RPCAP client/server common routines
 251         rpcap-protocol.h    - RPCAP client/server common prototypes
 252         savefile.c          - offline support
 253         scanner.l           - filter string scanner
 254         sf-pcap.c           - routines for .pcap savefiles
 255         sf-pcap.h           - prototypes for .pcap savefiles
 256         sf-pcapng.c         - routines for .pcapng savefiles
 257         sf-pcapng.h         - prototypes for .pcapng savefiles
 258         sockutils.c         - socket and name lookup API routines
 259         sockutils.h         - socket and name lookup API prototypes
 260         sslutils.c          - OpenSSL interface routines
 261         sslutils.h          - OpenSSL interface prototypes
 262         thread-local.h      - header for some thread-safe support
 263         varattrs.h          - variable attribute macros