pgsql_drv: PostgreSQL storage driver for DSPAM
API v3.0
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

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

- Centralized data storage
- Structured queries for information
- No need for context locking mechanisms

REQUIREMENTS

pgsql_drv storage driver requires PostgreSQL version 7.3 or higher.

CONFIGURING DSPAM

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

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

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

--with-pgsql-includes=/path/to/libs
Tells DSPAM where to find the Postgres headers.  They are usually located in
/usr/local/pgsql/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 PGSQL OBJECTS

Before pgsql_drv will function, you must run pgsql_objects.sql file
(located in the same directory as this readme) to create the table objects
required by the driver.

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.

CREATING A CONNECT DATA FILE

pgsql_drv needs to know how to connect to your PostgreSQL database. You will
need to create the file 'pgsql.data' in DSPAM's USERDIR directory (default
is /var/dspam).  This file should contain the following fields in this
format;

HOSTNAME
PORT
USERNAME
PASSWORD
DATABASE

An example pgsql.data file might look like:

127.0.0.1
5432
dspam
1234
dspamdb

Or if you'd like to connect using /tmp/.s.PGSQL.5432, for example:

/tmp

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

pgsql_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 may also be
run for deeper cleansing.  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.

Rustam Aliyev
<rustam@azernews.com>
