FAQs

qmrtg version 2.1


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


FREQUENTLY ASKED QUESTIONS


Q) What's the relationship between QMRTG and MRTG?
A) In the job of displaying graphically statistics, the information
to graph is first extracted and then displayed. QMRTG is who extracts
the actual information from a set of raw log files. MRTG is who
depicts this information graphically.
With more details, QMRTG handles extracting out "new" entries
from several log files, and analyzing them in ways to get actual
informations like "the mean number of concurrent users in the server".
On the other hand, MRTG takes the numeric result of QMRTG work and
graph it in an image.
MRTG is an external tool and is not responsability of the QMRTG project.


Q) How do I put QMRTG on a stanalone MRTG instance?
A) easy.
Create a home tree for the new mrtg instance:
$ mkdir /var/www/stats/mrtg-qmrtg/cfg
(you can choose another place, but the "cfg" subdir must exist)
In the qmrtg package you find the file "mrtg.cfg". It's a
configuration template for mrtg.
Set this path (without the "/cfg" suffix) into the mrtg.cfg file,
replacing the string
    ->  "##--QMRTG--MRTG_DOCUMENTROOT--#".
[ If you have unusual qmrtg paths, consider looking at the qmail
queue path specified as argument for qmail-queue in the "queue-size" target]
Copy the mrtg.cfg file into the cfg subdir:
$ cp mrtg.cfg /var/www/stats/mrtg-qmrtg/cfg
Tell cron to schedule mrtg every 5 (or more) minutes:
$ crontab -e
adding a new line
*/5 * * * * root mrtg /var/www/stats/mrtg-qmrtg/cfg/mrtg.cfg

There's a "html/" dir in the qmrtg package. It contains some html
templates you can quickly customize to get qmrtg fully deployed on
the web in a few minutes.


Q) Can I run QMRTG as an unprivileged user?
A) Sure. But there are two obvious requirements to get that:
    1) the qmail queue analyzer module needs credentials to access
    the queue directory, which by default are not granted to unprivileged
    users. To work around this you can run qmrtg unprivileged and
    mark the qmail queue analyzer setUID
    2) all the remaining analyzers need read access on all the log
    files the operate to
So, if you want qmrtg to run unprivileged you either give up
the queue analysis or set the queue analyzer (qmrtg-queue) setuid.
I suggest the second way. So, this is how to do it:
    1) choose a user to run qmrtg as (we'll call it "qmrtg" here),
    or create it:
    # adduser qmrtg
    set the home directory of this user to qmrtg's database directory
    (what you have as QMRTG_DBPATH in qmrtg's configuration file)
    2) change ownership for the database directory:
    # chown -R qmrtg ~qmrtg
    3) change ownsership for the MRTG working directory (your QMRTG
    DocumentRoot):
    # chown -R qmrtg /var/www/stats/mrtg-qmrtg/   [ replace dir as necessary ]
    4) set the set-user-ID on qmrtg-queue
    # chmod +s /usr/local/bin/qmrtg-queue
    5) put hands on your crontab and let mrtg run as the "qmrtg" user.
    Edit contab's line:
    */5 * * * * root mrtg /var/www/stats/mrtg-qmrtg/cfg/mrtg.cfg    [ before ]
    to
    */5 * * * * qmrtg mrtg /var/www/stats/mrtg-qmrtg/cfg/mrtg.cfg    [ after ]

and you're done.


Q) Why does qmrtg report such a high peak at its first run?
A) You didn't bring its timestamps database in sync before
running it. Run the following command at the first time or whenever
you bring qmrtg back to activity after a long down:
$ qmrtgsync.sh


Q) Where do I find more analyzers?
A) There's not yet a formal place for this yet. Simple analyzers (like the
ones based on regular expessions) would probably not even be shared among
users as takes more time posting them than writing them :).
More complex analyzers can be proposed on the project mailing list
qmrtg@lists.dev.publicshout.org .
As some contribution arrive, making a public repository for them on the
web could be considered.


Q) I realized a new analyzer and I like to make it available to other
people. Who do I send it to?
A) such contibutions are greatly appreciated. Post everything to qmrtg's
mailing list qmrtg@lists.dev.publicshout.org . Please mind to include
your name/nickname and a short description of what the analyzer does.


Q) The analyzer I wrote needs some options on command line: can I use
it with qmrtg anyway?
A) Yes. Do what you do for every other module. Then, specify both the
command and the options instead of the command alone when enqueueing to
the ACTUALCMDS array. And be aware you need to specify all that
***between quotes ("")***.
Example: [..] "/usr/local/bin/myanalyzer -o foo -b bar" \ [..]
