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.