bpfmon - Man Page

BPF based visual packet rate monitor

Synopsis

bpfmon

bpfmon [-autzvIiLlnNh] <device> '<bpf_filter_code>'

bpfmon [-autzvIiLlnNh] iptables '[<table>] <chain> <rulenum>'

bpfmon [-autzvIiLlnNh] iptables [select]

bpfmon [-autzvIiLlnNh] ip6tables '[<table>] <chain> <rulenum>'

bpfmon [-autzvIiLlnNh] ip6tables [select]

bpfmon [-autzvIiLlnNh] custom <path-to-binary>

bpfmon (like tcpdump) uses BPF filter to select packets that match the filter. While with tcpdump it is easy to see what packets match the filter, bpfmon shows how much are the matched packets in terms of bytes per second and packets per second.

bpfmon displays the information in pseudo-graphical text interface, developed for modern terminals, but it also supports non-interactive pure ASCII display.

In addition, bpfmon allows instead of monitoring packets matching a BPF filter to get its data from an iptables/ip6tables rule (on Linux systems).

bpfmon also supports fetching the data from a custom script. The script may be simple and provide only a single counter pair or a more complex one that allows selecting from multiple different counter pairs by using a selection dialog.

When called to produce data, the script must print to standard output two whitespace-separated non-negative integers on a single line: the packet counter first and the byte counter second. Only these first two values are read. bpfmon treats them as cumulative totals and displays the difference between successive readings, so the script must report monotonically increasing counters rather than instantaneous rates; the first value is shown as the packets-per-second figure and the second as the bytes-per-second figure. The first reading only establishes a baseline, and if a counter decreases between two readings (for example because the underlying counter was reset) that interval is shown as zero.

Example simple script to show incoming packets on the lo interface (this is a Linux example; it prints the packet count followed by the byte count):

#!/bin/sh
grep lo: /proc/net/dev|awk '{print $3" "$2}'

bpfmon detects whether the script supports multiple counters by first executing it with bpfmon-list as its only argument. Every script is invoked this way at startup, so a script that inspects its argument must recognise or ignore bpfmon-list (the simple example above ignores its arguments). If the first non-empty line of that output is exactly #bpfmon-counters, followed by one or more lines like this:

#bpfmon-counters
<argument1> <descripton1>
<argument2> <descripton2>
...
<argumentN> <descriptonN>

that will let bpfmon know that the script supports multiple counter pairs and allow the user to invoke a selection dialog. On each line the argument and its description are separated by the first space or tab, and any surrounding whitespace is ignored. Lines whose first character is # are treated as comments (so the #bpfmon-counters marker itself and any annotations are skipped), and a line that carries no description is ignored. The #bpfmon-counters marker must be the first non-empty line of the output; otherwise the script is treated as a single-counter one.

A single-counter script is invoked with no argument to fetch its data. For a multi-counter script the first item is automatically selected at startup and the script is called with <argument1>; selecting another entry invokes the script with that entry's argument.

See the c shortcut for how to invoke the selection dialog.

In interactive mode, there are hot keys to display help or modify the mode of operation.

Without any arguments, bpfmon will display its version and command line help.