"eximstate" Documentation 
=========================

Copyright (C) Claranet UK Ltd. (2002) by Ollie Cook.  All Rights Reserved.
$Id: README,v 1.6 2002/11/19 19:36:55 ollie Exp $

Table of Contents
-----------------

 1.    Introduction
 1.1.  Availability
 1.2.  Support
 1.3.  Features
 1.4.  Requirements
 2.    Client
 2.1.  Configuration
 2.2.  Signals
 3.    Server
 3.2.  Configuration
 3.3.  Signals
 4.    Logging
 5.    Graphs
 6.    Exitop
 7.    Debugging

==========================================================================

1.       Introduction
---------------------

  I started this project for two reasons. The first was that there was no software
  available for monitoring an Exim mail server and the second was an email from
  Yann Golanski on the exim-users mailing list[1], an excerpt from which I include
  here:

    "What is usefull and you can do is a reporting system that will tell
    managers states about their system. Think MRTG, but with mail info like
    CPU usage, memory, disk IO, spool size, frozen messages, number of
    processes, etc... Now that's usefull and pretty. Hell, you can even do
    some states on the log files like Existat and present it in a nice web
    form. That would be very usefull. Oh, if you choose to do that, please
    do not write it in some scripting language (perl, python, sh, tcl...) as
    they will hit the system too hard to get anything of value and they will
    be slow as hell. C is the ideal choice there."

  However, eximstate does not aim to monitor all the items in Yann's list, for
  the following reason: good tools already exist to monitor CPU usage, spool size
  etc. (ucd-snmp for example). eximstate only monitors the state of Exim itself,
  in terms of the size of its queue.

1.1.     Availability
---------------------

  eximstate will be available from my website when it is released:

    http://www.olliecook.net/projects/eximstate

1.2.     Support
----------------

  There is a mailing list set up for discussion of eximstate where questions
  can be asked. Details of how to join the mailing list are on the website.

1.3.     Features
-----------------

  There are four distinct parts to the eximstate package:

    -   client
    -   server
    -   graphing utility
    -   exitop console utility

1.4      Requirements
---------------------

  The eximstate package depends on Tobias Oetiker's RRDtool[2] for both data
  storage and the drawing of the graphs.

  RRDtool is ideal for this purpose as it stores the data in a compact format
  and has powerful built in graphing capabilities.

2.       Client
---------------

  The client runs on each of the mail servers that you want to monitor. It is a
  daemon process which comes to life at regular intervals and counts the number
  of items that are in the mail queue on the server, and how many of those
  messages are frozen or are bounces. It writes this information to its log file
  and also sends this information to the server for permanent storage in a
  database.

  The client can cope with Exim's split_spool_directory option.

  The client is designed to be fast and to not impact the performance of the mail
  server's normal operation in any way.

	You may specify a difference configuration file at runtime with the -c flag.

2.1      Configuration
----------------------

  The configuration file format for each line in the configuration file is
     
    <key> <whitespace> <value>

  Lines starting with whitespace or a comment character '#' are ignored.

  The following configuration keys exist, and must be specified in the configuration
  file (/usr/local/etc/eximstate.conf):

    exim_input_directory <string>            The directory where Exim's -H spool header
                                             files are stored, or in the case of a split
                                             spool, the directory with the sub-spools. 
    
    sample_interval      <integer>           The number of seconds between scans of the
                                             spool. If anything other than 300 the RRD
                                             database definition will need to be changed.

    pid_file             <string>            Path to the PID file.
 
    port                 <integer>           The port to contact the server on.

    host                 <string>            The host the server is running on.

    identity             <string>            The unique identifier for this host.

	You may specify a difference configuration file at runtime with the -c flag.

2.2.     Signals
----------------

  Upon receipt of a HUP signal, the configuration file will be reread. If an error is
  encountered rereading the configuration file, the client will exit.

  All other signals cause the monitor to exit.

3.       Server
---------------
 
  The server is installed on the monitoring server, or in a single host environment
  on the same host as the client. The server listens for incoming connections from
  clients and stores the information it is sent in RRD databases.

3.1      Configuration
----------------------

  The configuration file format for each line in the configuration file is
     
    <key> <whitespace> <value>

  Lines starting with whitespace or a comment character '#' are ignored.

  The following configuration keys exist, and must be specified in the configuration
  file (/usr/local/etc/eximstated.conf):

    pid_file             <string>            Path to the PID file.
    
    port                 <integer>           The port to bind to and listen on.

    data_dir             <string>            The directory where the RRD databases
                                             are kept.

    timeout              <integer>           Number of seconds to wait since last
                                             valid command (or connection) before
                                             marking client for disconnection.

3.2.     Signals
----------------

  Upon receipt of a HUP signal, the configuration file will be reread. If an error is
  encountered rereading the configuration file, the server will exit.

  Although the server will have read a (possibly new) port number, it will not unbind
  from the old port, and will not bind to the new port. The data_dir will take immediate
  effect, though.

4.       Logging
----------------

  Both the client and the server log via syslog to the LOCAL3 facility. It is recommended
  you configure syslogd to put this output in a separate file and set up adequete log
  rotation.

5.       Graphs
---------------

  The third part of the eximstate package is responsible for making graphical
  representations of the data stored in the database.

  By default, for each host, a graph will be drawn showing the number of
  messages on the queue, how many are frozen, and how many are bounces over the
  last twenty-four hour period.

6.       Exitop
---------------

  Exitop is a console utility, similar to NOCOL[3], which can be on the server host.
  At intervals it reads the .rrd databases and presents the last measurements of total,
  frozen and bounce message counts for each host.
  
  The time of the last snapshot is displayed on the screen, unless there are insufficient
  rows to have one line per host and the data. If there are insufficient rows for all 
  the hosts even missing off the date, exitop will exit.

7.       Debugging
------------------

  eximstate and eximstated can be started with the -x flag which will cause them not
  to daemonise and to send debugging information to standard error.

==========================================================================

[1] - http://www.exim.org/mailman/htdig/exim-users/Week-of-Mon-20010903/029773.html
[2] - http://people.ee.ethz.ch/~oetiker/webtools/rrdtool/
[3] - http://www.netplex-tech.com/software/nocol/
