bwm-ng: The Ultimate Guide to Live Network Bandwidth Monitoring

Table of Contents#

What is bwm-ng?
Installation
Core Concepts
Basic Usage
Advanced Features
Best Practices for bwm-ng
Troubleshooting Common Issues
Conclusion
References

1. What is bwm-ng?#

bwm-ng is a free, open-source command-line tool designed to monitor real-time network bandwidth and disk I/O usage across all or specific interfaces on a system. It was created by Volker Gropp as a successor to the original bwm tool, with improved support for modern network interfaces, virtualization, and flexible output options.

Key advantages of bwm-ng include:

Lightweight footprint (uses less than 1% CPU in most cases)
Support for physical, virtual, and aggregated interfaces
Disk I/O monitoring via /proc/diskstats, kstat, devstat, IOKit, and libstatgrab
Multiple output formats for interactive monitoring, scripting, and logging (curses, bar-chart curses, plain text, CSV, HTML)
Cross-platform compatibility (Linux, macOS, BSD, Solaris, Windows)
Configuration file support (/etc/bwm-ng.conf, ~/.bwm-ng.conf)
Daemon mode for background logging
No dependencies on heavy monitoring stacks (e.g., Prometheus, Nagios)

2. Installation#

2.1 Debian/Ubuntu-based Systems#

Install via the official package repository:

sudo apt update && sudo apt install bwm-ng

2.2 RHEL/CentOS/Fedora Systems#

For RHEL/CentOS, first enable the EPEL repository:

sudo yum install epel-release
sudo yum install bwm-ng

For Fedora:

sudo dnf install bwm-ng

2.3 macOS#

Use Homebrew to install bwm-ng:

brew install bwm-ng

2.4 Compiling from Source#

To get the latest version (not available in package repositories), compile from source:

# Install dependencies (Debian/Ubuntu)
sudo apt install build-essential libncurses5-dev libstatgrab-dev autoconf automake
 
# Clone the repository (or download a release tarball)
git clone https://github.com/vgropp/bwm-ng.git
cd bwm-ng
 
# Generate the configure script
./autogen.sh
 
# Compile and install
./configure
make
sudo make install

Alternatively, download the latest release tarball from the official site or the GitHub releases page.

3. Core Concepts#

3.1 Monitored Interfaces#

bwm-ng automatically detects all active network interfaces, including:

Physical interfaces: eth0, enp0s3, wlan0
Virtual interfaces: docker0 (Docker bridges), tun0 (VPNs), vlan10 (VLANs)
Loopback: lo (local traffic)

You can filter interfaces using a comma-separated list of exact names with -I. Prefix the list with % to create a blacklist instead of a whitelist (e.g., -I %eth0,tun0 hides eth0 and tun0).

3.2 Input Methods#

bwm-ng supports multiple input methods for gathering data. The default depends on your OS:

Method	Default On	Description
`proc`	Linux	Parses `/proc/net/dev`
`getifaddrs`	BSD, macOS (>=10.3)	Uses the getifaddrs system call
`kstat`	Solaris	Uses the kstat system call
`sysctl`	IRIX, other UNIX	Uses the sysctl system call
`netstat`	Fallback	Backup for systems without the above
`libstatgrab`	Optional	External library; see i-scream.org

For disk I/O monitoring, bwm-ng uses disk (Linux /proc/diskstats), kstatdisk (Solaris), devstat (FreeBSD), ioservice (macOS IOKit), and libstatdisk (libstatgrab).

You can switch input methods at runtime in curses mode by pressing n.

3.3 Key Metrics#

bwm-ng tracks the following metrics per interface:

Bytes/Seconds: Total data transmitted/received in bytes per second
Bits/Seconds: Data rate converted to bits per second (ideal for internet speed measurements)
Packets/Seconds: Number of packets sent/received per second
Errors/Seconds: Number of transmission errors (e.g., dropped packets, CRC errors)
Total: The combined current rate of both transmitted and received data (In + Out)

You can cycle through these units at runtime by pressing u.

3.4 Output Modes#

bwm-ng supports multiple output modes to suit different use cases:

Curses (Default): Interactive terminal interface with real-time updates and keyboard shortcuts
Curses2: Bar-chart visualization of current I/O using curses output
Plain Text: Non-interactive output for scripting or piping to other tools
CSV: Comma-separated values for logging and spreadsheet analysis
HTML: Generates an HTML table of current metrics, suitable for embedding into a web page

4. Basic Usage#

4.1 Default Monitoring#

Start bwm-ng with the default curses interface to view all active interfaces:

bwm-ng

4.2 Keyboard Shortcuts#

In curses mode, bwm-ng supports the following keyboard shortcuts:

h: Show help
q: Quit
+ / -: Increase/decrease refresh interval by 100ms
u: Cycle units (bytes, bits, packets, errors)
n: Cycle input methods
t: Cycle stat types (current rate, max, sum, 30-second average)
a: Cycle interface display (all, only up, only up and not hidden)
s: Toggle whether hidden interfaces are included in totals
k / d: Switch between KB and dynamic auto-assigned units (Byte/KB/MB/GB)

4.3 Selecting Specific Interfaces#

Use the -I flag to monitor only the interfaces you care about (whitelist):

# Monitor eth0 and wlan0
bwm-ng -I eth0,wlan0
 
# Monitor specific Docker virtual interfaces (use exact names)
# bwm-ng -I docker0,docker1

To blacklist specific interfaces instead, prefix the list with %:

# Hide eth0 and tun0 from output
bwm-ng -I %eth0,tun0

4.4 Adjusting Units and Refresh Intervals#

Switch units: Use -u to toggle between bytes, bits, packets, or errors:

# Display rates in bits per second (common for internet speed)
bwm-ng -u bits

Set refresh interval: Use -t (or --timeout) to specify how often metrics are updated (in milliseconds):
```
# Refresh every 2 seconds (default is 500 milliseconds)
bwm-ng -t 2000
```

Combine both options:

bwm-ng -u bits -t 500  # 0.5-second (500ms) refresh with bits per second

5. Advanced Features#

5.1 Using Plain Text and CSV Outputs#

Use plain text output (-o plain) or CSV output (-o csv) for easy parsing in scripts or for logging.

Plain text example:

# Output once with 1-second interval
bwm-ng -o plain -t 1000 -c 1

CSV output example (with semicolon delimiter):

 # Output CSV format once
bwm-ng -o csv -t 1000 -c 1

The CSV format includes the following fields (rate mode):

timestamp;iface_name;bytes_out/s;bytes_in/s;bytes_total/s;bytes_in;bytes_out;packets_out/s;packets_in/s;packets_total/s;packets_in;packets_out;errors_out/s;errors_in/s;errors_in;errors_out;bits_out/s;bits_in/s;bits_total/s;bits_in;bits_out

You can change the delimiter with the -C flag (default is ;).

To skip the initial all-zeros output when using CSV, pass -c 0:

bwm-ng -o csv -c 0

5.2 Logging Bandwidth Data to Files#

Log metrics to a file for long-term analysis using the -F (outfile) flag for CSV and HTML modes, or shell redirection for plain text:

# Log to CSV file every 5 seconds (bits per second)
bwm-ng -o csv -F /var/log/bandwidth.log -u bits -t 5000
 
# Log plain text format using shell redirection
bwm-ng -o plain -u bits -t 10000 >> /var/log/bandwidth_plain.log

5.3 Running as a Daemon#

Use the -D flag to run bwm-ng as a background daemon. This requires the -F (outfile) flag to specify an output file, and only works with CSV or HTML output modes:

# Run as a daemon, logging CSV every 10 seconds
bwm-ng -o csv -F /var/log/bandwidth.log -u bits -t 10000 -D

5.4 Using a Configuration File#

Instead of passing many options on the command line, you can use a configuration file. By default, bwm-ng reads /etc/bwm-ng.conf and then ~/.bwm-ng.conf. You can also specify a custom config file as the last argument:

bwm-ng /path/to/my-config.conf

A configuration file uses the long-option names as keys:

UNIT=bits
OUTPUT=csv
OUTFILE=/var/log/bandwidth.log
TIMEOUT=5000
INTERFACES=eth0,wlan0

5.5 Real-Time Threshold Alerts#

bwm-ng doesn’t have built-in alerting, but you can combine it with a shell script to trigger alerts when bandwidth exceeds a threshold. Here’s an example that parses CSV output and sends an email alert:

#!/bin/bash
THRESHOLD=100000000  # 100 Mbps in bits per second
INTERFACE="eth0"
EMAIL="[email protected]"
 
while true; do
    # CSV rate format: timestamp;iface_name;bytes_out/s;bytes_in/s;bytes_total/s;...
    # Field 3 is bytes_out/s; we use -u bits so field 3 becomes bits_out/s
    TX_RATE=$(bwm-ng -o csv -t 1000 -c 1 -u bits | grep "^[0-9]*;$INTERFACE;" | cut -d';' -f3 | cut -d'.' -f1)
 
    if [ -n "$TX_RATE" ] && [ "$TX_RATE" -gt "$THRESHOLD" ]; then
        echo "High bandwidth alert on $INTERFACE: ${TX_RATE} bits/s" | mail -s "Bandwidth Threshold Exceeded" "$EMAIL"
        sleep 300  # Avoid spamming (wait 5 minutes)
    fi
    sleep 1
done

Make the script executable and run it in the background:

chmod +x bandwidth_alert.sh
nohup ./bandwidth_alert.sh &

5.6 Remote Network Monitoring#

Monitor a remote server using SSH to stream bwm-ng output locally:

# Monitor remote server's eth0 in curses mode
ssh -t user@remote-server "bwm-ng -I eth0"
 
# Get plain text output for scripting
ssh user@remote-server 'bwm-ng -o plain -t 1000'

For secure access, use SSH keys instead of passwords to avoid retyping credentials.

6. Best Practices for bwm-ng#

Filter Interfaces: Use -I to avoid monitoring unnecessary interfaces, reducing overhead and cluttering output. Use % prefix for blacklisting.
Choose Refresh Intervals: Use short intervals (0.1–0.5s) for debugging, and longer intervals (5–10s) for long-term logging.
Log to Structured Formats: Prefer CSV for logs, as it's easily parsed by tools like Excel or Grafana.
Use Configuration Files: Store commonly used options in ~/.bwm-ng.conf instead of typing them each time.
Leverage Daemon Mode: For long-term logging, run bwm-ng with -D and -F to daemonize it with output directed to a file.
Secure Remote Access: Always use SSH keys for remote monitoring, and restrict SSH access via firewall rules.
Cross-Verify Metrics: Compare bwm-ng's data with other tools (e.g., iftop, tcpdump) to ensure accuracy.
Monitor Disk I/O Too: Use bwm-ng's disk input methods to correlate network and disk activity on the same host.

7. Troubleshooting Common Issues#

7.1 No Interfaces Displayed#

Ensure the interface is active: Run ip link show to check.
Run bwm-ng with sudo: Virtual interfaces often require root privileges to monitor.
Explicitly specify the interface with -I if it’s not detected by default.

7.2 Zero Metrics but Active Traffic#

Confirm you’re monitoring the correct interface (use tcpdump to verify traffic flow).
Check if the interface is up: sudo ip link set eth0 up.

7.3 High CPU Usage#

Increase the refresh interval with -t to reduce polling frequency.
Switch from curses to plain text output mode, as curses uses additional CPU for rendering.

8. Conclusion#

bwm-ng is a versatile, lightweight tool that caters to both casual users and seasoned system administrators. Its support for multiple output formats, disk I/O monitoring, configuration files, daemon mode, and remote monitoring via SSH makes it an indispensable tool for real-time network troubleshooting, disk performance analysis, and long-term bandwidth monitoring. By following the best practices and advanced techniques outlined in this guide, you can leverage bwm-ng to keep your networks and storage running smoothly and efficiently.