$Id: UPGRADING,v 1.4 2005/01/19 19:51:15 jonz Exp $

UPGRADING FROM 3.2.5 TO 3.2.6

In v3.2.6, the default level of statistical sedation has been changed from
5 to 0 (off). This feature is normally overridden by dspam.conf, but if you
have removed the feature from the default configuration, this may change
DSPAM's behavior. To ensure that nothing changes in your filter's behavior,
make sure the following line is in your dspam.conf:

Feature tb=5

UPGRADING FROM 3.2.X TO 3.2.4

The only notable change to be made in upgrading to 3.2.4 from an existing
3.2 version is an additional index used in PostgreSQL systems. Apparently,
the lack of this (unnecessary) index confuses the PostgreSQL query builder.
Adding this index appears to make a noticeable improvement in performance:
 
CREATE INDEX id_token_data_04 ON dspam_token_data(uid);

With this exception, 3.2 versions of DSPAM may be upgraded with a simple
make install.

UPGRADING FROM 3.0 TO 3.2

Version 3.2 incorporates many changes to way DSPAM is configured. Many
functions have been moved out of DSPAM's configure script and into the new
dspam.conf file.

IMPORTANT: Installation directories have been standardized; therefore the
default dspam home is now /usr/local/var/dspam. You'll need to specify
the old home using --with-dspam-home, or adjust your filesystem to match.

Summary of changes:

Configure options:

  --with-dspam-home			support added to dspam.conf
					configure option writes to template
  --with-delivery-agent			moved to dspam.conf
					configure detects, adds to template
  --with-quarantine-agent		moved to dspam.conf
  --with-dspam-home[-mode,owner,etc]	moved to dspam.conf; defaults created
  --with-logdir				added, default DSPAM_HOME/log
  --disable-factors			moved to dspam.conf
  --enable-signature-headers		moved to dspam.conf
  --enable-signature-attachments	removed entirely
  --enable-spam-subject			moved to dspam.conf
  --enable-homedir-dotfiles		replaced with --enable-homedir	
  --disable-system-logging		moved to dspam.conf
  --disable-user-logging		moved to dspam.conf
  --enable-webmail			moved to dspam.conf (TrainPristine)
  --enable-opt-in			moved to dspam.conf
  --enable-source-address-tracking	moved to dspam.conf
  --enable-parse-to-headers		moved to dspam.conf
  --enable-broken-mta			moved to dspam.conf
  --enable-broken-return-codes		moved to dspam.conf
  --enable-broken-case			moved to dspam.conf
  --enable-chi-square			support added to dspam.conf (chi-square)
  --enable-robinson			support added to dspam.conf (robinson)
  --disable-traditional-bayesian	support added to dspam.conf (graham)
					configure now --disable-graham-bayesian
  --disable-alternative-bayesian	support added to dspam.conf (burton)
					configure now --disable-burton-bayesian

Data files which are now also supported in dspam.conf:

     default.prefs			supported or can specify in dspam.conf
     untrustred.mailer_args		moved to dspam.conf
     .debug files			moved to dspam.conf
     [driver].data			backward-compatible; moved to dspam.conf

   Commandline arguments:

     --mode				commandline or dspam.conf
     --feature				commandline or dspam.conf

Other Important Changes:

     1. The --enable-homedir option has been changed to store user data in
        ~/.dspam. If you were previously using homedir-dotfiles, you will
        need to move the user's data files into ~/.dspam. 

        NOTE: The --enable-homedir option is incompatible with the DSPAM CGI,
              and requires that dspam run as setuid root. 

     2. .nodspam and .dspam files now work a bit differently in HOMEDIR mode.
        If the .dspam directory (which is created automatically) exists,
        the user is opted-in, so you'll need to create .dspam directories in
        each user home instead of touching .dspam files.

        Since the directory now contains all the user's data, you'll need to
        touch a .nodspam file to temporarily opt-out a user. If both files
        exist, the user will be opted-out.

     3. Debugging logs are now stored in logdir. The default is /var/log.
        If you are not installing DSPAM as setuid root, you may want to
        change this using --with-logdir=

     4. New attributes and preferences added. See CHANGELOG for details.

     5. configure will no longer allow you to compile both Chi-Square and
        Bayesian algorithms together. This is because the combination
        produces many false positives and most people who try it can't 
        figure out why. To use Chi-Square, you will now HAVE to disable
        both bayesian calculations.

The best course of action for upgrading is to create a suitable dspam.conf
file based on the template provided and allow DSPAM to install it during
a make install. You may then work on phasing out your older files (which are
backward-compatible). 

POSTGRESQL

Rustam Aliyev recently discovered that turning off OID support for large
tables is both recommended and greatly speeds up access (by about 500%!).
The PostgreSQL table definitions have been updated to create tables WITHOUT 
OIDS, but existing database users should:

   ALTER TABLE dspam_token_data SET WITHOUT OIDS;
   ALTER TABLE dspam_signature_data SET WITHOUT OIDS;
   ALTER TABLE dspam_stats SET WITHOUT OIDS;
   ALTER TABLE dspam_neural_data SET WITHOUT OIDS;
   ALTER TABLE dspam_neural_decisions SET WITHOUT OIDS;
   ALTER TABLE dspam_preferences SET WITHOUT OIDS;
   ALTER TABLE dspam_virtual_uids SET WITHOUT OIDS;
   VACUUM ANALYSE;  
 
MYSQL

Support for MySQL v4.1 has been added, which makes some significant
improvements to how the database can be managed. If you're running v4.1,
it is recommended that you:

   1. Enable preferences extension support and recompile, allowing you to use
      the new purge-4.1.sql purge script which performs safer purging for
      TOE and TUM users. You'll need to move your user preferences from
      .prefs files to MySQL using dspam_admin. You will also want to declare
      ALL global databases as TOE, so that they are not purged for stale
      information. You can do this using:

      dspam_admin add pref [username] trainingMode TOE

   2. Update some important characteristics of the database:

      alter table dspam_token_data modify token bigint unsigned;
      alter table dspam_token_data PACK_KEYS=1;
      create index id_token_data_04 on dspam_token_data(uid);

      and if you haven't done so from previous versions:

      alter table dspam_token_data DELAY_KEY_WRITE=0; 

      NOTE: This may take a while, so please prepare an adequate amount of
      downtime for your database.

   3. Switch to purge-4.1.sql. This performs safer purging for TOE and TUM
      users.

