$Id: ora_drv.txt,v 1.7 2006/05/13 01:12:58 jonz Exp $ ora_drv: Oracle storage driver for DSPAM Copyright (c) 2002-2006 Jonathan A. Zdziarski 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; version 2 of the License. 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 src/tools.ora_drv) 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 present 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