Serverside Filter 2.0 README

	ServerSideFilter - Server Side mail filter plugin for SquirrelMail
	By Jon Stroud and Tony Lownds.  This plugin is meant to be a 
        replacement to the existing procfilter plugin and the existing 
        Server Side Filters plugin.

	ServerSideFilter is a SquirrelMail plugin that allows users to 
        configure procmail or maildrop filters for their mail.
        
        ServerSideFilters supports standard shell users and Virtual Domains.

        For qmail users, this script can also be configured to create the proper
        dot-qmail files for delivery.

	Dot-forward files can also be generated to invoke the filter app.

NOTE:	Since version 1.4, ServerSide Filter uses a setuid application for
        storing and retrieving files.  Every effort has been made to make
        this setuid application secure.  One thing to note, is that the
        application does NOT allow setting the UID to root.  You must
        pass in your IMAP credentials, which the application will
        verify against the imap server and then will set its UID to 
        that user or appropriate virtual domain owner and NOT root.  
        For more information please refer to the README in the script
         directory.


Requirements
        SquirrelMail 1.4.x (tested on 1.4.1 but should work on 
           other releases.)
        Compatibility plugin
        Maildrop or procmail

INSTALLATION
Note: Users upgrading from version < 1.4 need to go through the configuration
      process again as the changes were so vast, that the config files are
      quite a bit different.

	1) extract the serversidefilter tarball in the SquirrelMail
           plugins directory

        2) cp config.php.sample config.php
           Note:  Users upgrading from an older version can run the following 
                  command to update their old config file:
                      php migrate_config.php old_config.php > config.php
                  This assumes your old config.php file is in the current 
                  directory.
                  Also, you should scan the generated file to be sure the new
                  settings make sense.  You can refer to config.php.sample for
                  documentation on the new variable structure.

        3) edit config.php
           For security purposes, you must:
	   chown root:root config.php

        4) If your webserver runs as a user OTHER than apache:
             chown root:webuser script/filtercmd
           where webuser is the user that Apache runs as.
           
           Refer to script/README for more information.

        5) If you would like to include any additional filter directives at
           the beggining and/or end of all filter files created:
              cd skeleton/
              cp header.sample header
              cp footer.sample footer
           Edit header and footer with the desired text.

      Virtual Domain users (Non-virtual Domain users go to step 7):
	6) If you use qmail:
	   ln -s /var/qmail/control/virtualdomains .

           If you use another mail server:
           cp ./virtualdomains.sample ./virtualdomains

           edit the virtualdomains file.
           The format is:
	   domain:domain_user

           Where domain is the domain of each of your virtual domains
           and domain_user is the unix name of the user that owns the
           directory containing the mail folders for that domain.

        7) reconfigure SquirrelMail to enable the ServerSideFilter plugin.
        
	ServerSideFilters is released under the terms of the GNU GPL.

Debugging
      If you are having trouble, first try turning error reporting on in 
      php.  You can do this by typing the following command:

          echo -e "php_value error_reporting 2047\nphp_flag display_errors On" > .htaccess

      This method will require that you have .htaccess files enabled in your apache config.

      To check if you are able to retrieve your filter files correctly:
          cd script/
          ./test.sh
      Refer to the script/README for more help.

Contacts
        the author can be contacted at accounts@bsclimbing.com

	Many thanks to all those users who helped clean up the bugs in this plugin.
