vnStat, a traffic counter that asks the kernel instead of sniffing packets

Why the kernel is the right source

The design decision is stated in the first paragraph and it is the whole reason the tool is cheap. vnStat is a console-based network traffic monitor that uses the network interface statistics provided by the kernel as information source, which means it will not actually be sniffing any traffic and also ensures light use of system resources regardless of network traffic rate. That is a different proposition from a sniffer, and the difference shows up in three places. The CPU cost does not scale with traffic, so a monitored link can be saturated without the monitor noticing. The counters are the same numbers your operating system already shows, so a vnStat total agrees with what the kernel reports. And because nothing is inspected at the packet level, the tool adds no per-packet work to the link. The primary language is C, the licence is GPL-2.0, and the project is not archived with the last push on 2026-10-14.

vnStat is a console-based network traffic monitor that uses the network
interface statistics provided by the kernel as information source.

Four retention levels, and why five minutes is the floor

The default retention scheme is what makes the tool useful over time rather than a live meter. Traffic statistics are stored on a five minute level for the last 48 hours, on an hourly level for the last 4 days, on a daily level for the last 2 full months and on a yearly level forever. The durations are fully user configurable, so the shape of the history is a decision rather than a constant. The five minute granularity is the finest level offered, and it is what makes the 48 hour window useful for spotting an incident, while the daily and yearly levels are what let you answer a question about last March without the data having aged out. The window lengths are asymmetric on purpose, and a user who wants a month of hourly data is expected to change the configuration rather than work around the default. Total seen traffic and a top days listing are also provided, so the common questions do not need a query language.

five minute level for the last 48 hours

Installing: source, git or a container

The project says vnStat works best when installed, and there are three routes. The stable release is a tarball you download and unpack, with optional signature verification steps that fetch the detached signature and the signing key, then run gpg to verify, with the note that the signature is correct if the output shows a good signature from the named maintainer. The development version is a git clone of the repository, and in both cases you then continue with the instructions in the INSTALL file or the BSD-specific one depending on the operating system, with upgrade instructions in a separate file and release notes in a changes file. The third route is a Docker container containing the pre-compiled latest stable release, and the same images are also published to a registry hosting GitHub packages. The verification step is the part worth not skipping, since you are running a daemon that reads and writes system state.

wget https://humdi.net/vnstat/vnstat-latest.tar.gz
wget https://humdi.net/vnstat/vnstat-latest.tar.gz.asc
gpg --keyserver keys.openpgp.org --recv-key 0xDAFE84E63D140114
gpg --verify vnstat-latest.tar.gz.asc vnstat-latest.tar.gz

The container, and what it does not mount

The container example is worth reading closely because it shows the shape of the deployment. The image runs detached with a restart policy of unless-stopped and host networking, with an HTTP port environment variable, the local time and timezone files mounted read-only so the timestamps in the reports match the host, and the container named vnstat. What it does not mount is the data directory, which is the detail to notice. The host networking and the HTTP port suggest the container is meant to serve a web interface, and the examples directory carries the scripts that would do it, including a plain CGI script, a JSON variant, a metrics variant and PHP and JSON flavours. The timezone mounts exist so that a daily report emailed to you says what your clock says. The absence of a data volume is the gap, because the history is the value of the tool and the container as written does not preserve it across a recreation.

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

The output formats, and who each one is for

The examples directory is the clearest statement of the intended audience. There are init service definitions for the traditional init system, plus launchd, systemd and upstart examples, so the tool is expected to run as a daemon on several different init systems. Then there are the web front ends: a plain CGI script, a JSON variant, a metrics variant, a PHP variant, and a JSON one in PHP, which together cover the common ways of exposing the numbers to a browser or to a monitoring system. That combination, a scheduled text report for a human plus a CGI endpoint for a dashboard, is the whole product. The documentation also points to the official webpage for additional details and output examples, and the FAQ file at the repository root is part of the distribution alongside the install and upgrade instructions and a changelog. The main language recorded for the repository is C, and the release history shows steady annual work, with v2.13 in February 2025, v2.12 in January 2024 and v2.11 in August 2023.

Where it fits, and what to check before you rely on it

The honest scope of vnStat is a machine's interface counters, and it does that job with almost no overhead and a history that goes back years. That is exactly what you want for a server whose bandwidth bill you need to explain, a VPS whose traffic quota you are watching, or a home connection where you want to know whether the evening slowdown is the network or the application. It is not a tool for per-host, per-port or per-protocol accounting, because the kernel counters it reads do not carry that information, and pretending otherwise would defeat its simplicity. The two practical checks before you deploy it are about persistence and about the data you are reading. The history lives on disk, so whatever runs vnStat, whether it is a service or a container, needs that storage to survive restarts, and the container example as written does not mount it. And because the counters are the kernel's, they reset on some interfaces when the link goes down or the driver reloads, so a user comparing a monthly figure against a provider invoice should know where the resets are. The project itself is a good citizen about this kind of thing, publishing a FAQ, a changelog and upgrade notes alongside the code.

Editorial conclusion

Adopt vnStat if you want a traffic history for one machine on a long timescale without running a packet sniffer, and skip it if you need per-host or per-protocol visibility, because vnStat counts the interface and nothing below it. Verify three things before you rely on its numbers: that the interface counters are the ones you think they are, since the whole design reads what the kernel reports; that the retention settings match how you will read the data, because the default drops sub-five-minute detail after 48 hours; and that your history survives a reboot or a container restart, since the data is stored on disk by the tool and the container example mounts no volume for it.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-2.0
3. README
4. Releases
5. vergoh/vnstat on GitHub