$Id: README,v 1.1 2004/10/24 21:31:34 jonz Exp $

ora_drv: Oracle 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

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

- Centralized data storage
- Structured queries for information
- No need for external locking mechanisms
- Clustering and other Oracle features

IMPORTANT:

Before you can use the Oracle storage driver, you must have the Oracle 
Call Interface installed on the target machine.  If Oracle is running on the
same server as the machine you are configuring DSPAM on, this should have
already been installed.  If not, you will need to install this from the
Universal Installer.  Select a 'CUSTOM' installation of the Oracle Clients.
Scroll down and check "Oracle Call Interface".  This is necessary, as the
Oracle Clients do not install the OCI by default.

CONFIGURING DSPAM

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

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

--with-oracle-home=/path/to/home
Tells DSPAM where your Oracle Home is (or your client home).  DSPAM will use
this base directory to configure for the OCI libraries and headers.  It is
important that $ORACLE_HOME/lib be present in your MTA users' LD_LIBRARY_PATH,
otherwise DSPAM will not be able to locate the oci library at runtime.  You
can also create a symlink from $ORACLE_HOME/lib/libclntsh.so 
to /usr/lib/libclntsh.so if you do not wish to set the library path.

--with-oracle-version=MAJOR
Tells DSPAM the major Oracle version. This is only necessary if you're building
version 10, which requires an additional library to be linked in.

--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 ORACLE OBJECTS

Before ora_drv will function, you must run ora_objects.sql (located in
the same directory as this readme) to create the table objects required by
the driver.  See your Oracle 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.

CREATING A CONNECT DATA FILE

ora_drv needs to know how to connect to your Oracle database. You'll need to
specify this in dspam.conf. An example is already prevent in the file:

OraServer       (DESCRIPTION=(ADDRESS=(PROTOCOL=TCP)(HOST=127.0.0.1)(PORT=1521))(CONNECT_DATA=(SID=PROD)))
OraUser         dspam
OraPass         changeme
OraSchema       dspam

NIGHTLY PURGE

ora_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.

IMPORTANT! If you are supporting TOE-mode users on your system, you will want
to remove the following line from purge.sql:

delete from dspam_token_data
  where SYSDATE-last_hit > 90
/

This will prevent the absolute purging of stale tokens. All other purges should
be safe even for TOE-mode users.

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>

