ipband(8)

✨ NAME ✨

ipband — IP bandwidth watchdog 🐕🦺💖

This page is ipband(8), bestie. Buckle up.

---

📜 SYNOPSIS 📜

ipband -aAbcCdfFhJlLmMowPrtTv INTERFACE

---

🌸 DESCRIPTION 🌸

ipband is a pcap-based IP traffic monitor. It tallies per-subnet traffic and bandwidth usage, and the second the traffic for a specific subnet blows past the threshold you set, it starts detailed logging. If traffic stays high for a certain period of time, it generates a report for that subnet — and you can append that report to a file or e-mail it. When bandwidth usage drops back below the threshold, detailed logging for that subnet stops and the memory gets freed. Cleanup era. 🧹✨

This utility is lowkey a lifesaver in a limited-bandwidth WAN environment (frame relay, ISDN, etc. circuits) — like, when certain links get saturated to the point where legit packets start getting dropped, it helps you pinpoint the offending traffic source. 👑

It can also be used to monitor an internet connection when you specify the range of local IP addresses (so you don't fire off reports about networks that aren't yours). No one needs that drama. 🙈

Bandwidth is defined as the total size in kBytes of the layer 2 frames with IP packets passing the specified interface during the averaging period, divided by the number of seconds in that period. Math but make it cute. 🎀

---

💅 COMMAND LINE OPTIONS 💅

• interface — the network interface we're reading data from.
• -a secs — averaging period in seconds, i.e. how often total traffic and bandwidth should be calculated. Default is 60 secs. ⏱️
• -A — include threshold-exceeded accumulated time and percentage in the report. Heads up bestie: this option only works with preloaded subnets (that's the "subnet" directive), because otherwise subnet data gets deleted when bandwidth usage drops below threshold, to clear memory and cut down processing time. So if you don't preload, the data's just... gone. 💀
• -b kBps — bandwidth threshold in kBytes per sec. Default is 7 kBps, i.e. 56 kbps.
• -c filename — use filename as the configuration file. Default is /etc/ipband.conf. Setting a different bandwidth threshold per subnet is only available through the config file — check the subnet directive in the CONFIGURATION FILE section below.
• -C — ignore the configuration file. Not today, config. 🚫
• -d level — debug level. 0 — no debugging; 1 — summary; 2 — subnet statistics; 3 — all packets captured. Default is 0.
• -f filterstr — use filterstr as the pcap filter. See the manual page for tcpdump. Also peep the EXAMPLES section below.
• -F — fork and run in the background. Default is to run in the foreground.
• -h — print help and exit. 🆘
• -J number — packet length adjustment in bytes. Use this when the layer 2 frame sizes for the interface ipband is listening on and the interface you're measuring bandwidth for are different. Example: if you care about bandwidth usage on a router's frame relay interface with 6 bytes overhead (frame header + RFC1490 encapsulation) while ipband is running on an ethernet interface with 14 bytes MAC frame, you could use the value -8 for this option to get a more accurate bandwidth calculation. The number can be a positive or a negative integer. Negative values should not exceed the layer 2 frame size for ipband's interface — so, like, you can't use -15 in the example above. The default is 0.
• -l filename — if the -M option (or the mailto directive in the config file) is set, this specifies the name of the file to be appended to the end of e-mail reports.
• -L ip-range[:ip-range[:ip-range[..]]] — this option says which network numbers should be considered local when collecting data and generating reports (fr, non-local networks aren't logged at all). It can be used instead of the config file's multiple "subnet" directives — but heads up, unlike that directive, there'd be a single bandwidth threshold, specified by the -b option. This option is perfect for monitoring internet connections when you do NOT want reports about someone else's networks. 👀

There can be many ip-ranges separated by colons. No spaces may appear in the argument. Each ip-range can be:

• a single IP address such as 192.168.1.1, which indicates a range of one,
• a partial IP address such as 192.168.1.0, which indicates a range from 192.168.1.0 to 192.168.1.255,
• a low and high IP address separated by a hyphen (-),
• and a single IP address, a slash (/) and an integer between 0 and 32 (a "net address"), which indicates a network.

If you run ipband with the debug option (-d), the program will print the entire list of IP ranges, so you can check their values. Vibe check your ranges, bestie. 🔍

Here's a list of arguments to -L along with the corresponding range:

COMMAND: ipband eth0 -l 137.99.11
RANGE:   137.99.11.0-137.99.11.255

COMMAND: ipband eth0 -L 137.99.11:127.0.5/23
RANGE:   137.99.11.0-137.99.11.255,127.0.4.0-127.0.5.255

COMMAND: ipband eth0 -L 127.1.5.17-127.1.7.131
RANGE:   127.1.5.17-127.1.7.131

• -m maskbits — set number of subnet mask bits (1-32) for subnet traffic aggregation. Default is 24 (255.255.255.0).
• -M email address(es) — send the detailed subnet report to the specified e-mail address(es). Multiple addresses must be separated by comma. 📧
• -o filename — filename to output the detailed subnet report. Default is ipband.txt in the current directory.
• -w filename — HTML report output file. Default is ipband.html in the current directory. The styles.css file can be used in the same directory to customize its look and feel. ✨ (aesthetic customization, we love to see it)
• -P — do not use promiscuous mode on the network interface we're listening on.
• -r secs — reporting period: the number of seconds the bandwidth threshold may be exceeded before it should be reported. Default is 300 seconds.
• -t number — limit the subnet report to a given number of per-host connections with the highest byte count (top connections). Default is no limit.
• -T string — MTA command string for mailing reports. Default is "/usr/sbin/sendmail -t -oi". The string is tokenized and passed directly to exec(), so shell metacharacters are not interpreted. 🔒
• -v — print version and exit.

---

🎀 CONFIGURATION FILE 🎀

On top of the command line options, you can use a configuration file. When ipband starts, it first looks for /etc/ipband.conf. You can also pass '-c' (see OPTIONS above) to specify a configuration file.

The options in the config file are specified by keyword/value pairs. Lines starting with # are ignored. (Comments! We stan. 💬)

Below is a list of config file options:

• interface interface — interface to read packets from.
• promisc {yes/no} — like the -P option, this specifies whether or not to use promiscuous mode on the listening network interface. Promiscuous mode is the default.
• debug {0-3} — like the -d option, specifies the debug level.
• fork {yes/no} — like the -F option, specifies whether or not to run in the background. Default is no.
• filter filterstr — like the -f option, specifies the pcap filter.
• outfile filename — like the -o option, specifies the report file name. Default is ipband.txt in the current directory.
• htmlfile filename — like the -w option, HTML report output file. Default is ipband.html in the current directory. The styles.css file can be used in the same directory to customize its look and feel.
• htmltitle title — HTML title of the report output file.
• bandwidth kBps — like the -b option, bandwidth threshold in kBytes per second. Default is 7.0 kBps.
• average secs — like the -a option, tells ipband the number of seconds to average per-subnet traffic and calculate bandwidth usage. Default is 60 seconds.
• lenadj number — like the -J option, specifies packet length adjustment in bytes.
• report secs — like the -r option, the number of seconds the specified threshold(s) may be exceeded before a report is fired off. Default is 300 secs.
• top number — like the -t option, limits the subnet report to a given number of per-host connections with the highest byte count (top connections). Default is 0 — no limit.
• accumulate {yes/no} — like the -A option, whether or not to include threshold-exceeded accumulated time and percentage in the report. Default is no.
• mailto email address(es) — like the -M option, the e-mail address(es) the detailed subnet report should be sent to. Multiple addresses must be separated by comma.
• mailfoot filename — like the -l option, name of the file to be appended to the end of e-mail reports.
• mtastring string — like the -T option, specifies the MTA command string for mailing reports. Default is "/usr/sbin/sendmail -t -oi".
• maskbits {1-32} — like the -m option, sets the number of network mask bits. Default is 24 (corresponding to subnet mask 255.255.255.0).
• localrange ip_range — like the -L option, determines which range(s) of IP addresses are considered local.
• subnet subnet-ip bandwidth kBps — specifies which subnets ipband should work with and sets individual bandwidth thresholds for them — one subnet option per line (the subnet mask is set by the maskbits option). This option is only available through a configuration file. Setting it limits data collection and reporting to the specified subnets.

---

🌈 EXAMPLES 🌈

ipband eth0 -f net 10.10.0.0/16 -m 24 -a 300 -r 900

Will capture packets from/to IP addresses matching 10.10.0.0/255.255.0.0, tally traffic by the third octet, calculate bandwidth utilization every 5 minutes, and report per host traffic every 15 minutes. ✨

ipband -c ipband.conf

Read configuration from file ipband.conf.

---

💀 BUGS 💀

Report mailing blocks until the pipe to sendmail returns. (Yeah. It just sits there. 😭)

Report any bugs to anevynni@russelmetals.com. Thanks.

---

👑 AUTHOR 👑

Andrew Nevynniy anevynni@russelmetals.com

ipband is based on ipaudit-0.95 by J Rifkin jon.rifkin@uconn.edu (http://www.sp.uconn.edu/~jrifkin).

---

⭐ VERSION ⭐

0.8.1 Jun 13, 2008

---

🦋 SEE ALSO 🦋

tcpdump(1) pcap(3)

---

And that's the whole page, bestie — written by Andrew Nevynniy, dated Jun 13, 2008, and this little manual is ipband(8), so now you're in the group chat. Go watch some bandwidth. 🫶💖