@(#) $Header: /tcpdump/master/libpcap/README,v 1.34 2008-12-14 19:44:14 guy Exp $ (LBL)

LIBPCAP 1.x.y

www.tcpdump.org

Please send inquiries/comments/reports to:
	tcpdump-workers@lists.tcpdump.org

Anonymous Git is available via:
	git clone git://bpf.tcpdump.org/libpcap

Please submit patches by forking the branch on GitHub at

	http://github.com/the-tcpdump-group/libpcap/tree/master

and issuing a pull request.

formerly from 	Lawrence Berkeley National Laboratory
		Network Research Group <libpcap@ee.lbl.gov>
		ftp://ftp.ee.lbl.gov/old/libpcap-0.4a7.tar.Z

This directory contains source code for libpcap, a system-independent
interface for user-level packet capture.  libpcap provides a portable
framework for low-level network monitoring.  Applications include
network statistics collection, security monitoring, network debugging,
etc.  Since almost every system vendor provides a different interface
for packet capture, and since we've developed several tools that
require this functionality, we've created this system-independent API
to ease in porting and to alleviate the need for several
system-dependent packet capture modules in each application.

For some platforms there are README.{system} files that discuss issues
with the OS's interface for packet capture on those platforms, such as
how to enable support for that interface in the OS, if it's not built in
by default.

The libpcap interface supports a filtering mechanism based on the
architecture in the BSD packet filter.  BPF is described in the 1993
Winter Usenix paper ``The BSD Packet Filter: A New Architecture for
User-level Packet Capture''.  A compressed PostScript version can be
found at

	ftp://ftp.ee.lbl.gov/papers/bpf-usenix93.ps.Z

or

	http://www.tcpdump.org/papers/bpf-usenix93.ps.Z

and a gzipped version can be found at

	http://www.tcpdump.org/papers/bpf-usenix93.ps.gz

A PDF version can be found at

	http://www.tcpdump.org/papers/bpf-usenix93.pdf

Although most packet capture interfaces support in-kernel filtering,
libpcap utilizes in-kernel filtering only for the BPF interface.
On systems that don't have BPF, all packets are read into user-space
and the BPF filters are evaluated in the libpcap library, incurring
added overhead (especially, for selective filters).  Ideally, libpcap
would translate BPF filters into a filter program that is compatible
with the underlying kernel subsystem, but this is not yet implemented.

BPF is standard in 4.4BSD, BSD/OS, NetBSD, FreeBSD, OpenBSD, DragonFly
BSD, and Mac OS X; an older, modified and undocumented version is
standard in AIX.  {DEC OSF/1, Digital UNIX, Tru64 UNIX} uses the
packetfilter interface but has been extended to accept BPF filters
(which libpcap utilizes).  Also, you can add BPF filter support to
Ultrix using the kernel source and/or object patches available in:

	http://www.tcpdump.org/other/bpfext42.tar.Z

Linux, in the 2.2 kernel and later kernels, has a "Socket Filter"
mechanism that accepts BPF filters; see the README.linux file for
information on configuring that option.

Note to Linux distributions and *BSD systems that include libpcap:

There's now a rule to make a shared library, which should work on Linux
and *BSD, among other platforms.

It sets the soname of the library to "libpcap.so.1"; this is what it
should be, *NOT* libpcap.so.1.x or libpcap.so.1.x.y or something such as
that.

We've been maintaining binary compatibility between libpcap releases for
quite a while; there's no reason to tie a binary linked with libpcap to
a particular release of libpcap.

Problems, bugs, questions, desirable enhancements, etc. should be sent
to the address "tcpdump-workers@lists.tcpdump.org".  Bugs, support
requests, and feature requests may also be submitted on the GitHub issue
tracker for libpcap at

	https://github.com/the-tcpdump-group/libpcap/issues

Source code contributions, etc. should be sent to the email address
above or submitted by forking the branch on GitHub at

	http://github.com/the-tcpdump-group/libpcap/tree/master

and issuing a pull request.

Current versions can be found at www.tcpdump.org.

 - The TCPdump team

Under Win32, libpcap is integrated in the WinPcap packet capture system.
WinPcap provides a framework that allows libpcap to capture the packets
under Windows 95, Windows 98, Windows ME, Windows NT 4, Windows 2000
and Windows XP.
WinPcap binaries and source code can be found at http://winpcap.polito.it:
they include also a developer's pack with all the necessary to compile
libpcap-based applications under Windows.

How to compile libpcap with Visual Studio
-----------------------------------------

In order to compile libpcap you will need:

- version 6 (or higher) of Microsoft Visual Studio
- The November 2001 (or later) edition of Microsoft Platform
Software Development Kit (SDK), that contains some necessary includes
for IPv6 support. You can download it from http://www.microsoft.com/sdk
- the latest WinPcap sources from http://winpcap.polito.it/install

The WinPcap source code already contains a recent (usually the latest
stable) version of libpcap. If you need to compile a different one,
simply download it from www.tcpdump.org and copy the sources in the
winpcap\wpcap\libpcap folder of the WinPcap distribution. If you want to
compile a libpcap source retrieved from the tcpdump.org Git, you will
have to create the scanner and the grammar by hand (with lex and yacc)
or with the cygnus makefile, since The Visual Studio project is not able
to build them.

Open the project file winpcap\wpcap\prj\wpcap.dsw with Visual Studio and
build wpcap.dll. wpcap.lib, the library file to link with the applications,
will be generated in winpcap\wpcap\lib\. wpcap.dll will be generated in
winpcap\wpcap\prj\release or winpcap\wpcap\prj\debug depending on the type
of binary that is being created.

How to compile libpcap with Cygnus
----------------------------------

To build wpcap.dll, cd to the directory WPCAP/PRJ of the WinPcap source code
distribution and type "make". libwpcap.a, the library file to link with the
applications, will be generated in winpcap\wpcap\lib\. wpcap.dll will be
generated in winpcap\wpcap\prj.

Remember, you CANNOT use the MSVC-generated .lib files with gcc, use
libwpcap.a instead.

"make install" installs wpcap.dll in the Windows system folder.

Using BPF:

(1) AIX 4.x's version of BPF is undocumented and somewhat unstandard; the
    current BPF support code includes changes that should work around
    that; it appears to compile and work on at least one AIX 4.3.3
    machine.

    Note that the BPF driver and the "/dev/bpf" devices might not exist
    on your machine; AIX's tcpdump loads the driver and creates the
    devices if they don't already exist.  Our libpcap should do the
    same, and the configure script should detect that it's on an AIX
    system and choose BPF even if the devices aren't there.

(2) If libpcap doesn't compile on your machine when configured to use
    BPF, or if the workarounds fail to make it work correctly, you
    should send to tcpdump-workers@lists.tcpdump.org a detailed bug
    report (if the compile fails, send us the compile error messages;
    if it compiles but fails to work correctly, send us as detailed as
    possible a description of the symptoms, including indications of the
    network link-layer type being wrong or time stamps being wrong).

    If you fix the problems yourself, please submit a patch by forking
    the branch at

	https://github.com/the-tcpdump-group/libpcap/issues

    and issuing a pull request, so we can incorporate the fixes into the
    next release.

    If you don't fix the problems yourself, you can, as a workaround,
    make libpcap use DLPI instead of BPF.

    This can be done by specifying the flag:

       --with-pcap=dlpi

    to the "configure" script for libpcap.

If you use DLPI:

(1) It is a good idea to have the latest version of the DLPI driver on
    your system, since certain versions may be buggy and cause your AIX
    system to crash.  DLPI is included in the fileset bos.rte.tty.  I
    found that the DLPI driver that came with AIX 4.3.2 was buggy, and
    had to upgrade to bos.rte.tty 4.3.2.4:

	    lslpp -l bos.rte.tty

	    bos.rte.tty     4.3.2.4  COMMITTED  Base TTY Support and Commands

    Updates for AIX filesets can be obtained from:
    ftp://service.software.ibm.com/aix/fixes/

    These updates can be installed with the smit program.

(2) After compiling libpcap, you need to make sure that the DLPI driver
    is loaded.  Type:

	    strload -q -d dlpi

    If the result is:

	    dlpi: yes

    then the DLPI driver is loaded correctly.

    If it is:

	    dlpi: no

    Then you need to type:

	    strload -f /etc/dlpi.conf

    Check again with strload -q -d dlpi that the dlpi driver is loaded.

    Alternatively, you can uncomment the lines for DLPI in
    /etc/pse.conf and reboot the machine; this way DLPI will always
    be loaded when you boot your system.

(3) There appears to be a problem in the DLPI code in some versions of
    AIX, causing a warning about DL_PROMISC_MULTI failing; this might
    be responsible for DLPI not being able to capture outgoing packets.

The following instructions apply if you have a Linux or FreeBSD platform and
want libpcap to support the DAG range of passive network monitoring cards from
Endace (http://www.endace.com, see below for further contact details).

1) Install and build the DAG software distribution by following the
instructions supplied with that package. Current Endace customers can download
the DAG software distibution from https://www.endace.com

2) Configure libcap. To allow the 'configure' script to locate the DAG
software distribution use the '--with-dag' option:

        ./configure --with-dag=DIR

Where DIR is the root of the DAG software distribution, for example
/var/src/dag. If the DAG software is correctly detected 'configure' will
report:

        checking whether we have DAG API... yes

If 'configure' reports that there is no DAG API, the directory may have been
incorrectly specified or the DAG software was not built before configuring
libpcap.

See also the libpcap INSTALL.txt file for further libpcap configuration
options.

Building libpcap at this stage will include support for both the native packet
capture stream (linux or bpf) and for capturing from DAG cards. To build
libpcap with only DAG support specify the capture type as 'dag' when
configuring libpcap:

        ./configure --with-dag=DIR --with-pcap=dag

Applications built with libpcap configured in this way will only detect DAG
cards and will not capture from the native OS packet stream.

----------------------------------------------------------------------

Libpcap when built for DAG cards against dag-2.5.1 or later releases:

Timeouts are supported. pcap_dispatch() will return after to_ms milliseconds
regardless of how many packets are received. If to_ms is zero pcap_dispatch()
will block waiting for data indefinitely.

pcap_dispatch() will block on and process a minimum of 64kB of data (before
filtering) for efficiency. This can introduce high latencies on quiet
interfaces unless a timeout value is set. The timeout expiring will override
the 64kB minimum causing pcap_dispatch() to process any available data and
return.

pcap_setnonblock is supported. When nonblock is set, pcap_dispatch() will
check once for available data, process any data available up to count, then
return immediately.

pcap_findalldevs() is supported, e.g. dag0, dag1...

Some DAG cards can provide more than one 'stream' of received data.
This can be data from different physical ports, or separated by filtering
or load balancing mechanisms. Receive streams have even numbers, e.g.
dag0:0, dag0:2 etc. Specifying transmit streams for capture is not supported.

pcap_setfilter() is supported, BPF programs run in userspace.

pcap_setdirection() is not supported. Only received traffic is captured.
DAG cards normally do not have IP or link layer addresses assigned as
they are used to passively monitor links.

pcap_breakloop() is supported.

pcap_datalink() and pcap_list_datalinks() are supported. The DAG card does
not attempt to set the correct datalink type automatically where more than
one type is possible.

pcap_stats() is supported. ps_drop is the number of packets dropped due to
RX stream buffer overflow, this count is before filters are applied (it will
include packets that would have been dropped by the filter). The RX stream
buffer size is user configurable outside libpcap, typically 16-512MB.

pcap_get_selectable_fd() is not supported, as DAG cards do not support
poll/select methods.

pcap_inject() and pcap_sendpacket() are not supported.

Some DAG cards now support capturing to multiple virtual interfaces, called
streams. Capture streams have even numbers. These are available via libpcap
as separate interfaces, e.g. dag0:0, dag0:2, dag0:4 etc. dag0:0 is the same
as dag0. These are visible via pcap_findalldevs().

libpcap now does NOT set the card's hardware snaplen (slen). This must now be
set using the appropriate DAG coniguration program, e.g. dagthree, dagfour,
dagsix, dagconfig. This is because the snaplen is currently shared between
all of the streams. In future this may change if per-stream slen is
implemented.

DAG cards by default capture entire packets including the L2
CRC/FCS. If the card is not configured to discard the CRC/FCS, this
can confuse applications that use libpcap if they're not prepared for
packets to have an FCS.

Libpcap now reads the environment variable ERF_FCS_BITS to determine
how many bits of CRC/FCS to strip from the end of the captured
frame. This defaults to 32 for use with Ethernet. If the card is
configured to strip the CRC/FCS, then set ERF_FCS_BITS=0. If used with
a HDLC/PoS/PPP/Frame Relay link with 16 bit CRC/FCS, then set
ERF_FCS_BITS=16.

If you wish to create a pcap file that DOES contain the Ethernet FCS,
specify the environment variable ERF_DONT_STRIP_FCS. This will cause
the existing FCS to be captured into the pcap file. Note some
applications may incorrectly report capture errors or oversize packets
when reading these files.

----------------------------------------------------------------------

Please submit bug reports via <support@endace.com>.

Please also visit our Web site at:

        http://www.endace.com/

For more information about Endace DAG cards contact <sales@endace.com>.

For HP-UX 11i (11.11) and later, there are no known issues with
promiscuous mode under HP-UX.  If you are using a earlier version of
HP-UX and cannot upgrade, please continue reading.

HP-UX patches to fix packet capture problems

Note that packet-capture programs such as tcpdump may, on HP-UX, not be
able to see packets sent from the machine on which they're running.
Some articles on groups.google.com discussing this are:

	http://groups.google.com/groups?selm=82ld3v%2480i%241%40mamenchi.zrz.TU-Berlin.DE

which says:

  Newsgroups: comp.sys.hp.hpux
  Subject:  Re: Did someone made tcpdump working on 10.20 ?
  Date: 12/08/1999
  From: Lutz Jaenicke <jaenicke@emserv1.ee.TU-Berlin.DE>

  In article <82ks5i$5vc$1@news1.dti.ne.jp>, mtsat <mtsat@iris.dti.ne.jp>
  wrote:
   >Hello,
   >
   >I downloaded and compiled tcpdump3.4 a couple of week ago. I tried to use
   >it, but I can only see incoming data, never outgoing.
   >Someone (raj) explained me that a patch was missing, and that this patch
   >must me "patched" (poked) in order to see outbound data in promiscuous mode.
   >Many things to do .... So the question is : did someone has already this
   >"ready to use" PHNE_**** patch ?

   Two things:
   1. You do need a late "LAN products cumulative patch" (e.g.  PHNE_18173
  for   s700/10.20).
   2. You must use
echo 'lanc_outbound_promisc_flag/W1' | /usr/bin/adb -w /stand/vmunix /dev/kmem
     You can insert this e.g. into /sbin/init.d/lan

   Best regards,
   Lutz

and

	http://groups.google.com/groups?selm=88cf4t%24p03%241%40web1.cup.hp.com

which says:

  Newsgroups: comp.sys.hp.hpux
  Subject: Re: tcpdump only shows incoming packets
  Date: 02/15/2000
  From: Rick Jones <foo@bar.baz.invalid>

  Harald Skotnes <harald@cc.uit.no> wrote:
  > I am running HPUX 11.0 on a C200 hanging on a 100Mb switch. I have
  > compiled libpcap-0.4 an tcpdump-3.4 and it seems to work. But at a
  > closer look I only get to see the incoming packets not the
  > outgoing. I have tried tcpflow-0.12 which also uses libpcap and the
  > same thing happens.  Could someone please give me a hint on how to
  > get this right?

  Search/Read the archives ?-)

  What you are seeing is expected, un-patched, behaviour for an HP-UX
  system.  On 11.00, you need to install the latest lancommon/DLPI
  patches, and then the latest driver patch for the interface(s) in use.
  At that point, a miracle happens and you should start seeing outbound
  traffic.

[That article also mentions the patch that appears below.]

and

	http://groups.google.com/groups?selm=38AA973E.96BE7DF7%40cc.uit.no

which says:

  Newsgroups: comp.sys.hp.hpux
  Subject: Re: tcpdump only shows incoming packets
  Date: 02/16/2000
  From: Harald Skotnes <harald@cc.uit.no>

  Rick Jones wrote:

	...

  > What you are seeing is expected, un-patched, behaviour for an HP-UX
  > system. On 11.00, you need to install the latest lancommon/DLPI
  > patches, and then the latest driver patch for the interface(s) in
  > use. At that point, a miracle happens and you should start seeing
  > outbound traffic.

  Thanks a lot.  I have this problem on several machines running HPUX
  10.20 and 11.00.  The machines where patched up before y2k so did not
  know what to think.  Anyway I have now installed PHNE_19766,
  PHNE_19826, PHNE_20008, PHNE_20735 on the C200 and now I can see the
  outbound traffic too.  Thanks again.

(although those patches may not be the ones to install - there may be
later patches).

And another message to tcpdump-workers@tcpdump.org, from Rick Jones:

  Date: Mon, 29 Apr 2002 15:59:55 -0700
  From: Rick Jones
  To: tcpdump-workers@tcpdump.org
  Subject: Re: [tcpdump-workers] I Can't Capture the Outbound Traffic

	...

  http://itrc.hp.com/ would be one place to start in a search for the most
  up-to-date patches for DLPI and the lan driver(s) used on your system (I
  cannot guess because 9000/800 is too generic - one hs to use the "model"
  command these days and/or an ioscan command (see manpage) to guess what
  the drivers (btlan[3456], gelan, etc) might be involved in addition to
  DLPI.

  Another option is to upgrade to 11i as outbound promiscuous mode support
  is there in the base OS, no patches required.

Another posting:

	http://groups.google.com/groups?selm=7d6gvn%24b3%241%40ocean.cup.hp.com

indicates that you need to install the optional STREAMS product to do
captures on HP-UX 9.x:

  Newsgroups: comp.sys.hp.hpux
  Subject:  Re: tcpdump HP/UX 9.x
  Date: 03/22/1999
  From: Rick Jones <foo@bar.baz>

  Dave Barr (barr@cis.ohio-state.edu) wrote:
  : Has anyone ported tcpdump (or something similar) to HP/UX 9.x?

  I'm reasonably confident that any port of tcpdump to 9.X would require
  the (then optional) STREAMS product.  This would bring DLPI, which is
  what one uses to access interfaces in promiscuous mode.

  I'm not sure that HP even sells the 9.X STREAMS product any longer,
  since HP-UX 9.X is off the pricelist (well, maybe 9.10 for the old 68K
  devices).

  Your best bet is to be up on 10.20 or better if that is at all
  possible.  If your hardware is supported by it, I'd go with HP-UX 11.
  If you want to see the system's own outbound traffic, you'll never get
  that functionality on 9.X, but it might happen at some point for 10.20
  and 11.X.

  rick jones

(as per other messages cited here, the ability to see the system's own
outbound traffic did happen).

Rick Jones reports that HP-UX 11i needs no patches for outbound
promiscuous mode support.

An additional note, from Jost Martin, for HP-UX 10.20:

	Q: How do I get ethereral on HPUX to capture the _outgoing_ packets
	   of an interface
	A: You need to get PHNE_20892,PHNE_20725 and PHCO_10947 (or
	   newer, this is as of 4.4.00) and its dependencies.  Then you can
	   enable the feature as descibed below:

	Patch Name: PHNE_20892
	Patch Description: s700 10.20 PCI 100Base-T cumulative patch
		To trace the outbound packets, please do the following
		to turn on a global promiscuous switch before running
		the promiscuous applications like snoop or tcpdump:

		adb -w /stand/vmunix /dev/mem
		lanc_outbound_promisc_flag/W 1
		(adb will echo the result showing that the flag has
		been changed)
		$quit
	(Thanks for this part to HP-support, Ratingen)

		The attached hack does this and some security-related stuff
	(thanks to hildeb@www.stahl.bau.tu-bs.de (Ralf Hildebrandt) who
	posted the security-part some time ago)

		 <<hack_ip_stack>>

		(Don't switch IP-forwarding off, if you need it !)
		Install the hack as /sbin/init.d/hacl_ip_stack (adjust
	permissions !) and make a sequencing-symlink
	/sbin/rc2.d/S350hack_ip_stack pointing to this script.
		Now all this is done on every reboot.

According to Rick Jones, the global promiscuous switch also has to be
turned on for HP-UX 11.00, but not for 11i - and, in fact, the switch
doesn't even exist on 11i.

Here's the "hack_ip_stack" script:

-----------------------------------Cut Here-------------------------------------
#!/sbin/sh
#
# nettune:  hack kernel parms for safety

OKAY=0
ERROR=-1

# /usr/contrib/bin fuer nettune auf Pfad
PATH=/sbin:/usr/sbin:/usr/bin:/usr/contrib/bin
export PATH


##########
#  main  #
##########

case $1 in
   start_msg)
      print "Tune IP-Stack for security"
      exit $OKAY
      ;;

   stop_msg)
      print "This action is not applicable"
      exit $OKAY
      ;;

   stop)
      exit $OKAY
      ;;

   start)
      ;;  # fall through

   *)
      print "USAGE: $0 {start_msg | stop_msg | start | stop}" >&2
      exit $ERROR
      ;;
   esac

###########
#  start  #
###########

#
# tcp-Sequence-Numbers nicht mehr inkrementieren sondern random
# Syn-Flood-Protection an
# ip_forwarding aus
# Source-Routing aus
# Ausgehende Packets an ethereal/tcpdump etc.

/usr/contrib/bin/nettune -s tcp_random_seq 2 || exit $ERROR
/usr/contrib/bin/nettune -s hp_syn_protect 1 || exit $ERROR
/usr/contrib/bin/nettune -s ip_forwarding 0 || exit $ERROR
echo 'ip_block_source_routed/W1' | /usr/bin/adb -w /stand/vmunix /dev/kmem || exit $ERROR
echo 'lanc_outbound_promisc_flag/W 1' | adb -w /stand/vmunix /dev/mem  || exit $ERROR

exit $OKAY
-----------------------------------Cut Here-------------------------------------

In order for libpcap to be able to capture packets on a Linux system,
the "packet" protocol must be supported by your kernel.  If it is not,
you may get error messages such as

	modprobe: can't locate module net-pf-17

in "/var/adm/messages", or may get messages such as

	socket: Address family not supported by protocol

from applications using libpcap.

You must configure the kernel with the CONFIG_PACKET option for this
protocol; the following note is from the Linux "Configure.help" file for
the 2.0[.x] kernel:

	Packet socket
	CONFIG_PACKET
	  The Packet protocol is used by applications which communicate
	  directly with network devices without an intermediate network
	  protocol implemented in the kernel, e.g. tcpdump. If you want them
	  to work, choose Y.

	  This driver is also available as a module called af_packet.o ( =
	  code which can be inserted in and removed from the running kernel
	  whenever you want). If you want to compile it as a module, say M
	  here and read Documentation/modules.txt; if you use modprobe or
	  kmod, you may also want to add "alias net-pf-17 af_packet" to
	  /etc/modules.conf.

and the note for the 2.2[.x] kernel says:

	Packet socket
	CONFIG_PACKET
	  The Packet protocol is used by applications which communicate
	  directly with network devices without an intermediate network
	  protocol implemented in the kernel, e.g. tcpdump. If you want them
	  to work, choose Y. This driver is also available as a module called
	  af_packet.o ( = code which can be inserted in and removed from the
	  running kernel whenever you want). If you want to compile it as a
	  module, say M here and read Documentation/modules.txt.  You will
	  need to add 'alias net-pf-17 af_packet' to your /etc/conf.modules
	  file for the module version to function automatically.  If unsure,
	  say Y.

In addition, there is an option that, in 2.2 and later kernels, will
allow packet capture filters specified to programs such as tcpdump to be
executed in the kernel, so that packets that don't pass the filter won't
be copied from the kernel to the program, rather than having all packets
copied to the program and libpcap doing the filtering in user mode.

Copying packets from the kernel to the program consumes a significant
amount of CPU, so filtering in the kernel can reduce the overhead of
capturing packets if a filter has been specified that discards a
significant number of packets.  (If no filter is specified, it makes no
difference whether the filtering isn't performed in the kernel or isn't
performed in user mode. :-))

The option for this is the CONFIG_FILTER option; the "Configure.help"
file says:

	Socket filtering
	CONFIG_FILTER
	  The Linux Socket Filter is derived from the Berkeley Packet Filter.
	  If you say Y here, user-space programs can attach a filter to any
	  socket and thereby tell the kernel that it should allow or disallow
	  certain types of data to get through the socket. Linux Socket
	  Filtering works on all socket types except TCP for now. See the text
	  file linux/Documentation/networking/filter.txt for more information.
	  If unsure, say N.

Note that, by default, libpcap will, if libnl is present, build with it;
it uses libnl to support monitor mode on mac80211 devices.  There is a
configuration option to disable building with libnl, but, if that option
is chosen, the monitor-mode APIs (as used by tcpdump's "-I" flag, and as
will probably be used by other applications in the future) won't work
properly on mac80211 devices.

Linux's run-time linker allows shared libraries to be linked with other
shared libraries, which means that if an older version of a shared
library doesn't require routines from some other shared library, and a
later version of the shared library does require those routines, the
later version of the shared library can be linked with that other shared
library and, if it's otherwise binary-compatible with the older version,
can replace that older version without breaking applications built with
the older version, and without breaking configure scripts or the build
procedure for applications whose configure script doesn't use the
pcap-config script if they build with the shared library.  (The build
procedure for applications whose configure scripts use the pcap-config
script if present will not break even if they build with the static
library.)

Statistics:
Statistics reported by pcap are platform specific.  The statistics
reported by pcap_stats on Linux are as follows:

2.2.x
=====
ps_recv   Number of packets that were accepted by the pcap filter
ps_drop   Always 0, this statistic is not gatherd on this platform

2.4.x
=====
ps_recv   Number of packets that were accepted by the pcap filter
ps_drop   Number of packets that had passed filtering but were not
          passed on to pcap due to things like buffer shortage, etc.
          This is useful because these are packets you are interested in
          but won't be reported by, for example, tcpdump output.

As with other systems using BPF, Mac OS X allows users with read access
to the BPF devices to capture packets with libpcap and allows users with
write access to the BPF devices to send packets with libpcap.

On some systems that use BPF, the BPF devices live on the root file
system, and the permissions and/or ownership on those devices can be
changed to give users other than root permission to read or write those
devices.

On newer versions of FreeBSD, the BPF devices live on devfs, and devfs
can be configured to set the permissions and/or ownership of those
devices to give users other than root permission to read or write those
devices.

On Mac OS X, the BPF devices live on devfs, but the OS X version of
devfs is based on an older (non-default) FreeBSD devfs, and that version
of devfs cannot be configured to set the permissions and/or ownership of
those devices.

Therefore, we supply:

	a "startup item" for older versions of Mac OS X;

	a launchd daemon for Tiger and later versions of Mac OS X;

Both of them will change the ownership of the BPF devices so that the
"admin" group owns them, and will change the permission of the BPF
devices to rw-rw----, so that all users in the "admin" group - i.e., all
users with "Allow user to administer this computer" turned on - have
both read and write access to them.

The startup item is in the ChmodBPF directory in the source tree.  A
/Library/StartupItems directory should be created if it doesn't already
exist, and the ChmodBPF directory should be copied to the
/Library/StartupItems directory (copy the entire directory, so that
there's a /Library/StartupItems/ChmodBPF directory, containing all the
files in the source tree's ChmodBPF directory; don't copy the individual
items in that directory to /Library/StartupItems).  The ChmodBPF
directory, and all files under it, must be owned by root.  Installing
the files won't immediately cause the startup item to be executed; it
will be executed on the next reboot.  To change the permissions before
the reboot, run

	sudo SystemStarter start ChmodBPF

The launchd daemon is the chmod_bpf script, plus the
org.tcpdump.chmod_bpf.plist launchd plist file.  chmod_bpf should be
installed in /usr/local/bin/chmod_bpf, and org.tcpdump.chmod_bpf.plist
should be installed in /Library/LaunchDaemons.  chmod_bpf, and
org.tcpdump.chmod_bpf.plist, must be owned by root.  Installing the
script and plist file won't immediately cause the script to be executed;
it will be executed on the next reboot.  To change the permissions
before the reboot, run

	sudo /usr/local/bin/chmod_bpf

or

	sudo launchctl load /Library/LaunchDaemons/org.tcpdump.chmod_bpf.plist

If you want to give a particular user permission to access the BPF
devices, rather than giving all administrative users permission to
access them, you can have the ChmodBPF/ChmodBPF script change the
ownership of /dev/bpf* without changing the permissions.  If you want to
give a particular user permission to read and write the BPF devices and
give the administrative users permission to read but not write the BPF
devices, you can have the script change the owner to that user, the
group to "admin", and the permissions to rw-r-----.  Other possibilities
are left as an exercise for the reader.

(NOTE: due to a bug in Snow Leopard, if you change the permissions not
to grant write permission to everybody who should be allowed to capture
traffic, non-root users who cannot open the BPF devices for writing will
not be able to capture outgoing packets.)

The following instructions apply if you have a Linux platform and want
libpcap to support the Septel range of passive network monitoring cards
from Intel (http://www.intel.com)

1) Install and build the Septel software distribution by following the
instructions supplied with that package.

2) Configure libcap. To allow the 'configure' script to locate the Septel
software distribution use the '--with-septel' option:

        ./configure --with-septel=DIR

where DIR is the root of the Septel software distribution, for example
/var/src/septel.

By default (if you write only ./configure --with-septel) it takes
./../septel as argument for DIR.

If the Septel software is correctly detected 'configure' will
report:

        checking whether we have Septel API... yes

If 'configure' reports that there is no Septel API, the directory may have been
incorrectly specified or the Septel software was not built before configuring
libpcap.

See also the libpcap INSTALL.txt file for further libpcap configuration
options.

Building libpcap at this stage will include support for both the native
packet capture stream and for capturing from Septel cards.  To build
libpcap with only Septel support specify the capture type as 'septel'
when configuring libpcap:

        ./configure --with-septel=DIR --with-pcap=septel

Applications built with libpcap configured in this way will only detect Septel
cards and will not capture from the native OS packet stream.

Note: As mentioned in pcap-septel.c we should first edit the system.txt
file to change the user part example (UPE) module id to 0xdd instead of
0x2d for technical reason.  So this change in system.txt is crutial and
things will go wrong if it's not done.  System.txt along with config.txt
are configuration files that are edited by the user before running the
gctload program that uses these files for initialising modules and
configuring parameters.

----------------------------------------------------------------------
for more information please contact me : gil_hoyek@hotmail.com

The following instructions apply if you have a Linux platform and want
libpcap to support the 'ACN' WAN/LAN router product from from SITA
(http://www.sita.aero)

This might also work on non-Linux Unix-compatible platforms, but that
has not been tested.

See also the libpcap INSTALL.txt file for further libpcap configuration
options.

These additions/extensions have been made to PCAP to allow it to
capture packets from a SITA ACN device (and potentially others).

To enable its support you need to ensure that the distribution has
a correct configure.in file; that can be created if neccessay by
using the normal autoconf procedure of:

aclocal
autoconf
autoheader
automake

Then run configure with the 'sita' option:

./configure --with-sita

Applications built with libpcap configured in this way will only detect SITA
ACN interfaces and will not capture from the native OS packet stream.

The SITA extension provides a remote datascope operation for capturing
both WAN and LAN protocols.  It effectively splits the operation of
PCAP into two halves.  The top layer performs the majority of the
work, but interfaces via a TCP session to remote agents that
provide the lower layer functionality of actual sniffing and
filtering. More detailed information regarding the functions and
inter-device protocol and naming conventions are described in detail
in 'pcap-sita.html'.

pcap_findalldevs() reads the local system's /etc/hosts file looking
for host names that match the format of IOP type devices.  ie.  aaa_I_x_y
and then queries each associated IP address for a list of its WAN and
LAN devices.  The local system the aggregates the lists obtained from
each IOP, sorts it, and provides it (to Wireshark et.al) as the
list of monitorable interfaces.

Once a valid interface has been selected, pcap_open() is called
which opens a TCP session (to a well known port) on the target IOP
and tells it to start monitoring.

All captured packets are then forwarded across that TCP session
back to the local 'top layer' for forwarding to the actual
sniffing program (wireshark...)

Note that the DLT_SITA link-layer type includes a proprietary header
that is documented as part of the SITA dissector of Wireshark and is
also described in 'pcap-sita.html' for posterity sake.

That header provides:
- Packet direction (in/out) (1 octet)
- Link layer hardware signal status (1 octet)
- Transmit/Receive error status (2 octets)
- Encapsulated WAN protocol ID (1 octet)

The following instructions are applicable to Tru64 UNIX
(formerly Digital UNIX (formerly DEC OSF/1)) version 4.0, and
probably to later versions as well; at least some options apply to
Digital UNIX 3.2 - perhaps all do.

In order to use kernel packet filtering on this system, you have
to configure it in such a way:

Kernel configuration
--------------------

The packet filtering kernel option must be enabled at kernel
installation.  If it was not the case, you can rebuild the kernel with
"doconfig -c" after adding the following line in the kernel
configuration file (/sys/conf/<HOSTNAME>):

	option PACKETFILTER

or use "doconfig" without any arguments to add the packet filter driver
option via the kernel option menu (see the system administration
documentation for information on how to do this).

Device configuration
--------------------

Devices used for packet filtering must be created thanks to
the following command (executed in the /dev directory):

	./MAKEDEV pfilt

Interface configuration
-----------------------

In order to capture all packets on a network, you may want to allow
applications to put the interface on that network into "local copy"
mode, so that tcpdump can see packets sent by the host on which it's
running as well as packets received by that host, and to put the
interface into "promiscuous" mode, so that tcpdump can see packets on
the network segment not sent to the host on which it's running, by using
the pfconfig(1) command:

	pfconfig +c +p <network_device>

or allow application to put any interface into "local copy" or
"promiscuous" mode by using the command:

	pfconfig +c +p -a

Note: all instructions given require root privileges.