README

qmrtg version 2.1


qmrtg is a tool to analyze qmail's activity with the goal
to graph everything through MRTG.
See the INSTALL.txt file for more infos about how to install qmrtg.
See the LICENSE.txt file for more infos about its license.
The official home is http://dev.publicshout.org/qmrtg/ .


WHAT IS QMRTG

qmrtg means QmailMRTG.
Qmrtg is a set of tools that can extract informations from
qmail log files, the "analyzers".
The output of any analyzer, properly filtered, is meant to
feed MRTG.
MRTG is a monitoring tool. It gathers streams of data and
represent them through nice graphs. With MRTG graphs it is
prompt to get an idea of the status of a server. Take a look
at the MRTG webpage for more about it:
http://people.ee.ethz.ch/~oetiker/webtools/mrtg/ .


HOW QMRTG WORKS

qmrtg analyzers are not meant to be directly called by the
user (or by MRTG). There is a user interface (UI) for that.
What this UI expects from the user is just the name of
the statistical analysis to perform (called "target").
The list of targets recognized by qmrtg is tuneable by
looking in its configuration file qmrtg.conf.

The UI will find which part of log files contain entries
that haven't been analyzed yet, and calls the proper analyzer
for all of them.

Analyzer from the original qmrtg package have commonly a
name like "qmrtg-something". They're written in C.
The qmrtg user interface is called "qmrtg.sh". It's written in
bash.

If you want to extract how many messages went through your server
since the last time you checked, you run qmrtg.sh this way:
	$ qmrtg.sh messages
If the target is recognized, qmrtg finds the command set for
serving it, and the multilog-generated log directory from
which taking log files.


What does happen with such a call?
Roughly, qmrtg.sh does what follows:
1) it gets the timestamp of the last log entry analyzed. It's been
computed and saved after the previous run.
2) it finds the first logfile that could possibly contain log entries
after that timestamp, skipping the ones it's sure can not.
3) it executes the analyzer itself, by passing it just those
log lines of the file that are newer than the timestamp stored.
The analyzer outputs as follows (one per line):
	1) the first variable ("IN" for MRTG). Here, the number
	of messages delivered to locals.
	2) the second variable ("OUT"). Here, the number of
	messages delivered to remotes.
By convention, qmrtg.sh expects analyzers to return 0 for status ok,
non-zero on errors.
4) increments the grand total variables (IN and OUT for MRTG) with
the output of this execution of the analyzer, so that they correctly
keep the whole history since the last execution of qmrtg.sh
5) updates the "messages.last" db file
6) checks for other log files containing other stuff to analyze.
If it finds one, it starts again from step 3.

And so on.


HOW DOES QMRTG INTERFACE TO EXTERNAL/CUSTOM TOOLS or ANALYZERS

With the set of analyzers provided by the qmrtg package you wouldn't
probably have to write your own. Think if you can carry out your
goal with one of them (usually qmrtg-regex covers 90% of the
necessities). You would be successful in matter of seconds!
If you have some specific requirement, then go ahead.
The UI is tought in a manner that makes it quick and easy to extend
the set of analyzers with custom ones. They are simply processes,
and qmrtg doesn't care about their essence (scripts or binaries).
For example, you could want to monitor how many times a log entry
referring a particular IP address has been recorded by the smtp
daemon since the last time you checked. With qmrtg, you can do this
with a bash script shorter than 10 lines.
It does just care that qmrtg is permitted to execute it.

You can write your own analyzer. If it respects the interface of
qmrtg for both its input and its output, it will work with qmrtg.
Your module is asked for:
1) accept the log lines from standard input
2) output at least 2 plain-text lines, both positive integer values.
If you only mind one value and not two, output "0" for the second one.
If a 3rd argument is provided, it's expected to be a string valid
to be compared with TAI timestamps. This is what qmrtg will store in
its "last entry" timestamp database for your analyzer. Otherwise,
qmrtg will handle saving such timestamp by itself.
3) run for a finite (better short) amount of time. This is subjective,
you could say. Yes, in fact this isn't a qmrtg.sh-specific requirement.
To provide numbers, analyzers should handle whatever amount of parsing
(up to less than megabytes is something realistic) in matter of seconds
(so less than one minute).
This is a MRTG requirement. You'll get a nice DoS if you use qmrtg with
modules that make it hang.

Once made that, try testing it outside qmrtg, as "standalone". You
know what it expects.
If it complies qmrtg's interface, you made nearly everything you need.
You just left to tell qmrtg about yout script:
1) edit the qmrtg.conf configuration file (commonly in /etc or /usr/local/etc).
Find where's defined the "ACTUALCMDS" option.
2) add the full path of your script *on the last line before the closing bracket*.
If you place it somewhere else, you mess up the other tools too.
3) find where's defined the "AVAILCMDS" option.
4) add the name of your analyzer *on the last line before the closing
bracket*. If you place it somewhere else, you mess up the other tools too.
The name is a string that conceptually points out what your analyzer
does or regards.
5) find the LOGDIRS option and entail to it the directory by which the
analyzer should be fed logs

and it's done. Test it inside qmrtg.sh and see if it works. Test it inside
MRTG and see if it works.

Please consider contributing your analyzer to the qmrtg mailing list
(see below), so that other users can take advantage of your work.


WHOM DO I CONTACT FOR QUESTIONS etc RELATED TO QMRTG?
IS THERE A MAILING LIST SUPPORTING QMRTG USERS?
WHERE DO I FIND MORE INFORMATIONS ABOUT QMRTG?

Try with the author. Mij <mij@bitchx.it>
He won't prepare a ml if the traffic is low (a mail a month or less).
You can always find other informations on the project webpage at
http://dev.publicshout.org/qmrtg/ .
you will also find a faq page possibly containing other precious
informations.
