mysql_drv: MySQL storage driver for DSPAM <jonathan@nuclearelephant.com>
Copyright (c) 2003 Network Dweebs Corporation
http://www.nuclearelephant.com/projects/dspam/

LICENSE

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; either version 2
of the License, or (at your option) any later version.

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., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.

ABOUT

mysql_drv is a MySQL storage driver for DSPAM v2.7 and above.  This driver
enables DSPAM to read and write all token, signature, and statistics data
from a MySQL database.  The advantages of using a SQL backend are obvious:

- Centralized data storage
- Structured queries for information
- No need for context locking mechanisms
- Replication and other MySQL features

CONFIGURING DSPAM

To configure DSPAM to use mysql_drv, use the following arguments while running
DSPAM's configure:

--with-storage-driver=mysql_drv 
Tells DSPAM to use the mysql_drv driver

--with-mysql-libraries=/path/to/libs
Tells DSPAM where to find the MySQL client libraries.  They are usually
located in /usr/local/mysql/lib

--with-mysql-includes=/path/to/libs
Tells DSPAM where to find the MySQL headers.  They are usually located in
/usr/local/mysql/include

--enable-virtual-users
Tells DSPAM to create virtual user ids for each dspam user.  Use this if your 
users don't really exist on the system (e.g. via getpwuid) or if you're doing
something weird like sharing uids.

After configure has successfully finished, build and install DSPAM using the
instructions from DSPAM's readme.

CREATING MYSQL OBJECTS

Before mysql_drv will function, you must run one of the mysql_objects.sql files
(located in the same directory as this readme) to create the table objects 
required by the driver.  Depending on whether you are looking to optimize for
speed or disk space, you should run the appropriately named script.
See your mysql documentation for further information.

If you plan on enabling virtual users (something you'll need to do if the users
don't actually exist on your system), also run virtual_users.sql.

Finally, run blackbox_objects.sql if you plan on compiling DSPAM with
black box support (management GUI and ASP support).

NOTE: The MySQL objects use a delayed key write for best performance.  As a
result, you should use the --myisam-recover option when starting MySQL

CREATING A CONNECT DATA FILE

mysql_drv needs to know how to connect to your MySQL database.  You will
need to create the file 'mysql.data' in DSPAM's USERDIR directory (default
is /etc/mail/dspam).  This file should contain the following fields in this
format;

HOSTNAME
PORT
USERNAME
PASSWORD
DATABASE

An example mysql.data file might look like:

127.0.0.1
3306
dspam
1234
dspamdb

Or if you'd like to connect using /tmp/mysql.sock, for example:

/tmp/mysql.sock

dspam
1234
dspamdb

DSPAM checks to see if the first character of the HOSTNAME field is a slash, 
and if so will treat it like a socket file.

Be sure this file is group readable by the group set for dspam (ls -la 
/usr/local/bin/dspam).

NIGHTLY PURGE

mysql_drv does not have a purge binary.  Instead, if you would like to purge 
the many stale tokens DSPAM will have lying around the database, you should 
run the purge.sql script nightly.  The dspam_clean tool should also be 
configured to clean old signatures from the database.  See DSPAM's README for 
more information about the dspam_clean tool.

ERRORS

Any SQL errors will be reported to /tmp/sql.errors as well as the standard
syslog facilities (although the query will be truncated).

QUESTIONS

Please contact the dspam-dev mailing list with any questions or constructive
feedback.

Jonathan A. Zdziarski
<jonathan@nuclearelephant.com>
