README.ring
To build this thing from absolute scratch:
1. rm -rf config
2. sh bootstrap
y
3. Peruse .warrantee
4. ./configure ...
5. make
To further understand:
Please read README.linux first. This README describes an additional
mechanism, using shared memory ring buffers first implimented in the linux
kernel by Alexey Kuznetsov as a patch to the 2.2.x kernel and a kernel
configuration option (CONFIG_PACKET_MMAP) in the 2.4.x kernel. The
original source for the modifications to the LBL libpcap package was made
available by Alexey sometime around March of 1999.
Note: This version of linux pcap supports the nonblock features and the "any"
interface(s)
Note: Versions of libpcap based on tcpdump.org 0.8 have been changed in regard
to the "to_ms" argument to pcap_open_live. Here is how it is used:
1. With a positive timeout (initialized by the to_ms value on each
call to pcap_read), a "read" will return if either
a. enough polls have been called to exhaust the timeout value,
or
b. the timeout expires even if no packets have been received.
2. With a zero timeout, a "pcap_read" will never return. The timeout is
considered infinite. Of course callbacks will continue for each packet
that arrives. And the PCAP_TIMEOUT environment variable can be used
to signal an error of ETIMEDOUT.
3. With a value of -1, "pcap_read" will return if either
a. there are no packets on the ring,
or
b. the packets that have been queued on the ring have all been
processed. In otherwords, it is non-blocking. The recommended
'non blocking' mechanism is to use 'pcap_setnonblock' and
'pcap_getnonblock' to set/unset or retrieve the blocking/nonblocking
state. In otherwords, calling pcap_setnonblock is equivalent to
calling pcap_open_live with to_ms == -1.
The current linux libpcap implimentation relies heavily on Alexey's code.
However, any problems should be reported to cornett@arpa.net who is responsible
for this linux library implimentation. Every effort was made to make the
changes available to libpcap dependent applications without their having to
be recompiled. If the application (tcpdump for example) was built with
shared libraries in mind, then there should be no problem installing the
mmap libpcap in the usual place (/usr/lib), and availing yourself of the
ring buffer option. How could this be?
There are a number of ways a libpcap based application can be coerced into using
the ring buffer:
1. If shared libraries are being used by the application, then you can set
an environment variable to clue pcap_open_live to go the ring route:
# PCAP_FRAMES=max tcpdump -i eth1 ...
Note: setting PCAP_FRAMES to max actually sets the size of the ring
buffer to 32768 (0x8000) which appears to be the maximum number
of iovecs the kernel can handle. You need memory for this. For
32,768 frame ring buffer with 1530 bytes per frame (ethernet
mtu + frame overhead + 16), tcpdump will tie up at around 51 Mbytes
for the ring buffer alone.
Other environment variables include:
PCAP_SNAPLEN think tcpdump -s
PCAP_PROMISC -1 = promiscous -2 = not promiscuous
PCAP_TO_MS variable meanings, think milliseconds(ms) to wait for pkt,
or how long to loop reading packets and calling the user
supplied callback.
PCAP_RAW 2 = cooked mode
PCAP_PROTO ip,ipv6,arp,rarp,802.2,802.3,lat,dec,atalk,aarp,ipx,x25
PCAP_MADDR requires hex string which will override PCAP_PROMISC
PCAP_FRAMES greater than 0 up to 32768, "max" is equiv to 32768
PCAP_MEMORY better than PCAP_FRAMES. Give it some number of K bytes
like PCAP_MEMORY=3000000 if you have 3 Gigs available.
This will give you a ring buffer for about 1.9 million
packets. Gotta pay for that memory though.
PCAP_VERBOSE print informative messages, since old app doesn't see them.
PCAP_STATS print pcap statistics to stderr every PCAP_PERIOD ms.
Stats will also be printed whenever pcap_read, pcap_dispatch,
and pcap_loop return to the calling program.
PCAP_TIMEOUT return errno "ETIMEDOUT" when packet time is greater than
value provided (eg PCAP_TIMEOUT=1044406300 will cause
tcpdump to quit on Mon Feb 4 17:51:40 MST 2003).
PCAP_PERIOD milliseconds between stats (will not cause pcap_dispatch
to return, will generate stats).
Note: The format for PCAP_STATS is a 32 bit mask. See pcap-ring.h for
field definitions. If a bit is set in this mask, then the corresonding
value will be printed. The values are separated by a space.
bit 0 is defined to be 0x00000001 so If you wanted to print the
"time" followed by number of packets dropped by the kernel and
seen by the device, you would set PCAP_STATS=0x24
0 Start date and time
1 Packets processed
2 Packets dropped
3 Packets total
4 Packets ignored
5 Packets seen by device (in and out)
6 Bytes seen by device (in and out)
7 Bytes received
8 Number of times poll system call called
9 Current ring buffer index
10 Maximum number of frames pulled from ring before having to poll
11 Specious signal to pull frames from ring
12 Elapsed time between first and last packet seen during sample time
13 Received errors
14 Received drops
15 Transfer errors
16 Transfer drops
17 Multicast packet count (the Packets total includes this number)
By setting PCAP_STATS=0x021fff, the ring statistics line would print
items 0 through 12 and item 17 in that order. I've been known to
use PCAP_STATS=0x21fff.
2. If static libraries are being used the the application will need to be
re-loaded.
3. Or, one can write non-portable libpcap based applications by calling a
linux specific pcap routine called pcap_ring_args which initializes
ebuf prior to calling pcap_open_live as a way of passing in extra ring
related arguments. Not recommended.