NAME

dspam_ - Plugin to monitor various aspects of DSPAM performance

APPLICABLE SYSTEMS

Any system running a recent (3.8.0 or higher) DSPAM install.

CONFIGURATION

The plugin uses the output of the dspam_stats command, which is usually part of any DSPAM install. You'll need to run this plugin as a user that has enough rights to run dspam_stats and generate data for all users. This means that the plugin needs to be run either as root, or as a user that has read access to dspam.conf, and is added as a Trusted user in dspam.conf.

The following environment variables are used by this plugin:

 dspam_stats - Where to find the dspam_stats binary when it's not in
               $PATH (default: find anywhere in $PATH).
 statefile   - Where to read/write the statefile that is used to store
               dspam_stats output
               (default: $MUNIN_PLUGSTATE/dspam.state).
 warning     - When to trigger a warning (default: 95:).
 critical    - When to trigger a critical (default: 90:).
 pattern     - A pattern that is passed to grep in order to find the
               DSPAM uids to display. When this variable is set, the
               value of target (see USAGE) is ignored (default: empty).
 description - A string describing the set of uids selected by
               above pattern (default: empty).

Warning and critical values can also set on a DSPAM uid basis, use Munins internal format for the DSPAM uid for this notation (see CONFIGURATION EXAMPLES and USAGE for details).

CONFIGURATION EXAMPLES

 [dspam*]
 user root
 env.dspam_stats /opt/dspam/bin/dspam_stats
 env.statefile /tmp/dspam.state

 [dspam_accuracy*]
 env.critical 95:
 env.warning 96:

 # raise warning level for username@example.org
 env.username_example_org_warning 97:

 # show all accounts from one domain
 env.pattern @example\.org
 env.description domain example.org

USAGE

Link this plugin to /etc/munin/plugins/ and restart the munin-node. The link should be in the format: dspam_<graph>_<target>, where:

 graph      - One of: accuracy, processed, absprocessed, relprocessed.
 target     - The uid that DSPAM generates in dspam_stats output,
              but converted to Munin internal name format. Normally
              this means that non-alphabetic and non-numeral characters
              are replaced by an underscore. For example,
              username@example.org will become username_example_org.
              A special case is uid ALL, which will draw a graph for
              a total of all uids, or for a list of all uids (depending
              on the graph type).
              NB For advanced uid selection such as 'all users of domain
              example.org', please see the environment variable 'pattern'
              under CONFIGURATION.

INTERPRETATION

The plugin supports the following graph types:

 accuracy     - Shows the overall accuracy of all users as a
                percentage. The overall accuracy is the number of
                correctly classified messages (both ham and spam) in
                relation to the number of all processed messages.

 absprocessed - Shows the absolute numbers of messages processed,
                sorted by the classification that DSPAM uses. The
                numbers are stacked, making the height of the column
                display the increase of processed messages over time.

 relprocessed - Shows the same data as dspam_absprocessed_, but as
                messages per minute instead of ever-growing asolute
                values.

 processed    - Shows the same data as dspam_absprocessed_, but as
                percentage of the total amount of processed messages,
                making it clear to see how the amounts of classified
                messages are divided.

AUTHOR

Copyright 2010 Tom Hendrikx <tom@whyscream.net>

LICENSE

GPLv2

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; version 2 dated June, 1991.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.

BUGS

None known. Please report to author when you think you found something.

TODO LIST

Currently developed and tested with bash/dash on linux. More testing might be needed with other shells and OSes.

VERSION

$Id: dspam_ 72 2010-09-15 22:09:15Z tomhendr $

MAGIC MARKERS

 #%# family=auto
 #%# capabilities=autoconf suggest