INSTALL

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 (in the "doc/" directory) for more about qmrtg.
See the LICENSE.txt file (in the "doc/" directory) for more about its license.
The official home is http://dev.publicshout.org/qmrtg/ .

HOW TO INSTALL

First, note that installing qmrtg from packages (deb and rpm are
going to be provided in the future) or freebsd ports is strongly
recommended. They will provide a cleaner, simpler, faster installation.


If you otherwise choose to install qmrtg from sources, that's what
you have to do.

1) get qmrtg.
You can get the stable version from
http://dev.publicshout.org/qmrtg/download
and decompress the tgz package with the command
$ tar xzf qmrtg-#whatever#


2) compile qmrtg.
Recommended to be done as unprivileged user.
$ ./configure
$ make
# [ as superuser: ] make install


3) prepare an home for the qmrtg stuff.
[This will be done by the qmrtg/mrtg setup script if you alreay
have a working mrtg system. Skip this step in this case, and jump to
point 4.]
# mkdir -p /var/db/qmrtg
you can choose a different place (linux users may prefer "/var/lib/qmrtg").
If you do, you must update the corresponding setting in the configuration file "qmrtg.conf", entry "QMRTG_DBPATH".
Possibly chown this directory to the user you mean to run qmrtg as.
If you run qmrtg as an unprivileged user, make sure all its analyzers
have reading access to the log files they're fed with


4) configure qmrtg.
Provide the system a qmrtg.conf configuration file (by default it's expected
to be in /usr/local/etc). There's a good template in the "examples/"
directory inside the qmrtg package. Look in particolar if the following
options are adequate for you (they are well explained by comments):
- QMRTG_DBPATH
- VERBOSITY_LEVEL and DEBUG
- *especially*: LOGDIRS
once you're done, use the qmrtgcheckconf.sh script to check the config file.


5) prepare qmrtg to run.
Qmrtg works incrementally. This means that if a run comes late a few seconds (or minutes etc), you won't loose data.
Qmrtg remembers the last log entry analyzed via some db files. If they
aren't available (as will be the first time you install it), qmrtg
will return the whole history of your MTA, which could be a bit violent
to the report graphs you're setting up.
To skip this behaviour, you may run the proper script provided:
$ qmrtgsync.sh
(an "usage message" will be returned, read it and call the tool again
with the form it requests)

you can ** uninstall ** qmrtg whenever you like using the uninstall facility:
as superuser - root:
$ make uninstall


6) qmrtg unprivileged.
You may also want to make QMRTG run as unprivileged user
for further security. If you do, look at the corresponding
Question in the FAQs.


7) -optional-
consider notifying that qmrtg has one more user:
http://dev.publicshout.org/qmrtg/usersbook/


SETTING UP MRTG TO USE QMRTG
8) You have two chances.
The first is the way supported and recommended: qmrtg
is dedicated a qmrtg instance for its own.
The second way is using an existent mrtg instance for
displaying qmrtg reports too. This spares some cpu cycles,
but requires some manual merging of configuration files
I'd get bored to explain. :)

Having one mrtg instance dedicated to qmrtg is very easy.
For what regards the MRTG and web container setup have
a look at the corresponding Question in the FAQs.


##
qmrtg faqs: http://dev.publicshout.org/qmrtg/doc.html
qmrtg support: http://dev.publicshout.org/qmrtg/support.html

for submitting bugs, requests and other things related to qmrtg contact
Mij <mij@dev.publicshout.org>.
