contrib/libpcap/INSTALL.txt

   1 @(#) $Header: /tcpdump/master/libpcap/INSTALL.txt,v 1.12.2.2 2007/09/12 19:17:24 guy Exp $ (LBL)
   2
   3 To build libpcap, run "./configure" (a shell script). The configure
   4 script will determine your system attributes and generate an
   5 appropriate Makefile from Makefile.in. Next run "make". If everything
   6 goes well you can su to root and run "make install". However, you need
   7 not install libpcap if you just want to build tcpdump; just make sure
   8 the tcpdump and libpcap directory trees have the same parent
   9 directory.
  10
  11 If configure says:
  12
  13     configure: warning: cannot determine packet capture interface
  14     configure: warning: (see INSTALL for more info)
  15
  16 then your system either does not support packet capture or your system
  17 does support packet capture but libpcap does not support that
  18 particular type. (If you have HP-UX, see below.) If your system uses a
  19 packet capture not supported by libpcap, please send us patches; don't
  20 forget to include an autoconf fragment suitable for use in
  21 configure.in.
  22
  23 It is possible to override the default packet capture type, although
  24 the circumstance where this works are limited. For example if you have
  25 installed bpf under SunOS 4 and wish to build a snit libpcap:
  26
  27     ./configure --with-pcap=snit
  28
  29 Another example is to force a supported packet capture type in the case
  30 where the configure scripts fails to detect it.
  31
  32 You will need an ANSI C compiler to build libpcap. The configure script
  33 will abort if your compiler is not ANSI compliant. If this happens, use
  34 the GNU C compiler, available via anonymous ftp:
  35
  36         ftp://ftp.gnu.org/pub/gnu/gcc/
  37
  38 If you use flex, you must use version 2.4.6 or higher. The configure
  39 script automatically detects the version of flex and will not use it
  40 unless it is new enough. You can use "flex -V" to see what version you
  41 have (unless it's really old). The current version of flex is available
  42 via anonymous ftp:
  43
  44         ftp://ftp.ee.lbl.gov/flex-*.tar.Z
  45
  46 As of this writing, the current version is 2.5.4.
  47
  48 If you use bison, you must use flex (and visa versa). The configure
  49 script automatically falls back to lex and yacc if both flex and bison
  50 are not found.
  51
  52 Sometimes the stock C compiler does not interact well with flex and
  53 bison. The list of problems includes undefined references for alloca.
  54 You can get around this by installing gcc or manually disabling flex
  55 and bison with:
  56
  57     ./configure --without-flex --without-bison
  58
  59 If your system only has AT&T lex, this is okay unless your libpcap
  60 program uses other lex/yacc generated code. (Although it's possible to
  61 map the yy* identifiers with a script, we use flex and bison so we
  62 don't feel this is necessary.)
  63
  64 Some systems support the Berkeley Packet Filter natively; for example
  65 out of the box OSF and BSD/OS have bpf. If your system does not support
  66 bpf, you will need to pick up:
  67
  68         ftp://ftp.ee.lbl.gov/bpf-*.tar.Z
  69
  70 Note well: you MUST have kernel source for your operating system in
  71 order to install bpf. An exception is SunOS 4; the bpf distribution
  72 includes replacement kernel objects for some of the standard SunOS 4
  73 network device drivers. See the bpf INSTALL document for more
  74 information.
  75
  76 If you use Solaris, there is a bug with bufmod(7) that is fixed in
  77 Solaris 2.3.2 (aka SunOS 5.3.2). Setting a snapshot length with the
  78 broken bufmod(7) results in data be truncated from the FRONT of the
  79 packet instead of the end.  The work around is to not set a snapshot
  80 length but this results in performance problems since the entire packet
  81 is copied to user space. If you must run an older version of Solaris,
  82 there is a patch available from Sun; ask for bugid 1149065. After
  83 installing the patch, use "setenv BUFMOD_FIXED" to enable use of
  84 bufmod(7). However, we recommend you run a more current release of
  85 Solaris.
  86
  87 If you use the SPARCompiler, you must be careful to not use the
  88 /usr/ucb/cc interface. If you do, you will get bogus warnings and
  89 perhaps errors. Either make sure your path has /opt/SUNWspro/bin
  90 before /usr/ucb or else:
  91
  92     setenv CC /opt/SUNWspro/bin/cc
  93
  94 before running configure. (You might have to do a "make distclean"
  95 if you already ran configure once).
  96
  97 Also note that "make depend" won't work; while all of the known
  98 universe uses -M, the SPARCompiler uses -xM to generate makefile
  99 dependencies.
 100
 101 If you are trying to do packet capture with a FORE ATM card, you may or
 102 may not be able to. They usually only release their driver in object
 103 code so unless their driver supports packet capture, there's not much
 104 libpcap can do.
 105
 106 If you get an error like:
 107
 108     tcpdump: recv_ack: bind error 0x???
 109
 110 when using DLPI, look for the DL_ERROR_ACK error return values, usually
 111 in /usr/include/sys/dlpi.h, and find the corresponding value.
 112
 113 Under {DEC OSF/1, Digital UNIX, Tru64 UNIX}, packet capture must be
 114 enabled before it can be used.  For instructions on how to enable packet
 115 filter support, see:
 116
 117         ftp://ftp.digital.com/pub/Digital/dec-faq/Digital-UNIX
 118
 119 Look for the "How do I configure the Berkeley Packet Filter and capture
 120 tcpdump traces?" item.
 121
 122 Once you enable packet filter support, your OSF system will support bpf
 123 natively.
 124
 125 Under Ultrix, packet capture must be enabled before it can be used. For
 126 instructions on how to enable packet filter support, see:
 127
 128         ftp://ftp.digital.com/pub/Digital/dec-faq/ultrix
 129
 130 If you use HP-UX, you must have at least version 9 and either the
 131 version of cc that supports ANSI C (cc -Aa) or else use the GNU C
 132 compiler. You must also buy the optional streams package. If you don't
 133 have:
 134
 135     /usr/include/sys/dlpi.h
 136     /usr/include/sys/dlpi_ext.h
 137
 138 then you don't have the streams package. In addition, we believe you
 139 need to install the "9.X LAN and DLPI drivers cumulative" patch
 140 (PHNE_6855) to make the version 9 DLPI work with libpcap.
 141
 142 The DLPI streams package is standard starting with HP-UX 10.
 143
 144 The HP implementation of DLPI is a little bit eccentric. Unlike
 145 Solaris, you must attach /dev/dlpi instead of the specific /dev/*
 146 network pseudo device entry in order to capture packets. The PPA is
 147 based on the ifnet "index" number. Under HP-UX 9, it is necessary to
 148 read /dev/kmem and the kernel symbol file (/hp-ux). Under HP-UX 10,
 149 DLPI can provide information for determining the PPA. It does not seem
 150 to be possible to trace the loopback interface. Unlike other DLPI
 151 implementations, PHYS implies MULTI and SAP and you get an error if you
 152 try to enable more than one promiscuous mode at a time.
 153
 154 It is impossible to capture outbound packets on HP-UX 9.  To do so on
 155 HP-UX 10, you will, apparently, need a late "LAN products cumulative
 156 patch" (at one point, it was claimed that this would be PHNE_18173 for
 157 s700/10.20; at another point, it was claimed that the required patches
 158 were PHNE_20892, PHNE_20725 and PHCO_10947, or newer patches), and to do
 159 so on HP-UX 11 you will, apparently, need the latest lancommon/DLPI
 160 patches and the latest driver patch for the interface(s) in use on HP-UX
 161 11 (at one point, it was claimed that patches PHNE_19766, PHNE_19826,
 162 PHNE_20008, and PHNE_20735 did the trick).
 163
 164 Furthermore, on HP-UX 10, you will need to turn on a kernel switch by
 165 doing
 166
 167         echo 'lanc_outbound_promisc_flag/W 1' | adb -w /stand/vmunix /dev/mem
 168
 169 You would have to arrange that this happen on reboots; the right way to
 170 do that would probably be to put it into an executable script file
 171 "/sbin/init.d/outbound_promisc" and making
 172 "/sbin/rc2.d/S350outbound_promisc" a symbolic link to that script.
 173
 174 Finally, testing shows that there can't be more than one simultaneous
 175 DLPI user per network interface.
 176
 177 If you use Linux, this version of libpcap is known to compile and run
 178 under Red Hat 4.0 with the 2.0.25 kernel.  It may work with earlier 2.X
 179 versions but is guaranteed not to work with 1.X kernels.  Running more
 180 than one libpcap program at a time, on a system with a 2.0.X kernel, can
 181 cause problems since promiscuous mode is implemented by twiddling the
 182 interface flags from the libpcap application; the packet capture
 183 mechanism in the 2.2 and later kernels doesn't have this problem.  Also,
 184 packet timestamps aren't very good.  This appears to be due to haphazard
 185 handling of the timestamp in the kernel.
 186
 187 Note well: there is rumoured to be a version of tcpdump floating around
 188 called 3.0.3 that includes libpcap and is supposed to support Linux.
 189 You should be advised that neither the Network Research Group at LBNL
 190 nor the Tcpdump Group ever generated a release with this version number.
 191 The LBNL Network Research Group notes with interest that a standard
 192 cracker trick to get people to install trojans is to distribute bogus
 193 packages that have a version number higher than the current release.
 194 They also noted with annoyance that 90% of the Linux related bug reports
 195 they got are due to changes made to unofficial versions of their page.
 196 If you are having trouble but aren't using a version that came from
 197 tcpdump.org, please try that before submitting a bug report!
 198
 199 On Linux, libpcap will not work if the kernel does not have the packet
 200 socket option enabled; see the README.linux file for information about
 201 this.
 202
 203 If you use AIX, you may not be able to build libpcap from this release.
 204 We do not have an AIX system in house so it's impossible for us to test
 205 AIX patches submitted to us.  We are told that you must link against
 206 /lib/pse.exp, that you must use AIX cc or a GNU C compiler newer than
 207 2.7.2, and that you may need to run strload before running a libpcap
 208 application.
 209
 210 Read the README.aix file for information on installing libpcap and
 211 configuring your system to be able to support libpcap.
 212
 213 If you use NeXTSTEP, you will not be able to build libpcap from this
 214 release. We hope to support this operating system in some future
 215 release of libpcap.
 216
 217 If you use SINIX, you should be able to build libpcap from this
 218 release. It is known to compile and run on SINIX-Y/N 5.42 with the C-DS
 219 V1.0 or V1.1 compiler. But note that in some releases of SINIX, yacc
 220 emits incorrect code; if grammar.y fails to compile, change every
 221 occurence of:
 222
 223         #ifdef YYDEBUG
 224
 225 to:
 226         #if YYDEBUG
 227
 228 Another workaround is to use flex and bison.
 229
 230 If you use SCO, you might have trouble building libpcap from this
 231 release. We do not have a machine running SCO and have not had reports
 232 of anyone successfully building on it. Since SCO apparently supports
 233 DLPI, it's possible the current version works. Meanwhile, SCO provides
 234 a tcpdump binary as part of their "Network/Security Tools" package:
 235
 236     http://www.sco.com/technology/internet/goodies/#SECURITY
 237
 238 There is also a README that explains how to enable packet capture.
 239
 240 If you use UnixWare, you will not be able to build libpcap from this
 241 release. We hope to support this operating system in some future
 242 release of libpcap. Meanwhile, there appears to be an UnixWare port of
 243 libpcap 0.0 (and tcpdump 3.0) in:
 244
 245     ftp://ftp1.freebird.org/pub/mirror/freebird/internet/systools/
 246
 247 UnixWare appears to use a hacked version of DLPI.
 248
 249 If linking tcpdump fails with "Undefined: _alloca" when using bison on
 250 a Sun4, your version of bison is broken. In any case version 1.16 or
 251 higher is recommended (1.14 is known to cause problems 1.16 is known to
 252 work). Either pick up a current version from:
 253
 254         ftp://ftp.gnu.org/pub/gnu/bison
 255
 256 or hack around it by inserting the lines:
 257
 258         #ifdef __GNUC__
 259         #define alloca __builtin_alloca
 260         #else
 261         #ifdef sparc
 262         #include <alloca.h>
 263         #else
 264         char *alloca ();
 265         #endif
 266         #endif
 267
 268 right after the (100 line!) GNU license comment in bison.simple, remove
 269 grammar.[co] and fire up make again.
 270
 271 If you use SunOS 4, your kernel must support streams NIT. If you run a
 272 libpcap program and it dies with:
 273
 274     /dev/nit: No such device
 275
 276 You must add streams NIT support to your kernel configuration, run
 277 config and boot the new kernel.
 278
 279 If you are running a version of SunOS earlier than 4.1, you will need
 280 to replace the Sun supplied /sys/sun{3,4,4c}/OBJ/nit_if.o with the
 281 appropriate version from this distribution's SUNOS4 subdirectory and
 282 build a new kernel:
 283
 284         nit_if.o.sun3-sunos4            (any flavor of sun3)
 285         nit_if.o.sun4c-sunos4.0.3c      (SS1, SS1+, IPC, SLC, etc.)
 286         nit_if.o.sun4-sunos4            (Sun4's not covered by
 287                                             nit_if.o.sun4c-sunos4.0.3c)
 288
 289 These nit replacements fix a bug that makes nit essentially unusable in
 290 pre-SunOS 4.1.  In addition, our sun4c-sunos4.0.3c nit gives you
 291 timestamps to the resolution of the SS-1 clock (1 us) rather than the
 292 lousy 20ms timestamps Sun gives you  (tcpdump will print out the full
 293 timestamp resolution if it finds it's running on a SS-1).
 294
 295 FILES
 296 -----
 297 CHANGES         - description of differences between releases
 298 ChmodBPF/*      - Mac OS X startup item to set ownership and permissions
 299                   on /dev/bpf*
 300 CREDITS         - people that have helped libpcap along
 301 FILES           - list of files exported as part of the distribution
 302 INSTALL.txt     - this file
 303 LICENSE         - the license under which tcpdump is distributed
 304 Makefile.in     - compilation rules (input to the configure script)
 305 README          - description of distribution
 306 README.aix      - notes on using libpcap on AIX
 307 README.dag      - notes on using libpcap to capture on Endace DAG devices
 308 README.hpux     - notes on using libpcap on HP-UX
 309 README.linux    - notes on using libpcap on Linux
 310 README.macosx   - notes on using libpcap on Mac OS X
 311 README.septel   - notes on using libpcap to capture on Intel/Septel devices
 312 README.tru64    - notes on using libpcap on Digital/Tru64 UNIX
 313 README.Win32    - notes on using libpcap on Win32 systems (with WinPcap)
 314 SUNOS4          - pre-SunOS 4.1 replacement kernel nit modules
 315 VERSION         - version of this release
 316 acconfig.h      - support for post-2.13 autoconf
 317 aclocal.m4      - autoconf macros
 318 arcnet.h        - ARCNET definitions
 319 atmuni31.h      - ATM Q.2931 definitions
 320 bpf/net         - copy of bpf_filter.c
 321 bpf_dump.c      - BPF program printing routines
 322 bpf_filter.c    - symlink to bpf/net/bpf_filter.c
 323 bpf_image.c     - BPF disassembly routine
 324 config.guess    - autoconf support
 325 config.h.in     - autoconf input
 326 config.sub      - autoconf support
 327 configure       - configure script (run this first)
 328 configure.in    - configure script source
 329 etherent.c      - /etc/ethers support routines
 330 ethertype.h     - Ethernet protocol types and names definitions
 331 fad-getad.c     - pcap_findalldevs() for systems with getifaddrs()
 332 fad-gifc.c      - pcap_findalldevs() for systems with only SIOCGIFLIST
 333 fad-glifc.c     - pcap_findalldevs() for systems with SIOCGLIFCONF
 334 fad-null.c      - pcap_findalldevs() for systems without capture support
 335 fad-win32.c     - pcap_findalldevs() for WinPcap
 336 gencode.c       - BPF code generation routines
 337 gencode.h       - BPF code generation definitions
 338 grammar.y       - filter string grammar
 339 inet.c          - network routines
 340 install-sh      - BSD style install script
 341 lbl/os-*.h      - OS-dependent defines and prototypes
 342 llc.h           - 802.2 LLC SAP definitions
 343 missing/*       - replacements for missing library functions
 344 mkdep           - construct Makefile dependency list
 345 msdos/*         - drivers for MS-DOS capture support
 346 nametoaddr.c    - hostname to address routines
 347 nlpid.h         - OSI network layer protocol identifier definitions
 348 net             - symlink to bpf/net
 349 optimize.c      - BPF optimization routines
 350 packaging       - packaging information for building libpcap RPMs
 351 pcap-bpf.c      - BSD Packet Filter support
 352 pcap-bpf.h      - BPF definitions
 353 pcap-dag.c      - Endace DAG device capture support
 354 pcap-dag.h      - Endace DAG device capture support
 355 pcap-dlpi.c     - Data Link Provider Interface support
 356 pcap-dos.c      - MS-DOS capture support
 357 pcap-dos.h      - headers for MS-DOS capture support
 358 pcap-enet.c     - enet support
 359 pcap-int.h      - internal libpcap definitions
 360 pcap-linux.c    - Linux packet socket support
 361 pcap-namedb.h   - public libpcap name database definitions
 362 pcap-nit.c      - SunOS Network Interface Tap support
 363 pcap-nit.h      - SunOS Network Interface Tap definitions
 364 pcap-null.c     - dummy monitor support (allows offline use of libpcap)
 365 pcap-pf.c       - Ultrix and Digital/Tru64 UNIX Packet Filter support
 366 pcap-pf.h       - Ultrix and Digital/Tru64 UNIX Packet Filter definitions
 367 pcap-septel.c   - INTEL/Septel device capture support
 368 pcap-septel.h   - INTEL/Septel device capture support
 369 pcap-stdinc.h   - includes and #defines for compiling on Win32 systems
 370 pcap-snit.c     - SunOS 4.x STREAMS-based Network Interface Tap support
 371 pcap-snoop.c    - IRIX Snoop network monitoring support
 372 pcap-win32.c    - WinPcap capture support
 373 pcap.3          - manual entry
 374 pcap.c          - pcap utility routines
 375 pcap.h          - public libpcap definitions
 376 ppp.h           - Point to Point Protocol definitions
 377 rawss7.h        - information on DLT_ types for SS7
 378 savefile.c      - offline support
 379 scanner.l       - filter string scanner
 380 sll.h           - definitions for Linux cooked mode fake link-layer header
 381 sunatmpos.h     - definitions for SunATM capturing
 382 Win32           - headers and routines for building on Win32 systems