***
*** linux_loadavg_mrtg: an external sensor to get the
*** current system-load into MRTG. Written in C to be
*** faster than the usual perl-scripts.
***

Compiling and Installing
------------------------

Type "make" to compile the program. Then, as a user who as
write-permissions to the target directory, type "make install" to
install the program.

	chris@pi2105$ make
	gcc -Wall -g -O3   -c -o linux_loadavg_mrtg.o linux_loadavg_mrtg.c
	gcc   linux_loadavg_mrtg.o   -o linux_loadavg_mrtg

	chris@pi2105$ sudo make install
	install -m755 linux_loadavg_mrtg /usr/local/mrtg/bin

You can change the destination directory by adding EXE_DIR
to the make command:

	chris@pi2105$ sudo make EXE_DIR=/tmp install
	install -m755 linux_loadavg_mrtg /tmp

Usage:
------

Add a target that looks like this into your mrtg-config:
	Title[loadavg]: Load Average
	Target[loadavg]: `/usr/local/mrtg/bin/linux_loadavg_mrtg -n2`
	PageTop[loadavg]: Load Average
	MaxBytes[loadavg]: 100
	Options[loadavg]: gauge

Theroy of operation
-------------------

linux_loadavg_mrtg opens /proc/loadavg and reads numbers representing
the current system-load from this pseudo-file. (see manual for proc(5)).

	0.00 0.02 0.00 1/52 27959
	^    ^    ^
	|    |    |
	|    |    15 minute loadavg
	|    5-minute loadavg
	1-minute loadavg

The file that is opened can be changed with the -f option (defaults to
/proc/loadavg). The number that is read by default is the first one, the
1-minute loadavg. You might want to change this to be the 2nd number
(-n2 option) or the 3rd one (-n3 option) for the 5 or 15 minute averaged
loadvalue.

After it has read this file it will print this number, followed by a '0'
(MRTG always wants two values).

It then opens /proc/uptime (or the file specified via the -u option)
and reads the current uptime in seconds. They are printed in a somehow
human-readable format with days:hours:minutes:seconds of uptime.

As a fourth value, the hostname as given via the hostname(2) system call
is appended to the output.

Help
----

Calling linux_loadavg_mrtg with the -h option produces
this short help:

	Usage: ./linux_loadavg_mrtg [options]
	Options:     Description (default):
	  -n n       use nth float from loadavg file (1)
		     n=1: 1min, n=2:5min, n=3:15min average
	  -f file    get loadavg from file (/proc/loadavg)
	  -u file    get uptime from file (/proc/uptime)
	  -h         this help

	Written 2003 by chris@hedonism.cx

	This program is used as an external data-gatherer
	for MRTG. It gathers the loadavg of the machine
	and is currently linux-specific (uses /proc/...)

	Use is like this (mrtg.cfg):
	 Target[load]: `/usr/local/mrtg/bin/linux_loadavg_mrtg`

	MRTG is (c) by Tobias Oetiker  <oetiker@ee.ethz.ch>
	http://people.ee.ethz.ch/~oetiker/webtools/mrtg/

Sample output
-------------

A sample output of this program looks like this:

	0.000000		<-- current system load
	0			<-- always '0'
	Up 4:00:49:00		<-- uptime in days:hours:mins:secs
	pi2105			<-- hostname


Copyright (or lack thereof)
---------------------------

This program has been written by me, Christian Vogel, in 2003 and is
placed in the public domain.

	Chris <chris@hedonism.cx>, 16.7.2003