Program written by venge@lokalsound.com 04/26/2002 Version 1.0b

Changes:
--------
version 1.0b (07/May/2002) 
- Initial version

version 1.01b (08/May/2002) 
- Minor fixes to wl[] and bl[] due to IE failing
- Added more documentation to cover permissioning problems
- Minor cosmetic changes to "Manage Spam Rules" table
- Sorted the "rules" list alphabetically, makes easier to find rules

version 1.1 (09/May/2002)
- Now run check to see if Hashing is enabled
- Changed the rewrite.pl script for automagically finding of userhome (thanks Logan!)
- Changed rewrite.pl so that is will automagically find your group
- Removed the need to specify SM_data_dir in main.php (if will find your data_dir now)

version 1.2 (10/May/2002)
- Version 1.1 broke the ability to use SM theme, this is now fixed
- Removed all un-needed chdir commands
- Added check in rewrite.pl to make sure that supplied user is actually on system
- Added security check for rewrite.pl so that any uid under 100 is not allowed, if you want to disable this, set the value to -1. (Or pick a lower/higher value based on your standard uid numbers)

version 1.3 (14/May/2002)
- If your .pref file has no theme line in it, uses the default colors of this program
- Added options to the rewrite.pl script (For below)
- Added option to disable (or re-enable) filtering (See Disable Section below)

version 1.31 (15/May/2002)
- Added  <a name> tag to the top of each table set. This puts you back to where you left off after a submit
- Fixed coding from 1.3 regarding .pref file not having theme line.

version 1.40 (04/June/2002)
- Added a link to add an email to your white/black list via the read_body.php screen
- These links will only appear if email is not already listed in your .spam file
- If an email address exists on the opposite list that you are adding to, it will be removed from other list
  (If you are adding 1@2.com to the whitelist, but it is already on the blacklist, it will be removed
   from the blacklist automagically, and vice versa)

version 1.41 (14/June/2002)
- Changed /usr/bin/suidperl to /usr/bin/perl -Uw (in rewrite.pl)
- Added an Options menu link
  (If you don't want the SpamAssassin link on the menuline, comment out
   the proper line in the setup.php file. I am considering making a Yes/No
   feature in the Display Options page to turn the Menuline on/off for 
   per-user basis control)
- If a <user>.spam file does not exist, the links for Add To are not shown
  (This prevents "grep" errors in your logs from showing up)

version 1.42 (17/June/2002)
- Small fix to setup.php which adds a separate include_once for prefs.php
  (This is for those that are getting warnings about uncalled functions)

version 1.43 (24/June/2002)
- Fixed problem where it would assume you had 4 levels of hashing
  (If you used 4 levels or do not use hashing, you do not need this patch)

version 1.50 (26/June/2002)
- Added support for those who want to use spamd/spamc in main.php
  (You need to set the variable in main.php to enable it)
- Changed rewrite.pl to support spamd/spamc

version 1.52 (05/July/2002)
- Now supports external config file (sa_config.php)
  (So you can upgrade versions w/o having to re-edit your defaults)
- Fixed rewrite.pl bug with spamc/spamd
  (Now a setable variable)
- Added a few checks to ensure variables are being passed and set correctly
  (Program will tell you if things are not ok)

version 1.60 (30/July/2002)
- Fixed problem with SPAM FOLDER having a name in it. Procmail file will now
  use quotes
- Removed the #find_* stuff from main.php, this was causing the page not to fully load
- Changed the display of the Spam Folder, so it will show the actual folder, not a parent folder
- Removed entries for MAILDIR= in main.php
- SM theme is now default
- Updated tests.list for SA version 1.31 
  (copy tests.220 to tests.list if you still use 2.20, 2.30 should upgrade to 2.31)
- New variable in sa_config.php for users with Maildir (Set to 1 to use)
  (this will add .<folder> instead of INBOX.<folder> to your .procmail-spamrc)

  (Thanks to Stephen Bader for following:)
- *BETA* support for DB.pref backend (no need to enable it, autosensing)
- Fixed up main.php coding for spamc/spamd
- Source of wrapper.c #include fixed (BSD should no longer complain)
- .forward support (spamd = 2 option)
  (This is very basic and will only write one if not found for that user)

version 1.61 (01/aug/2002)
- Changed the procmail-spamrc :0: to :0 H (header), this should now 
  not filter things if X-Spam-Status: Yes is in the body
  (This is seen if you filter your spam to a different folder)
- Actually fixed the Display of SPAM FOLDERS for Courier (the INBOX.FOLDER system) (CONFIRMED)
  (This will display just FOLDER instead of nothing)
- Actually fixed the .procmail-spamrc INBOX.FOLDER issue so it will put .FOLDER now (CONFIRMED)
  (Now just need to confirm that this plugin works with MailDir systems :] )

version 1.65 (22/aug/2002)
- Added 2 new options to $use_sf_spamd. (See sa_config.php.sample)
  * This will not allow the user to directly edit the file without losing changes to his/her config *
  * This feature has no real value than to keep user_prefs up to date with your user.spam file *
- Relative data_dir path fix now in use (Thanks to David Smith)
- Changed setup.php to look nicer and have smaller filesize (combined wl&bl functions)
- 1.3.x is now supported for the add wl/bl links

version 1.66 (23/aug/2002)
- pure php code (for .php files), cleaned up setup.php even more
- Changed so that if you are in your Sent folder, the wl/bl will check the TO: instead of FROM:

---------------------------------------------------------------------------------------
possibles in upcoming versions:

- Find a way for php to check to see if the spamd is running
  (If not, will automagically set $sf_use_spamd to 0)
- Find suitable color scheme for all themes (call external file)
- Finalize program with all bug fixes
- Add TODO (1) spam folder no longer existent [might not need to do]
- Add TODO (2) backup system

VERSION 2.x (??/??/????)
- Add "Razor" functionality (The manual reporting part of it)
- Rewrite the code (for speed improvements)
- Advanced features of spamassassin (create own rules)
- Possible support for qmail based systems (using virtual users)
- Allow user to define layout of tables


File List:
----------
.htaccess (controls the rewrite.pl and sa_wrapper files)
func.php (functions used by main.php)
main.php (main file)
menu_inc.php (contains the method for displaying the rule descriptions)
setup.php (Config file for SM to use this plugin)
tests.list (Text file with the rule descriptions)
rewrite.pl (SUID perl script that creates the .procmail files for user)
sa_wrapper (C program that calls the rewrite.pl file)
README (this file)
sa_config.php.sample (Sample external config file)

I have included the C source code for the wrapper program. If you do not want to use it, then just delete the source directory. You can use this if you don't like the rewrite.pl name. To rebuild the wrapper:
gcc -o <wrapper_name> wrapper.c

Make sure you change the exec in main.php for any instances of sa_wrapper.

Requirements:
-------------

- Squirrelmail
- *nix distro (should work on all flavors)
- suidperl (#!/path/to/perl -Uw   seems to work also)
- procmail
- an MTA that honors .procmailrc files in the user home directory
- spamassassin
- FULL PATH for your data_dir in your setup


Tested on:
----------

- SquirrelMail (v. 1.2.6)
- UW Imap 2000 (v. 2000c)
- Sendmail (v. 8.11.6)
- Procmail (v. 3.21)
- Apache (v. 1.3.22)

These are all stock Redhat 7.2 rpms. 


Installation:
-------------
extract the package (tar -zxvf spamassassin_1.0-1.2.6.tar.gz) into your SM plugins directory.
Run the SM perl configurator and under Option 8, add spamassassin to the installed list.
You should now see a link to Spamassassin up top (where Compose,Folder,Options... are)
Be sure to set the values for:

rewrite.pl (change any variable that is needed to reflect your system config)
(Note: you shouldn't have to modify this file at all anymore)

You might also have to change the #! line. (Find your perl "which suidperl"). If you do not have suidperl installed ("which perl") and set the #! to:

#!/path/to/perl -Uw

Permissions:
------------
*.php = change all .php files to your webserver user (Default apache)
sa_wrapper = C wrapper to run the rewrite.pl script as root (chown root.apache; chmod 4750 sa_wrapper)
rewrite.pl = Perl script to create the .procmail* files for user (chown root.root; chmod 4700 rewrite.pl)

Basically it should look like this:

ls -l sa_wrapper rewrite.pl
-rws------    1 root     root         1813 May  7 14:12 rewrite.pl
-rwsr-x---    1 root     apache      14093 May  7 14:14 sa_wrapper


**** This is a must ****

You must make sure that your $data_dir (and all of the hashes) are e(x)ecutable by everyone! (Not just apache). A sample data_dir would look like:

drwx--x--x   17 apache   apache       4096 Apr 19 18:25 .
drwx--x--x   18 apache   apache       4096 Mar 15 17:01 1
drwx--x--x   18 apache   apache       4096 Mar 15 17:01 2


...etc and so on... basically if you do:

chmod -R 711 .; chmod -R 711 * 
(while inside your data_dir) it will take care of things. If you are paranoid:
chmod -R 644 */*/*/*/*.*    (the */ would = the number of hashes and the *.* covers all files (not directories).


You should change apache to whatever your webserver runs as.


Disabling Filtering:
--------------------
Added in version 1.3, the user can now disable the usage of the filter. All this does is calls the rewrite.pl program with the "D" option. This option removes the INCLUDERC line from the users .procmailrc file, which in turn, disables the usage of .procmail-spamrc. Once the user has disabled the feature, they can't make any changes to the general settings. They can add/remove whitelist & blacklist entries as well as personalize rules (This may be removed). If the user has the filtering disabled, but they click on Yes to enable it as well as change values, those values will update along with the usage of the filtering. 

(NOTE: the users .procmail-spamrc file is not deleted by any means when disabling the filter)


Explaination of Product:
------------------------
This is a web frontend to the "spamassassin" (http://spamassassin.org) filter program.
I assume that you already have this installed with the default settings in place. There are no advanced features for Razor (http://razor.sourceforge.net). If you have it installed on your system, it should run its checks for RAZOR_CHECK. I am unsure if the auto_report_threshold will kick in at 30 and auto submit or not. I do know that you will not be able to submit a spammer's email address to the razor database. This may be included in a future version.

Why spamassassin you ask? Simple. Sometimes you do not have access to good rbl's (and sometimes those rbl's don't work anyways). Spamassassin gives the end user a bit more control over how they want their mail filtered. Since spamassassin is called via a .procmailrc file, the filtering is done when the email hits the server, so no need to wait on SM's filtering process (and I'm sure it will save time for SM as well). With this plugin the user has full control as to where the email can be delivered (/dev/null too!!) and also has a set of "rules" that they can customize. The user can set their own "threshold" so it adds for great flexibility. If a user does not feel like customizing any rules, they can take the default points associated with them (as supplied by spamassassin).

I have been using spamassassin for about 2 weeks and I have flagged (and moved) over 2000 pieces of spam. (with a 100% spam filtering rate).


TODO:
-----

-(1) If SPAM FOLDER is deleted, update the <user>.pref and ~<user>/.procmail-spamrc file properly
-(2) Have a backup/restore function in case the user loses their <user>.spam file
-(x) Fix Bugs!
-(x) Add new features (see func.php file)


NOTES:
------
This software is free for use. I am not responsible for anything that may happen to your system if you use this software. I consider it to be licensed under the GNU GPL. You can modify this software however you like, all I ask is that you give me credit for anything that may be used from the program. If you use the program, I expect you keep the comments listed in the top of the .php files.

Thank you and enjoy!


----------------------------------------------------------------------------------

To use this with a qmail based system (and any imap system) that uses virtual users, you will have to modify
this program at your own risk. If I have the time, I will try to test it on other systems. You will most likely have to modify/add a few variables to the main.php file and you will have to rewrite the rewrite.pl file.
