SquirrelSAP
Ron Smith, MD


About SquirrelSAP
----------------------------------------------------------------------

The project was inherited by me from Limelyte who in turn had inherited it from someone previous under the GPL. I developed it much further to accommodate both 2.6x and 3.x versions of Spamassassin. It continues under the squirrel-sa-sql project on SourceForge under the Open Source license thereto though I affectionately call it 'SquirrelSAP.'

With these versions of Spamassassin, MySQL was used to store individual user settings for Spamassassin. Spamassasssin and MySQL setup is beyond the scope of this document, but the key features of SquirrelSAP are as follows:

1. Whitelisted email addresses, and domains with wildcard support
2. Blacklisted email addresses, and domains with wildcard support
3. Custom spam marking threshold
4. Option to use (or not) subject prefixing for marked spam
5. Option to use (or not) the make spam safe option (Report_safe in SA)

Certain features are NOT present becasue they are not present in Spamassassin. Specifically, SA does NOT have a discard threshold. (That would be on my wish list too!). You'll have to address any automatic discards within your email platform. It should be easy to do however because you can use the SA scoring as the discard filter. As SA continues to improve, then I'll continue to add features, such as an automatic discard.

To add features, feel free to modify the code to suit you. In my case, my mail server setup already has a discard threshold feature separate from SA but which I will likely incorporate in my personal version of SquirrelSAP.


Compatibilty & Requirements
----------------------------------------------------------------------

These php scripts should be compatible with both the latest 4.x and 5.o.x versions of php. They do NOT rely on registering globals as previous incarnations did.

The latest 3.x and all 4.x versions of MySQL should work fine. I see little reason to think that most versions of SQL wouldn't work also as long as its compatible with Spamassassin.

Spamassassin 2.63 and later are compatible (and selectable in the configuration).


Converting From SpamAssassin 2.6.x to 3.x.x 
----------------------------------------------------------------------

The main difference between the sql configuration between these two versions of which you should be aware is the subject rewriting feature. For version 3.x.x the preference field is 'rewrite_header Subject' as opposed to 'rewrite_subject' in version 2.6.x. The value field for version 3.x.x is that actual string that is prefixed into the subject where it is either a 0 or 1 in version 2.6.3. The subject prefix string in 2.6.3 is specified in the local.cf file. So in version 3.x.x each user could actually have their own specific subject prefix. SquirrelSAP however does not support individual user-specfied prefixes. For version 2.6.x, you specify that in the local.cf or as a $Global preference in sql where you manually configure that...see the Spamassassin pages at http://wiki.apache.org/spamassassin/UsingSQL for more information. For version 3.x.x however you specify this in the configuration settings as described below.

Here's what you have to change in the sql databases. You'll need to do this manually through sql.

Version       preference                value          maining
SA v 2.6.x    rewrite_subject           0              subject rewrite off
SA v 2.6.x    rewrite_subject           1

SA v 3.x.x    rewrite_header Subject    xx.. _SCORE_   subject rewrite on
SA v 3.x.x    rewrite_header Subject    {blank}        subject rewrite off


Future Improvement Considerations
----------------------------------------------------------------------

We've had at least one request for the ability to upload whitelist and blacklist files. Specific subject prefixing might be useful for individuals, but might not fit with the specific mail provisioning setup. The difficulty in providing the advanced features of spamassassin to the average user is that most will be overwhelmed by the offerings. Perhaps we will provide both a basic and advanced user interface that is user-selectable in the next version.


Step-by-Step
----------------------------------------------------------------------

Step 1. Set up MySQL (or your preferred SQL database) to match your configuration above. Remember that the local.cf file MUST have matching settings for SA to also access the user preferences. (You can set defaults also in your database if you prefer. Check the Spamassassin documentation for specifics.)

Step 2. Copy the tar file to the plugin folder in SquirrelMail on your web site. Untar it there. I suggest that you name the plugin folder 'spamassassin' but you may do whatever floats your boat.

Step 3. In the untarred files, locate the config.php file. Use the sample settings included in this document to configure it for your particular setup.

Step 4. Using a terminal application with appropriate privileges, and with your directory location IN the SquirrelMail folder, execute the following in the command line:

./config/conf.pl

Step 4. Choose the Plugins selection and then choose the 'spamassassin' selection. Save the changes. Then Quit.


Test It
----------------------------------------------------------------------

Log into Squirrel Mail and click Options. Then click on SPAM Tagging Options. Make your configuration selections and add allowed and denied email addresses to suit you.

Sample Configuration Options
----------------------------------------------------------------------

// dbhost - the name of the server running MySQL
// MySQL need not be on the same host as SA, but is recommended

$spam_dbhost = "mail.pmbx.net";

// Enter the correct MySQL account info
// dbuser - the MySQL username allowed access to this database

$spam_dbuser = "your_mysql_username";

// dbpass - the MySQL password for $dbuser

$spam_dbpass = "your_mysql_password";

// dbname - the database name for storing the SpamAssassin settings
// your MySQL database MUST match this name

$spam_dbname = "spamassassin";

// satable -    the table name that holds the SpamAssassin settings
// your MySQL table MUST match this setting

$spam_satable = "userpref";


// Postmaster/Sysop Settings
// SA Defaults - SHOULD match YOUR local.cf settings
// spam marking threshold

$required_hits_default = 5.000;

// subject prefixing - make this match your local.cf Spamassassin file
// or your $Global sql preference

$rewrite_subject_default = 1;
$rewrite_subject_prefix = "xx.. [score] ..";

// report safe
$report_safe_default = 0;

// Version os Spamassassin - 2.6x or 3.x.x
// Uncomment the Spamassassin version you're running 

$sa_version = "2.6x";
//$sa_version = "3.x.x";


Changlog
----------------------------------------------------------------------
1.0.5 - Fixed an issue where the subject rewriting function would not work for Spamassassin 3.x.x
1.0.4 - Fixed a minor problem with the regular expression processing of whitelist and blacklist addresses.
1.0.3 - Initial published version
1. Rewrote the entire GUI. Added online documentation.
2. Removed all dependencies on registering globals.
3. Compatible with php 5 and the latest php 4 releases.
4. Full support for Spamassassin wildcards in whitelisting and blacklisting.
5. Support for Spamassasin version 2.63 and 3.x.
6. Compatible with most if not all SQL databases.
7. Whitelisting, blacklisting, spam marking thresholds, subject prefixing, and make spam safe.