################################################################################
# vmstats-daemon.pl
# v0.02 (20050908)
#
# Written by Stuart J. Browne, <bekar@bekar.id.au>
################################################################################

Contents
--------
	What is it

	How it works

	How to install

	Example usage

	Where to get it from

	Trouble Shooting

	Version History

What is it
----------

"vmstats-daemon.pl" is a short routine to grab the block/swap IO details from
the 'vmstat' tool, and allow them to be graphed using mrtg.

This tool grabs swap allocated/free details, memory active/inactive, as well
as Swap Blocks in/out, and normal IO in/out.

It was written based on Fedora Core 1's distribution of 'vmstat' (2.0.17), but
there should be no reason it wouldn't work (with minor tweaks) with previous
versions of 'vmstat'.  The called arguments (-ban) will also need to be
tweaked (-b, bytes doesn't exist for older versions of vmstat).


How it works
------------

It starts by running in the background, forking of a 'vmstat' process spitting
stats out every second (/usr/bin/vmstat -ban 1).  It accumulates the 'si',
'so', 'bi', and 'bo' values, until it receives a 'SIGHUP'.  It then dumps out
a file (/tmp/vmstat.out by default), and formats the appropriate values in the
MRTG format.

The perl routine takes one of 5 arguments, as listed:

		vmstat-daemon.pl -d		# Start as a background daemon

	Collect statistics:
		vmstat-daemon.pl -f		# Allocated/Free Swap
		vmstat-daemon.pl -m		# Inactive/Active memory pages
		vmstat-daemon.pl -s		# Swap blocks in/out
		vmstat-daemon.pl -b		# IO blocks in/out

How to install
--------------

Installation is extremely simple.  Just extract the 'vmstats-daemon.pl' from
the archive (you've already done that if you're reading this!), make sure that
the #!path to perl is correct (/usr/bin/perl by default), and the path to your
'vmstat' and 'uptime' binaries are right (/usr/bin/ by default).

You can also tweak the amount of time that the routine will ignore stat-dump
requests.

Modify and add the details to your mrtg.cfg (example supplied), or just 
"Include:" it after changing the appropraite details.  It should just work!


Example usage
-------------

Included in the distribuion is my 'system-stats.cfg' that I Include in my
'mrtg.cfg'.

Also add to your start-up routines the following line somewhere:

	/path/to/vmstats-daemon.pl -d

I use /etc/rc.d/rc.local on my fedora machine.


Where to get it from
--------------------

The latest update to this routine should always be floating around my home site
somewhere:

	http://www.bekar.id.au/~bekar/mrtg/


Trouble Shooting
----------------

Any errors should either come out on STDOUT, or be logged to syslog on either
"local0.notice" or "local0.debug".

I've not tried this on any platform other than Linux, so user feed-back is most
definately welcome!

Feel free to email me at bekar@bekar.id.au if you get stuck, and I'll try as to
help as best as I can.


Version History
---------------
v 0.02	- 20050908	Write wraparounds for vmstat child process, will
			automatically restart it's self without external
			intervention.
			Now gives a warning if called with an insufficiently
			priveliged user for stats gathering.

v 0.01	- 20040328	Initial Release
