sasql - SpamAssassin+SQL DB plugin for SquirrelMail

Author: Randy Smith <perlstalker@vuser.org>
Home page: http://www.sourceforge.net/projects/sasql

The sasql SquirrelMail plugin lets users change a pre-defined set of
SpamAssassin settings when those settings are stored in a SQL DB
rather than a config file.

INSTALLATION

o sasql requires Pear DB.
o Unpack in the plugins directory of your SM installation.
o Copy sasql_conf.php.dist to sasql_conf.php.
o Edit sasql_conf.php and change the DSN and table name to suit
  your database. (The schema used by SA is defined in
  http://www.spamassassin.org/dist/sql/README.)
o Enable the sasql plugin.

NOTE: sasql requires PEAR-DB. PEAR-DB is also required by SquirrelMail
when preferences are stored in SQL so you may already have this. If you
get errors about PHP being unable to find DB.php, that means that
PEAR-DB is not installed.

SUPPORTED SPAMASSASSIN SETTINGS

This is an incomplete list. See sa_opts-dist.php for the complete list
of supported settings.

o [un]whitelist_from / [un]blacklist_from / whitelist_to
o required_hits / required_score
o use_terse_report
o rewrite_subject
o use_dcc
o use_razor1
o use_razor2
o always_add_headers
o ok_languages
o use_bayes
o auto_learn
o report_safe

Settings removed from SpamAssassin 2.50. Set $useSA2_43 to enable,
or add to $allowed_params.
o report_header
o defang_mime

ADDING ADDITIONAL SETTINGS

Additional settings can be added very easily in sa_opts.php.
To do so, add a new entry to $sa_params with the following fields:
- title: A short title for the setting. This is not the name of
the setting that SpamAssassin uses.
- descr: A description of the setting. HTML formatting is ok here.
- type: The type of widget to use for input. Currently allowed are:
	select: Creates drop-down box for input.
	checkbox: Creates a simple checkbox for input.
	text: Create a plain text box.
- multiple: Allow multiple selections. Only useful with the 'select' type.
- size: The size of the widget. If omitted, then the default size for that
	widget is used. Not used for 'checkbox' types.
- values: This varies depending on the type chosen above.
	select: This is an associative array of values and descriptions.
		See the 'required_score' setting for an example.
	checkbox: This is the value for a selected checkbox.
	text: not used
- default: This is the default value for the setting. For settings
           with the 'select' type, the default should be one of the keys
           of the array.
- delete: Generally used on 'text' type settings to remove them from the
          database if the value is set to ''. Note: Setting the default
          value to some non-empty value for options with the 'delete' flag
          will probably fail in interesting ways. Most likely, the user
          will never be able to turn it off.

Example:
Let's say we wanted to add a setting named 'use_foo'. We need to
create 'title', 'descr', 'type', 'values' and 'default' fields.
Note: The first index MUST be the name of the setting as SpamAssassin
uses it.

$sa_params['use_foo']['title'] = "Use Foo";
$sa_params['use_foo']['descr'] = "Use Foo to check messages for spam.";

This will be a simple on/off switch so we will make it a checkbox.

$sa_params['use_foo']['type'] = 'checkbox';

SpamAssassin sees things as on if they have value of 1 and off if the
value is 0. So we'll set 'values' to 1 and the 'default' to 0;

$sa_params['use_foo']['values'] = 1;
$sa_params['use_foo']['default'] = 0;

The last thing we need to do is enable the setting in $allowed_params.

$allowed_params = array('required_score', ..., 'use_foo');

If you create a settings entry for a standard SpamAssassin setting
that is not already included, please email me the entry and I'll see
about adding it to the standard package. Thanks!

ADDING ADDITIONAL SECTIONS

You can reorder, remove or add sections to the main options page by
changing $allowed_sections in sasql_conf.php. This will allow you to
easily add additional, local features to your setup. Included is an example
for adding a dspam opt-in/opt-out page.

To add a custom section, create a file called <section_name>.inc.php where
<section_name> is the name of the section (without <>'s). Then add
<section_name> to $allowed_sections.

ADDITIONAL FEATURES

o Read-only support for '@GLOBAL' (and '!GLOBAL') settings. Users' settings
will default to value of the setting for the '@GLOBAL' user. '@GLOBAL'
settings must be set in the database "by hand." There is no way to
edit them through the plugin. Note: Global settings that are not in
the $allowed_params list are not shown by the plugin.

o The included process-spam.pl Perl script can be used with the 'x-spam-days'
setting to clean out users' spam folders. It should be reasonably easy to
modify to fit your server setup. Run 'pod2text process-spam.pl' for the
script's documentation. See the FAQ about sa-learn for more details.

o Add the from address to the white/blacklist from the message view.

FAQ

Q: How can I make sasql store the user name as 'foo@domain' instead
of 'foo'?
A: sasql gets the user name from SquirrelMail which, generally,
doesn't include the domain. You can use the 'vlogin' plugin to append
a default domain to the user name. You can also set a default domain
in sasql_conf.php.

Q: Why is SA ignoring my users' whitelist/blacklist preferences?
A: Make sure that spamd is invoked with '-q', otherwise, it will not even
attempt to connect to your database and will not retrieve any user
preferences, even if you have the correct dsn settings in your local.cf
SA configuration file. You can use the '-x' option to tell spamd to ignore
settings users' .spamassassin directories.

Q: Why do you have a dspam section in a SpamAssassin plugin?
A: The short answer is that I used to use both at the ISP I work at and
wanted a unified place to configure both. (My setup is doc'd at
http://perlstalker.vuser.org/tiki/tiki-index.php?page=CourierDspam)
It also provides a good example of a way to include local spam filter
customizations that may or may not interact with SpamAssassin.

Q: Why can't I see the value of 'rewrite_header Subject'?
A: Basically, there are two ways of storing this option in the database.

Option 1)
Preference: rewrite_header
Value: Subject ****SPAM****

Option 2)
Preference: rewrite_header Subject
Value: ****SPAM****

sasql only supports Option 2 for now. I want to add support for
Option 1) at some point but haven't had the time to do it. (Patches
welcome :-)) I think that Option 2 makes more sense but I know
there are some that disagree.

Q: How can I feed my mail to sa-learn?
A: There a couple of ways to use sa-learn with sasql.

Option 1a: You can use the included process-spam.pl perl script. I use
process-spam.pl on the servers at Amigo.Net and it works well, but it
may not be flexible enough to handle your setup and it will almost
guarantee that you'll have to modify the code a little to support your
system.

Option 1b: Rather than use process-spam.pl, you can use some other tool
to read the messages from the Learn folders. There are many such tools
out there. The SpamAssassin wiki lists several.

Option 2: You can use the Spam Buttons plugin.
(http://www.squirrelmail.org/plugin_view.php?id=242) If you choose to
use Spam Buttons, you should set $sasql_use_learn = false; in
sasql_conf.php. Try this if you are having problems with process-spam.pl.

TRANSLATIONS

An empty gettext .pot files (sasql.pot) is included in this package. The
script contrib/xgetpot may be used to create a new .pot file. e.g.

	cd SM_PATH/plugins/sasql
	contrib/xgetpot

Note: sasql requires that you use a version of gettext that supports the
'-L php' option.

BUGS

Reports bugs at http://sourceforge.net/tracker/?group_id=102673&atid=632496.

ACKNOWLEDGMENTS

This plugin was originally based on php-sa-mysql-0.5.tar.gz by
Justin England which can be downloaded from
http://www.spamassassin.org/devel/.

Thanks to the SquirrelMail team for builing such a great app and
for all the work they do to keep it running.

Thanks to all those who have sent in patches and suggested
improvements.

USING THE DSPAM SECTIONS

The dspam section (dspam.inc.php) is included as an example of how to
add your own options sections to sasql.

NOTE: I am no longer maintaining the dspam sections. It is my belief that
they still work as of 6 Oct 2005. They will remain part of sasql as an
example of how the section feature works but may not always work.

CONFIGURATION

1) Make dspam configuration changes to dspam_conf.php.

2) Add 'dspam' to $allowed_sections in sasql_conf.php.

TROUBLESHOOTING TIPS

o The dspam user dir defined is ($dspam_userdir) must be writable by the
web server. If it isn't, you will not be able to opt-in to dspam.

USING THE POLICYD SECTIONS

Policyd (http://policyd.sourceforge.net/) is an anti-spam plugin for
postfix that supports Greylisting, spamtraps, sender throttling, etc.

Greylisting in policyd is provided as an opt-in/opt-out option on a
per-recipient basis. This section allows users to enable or disable
Greylisting for their account.

CONFIGURATION

1) Copy policyd_conf-dist.php to policyd_conf.php and make any changes
   needed for your system. You will, at least, need to change the database
   information.

2) Add 'policyd' to $allowed_sections is sasql_conf.php