README revision 214518
1214518Srpaulo@(#) $Header: /tcpdump/master/libpcap/README,v 1.34 2008-12-14 19:44:14 guy Exp $ (LBL) 217683Spst 3214518SrpauloLIBPCAP 1.x.y 417683Spst 5190225Srpaulowww.tcpdump.org 675107Sfenner 7190225SrpauloPlease send inquiries/comments/reports to: 8190225Srpaulo tcpdump-workers@lists.tcpdump.org 9190225Srpaulo 10214518SrpauloAnonymous Git is available via: 11214518Srpaulo git clone git://bpf.tcpdump.org/libpcap 1275107Sfenner 13214518SrpauloVersion 1.x.y of LIBPCAP can be retrieved with the CVS tag "libpcap_1_{x}rel{y}": 14214518Srpaulo cvs -d :pserver:tcpdump@cvs.tcpdump.org:/tcpdump/master checkout -r libpcap_1_{x}rel{y} libpcap 1575107Sfenner 16190225SrpauloPlease submit patches against the master copy to the libpcap project on 17190225Srpaulosourceforge.net. 1875107Sfenner 1975107Sfennerformerly from Lawrence Berkeley National Laboratory 2075107Sfenner Network Research Group <libpcap@ee.lbl.gov> 2175107Sfenner ftp://ftp.ee.lbl.gov/libpcap.tar.Z (0.4) 2275107Sfenner 2317683SpstThis directory contains source code for libpcap, a system-independent 2417683Spstinterface for user-level packet capture. libpcap provides a portable 2517683Spstframework for low-level network monitoring. Applications include 2617683Spstnetwork statistics collection, security monitoring, network debugging, 2717683Spstetc. Since almost every system vendor provides a different interface 2817683Spstfor packet capture, and since we've developed several tools that 2917683Spstrequire this functionality, we've created this system-independent API 3017683Spstto ease in porting and to alleviate the need for several 3117683Spstsystem-dependent packet capture modules in each application. 3217683Spst 33127664SbmsFor some platforms there are README.{system} files that discuss issues 34127664Sbmswith the OS's interface for packet capture on those platforms, such as 35127664Sbmshow to enable support for that interface in the OS, if it's not built in 36127664Sbmsby default. 37127664Sbms 3817683SpstThe libpcap interface supports a filtering mechanism based on the 3917683Spstarchitecture in the BSD packet filter. BPF is described in the 1993 4017683SpstWinter Usenix paper ``The BSD Packet Filter: A New Architecture for 41127664SbmsUser-level Packet Capture''. A compressed PostScript version can be 42127664Sbmsfound at 4317683Spst 44127664Sbms ftp://ftp.ee.lbl.gov/papers/bpf-usenix93.ps.Z 4517683Spst 46127664Sbmsor 47127664Sbms 48127664Sbms http://www.tcpdump.org/papers/bpf-usenix93.ps.Z 49127664Sbms 50127664Sbmsand a gzipped version can be found at 51127664Sbms 52127664Sbms http://www.tcpdump.org/papers/bpf-usenix93.ps.gz 53127664Sbms 54127664SbmsA PDF version can be found at 55127664Sbms 56127664Sbms http://www.tcpdump.org/papers/bpf-usenix93.pdf 57127664Sbms 5817683SpstAlthough most packet capture interfaces support in-kernel filtering, 5917683Spstlibpcap utilizes in-kernel filtering only for the BPF interface. 6017683SpstOn systems that don't have BPF, all packets are read into user-space 6117683Spstand the BPF filters are evaluated in the libpcap library, incurring 6217683Spstadded overhead (especially, for selective filters). Ideally, libpcap 6317683Spstwould translate BPF filters into a filter program that is compatible 6417683Spstwith the underlying kernel subsystem, but this is not yet implemented. 6517683Spst 66127664SbmsBPF is standard in 4.4BSD, BSD/OS, NetBSD, FreeBSD, and OpenBSD. DEC 67127664SbmsOSF/1/Digital UNIX/Tru64 UNIX uses the packetfilter interface but has 68127664Sbmsbeen extended to accept BPF filters (which libpcap utilizes). Also, you 69127664Sbmscan add BPF filter support to Ultrix using the kernel source and/or 70127664Sbmsobject patches available in: 7117683Spst 7217683Spst ftp://gatekeeper.dec.com/pub/DEC/net/bpfext42.tar.Z. 7317683Spst 74127664SbmsLinux, in the 2.2 kernel and later kernels, has a "Socket Filter" 75127664Sbmsmechanism that accepts BPF filters; see the README.linux file for 76127664Sbmsinformation on configuring that option. 7717683Spst 78190225SrpauloNote to Linux distributions and *BSD systems that include libpcap: 79190225Srpaulo 80190225SrpauloThere's now a rule to make a shared library, which should work on Linux 81214518Srpauloand *BSD, among other platforms. 82190225Srpaulo 83190225SrpauloIt sets the soname of the library to "libpcap.so.1"; this is what it 84214518Srpauloshould be, *NOT* libpcap.so.1.x or libpcap.so.1.x.y or something such as 85190225Srpaulothat. 86190225Srpaulo 87190225SrpauloWe've been maintaining binary compatibility between libpcap releases for 88190225Srpauloquite a while; there's no reason to tie a binary linked with libpcap to 89190225Srpauloa particular release of libpcap. 90190225Srpaulo 91127664SbmsProblems, bugs, questions, desirable enhancements, etc. should be sent 92190225Srpauloto the address "tcpdump-workers@lists.tcpdump.org". Bugs, support 93190225Srpaulorequests, and feature requests may also be submitted on the SourceForge 94190225Srpaulosite for libpcap at 9575107Sfenner 96127664Sbms http://sourceforge.net/projects/libpcap/ 9775107Sfenner 98127664SbmsSource code contributions, etc. should be sent to the email address 99190225Srpaulosubmitted as patches on the SourceForge site for libpcap. 100127664Sbms 101127664SbmsCurrent versions can be found at www.tcpdump.org, or the SourceForge 102127664Sbmssite for libpcap. 103127664Sbms 10475107Sfenner - The TCPdump team 105