Skip to main content.

Bandwidth monitoring and testing


Live demo in BSD Now Episode 021 | Originally written by TJ for | Last updated: 2014/01/22

NOTE: the author/maintainer of the tutorial(s) is no longer with the show, so the information below may be outdated or incorrect.

Today we'll be combining two programs for monitoring bandwidth and benchmarking network performance. Both of these would be great to have on your router. The tools are called vnstat and iperf. They're both available natively for all of the main BSDs.

Install them how you normally would and let's get set up.


You can monitor your bandwidth usage easily with this simple console program. Once you install it, you need to create a database for your NIC(s). For this example, I only have one NIC that's called em0.

# vnstat 

If you get an error like

Error: Unable to open database directory "/var/db/vnstat".
Make sure it exists and is at least read enabled for current user.

then make that directory by issuing:

# mkdir /var/db/vnstat

and rerunning the previous command. The first time you start it, you should see something like:

No database found, nothing to do. Use --help for help.

A new database can be created with the following command:
    vnstat -u -i eth0

Replace 'eth0' with the interface that should be monitored.

The following interfaces are currently available:
    em0 usbus0 usbus1 usbus2 usbus3 usbus4 lo0

Let's create a new database for our NIC(s) by doing:

# vnstat -u -i em0

Error: Unable to read database "/var/db/vnstat/em0".
Info: -> A new database has been created.

Replace em0 with your interface of course, and repeat the process for any additional interfaces you want to be monitored. Now we can edit the configuration file. It will be in a different location depending on how you installed it, but /usr/local/etc or /etc are good places to look for the sample config. Since I'm using FreeBSD for this example, I'll go ahead and do:

# cp /usr/local/etc/vnstat.conf.sample /usr/local/etc/vnstat.conf
# vi /usr/local/etc/vnstat.conf

Take a look at all the commented options and edit them as you see fit. Finally, start the daemon!

# vnstatd -d -p /var/run/ 

Now it will automatically start collecting numbers. Download some files, upload some files and check back in maybe 10 minutes. You can see the current usage statistics by simply running:

$ vnstat

You can further drill down to weekly, monthly, daily or even hourly usage. It offers ascii graphs (or actual graphs with vnstati and a webserver) and lots of cool features. Let's check all the things it can do.

$ vnstat --longhelp

         -u, --update          update database
         -r, --reset           reset interface counters
         --sync                sync interface counters
         --enable              enable interface
         --disable             disable interface
         --nick                set a nickname for interface
         --cleartop            clear the top10
         --rebuildtotal        rebuild total transfers from months
         -q, --query           query database
         -h, --hours           show hours
         -d, --days            show days
         -m, --months          show months
         -w, --weeks           show weeks
         -t, --top10           show top10
         -s, --short           use short output
         -ru, --rateunit       swap configured rate unit
         --oneline             show simple parseable format
         --dumpdb              show database in parseable format
         --xml                 show database in xml format
         -i,  --iface          select interface (default: lo0)
         -?,  --help           short help
         -D,  --debug          show some additional debug information
         -v,  --version        show version
         -tr, --traffic        calculate traffic
         -l,  --live           show transfer rate in real time
         --style               select output style (0-4)
         --delete              delete database and stop monitoring
         --iflist              show list of available interfaces
         --dbdir               select database directory
         --locale              set locale
         --config              select config file
         --savemerged          save merged database to current directory
         --showconfig          dump config file with current settings
         --testkernel          check if the kernel is broken
         --longhelp            display this help

See also "man vnstat".

Note that it can do live monitoring as well! This is a really versatile program. I like to have it automatically start when the system boots up, so I'll add it to /etc/rc.local.

# echo '/usr/local/sbin/vnstatd -d -p /var/run/' >> /etc/rc.local

Depending on which BSD you're using, you should probably use the included rc.d script with that port of vnstat instead of rc.local. The above is example is a generic one that should work for them all. If you run it on your gateway, you can see total bandwidth and even per-client bandwidth usage, based on the interfaces. Here's an example from my own OpenBSD router:

                      rx      /      tx      /     total    /   estimated
       Jan '14     14.82 GiB  /  700.43 MiB  /   15.50 GiB  /   85.83 GiB
     yesterday      4.33 GiB  /  207.05 MiB  /    4.54 GiB
         today      2.00 GiB  /  149.34 MiB  /    2.14 GiB  /    3.58 GiB

       Jan '14    248.40 MiB  /    7.71 GiB  /    7.96 GiB  /   44.05 GiB
     yesterday    111.46 MiB  /    3.65 GiB  /    3.76 GiB
         today     59.85 MiB  /    1.64 GiB  /    1.70 GiB  /    2.84 GiB

       Jan '14     13.25 GiB  /    2.94 GiB  /   16.19 GiB  /   89.66 GiB
     yesterday      5.03 GiB  /  843.58 MiB  /    5.85 GiB
         today      1.60 GiB  /   71.93 MiB  /    1.67 GiB  /    2.79 GiB

       Jan '14      4.73 GiB  /   19.52 GiB  /   24.25 GiB  /  134.25 GiB
     yesterday      1.43 GiB  /    6.14 GiB  /    7.57 GiB
         today    110.05 MiB  /    1.90 GiB  /    2.01 GiB  /    3.36 GiB

In this example, re0 is the interface-facing "WAN port" and re1-3 are the LAN clients. It's worth noting that if you run it on your router, the rx and tx values will be reversed for the LAN clients, but normal for the WAN. Even though all three computers have collectively downloaded just over 30GB, only about 15GB of that was actually from the internet. The rest was internal traffic between them. If you have multiple IPs per NIC, you might be interested in bandwidthd instead of vnstat.


Now that you can watch how much bandwidth you use, you want to watch how fast you can push it, right? That's where iperf comes in. It operates on a simple client/server model; one machine runs the iperf server and the other connects to it. They then send a bunch of packets between each other and record the speed. After you install iperf, the usage is extremely basic. On the server, run:

$ iperf -ms

Server listening on TCP port 5001
TCP window size: 64.0 KByte (default)

By default it will listen on TCP port 5001, but this can be easily changed with the "-n" switch. Make sure you open that port in your firewall, at least for the client IP that you expect to be connecting. Use the "-w" switch to adjust the TCP window size. On the client, run:

$ iperf -mc ip-of-the-server

[  3] local port 55737 connected with port 5001
[ ID] Interval       Transfer     Bandwidth
[  3]  0.0-10.0 sec   808 MBytes   678 Mbits/sec
[  3] MSS size 1448 bytes (MTU 1500 bytes, ethernet)

You'll see a similar output in the server's console. You can use the "-u" switch to use UDP instead of TCP if you prefer. Check the man page for more options. If you're not satisfied with the default results, look into some network tuning sysctl options. There's also the previously-mentioned "-w" switch, which can increase performance. All of the BSDs can perform extremely well in this regard. Remember that running a lot of benchmarks (either on the LAN or WAN) may skew your vnstat bandwidth usage report. You might actually want to do the benchmarking first!

Latest News

New announcement


We understand that Michael Dexter, Brad Davis, and George Rosamond think there should be more real news....

Two Year Anniversary


We're quickly approaching our two-year anniversary, which will be on episode 105. To celebrate, we've created a unique t-shirt design, available for purchase until the end of August. Shirts will be shipped out around September 1st. Most of the proceeds will support the show, and specifically allow us to buy...

New discussion segment


We're thinking about adding a new segment to the show where we discuss a topic that the listeners suggest. It's meant to be informative like a tutorial, but more of a "free discussion" format. If you have any subjects you want us to explore, or even just a good name...

How did you get into BSD?


We've got a fun idea for the holidays this year: just like we ask during the interviews, we want to hear how all the viewers and listeners first got into BSD. Email us your story, either written or a video version, and we'll read and play some of them for...

Episode 276: ho, ho, ho - 12.0


Direct Download:MP3 AudioVideo Headlines FreeBSD 12.0 is available After a long release cycle, the wait is over: FreeBSD 12.0 is now officially available. We’ve picked a few interesting things to cover in the show, make sure to read the full Release Notes > Userland: > Group permissions on /dev/acpi have been changed to allow users in...

Episode 275: OpenBSD in stereo


Direct Download:MP3 AudioVideo Headlines DragonflyBSD 5.4 released DragonFly version 5.4 brings a new system compiler in GCC 8, improved NUMA support, a large of number network and virtual machine driver updates, and updates to video support. This release is 64-bit only, as with previous releases. The details of all commits...

Episode 274: Language: Assembly


Direct Download:MP3 AudioVideo Headlines Assembly language on OpenBSD amd64+arm64 This is a short introduction to assembly language programming on OpenBSD/amd64+arm64. Because of security features in the kernel, I have had to rethink a series of tutorials covering Aarch64 assembly language on OpenBSD, and therefore this will serve as a placeholder-cum-reminder....

Episode 273: A thoughtful episode


Direct Download:MP3 AudioVideo Headlines Some thoughts on NetBSD 8.0 NetBSD is a highly portable operating system which can be run on dozens of different hardware architectures. The operating system's clean and minimal design allow it to be run in all sorts of environments, ranging from embedded devices, to servers, to workstations....