1*6f9cba8fSJoseph Mingrone# LIBPCAP 1.x.y by [The Tcpdump Group](https://www.tcpdump.org) 2*6f9cba8fSJoseph Mingrone 3*6f9cba8fSJoseph Mingrone**To report a security issue please send an e-mail to security@tcpdump.org.** 457e22627SCy Schubert 557e22627SCy SchubertTo report bugs and other problems, contribute patches, request a 6*6f9cba8fSJoseph Mingronefeature, provide generic feedback etc please see the 7*6f9cba8fSJoseph Mingrone[guidelines for contributing](CONTRIBUTING.md). 857e22627SCy Schubert 9*6f9cba8fSJoseph MingroneThe [documentation directory](doc/) has README files about specific 10*6f9cba8fSJoseph Mingroneoperating systems and options. 1157e22627SCy Schubert 1257e22627SCy SchubertAnonymous Git is available via: 1357e22627SCy Schubert 14*6f9cba8fSJoseph Mingrone https://github.com/the-tcpdump-group/libpcap.git 1557e22627SCy Schubert 1657e22627SCy SchubertThis directory contains source code for libpcap, a system-independent 1757e22627SCy Schubertinterface for user-level packet capture. libpcap provides a portable 1857e22627SCy Schubertframework for low-level network monitoring. Applications include 1957e22627SCy Schubertnetwork statistics collection, security monitoring, network debugging, 2057e22627SCy Schubertetc. Since almost every system vendor provides a different interface 2157e22627SCy Schubertfor packet capture, and since we've developed several tools that 2257e22627SCy Schubertrequire this functionality, we've created this system-independent API 2357e22627SCy Schubertto ease in porting and to alleviate the need for several 2457e22627SCy Schubertsystem-dependent packet capture modules in each application. 2557e22627SCy Schubert 26*6f9cba8fSJoseph Mingrone```text 27*6f9cba8fSJoseph Mingroneformerly from Lawrence Berkeley National Laboratory 28*6f9cba8fSJoseph Mingrone Network Research Group <libpcap@ee.lbl.gov> 29*6f9cba8fSJoseph Mingrone ftp://ftp.ee.lbl.gov/old/libpcap-0.4a7.tar.Z 30*6f9cba8fSJoseph Mingrone``` 31*6f9cba8fSJoseph Mingrone 32*6f9cba8fSJoseph Mingrone### Support for particular platforms and BPF 33*6f9cba8fSJoseph MingroneFor some platforms there are `README.{system}` files that discuss issues 3457e22627SCy Schubertwith the OS's interface for packet capture on those platforms, such as 3557e22627SCy Schuberthow to enable support for that interface in the OS, if it's not built in 3657e22627SCy Schubertby default. 3757e22627SCy Schubert 3857e22627SCy SchubertThe libpcap interface supports a filtering mechanism based on the 3957e22627SCy Schubertarchitecture in the BSD packet filter. BPF is described in the 1993 4057e22627SCy SchubertWinter Usenix paper ``The BSD Packet Filter: A New Architecture for 41*6f9cba8fSJoseph MingroneUser-level Packet Capture'' 42*6f9cba8fSJoseph Mingrone([compressed PostScript](https://www.tcpdump.org/papers/bpf-usenix93.ps.Z), 43*6f9cba8fSJoseph Mingrone[gzipped PostScript](https://www.tcpdump.org/papers/bpf-usenix93.ps.gz), 44*6f9cba8fSJoseph Mingrone[PDF](https://www.tcpdump.org/papers/bpf-usenix93.pdf)). 4557e22627SCy Schubert 4657e22627SCy SchubertAlthough most packet capture interfaces support in-kernel filtering, 4757e22627SCy Schubertlibpcap utilizes in-kernel filtering only for the BPF interface. 4857e22627SCy SchubertOn systems that don't have BPF, all packets are read into user-space 4957e22627SCy Schubertand the BPF filters are evaluated in the libpcap library, incurring 5057e22627SCy Schubertadded overhead (especially, for selective filters). Ideally, libpcap 5157e22627SCy Schubertwould translate BPF filters into a filter program that is compatible 5257e22627SCy Schubertwith the underlying kernel subsystem, but this is not yet implemented. 5357e22627SCy Schubert 5457e22627SCy SchubertBPF is standard in 4.4BSD, BSD/OS, NetBSD, FreeBSD, OpenBSD, DragonFly 55*6f9cba8fSJoseph MingroneBSD, macOS, and Solaris 11; an older, modified and undocumented version 56*6f9cba8fSJoseph Mingroneis standard in AIX. {DEC OSF/1, Digital UNIX, Tru64 UNIX} uses the 57*6f9cba8fSJoseph Mingronepacketfilter interface but has been extended to accept BPF filters 58*6f9cba8fSJoseph Mingrone(which libpcap utilizes). 5957e22627SCy Schubert 6057e22627SCy SchubertLinux has a number of BPF based systems, and libpcap does not support 6157e22627SCy Schubertany of the eBPF mechanisms as yet, although it supports many of the 6257e22627SCy Schubertmemory mapped receive mechanisms. 63*6f9cba8fSJoseph MingroneSee the [Linux-specific README](doc/README.linux) for more information. 6457e22627SCy Schubert 65*6f9cba8fSJoseph Mingrone### Note to Linux distributions and *BSD systems that include libpcap: 6657e22627SCy Schubert 6757e22627SCy SchubertThere's now a rule to make a shared library, which should work on Linux 6857e22627SCy Schubertand *BSD, among other platforms. 6957e22627SCy Schubert 70*6f9cba8fSJoseph MingroneIt sets the soname of the library to `libpcap.so.1`; this is what it 71*6f9cba8fSJoseph Mingroneshould be, **NOT** `libpcap.so.1.x` or `libpcap.so.1.x.y` or something such as 7257e22627SCy Schubertthat. 7357e22627SCy Schubert 7457e22627SCy SchubertWe've been maintaining binary compatibility between libpcap releases for 7557e22627SCy Schubertquite a while; there's no reason to tie a binary linked with libpcap to 7657e22627SCy Schuberta particular release of libpcap. 77