User Tools

Site Tools


doc:howto:vnstat

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision
Previous revision
doc:howto:vnstat [2013/01/01 21:08]
written_direcon
doc:howto:vnstat [2015/12/11 21:48] (current)
tmomas
Line 1: Line 1:
 +====== vnStat ======
 +vnStat is a console-based network traffic monitor for Linux and BSD that keeps a log of network traffic for the selected interface(s). It uses the network interface statistics provided by the kernel as information source. This means that vnStat won't actually be sniffing any traffic and also ensures light use of system resources. [[http://​humdi.net/​vnstat/​|As it says on their website]] ​
 +===== Installing =====
  
 +==== Base ====
 +<​code>​opkg update
 +opkg install vnstat</​code>​
 +
 +==== Webserver (optional) ====
 +<​code>​opkg update
 +opkg install uhttpd vnstati</​code>​
 +
 +===== Configuring =====
 +The only configuring it really needs is to tell it what interface(s) to monitor, and some method of updating the database such as a cronjob. You might want to backup your database file. The vnstati package comes with a '​restore'​ and init.d script that downloads the backup from a webserver upon reboot. Its up to you to chose how to backup/​restore the data( via HTTP/​FTP/​SSH/​ETC)
 +
 +==== Setup ====
 +| {{:​meta:​icons:​tango:​dialog-information.png?​nolink}} | **This step is required for vnStat to function.** |
 +
 +The common choice for monitoring is your WAN interface. To locate your WAN ifname and setup interfaces to monitor and create database do:
 +<code bash>
 +. /​lib/​functions/​network.sh;​ if network_get_device if_wan wan; then
 +vnstat -u -i $if_wan; else echo WTF! Is WAN up?; fi
 +</​code>​
 +
 +:!: The interface must be active for the above command to work.  See ticket [[https://​dev.openwrt.org/​ticket/​19116|19116]].
 +==== Database Updating ====
 +| {{:​meta:​icons:​tango:​dialog-information.png?​nolink}} | **This step is required for vnStat to function.** The package doesn'​t setup database updating at all. Its up to you to configure when vnStat will update. Use the daemon or a cron job. |
 +=== Using included daemon: ===
 +<​code>/​etc/​init.d/​vnstat enable
 +/​etc/​init.d/​vnstat start</​code>​
 +
 +| {{:​meta:​icons:​tango:​dialog-error.png?​nolink}} | **''/​etc/​config/​vnstat''​** is the database restore config, __not the vnstatd config.__ vnstatd config is located at **''/​etc/​vnstatd.conf''​** |
 +This same init.d script will automatically download a database backup if you configured ''/​etc/​config/​vnstat''​ corrrectly. Useful for recovering db after a router reboot. Down side is that there is no implemented upload method using the uci config. You will need to write a script that cron will run to do all the uploading, so why not use the same protocol for downloading too? I suggest rsync, ftp, or scp.
 +=== Using a cronjob: ===
 +Add to crontab:
 +<​code>​echo "*/5 * * * * vnstat -u" >> /​etc/​crontabs/​root</​code>​
 +Restart cron with:
 +<​code>/​etc/​init.d/​cron restart</​code>​
 +
 +==== Image Generation ​ ====
 +You can install webif and it will generate images. But thats not lightweight so RealOpty developed scripts based off webif code that will generate the images without webif.
 +
 +You might want to setup a crontab to execute this script every 15 min.
 +
 +I always output the images to the tmpfs so it dont always write to flash.
 +
 +| <code bash>
 +#!/bin/sh
 +# vnstati image generation script.
 +# Source: http://​code.google.com/​p/​x-wrt/​source/​browse/​trunk/​package/​webif/​files/​www/​cgi-bin/​webif/​graphs-vnstat.sh
 +
 +WWW_D=/​tmp/​www/​vnstat # output images to here
 +LIB_D=/​var/​lib/​vnstat # db location
 +BIN=/​usr/​bin/​vnstati ​ # which vnstati
 +
 +outputs="​s h d t m" ​  # what images to generate
 +
 +# Sanity checks
 +[ -d "​$WWW_D"​ ] || mkdir -p "​$WWW_D"​ # make the folder if it dont exist.
 +
 +# You might want to setup a link if it dont exist.
 +# [ -L /www/vnstat ] || ln -sf /www/vnstat /tmp/www/
 +
 +# End of config changes
 +interfaces="​$(ls -1 $LIB_D)"​
 +
 +if [ -z "​$interfaces"​ ]; then
 +    echo "No database found, nothing to do."
 +    echo "A new database can be created with the following command: "
 +    echo " ​   vnstat -u -i eth0"
 +    exit 0
 +else
 +    for interface in $interfaces;​ do
 +        for output in $outputs; do
 +            $BIN -${output} -i $interface -o $WWW_D/​vnstat_${interface}_${output}.png
 +        done
 +    done
 +fi
 +
 +exit 1
 +</​code>​ |
 +
 +==== Sample HTML ====
 +| <code html>
 +<META HTTP-EQUIV="​refresh"​ CONTENT="​300">​
 +<​html>​
 +  <​head>​
 +    <​title>​Traffic of Interface eth1</​title>​
 +  </​head>​
 +  <​body>​
 +    <​h2>​Traffic of Interface eth1</​h2>​
 +    <​table>​
 +        <​tbody>​
 +            <tr>
 +                <td>
 +                    <img src="​vnstat_eth1_s.png"​ alt="​eth1 Summary"​ />
 +                </td>
 +                <td>
 +
 +                    <img src="​vnstat_eth1_h.png"​ alt="​eth1 Hourly"​ />
 +                </td>
 +            </tr>
 +            <tr>
 +                <td valign="​top">​
 +                    <img src="​vnstat_eth1_d.png"​ alt="​eth1 Daily" />
 +                </td>
 +                <td valign="​top">​
 +                    <img src="​vnstat_eth1_t.png"​ alt="​eth1 Top 10" />
 +                    <br />
 +                    <img src="​vnstat_eth1_m.png"​ alt="​eth1 Monthly"​ />
 +                </td>
 +            </tr>
 +        </​tbody>​
 +    </​table>​
 +  </​body>​
 +</​html>​
 +
 +</​code>​ |
 +
 +==== Persistent stats ====
 +vnStat stores stats to /​var/​lib/​vnstat by default, and information may not persist across restarts. This means that one might want to relocate the database directory to other forms of persistent storage like your device'​s flash or external thumb drives. vnStat is configured to write to the database directory every 30mins by default, and this can be adjusted in vnStat'​s configuration.
 +
 +For users considering to use your device'​s flash, be sure to consider the following points. I recommend the use of an external storage device.
 +  - OpenWRT device'​s flash space is limited in size
 +  - Database might not persist across firmware flashes, where your squashfs or jffs partition will be wiped
 +  - Consistent writes to flash may '​kill'​ your flash (even though this may not be a major concern
 +
 +=== Method 1 ===
 +To store the database on the thumb drive, ensure that [[usb.storage]] is working. Then, edit DatabaseDir in /​etc/​vnstat.conf to point to your flash drive, you may also want to modify SaveInterval to a larger value (the default 30min is still a good value) to minimise writes to flash.
 + 
 +=== Method 2 === 
 +This method stores the database to a temporary directory in memory, and uses a cronjob script to backup and restore the database to your USB device. However, script may not be that useful since most of these functions can be done via vnStat'​s configuration (i.e. backup every 30mins to file), and this is left as an alternative since it has already been written.
 +
 +== Config files ==
 +In config files (/​etc/​vnstat.conf) please edit these lines:
 +| ''​ DatabaseDir "/​tmp/​vnstat"​ ''​ |
 +Don't forget edit vnstati (image output) generator script if you use it (config lines).
 +
 +== Script ==
 +Please make this file for /​etc/​init.d/​vnstatbackup
 +| <code bash>
 +#!/bin/sh
 +## Please visit http://​wiki.openwrt.org/​doc/​howto/​vnstat
 +
 +BACKUP="/​usb"​
 +TEMP="/​tmp"​
 +DIRNAME="​vnstat"​
 +
 +case $1 in
 +  backup)
 +    cp -r $TEMP/​$DIRNAME $BACKUP
 +  ;;
 +  restore)
 +    cp -r $BACKUP/​$DIRNAME $TEMP
 +  ;;
 +  *)
 +    echo "​Please use '​backup'​ or '​restore'​ parameter for run";
 +  ;;
 +esac
 +
 +exit 0
 +</​code>​ |
 +
 +After:
 +
 +<​code>​chmod 755 /​etc/​init.d/​vnstatbackup</​code>​
 +
 +== Add for cron and for init ==
 +Do this: (backup every 30 minute, if you want other backup window please read cron section)
 +<​code>​echo "*/30 * * * * /​etc/​init.d/​vnstatbackup backup"​ >> /​etc/​crontabs/​root
 +/​etc/​init.d/​cron restart</​code>​
 +
 +Edit /​etc/​rc.local,​ like this: (important: The last line in this file must be 'exit 0')
 +| <code bash>
 +mount /dev/sda1 /usb
 +/​etc/​init.d/​vnstatbackup restore
 +
 +exit 0
 +</​code>​ |
 +Note: Dont use the first line if you haven'​t USB device.
 +
 +===== Example =====
 +A video demonstration of how vnStat 1.11-4 in the repositories can be installed on OpenWrt 14.07 Barrier Breaker: https://​www.youtube.com/​watch?​v=VGd8Rekm970