~/ linuxnetwork.net

vnStat – A Comprehensive Guide to Lightweight Network Traffic Monitoring

In an era where bandwidth usage is a critical metric for both personal and enterprise systems, having an efficient, low-overhead tool to monitor network traffic is essential. vnStat stands out as one of the best open-source solutions for this purpose. Unlike real-time packet sniffers (like Wireshark) or resource-intensive monitoring tools (like Nagios), vnStat leverages kernel-level network statistics to track bandwidth usage persistently, with minimal CPU and memory footprint.

Designed for long-term monitoring, vnStat stores historical traffic data in binary database files, allowing users to view hourly, daily, monthly, and yearly summaries. It supports multiple interfaces, custom reporting, traffic alerts, and integrates with various GUI tools and monitoring systems. This guide will cover everything from installation and basic usage to advanced configuration, best practices, and troubleshooting.

Table of Contents#

  1. Installation & Initial Setup
  2. Core Features & Key Concepts
  3. Basic Command-Line Usage
  4. Advanced Configuration
  5. Best Practices
  6. Troubleshooting Common Issues
  7. Integrations & Extensions
  8. Conclusion
  9. References

1. Installation & Initial Setup#

vnStat is available in the default repositories of most Linux and BSD distributions. Follow the steps below for your system:

1.1 Install vnStat on Major Distributions#

Ubuntu/Debian-based Systems#

# Update package lists
sudo apt update && sudo apt upgrade -y
 
# Install vnStat
sudo apt install vnstat -y

RHEL/CentOS/Fedora#

# Install vnStat (RHEL/CentOS may require EPEL)
sudo dnf install vnstat -y

Arch Linux#

sudo pacman -S vnstat

macOS#

vnStat is designed for Linux and BSD systems and is not available for macOS. It relies on kernel-provided network interface statistics (such as /proc/net/dev on Linux), which are not available on macOS. For macOS network monitoring alternatives, consider using built-in tools like netstat or nettop, or third-party applications.

1.2 Initialize Monitoring for Interfaces#

In vnStat version 2.x and later, the vnstatd daemon automatically detects and adds interfaces by default, so manual addition is typically unnecessary. To verify interfaces are being monitored:

# Verify the interface list
vnstat --iflist

1.3 Alternative: Docker Installation#

vnStat can also run as a Docker container, which includes a built-in web UI:

docker run -d \
    --restart=unless-stopped \
    --network=host \
    -e HTTP_PORT=8685 \
    -v /etc/localtime:/etc/localtime:ro \
    -v /etc/timezone:/etc/timezone:ro \
    --name vnstat \
    vergoh/vnstat

For more details, see the vnstat-docker repository.

1.4 Start & Enable the vnStat Service#

To ensure vnStat runs on boot and logs data continuously:

# Systemd-based systems
sudo systemctl enable --now vnstat
 
# Verify service status
systemctl status vnstat

2. Core Features & Key Concepts#

vnStat’s efficiency and flexibility stem from its core design principles:

2.1 Efficient Data Collection#

vnStat reads data from the kernel’s /proc/net/dev file, which contains raw network interface statistics. This approach avoids packet sniffing, making it extremely lightweight (uses <0.1% CPU and minimal memory).

2.2 Persistent Database Storage#

Traffic data is stored in binary database files (default location: /var/lib/vnstat/) per interface. These binary files ensure fast access and minimal disk usage. Each database tracks:

  • Hourly, daily, monthly, and yearly traffic totals
  • Peak bandwidth rates
  • Top traffic days

2.3 Non-Root Operation#

By default, vnStat runs as the vnstat system user, which has minimal permissions. This reduces security risks while still allowing it to read kernel statistics.

3. Basic Command-Line Usage#

vnStat offers a simple, intuitive CLI for accessing traffic data. Below are the most common commands:

3.1 View Summary Statistics#

Get a quick overview of traffic for all monitored interfaces:

vnstat

Output includes total sent/received traffic, daily averages, and top traffic days.

3.2 Filter by Interface#

View stats for a specific interface (e.g., wlan0):

vnstat -i wlan0

3.3 Hourly, Daily, Monthly Reports#

  • Hourly stats: 
    vnstat -h
  • Daily stats: 
    vnstat -d
  • Monthly stats: 
    vnstat -m
  • Yearly stats: 
    vnstat -y

3.4 Live Traffic Monitoring#

View real-time traffic rates (similar to nload or iftop):

vnstat -l -i eth0

The -l flag enables live mode, showing current in/out rates and total transferred during the session.

3.5 Export Data to JSON/XML#

Export stats for analysis or reporting:

# JSON format
vnstat --json d > daily_traffic.json
 
# XML format
vnstat --xml m > monthly_traffic.xml
 
# Simple one-line parsable output
vnstat --oneline

3.6 95th Percentile#

View the 95th percentile bandwidth calculation, commonly used for billing:

vnstat --95th

4. Advanced Configuration#

vnStat’s behavior can be customized via its configuration file (/etc/vnstat.conf). Below are common advanced tweaks:

4.1 Customize Output Units#

Edit /etc/vnstat.conf to change default units. vnStat automatically scales units (KiB, MiB, GiB) based on traffic volume, and UnitMode toggles between binary (default) and decimal prefixes:

# Use decimal prefixes (KB, MB, GB) instead of binary (KiB, MiB, GiB)
UnitMode 1
# Show rates in bits/s
RateUnit 1

4.2 Set Up Traffic Alerts#

vnStat 2.x includes a built-in alert mechanism via the --alert flag. For example, to trigger an alert when daily traffic on eth0 exceeds 500 MiB:

vnstat -i eth0 --alert 1 3 d total 500 MiB

This can be combined with a cron job to send email notifications:

#!/bin/bash
INTERFACE="eth0"
RESULT=$(vnstat -i $INTERFACE --alert 1 3 d total 100 GiB 2>&1)
if echo "$RESULT" | grep -q "exceeded\|limit"; then
  echo "$RESULT" | mail -s "Bandwidth Alert on $INTERFACE" [email protected]
fi

Save this as /usr/local/bin/vnstat-alert.sh, make it executable (chmod +x), and add a cron job to run daily at 23:00:

0 23 * * * /usr/local/bin/vnstat-alert.sh

4.3 Change Database Location#

Move the vnStat database to a different directory (e.g., for better disk space management):

# In vnstat.conf
DatabaseDir "/mnt/storage/vnstat"

Ensure the new directory is owned by the vnstat user:

sudo mkdir -p /mnt/storage/vnstat
sudo chown -R vnstat:vnstat /mnt/storage/vnstat
sudo systemctl restart vnstat

5. Best Practices#

To maximize vnStat’s utility and reliability, follow these best practices:

5.1 Monitor Relevant Interfaces#

Avoid monitoring temporary interfaces (e.g., VPN tunnels that connect/disconnect frequently) unless necessary. Focus on core interfaces like WAN/LAN ports.

5.2 Back Up the Database#

Regularly back up the /var/lib/vnstat/ directory to preserve historical data:

# Weekly backup to /backup
sudo tar -czf /backup/vnstat_backup_$(date +%Y%m%d).tar.gz /var/lib/vnstat/

5.3 Optimize Performance#

  • For systems with many interfaces, reduce the polling interval (default: 5 minutes) in vnstat.conf to balance granularity and disk usage: 
    PollInterval 300 # 5 minutes in seconds
  • Disable logging for unused interfaces to save disk space.

5.4 Security Considerations#

  • Do not run vnStat as root. The default vnstat user has sufficient permissions.
  • Restrict access to the vnStat database directory (/var/lib/vnstat/) to prevent unauthorized modifications.
  • If using a web frontend, add HTTP basic authentication or use a reverse proxy to limit access.

5.5 Regular Updates#

Keep vnStat updated to benefit from bug fixes and new features:

# Ubuntu/Debian
sudo apt update && sudo apt upgrade vnstat
 
# RHEL/Fedora
sudo dnf update vnstat

6. Troubleshooting Common Issues#

6.1 Interface Not Detected#

If an interface isn’t showing up in vnstat --iflist, ensure the interface is active and restart the vnStat service:

# Verify the interface is active
ip link show eth0
# Restart the vnStat service
sudo systemctl restart vnstat

6.2 No Data Logged#

  • Check if the interface is active: ip link show eth0
  • Verify the vnStat service is running: systemctl status vnstat
  • Ensure the vnstat user has read access to /proc/net/dev: 
    sudo ls -l /proc/net/dev

6.3 Incorrect Traffic Counts#

  • Compare vnStat’s data with kernel stats: cat /proc/net/dev | grep eth0
  • Ensure the interface wasn’t renamed (e.g., from eth0 to enp0s3). Update the database name if needed: 
    sudo vnstat --rename eth0 enp0s3

6.4 Permission Errors#

If vnStat can’t write to the database directory:

sudo chown -R vnstat:vnstat /var/lib/vnstat/
sudo chmod 755 /var/lib/vnstat/

7. Integrations & Extensions#

vnStat can be extended with GUI tools and integrated into larger monitoring systems:

7.1 vnStati: CLI Image Generator#

Generate PNG images of traffic stats for reports or dashboards:

# Install vnStati (usually included with vnStat)
sudo apt install vnstati -y
 
# Generate daily stats image
vnstati -d -o /var/www/html/daily_stats.png
 
# Generate hourly stats image
vnstati -h -o /var/www/html/hourly_stats.png

7.2 Web Frontends#

Several community web frontends are available for viewing vnStat data in a browser. Search for the latest maintained projects on GitHub, as the original PHP frontend is no longer actively maintained.

7.3 Prometheus Integration#

Use a vnStat Exporter to expose vnStat data as Prometheus metrics. This allows you to visualize traffic in Grafana using the vnstat metrics dashboard.

8. Conclusion#

vnStat is an indispensable tool for anyone needing to monitor network bandwidth efficiently. Its lightweight design, persistent storage, and flexible CLI make it ideal for both personal and enterprise use. By following the practices outlined in this guide, you can set up a robust, low-overhead monitoring system that provides valuable insights into your network usage over time.

9. References#

2026-05