BPFMON(8)

💖 BPFMON 💖

okay bestie, gather round, because this one is so cool. bpfmon — BPF based visual packet rate monitor 🦋

---

✨ SYNOPSIS ✨

no cap, here's exactly how you call her:

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>

---

🌸 DESCRIPTION 🌸

so like, bpfmon (just like tcpdump) uses a BPF filter to pick out which packets match. but here's the ✨twist✨: with tcpdump it's easy to see which packets matched — with bpfmon you see how much the matched packets are, in terms of bytes per second and packets per second. it's giving data, not drama. 💅

bpfmon shows you that info in a pseudo-graphical text interface, built for modern terminals. but she's versatile, okay? she also supports non-interactive pure ASCII display. range. 👑

plus — and this is the part that ate — instead of monitoring packets that match a BPF filter, bpfmon can pull its data from an iptables/ip6tables rule (on Linux systems). yes really.

bpfmon also supports getting its data from a custom script. the script can be simple and give you just a single counter pair, OR it can be fancy and let you pick from multiple different counter pairs via a selection dialog. it's giving choose-your-own-adventure 🎀

When it's 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 those first two values get read, bestie. bpfmon treats them as cumulative totals and shows you the difference between successive readings — so the script has to report monotonically increasing counters, not instantaneous rates. the first value shows up as the packets-per-second figure and the second as the bytes-per-second figure. the very first reading just sets a baseline 🧚, and if a counter decreases between two readings (say the underlying counter got reset) then 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 figures out whether a script supports multiple counters by first running it with bpfmon-list as its only argument. every script gets invoked this way at startup, so if your script inspects its argument it must recognise or ignore bpfmon-list (the simple example above ignores its arguments, lowkey iconic of it). 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>

then bpfmon knows the script supports multiple counter pairs and lets the user bring up 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 get 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. periodt.

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. and if you run it with no arguments at all? bpfmon will display its version and command line help. so helpful, so demure 🫶

---

⭐ OPTIONS ⭐

• -a — use ASCII drawing characters
• -u — use UTF-8 drawing characters
• -t — use no interface (simple text output)
• -z — use horizontal full-screen interface
• -v — use vertical full-screen interface
• -I — show history in vertical full-screen
• -i — hide history in vertical full-screen
• -L — show legend in vertical full-screen
• -l — hide legend in vertical full-screen
• -n — show interface white on black
• -N — show interface inverse (black on white)
• -h — show usage information and exit

---

🎀 KEYBOARD SHORTCUTS 🎀

these are your hot keys, bestie. memorize them, they're the vibe check:

• h, H, ? — toggle help screen
• a, A — switch to ASCII drawing chars
• u, U — switch to UTF-8 drawing chars
• m, M — toggle horizontal/vertical mode
• i, I — toggle history in vertical mode
• l, L — toggle legend in vertical mode
• n, N — toggle inverse mode
• z, Z — zero history and restart
• s, S — iptables rule select
• 6 — ip6tables rule select
• c — custom counter select
• r, R, Ctrl-L — refresh screen
• q, Q, Ctrl-C — exit

ngl, Ctrl+C and Ctrl+L are doing so much heavy lifting here. main character energy fr fr. 😭

---

🦋 SEE ALSO 🦋

tcpdump(8), bpf(4), pcap-filter(7) iptables(8),

---

👑 AUTHOR 👑

The bpfmon program was written by Boian Bonev from 2014 to 2025. twenty-eleven years of slay, honestly.

This manual page was written by Boian Bonev for the Debian project and is placed in the public domain. ✨

---

okay that's the whole thing, bestie 💖 you just read the BPFMON(8) page from the System Manager's Manual, dated July 29, 2026. go forth and monitor those packet rates. no cap, you're gonna be so good at this 🌈💅🍓