Search:  
Gentoo Wiki

HOWTO_vnStat

Contents

Introduction

vnStat is a very lightweight network monitoring program. Instead of using a packet sniffer, which can grind your computer to a halt under heavy traffic, it simply checks up on changes in the /proc using a cron script. While it doesn't come with a front end, nor is there one in Portage, you can find one here

Personally, I tried ntop, but it would eat up my cpu, as I run my server as a client on my university's DC++ hub and I regularly see upload speeds in excess of 10MB/s, and I tried Zabbix, but found it had far too many features, and was infinitely more complicated than I needed.

Installation

This is easy

vnStat has no use flags, and only one dependency, a cron daemon (virtual/cron). You should have installed one when you first installed Gentoo, if not, you can use the official Gentoo cron guide here.

As root, run

emerge vnstat

When this is finished (its small, so don't bother making that sandwich), run the command

vnstat -u -i interface

For each of your network interfaces that you want vnStat to monitor. For me, this meant

vnstat -u -i eth0 && vnstat -u -i eth2

as for some reason Gentoo skipped eth1. This will show an error about the database not being found, which is completely normal, as it will then go ahead and create it for you.

If you want your interfaces to have names as well, such as "Internet" or "Lan," you can do this with the command

vnstat -u -i interface --nick name

Setup

Now you can begin checking traffic on your cards. In order to update the database with new traffic, you have to use the command

vnstat -u

If you don't want to do this every hour, there is a cron script installed in cron.hourly which you can enable to do this instead.

File: /etc/cron.hourly/vnstat
#!/bin/bash

# run vnstat if installed and at least one database exists

# Uncomment the following to enable

#if [ -x /usr/bin/vnstat ] && [ `ls /var/lib/vnstat/ | wc -l` -ge 1 ] ; then
#    exec /usr/bin/vnstat -u
#fi

Uncomment (delete the #'s) the last three lines of this file. Now every hour, the script will check if vnStat is installed an you have at least one interface being monitored, and then execute vnstat -u for you.

Usage

vnStat comes with a text based frontend.

For an overall summary of total traffic, simply use

vnstat

For an ascii graph of traffic per hour

vnstat -h

per day

vnstat -d

per week

vnstat -w

per month

vnstat -m

For a list of the top 10 high traffic days

vnstat -t

And to monitor traffic in real time to get a network speed

vnstat -tr time in seconds

Where the time is how long you wish to monitor traffic, by default this is 5.

Frontend

You most likely will want a web based frontend to access and view. Since this isn't available alone, you will have to download and install the PHP front end from elsewhere.

For this, you will need Apache and PHP working nicely together. Normally, this consists of adding apache2 to your make.conf and emerging php. If you encounter problems, you might find help in the pages on Apache, such as Apache2 Install

To download the PHP frontend

wget http://www.sqweek.com/sqweek/files/vnstat_php_frontend-1.3.tar.gz

and unpack it

tar -xvzf vnstat*

Now create a directory in you Apache server to put these files in. You will probably want

mkdir /var/www/localhost/htdocs/vnstat
cp vnstat*/* /var/www/localhost/htdocs/vnstat/

Unless you have setup your server differently.

Now if Apache and PHP are working, if you point your browser to http://127.0.0.1/vnstat you should see a nicely formatted page which doesn't tell you anything. If your browser attempts to download a .php file, PHP is not setup right. If your browser times out, either Apache is not setup right or, more likely, is not running. To fix that

/etc/init.d/apache start

and to have Apache start when you boot

rc-update add apache default

Once you can successfully view this page, it's time to configure the frontend.

File: /var/www/localhost/htdocs/config.php
<?php
    //
    // vnStat PHP frontend 1.3 (c)2006-2007 Bjorge Dijkstra (bjd@jooz.net)
    //
    // This program is free software; you can redistribute it and/or modify
    // it under the terms of the GNU General Public License as published by
    // the Free Software Foundation; either version 2 of the License, or
    // (at your option) any later version.
    //
    // This program is distributed in the hope that it will be useful,
    // but WITHOUT ANY WARRANTY; without even the implied warranty of
    // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    // GNU General Public License for more details.
    //
    // You should have received a copy of the GNU General Public License
    // along with this program; if not, write to the Free Software
    // Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
    //
    //
    // see file COPYING or at http://www.gnu.org/licenses/gpl.html 
    // for more information.
    //

    //
    // configuration parameters
    //
    // edit these to reflect your particular situation
    //

    // list of network interfaces monitored by vnStat
    $iface_list = array('eth0', 'eth1', 'sixxs');

    //
    // optional names for interfaces
    // if there's no name set for an interface then the interface identifier
    // will be displayed instead
    //    
    $iface_title['eth0'] = 'Internal';
    $iface_title['eth1'] = 'Internet';
    $iface_title['sixxs'] = 'SixXS IPv6';

    //
    // There are two possible sources for vnstat data. If the $vnstat_bin
    // variable is set then vnstat is called directly from the PHP script
    // to get the interface data. 
    //
    // The other option is to periodically dump the vnstat interface data to
    // a file (e.g. by a cronjob). In that case the $vnstat_bin variable
    // must be cleared and set $data_dir to the location where the dumps
    // are stored. Dumps must be named 'vnstat_dump_$iface'.
    //
    // You can generate vnstat dumps with the command:
    //   vnstat --dumpdb -i $iface > /path/to/data_dir/vnstat_dump_$iface
    // 
    $vnstat_bin = '';
    $data_dir = './dumps';

Change the $iface_array and $iface_title fields to reflect your setup, and in the vnstat_bin field, put vnstat.

My config.php is shown as an example below.

File: /var/www/localhost/htdocs/config.php
<?php
    $iface_list = array('eth0', 'eth2');  
    $iface_title['eth0'] = 'Internet';
    $iface_title['eth2'] = 'Lan';
    $vnstat_bin = 'vnstat';
    $data_dir = './dumps';

If all is well, when you go to http://127.0.0.1/vnstat you should be greeted with your data and graphs.

Real-Time Frontend

When I installed this, I didn't like how the PHP page would only update every hour, and realized that if I changed the $vnstat_bin to vnstat -u && vnstat, the php script would unwittingly update the database every time a page is loaded. This works because if you run

vnstat -u && vnstat

it has identical output to

vnstat

but also gives you completely up-to-date information, not information from the last run of the cron script.

Note: Before vnstat-1.5, vnstat -u alone prints out the necessary information, so the second command is not necessary

Since Apache runs the script without root privileges, you have to change the permissions on the database files so that Apache will update them

chmod -v 666 /var/lib/vnstat/*

Now you can go ahead and edit your config.php to add the -u

File: /var/www/localhost/htdocs/config.php
<?php
    $iface_list = array('eth0', 'eth2');  
    $iface_title['eth0'] = 'Internet';
    $iface_title['eth2'] = 'Lan';
    $vnstat_bin = 'vnstat -u && vnstat';
    $data_dir = './dumps';

Be sure to keep the cron script running, as the graphs rely on vnStat being run at least once hourly.

Retrieved from "http://www.gentoo-wiki.info/HOWTO_vnStat"

Last modified: Mon, 04 Aug 2008 09:50:00 +0000 Hits: 2,004