bmon(8)

🦋 NAME 🦋

okay so bestie, meet bmon — it's a bandwidth monitor and rate estimator, and it hangs out in section 8 of the manual so everyone calls it bmon(8). no cap, that's literally the whole name. 💅

---

✨ SYNOPSIS ✨

bmon [--show-all] [--use-si] [--input=MODULE] [--output=MODULE]
[OPTIONS...]

---

🌸 DESCRIPTION 🌸

so like, bmon is a monitoring and debugging tool whose whole vibe is capturing networking-related statistics and then presenting them in a way that actual humans can read. it's giving "I got you, bestie." 🫶

it comes with various output methods, including an interactive curses user interface and a programmable text output that you can script with. iconic honestly.

---

💖 OPTIONS 💖

• -h, --help — prints a short help text and then dips out. bye! 👋
• -V, --version — prints the versioning identifier and exits. show me your ID bestie 🪪
• -i, --input=MODULE[:OPTIONS][,MODULE...] — sets the list of input modules to load and use. you can run multiple modules in parallel, lowkey multitasking queen. bmon will automatically load a useful and working input module by default. peek at INPUT MODULES for the full tea.
• -o, --outputMODULE[:OPTIONS][,MODULE...] — sets the list of output modules to load and use. multiple modules can run at the same time. by default bmon uses the curses output mode, and if that's not available because your console is incompatible, it falls back to a simple text mode. see OUTPUT MODULES for more.
• -U, --use-si — uses the SI unit system, meaning 1KB = 1'000 bytes instead of 1KB = 1'024 bytes. metric girlies rise 🙈
• -f, --configfile=FILE — sets an alternative path to the configuration file.
• -p, --policy=POLICY — sets the policy that defines which network interfaces get displayed. details live in INTERFACE SELECTION.
• -a, --show-all= — displays all interfaces, even the ones that are administratively down. no interface left behind fr fr.
• -r, --read-interval=FLOAT — sets the interval in seconds in which input modules read statistics from their source. the default is 1.0 seconds.
• -R, --rate-interval=FLOAT — sets the interval in seconds in which the rate per counter is calculated. the default is 1.0 seconds.
• -b, --use-bit — shows rates in bits per second instead of bytes per second. bits girlies, I see you ✨
• -L, --lifetime=FLOAT — sets the lifetime of an element in seconds before it's no longer displayed without receiving any statistical updates. the default is 30 seconds.

---

🔥 INPUT MODULES 🔥

input modules are the ones serving the data. they provide statistical data about elements. each element consists of attributes which represent a counter, a rate, or a percentage. elements can also carry additional child elements to represent a hierarchy — it's giving family tree 🧚. every element is assigned to a group defined by the input module. and input modules get polled at the frequency of the configured read interval.

here's the lineup of available input modules:

• netlink — uses the Netlink protocol to collect interface and traffic control statistics from the kernel. this is the default input module, main character energy 👑
• proc — reads interface statistics from the /proc/net/dev file. this is considered a legacy interface and is provided for backwards compatibility reasons. it's the fallback module if the Netlink interface isn't available.
• dummy — a programmable input module, made for debugging and testing purposes.
• null — no data collected. it's giving "I'm just here" 💀

wanna get more info about a module? run it with the "help" option set, like this:

bmon -i netlink:help

and see MODULE CONFIGURATION for more details.

---

💜 OUTPUT MODULES 💜

output modules display or export the statistical data that input modules collected. multiple output modules can run at the same time. heads up though — bmon will not prevent possible conflicts, such as multiple output modules writing to the console. so like, play nice. 😭

the output modules that exist:

• curses — an interactive curses-based text user interface providing real time rate estimations and a graphical representation of each attribute. press '?' to display the quick reference guide. this is the default output mode. the moment ✨
• ascii — simple programmable text output intended for human consumption. it can print a list of interfaces, detailed counters, and graphs to the console. this is the default fallback output mode if curses isn't available.
• format — a fully scriptable output mode intended for consumption by other programs. see the module help text for additional information.
• null — disables output. silence, but make it fashion 💅

to receive additional information about a module, run it with the "help" option set like this:

bmon -o curses:help

see MODULE CONFIGURATION for more details.

---

🎀 MODULE CONFIGURATION 🎀

the syntax to configure modules goes like this:

ARGUMENT ::= mod1[:OPTS][,mod2[:OPTS]...]
OPTS     ::= OPTION[;OPTION...]
OPTION   ::= option[=value]

run a module with the option "help" to get the list of options for each module:

bmon -i module:help

---

🌈 INTERFACE SELECTION 🌈

the following syntax defines the interface selection policy:

SELECTION ::= NAME[,NAME[,...]]
NAME      ::= [!]interface

the interface name may contain the character '*', which acts as a wildcard and represents any number of any character type — like eth*, h*0, ... you get it bestie, it's a glow-up for globbing ✨

examples:

lo,eth0,eth1
eth*,!eth0

---

⭐ EXAMPLES ⭐

to run bmon in curses mode monitoring the interfaces eth0 and eth1:

bmon -p eth0,eth1 -o curses

to run bmon in format mode, monitoring any eth* interfaces, with a specified format string:

bmon -p 'eth*' -o format:fmt='$(element:name)
$(attr:rxrate:packets)\n'

---

🍓 FILES 🍓

• /etc/bmon.conf
• $HOME/.bmonrc

---

👑 SEE ALSO 👑

• ip(8)
• netstat(8)
• ifconfig(8)
• netlink(7)

---

💌 AUTHOR 💌

Thomas Graf <tgraf@suug.ch> among others 🫶

---

and that's the whole page bestie!! this one came from the Bandwidth Monitor era of bmon, and yeah, it's bmon(8) all day. go monitor some bandwidth, you got this 💖🌸🦋