How to Monitor Network Bandwidth with vnStat

How to Monitor Network Bandwidth with vnStat

vnStat is a lightweight, console-based network traffic monitor that tracks bandwidth usage on your Breeze instance. Unlike packet-sniffing tools, vnStat reads data from the kernel's network interface counters, making it extremely resource-efficient and suitable for long-term monitoring.

Installing vnStat

sudo apt install -y vnstat    # Debian/Ubuntu
sudo dnf install -y vnstat    # CentOS/RHEL

Start and enable the vnStat daemon:

sudo systemctl enable --now vnstatd

Initial Setup

vnStat automatically detects and begins monitoring all interfaces. Verify which interfaces are being tracked:

vnstat --iflist
vnstat

If an interface is not listed, add it manually:

sudo vnstat --add -i eth0

Wait a few minutes for vnStat to collect initial data before querying statistics.

Viewing Traffic Statistics

vnStat provides several views of your bandwidth data:

# Summary for all interfaces
vnstat

# Hourly statistics
vnstat -h

# Daily statistics
vnstat -d

# Monthly statistics
vnstat -m

# Top 10 traffic days
vnstat -t

# Live traffic rate
vnstat -l -i eth0

# Five-minute interval statistics
vnstat -5

Filtering by Time Period

Query specific date ranges for reporting:

# Traffic for a specific day
vnstat -d --begin 2026-01-15 --end 2026-01-15

# Traffic for a date range
vnstat -d --begin 2026-01-01 --end 2026-01-31

# Current month detail
vnstat -m

JSON Output for Automation

vnStat can output data in JSON format, which is useful for scripts and monitoring integrations:

# JSON output for all data
vnstat --json

# JSON for hourly data on a specific interface
vnstat --json h -i eth0

# Parse with jq for total monthly traffic
vnstat --json m | jq '.interfaces[0].traffic.month[-1]'

Setting Up Traffic Alerts

Create a simple bandwidth alert script at /usr/local/bin/vnstat-alert.sh:

#!/bin/bash
LIMIT_GB=500
CURRENT=$(vnstat --json m | jq -r '.interfaces[0].traffic.month[-1].tx' )
CURRENT_GB=$((CURRENT / 1073741824))

if [ "$CURRENT_GB" -gt "$LIMIT_GB" ]; then
    echo "Warning: Monthly TX traffic is ${CURRENT_GB}GB (limit: ${LIMIT_GB}GB)" \
        | mail -s "Bandwidth Alert" admin@example.com
fi

Add it to cron to run daily:

echo "0 8 * * * /usr/local/bin/vnstat-alert.sh" | sudo crontab -

Per-Interface Monitoring

When your Breeze has multiple interfaces (public, private, VPN), monitor each independently:

vnstat -i eth0 -d    # Public interface
vnstat -i eth1 -d    # Private interface
vnstat -i wg0 -d     # WireGuard tunnel

Database and Configuration

vnStat stores its database at /var/lib/vnstat/. The configuration file at /etc/vnstat.conf lets you customize the update interval, default interface, and data retention periods. Key settings include:

DatabaseDir "/var/lib/vnstat"
UpdateInterval 20
PollInterval 5
SaveInterval 300
MonthRotate 1
MonthRotateAffectsYears 0

The UpdateInterval controls how often (in seconds) the daemon reads interface counters. The default of 20 seconds provides good granularity without excessive disk writes. vnStat retains data for years with minimal disk usage, making it ideal for long-term bandwidth tracking on your Breeze.