capstats
BPF-based network statistics

About

Capstats generates byte and packet counters based on a Berkeley Packet Filter (BPF) expression. An overview of the BPF syntax is here.

It is freely available under the terms of the GNU General Public License.

Download

capstats-0.2.tar.gz released 2009-03-13

Installing

To compile capstats, simply type make. You will need libpcap installed on your system, including its header files. Headers are usually in a separate package. For example, on debian-based systems you will need install both libpcap0.8 and libpcap0.8-dev.

After compiling, a single binary is generated: capstats. Copy this to a suitable location on your system, for example /usr/local/bin.

Capstats was written and tested on linux. It may not work properly on other unix-based systems. The kernel packet capture interfaces used by libpcap appears to have significant differences between systems, and the access control method (SCM_CREDENTIALS) used to verify the capstats client may not be 100% portable as implemented. Patches to make capstats work on other systems are welcome.

Using

The basic model is that you run capstats as a daemon (as root), and it will then take commands from a client. Using a client, you can create new capture sessions, modify them, pull up stats on running sessions, and so on.

Currently, the system consists of just one binary, which has both daemon and client modes.

Daemon mode

Run capstats with the -d option to start the daemon 
capstats -d
It will create a unix socket /var/run/capstats, on which it will accept client connections. When started this way, the daemon will only accept client connections from root; to make it accept connections from other users, start the daemon with 
capstats -d -g <group>
where <group> is the name (or gid) of a group from which the daemon should accept connections.

Client mode

The client is used to pass commands to the daemon. The syntax for using the capstats binary as a client is simply 
capstats <command>
The following commands are defined:

new <session-name> filter <filter>
Start a new session. <session-name> is any string you want to use to identify the capture session. <filter> is a BPF-compliant filter string to use. See here for BPF syntax.

modify <session-name> <filter>
Modify the named session to use a new filter.

stop <session-name>
Stop the named session.

list
List all the running sessions.

show <session-name>
Show information about the named session.

poll <session-name>
Output statistics for the named session.

watch <session-name> frequency <seconds>
Output statistics for the named session every given interval (interrupt with ctrl-c).

Capstats may also be invoked with the -D option to show some debugging output.

Author

Capstats was written by Bert Vermeulen. Feedback and patches are welcome.