Block Sender - A Plugin for SquirrelMail
========================================
Version: 2.02 
Version Date: 16-May-2003 
Author: Derek Battams <derek@battams.ca>
Requires SQMAIL: >= v1.4.0
Requires procmail: >= v3.15.x

Description
-----------
The Block Sender plugin allows users to create a list of e-mail
addresses that will be "blocked" from delivery.  When an e-mail arrives
for a user the sender's address is checked against their block list.  If
the sender's address is in the block list the mail will automatically be
delivered to their SquirrelMail trash folder.  Users can add addresses
to their blocked list by reading an e-mail and clicking on the "Block
Sender" link, which is added by this plugin.  Users can also manually
edit their blocked senders list through their SquirrelMail Options.

Users may also block messages from entire domains.
A link is added to each message - "Block Sender's Domain".
Clicking that link will add the sender's domain to the list of blocked
addresses.  When this is done any mail received from any user of the domain
will be delivered to the user's SM Trash folder.  User's can also add domains
to their blocked senders list manually.  From their SquirrelMail Options the
user should edit their Blocked Senders List and to block the domain
"bad-dom.com" add the following line to the blocked senders list:

"*@bad-dom.com" (no quotes)

When this line is added then any mail received from bad-dom.com will be
immediately delivered to the receipient's SM Trash folder.

This plugin relies on the use of the procmail LDA.  Within the plugin
directory is a file called 'sqblock.rc'.  This file contains a recipe
that must be added to the global procmailrc file (usually located at
/etc/procmailrc) along with variables that must be defined.  The easiest
way to do this is to simply include sqblock.rc in your global procmailrc
file by adding a line such as this:

INCLUDERC=/path/to/sqblock.rc

This should be the first line of your global procmailrc file.  The
recipe is only a delivery recipe if a match is found in the recepient's
block list.  If no match is found then processing continues as normal;
this means that this should not interfere with other procmail recipes.
The variables at the top of sqblock.rc are vital for proper operation
and must be set for your system.  PLEASE ENSURE THAT THE VARIABLES ARE
PROPERLY SET BEFORE INSTALLING THIS PLUGIN FOR USE!  Use of this recipe
and/or file requires special (root) access to your system.  Though every
effort has been made to ensure the accuracy and safety of the recipe,
the author is not responsible for the results of its use.

Included in this version of the plugin are multiple versions of each file.  Each
file provides different functionality.  When installing this plugin you must 
be sure to match up the appropriate version of each file (SEE INSTALL SECTION).

sqblock.rc.mbox-flat     => Recipe for mbox mailboxes with flatfile block list
sqblock.rc.mbox-mysql    => Recipe for mbox mailboxes with MySQL block list

sqblock.rc.maildir-flat  => Recipe for maildir support with flatfile block list
sqblock.rc.maildir-mysql => Recipe for maildir support with MySQL block list

block_sender.php.flat    => Version to use for flatfile block lists
block_sender.php.mysql   => Version to use for MySQL block lists

options.php.flat         => Version to use for flatfile block lists
options.php.mysql        => Version to use for MySQL block lists

NOTE: The default installation uses the flat file version block_sender.php and
options.php.  If you need MySQL support then rename the MySQL files.  A future
version of this plugin will hopefully clean this installation procedure up some.
However, the purpose of this release is to support SM 1.4.

Experimental MySQL Support
--------------------------
Starting in version 2.01 support is now available for storing user block lists
in a MySQL database.  Though initial testing has proved successful, MySQL
support should still be considered experimental at this stage.  In order to use
MySQL for your block lists the following must be done:

* Create a MySQL database called squirrelmail with a table called blocked with
  the following table structure:
     FIELD     TYPE
     ==============
     user      varchar(64)
     email     varchar(128)
     Create a composite primary key consisting of both fields.
     A script is available in the tools directory to do this.

* Create the isBlocked binary by typing make in the plugin directory.  This
  requires a C development environment along with the MySQL client library.
  A binary called 'isBlocked' will be created in the tools subdirectory.

* Install the PHP files for MySQL support by renaming the appropriate files.

* Edit the mysql.php file by updating the BLOCK_HOST, BLOCK_ID, and BLOCK_PWD
  values.  THIS IS CRITICAL AND WILL CAUSE THE PLUGIN TO FAIL IF NOT SETUP
  PROPERLY.

* Edit the appropriate procmail recipe file.  See the comments in the file for
  details.  THIS IS CRITICAL AND WILL CAUSE THE PLUGIN TO FAIL IF NOT SETUP 
  PROPERLY.  Please read through the recipe file closely before activating this
  plugin.

* If you're upgrading from 2.0 you can load your current flatfile block lists
  into your MySQL database by converting them into a MySQL script then running
  the script against your database.  The perl script is in the tools directory.
  See the README file in the tools directory for further details.

Installation
------------
To install this plugin rename the PHP files by dropping the description suffix
of each file for the support required.  For example, if you simply want 
flatfile block lists with mbox mailboxes all that's required is to rename
block_sender.php.flat to block_sender.php, options.php.flat to options.php,
and setup procmail to use the sqblock.rc.mbox-flat recipe file.  If you choose
to use the experimental MySQL support do the same thing plus follow the
instructions above for setting up the other requirements for using MySQL.

Finally, install the plugin within the SquirrelMail configure program (option
8).

NOTE: By default, in version 2.02, the flat file, mbox setup has been 
configured by default.

Notes
-----
* I realize setting up MySQL support is ugly right now, a future revision of
  this plugin will address this issue.

* If building the isBlocked binary fails please try to modify the Makefile to
  get it to work.  Check the LIBS variable as a possible reason for failure.
  If the actual code fails to compile then modify the #INCLUDE line for mysql.h
  to suit your system setup.  A future revision of this plugin will hopefully
  find a nice way to handle as many system setups as possible (anyone with
  suggestions on this?). 

* MySQL support will only ever be available in the 2.x series (i.e. you will
  require SM >= 1.2.8.  The 1.x series of this plugin and older will no longer
  be updated.  This will not change, please don't ask.

* The database requirements were chosen to best fit the requirements for SM
  database support (hence the reason why the database name must be
  squirrelmail).  A future revision of the plugin will be more flexible in the
  database schema required for operation.

* Please don't hesitate to send any questions/feedback to me.  I'm especially
  interested in people's success with implementing the MySQL support.  Please
  tell me about the setup issues you ran into, functionality problems,
  functionality missing, etc.

Comments/Questions
------------------
Send them to the author, Derek Battams <derek@battams.ca>.

Revision History
----------------
21-Feb-2002   0.1     Original version (BETA).
24-Feb-2002   0.2     Corrected a bug that would cause errors with the IMAP
                      server when blocking an address after deleting other
                      messages.  Now when a sender is blocked the message is
                      automatically deleted and the user is able to return to
                      the message list of the current folder.
25-Jul-2002   0.3     Corrected two minor bugs (one to do with the regex used
                      to determine the sender's address when blocking a sender
                      and the other to properly support the maildir delivery
                      format).  By popular demand, added the ability to block
                      entire domains.  To block a domain either click on the
                      "Block Sender's Domain" link from an email message or
                      add an entry of the form "*@dom-to-block.com" (no quotes).
14-Nov-2002   2.0     Added i18n support; added compatibility with SM >= 1.2.8.
                      The 2.x series of this plugin requires SM >= 1.2.8.  Older
                      versions of SM will not work with the 2.x series of this
                      plugin.  For older versions of SM please install the 1.x
                      series of this plugin.
06-Jan-2003   2.01    Added experimental MySQL support.
16-May-2003   2.02    Added support for SM 1.4.