INSTALLING SMARTSIEVE
~~~~~~~~~~~~~~~~~~~~~

This file contains notes on installing the SmartSieve Sieve 
script manager.

See the README file included in this distribution for more 
general notes on the features and requirements of SmartSieve.


DOWNLOADING SMARTSIEVE

The SmartSieve project is hosted on sourceforge.net. Releases 
can be found at:

http://sourceforge.net/project/showfiles.php?group_id=62641

Information on anonymous access to the CVS can be found here:

http://sourceforge.net/cvs/?group_id=62641


REQUIREMENTS

1. SmartSieve runs on a PHP enabled web server. Apache will be the 
   most common choice for this, and is currently the only web server 
   SmartSieve is known to run on. It is therefore recommended. You 
   can find apache at:

   httpd://www.apache.org

   Apache should be configured to read and honour .htaccess files 
   for the directory in which SmartSieve is installed. See the usage 
   of the AllowOverride directive in the apache documentation.

   As passwords will be passed between users and the web server, you 
   should consider securing access to the web server with something 
   like Secure Sockets Layer (SSL). To do this with Apache you will 
   need to install mod_ssl (http://www.modssl.org).

2. SmartSieve requires PHP version 4.1 or greater. SmartSieve is known 
   to work correctly on versions 4.1.2, 4.2.3, 4.3.10, and version 5 
   up to 5.1.6. The latest 4.4.x or 5.1 versions are recommended.

   Note: php-4.2 and above install with register_globals set to off by 
   default. SmartSieve is not dependent on the value of register_globals 
   and it is recommended you set this to 'Off'.

   The PHP magic_quotes_runtime variable must be set to 'Off'. This 
   is usually the PHP default.

   You should build PHP as an apache module (either the DSO or 
   the static builds).

   You will find PHP at:

   http://www.php.net

3. PHP must be built with IMAP support. This requires the UW c-client 
   library. You will find the c-client at:

   ftp://ftp.cac.washington.edu/imap/

4. SmartSieve will only work in conjunction with a Sieve enabled 
   email server which uses the managesieve protocol for remote 
   management of sieve scripts. It is currently only known to work 
   with the Cyrus imap server (http://cyrusimap.web.cmu.edu).

   You will need to configure Cyrus to run the timsieved daemon to 
   handle sieve requests. The master daemon's configuration file 
   is usually /etc/cyrus.conf. You will need to refer to the 
   cyrus-imapd documentation for this.

   SmartSieve currently supports the PLAIN and DIGEST-MD5 SASL 
   authentication mechanisms. Therefore, timsieved must be able to 
   authenticate users using one of these mechanisms. You can see what
   mechanisms timsieved supports by telneting to port 2000 of your
   mail server and observing the "SASL" capabilities line. See the
   Cyrus-sasl documentation for more on this.

   Some Sieve actions involve sending mail; vacation messaging and 
   mail redirection, for example. For these actions to work, Cyrus 
   imapd must be running deliver in lmtpd mode, and able to send mail 
   using sendmail or equivalent. See the cyrus-imapd documentation 
   for more on this.

5. SmartSieve requires a cryptography library to do encryption. 
   SmartSieve supports PHP's interface to the libmcrypt library. To 
   have SmartSieve use this you will need to install libmcrypt version 
   2.4.x or above. You can get this from:

     http://mcrypt.hellug.gr/

   Remember to build libmcrypt with the --disable-posix-threads option.
   If you are installing a version newer than 2.5.4 you will need the 
   --enable-dynamic-loading configure option.

   You will then need to build PHP with the configure option:

     --with-mcrypt=/libmcrypt/install/dir
   
   SmartSieve also supports the PHP Extension and Application Repository 
   (PEAR) Crypt_Rc4 and Crypt_HCEMD5 libraries for encryption purposes. 
   The Crypt_Rc4 library is not included in any PHP distributions, but 
   is available from the PEAR repository. You can install it with 
   something like:

     /usr/local/php/bin/pear install Crypt_Rc4

   See http://pear.php.net for more on this.

   If you are using a version of PHP older than 4.3.0 you will already 
   have the Crypt_HCEMD5 library installed. It has since been removed 
   completely from the PEAR repository. If you are using php-4.3.0 or 
   newer and you want to use the Crypt_HCEMD5 library, you will need 
   to get it from the php-4.2.x distribution.

   If you are using either of the PEAR libraries, make sure their 
   location is included in the PHP include_path for scripts to be able  
   to be able to find them.

6. SmartSieve can convert mailbox names into character encodings other 
   than ISO-8859-1. This is useful if you have mailbox names containing 
   non-ISO-8859-1 characters, which may be the case if you are using a 
   language other than English. For this to work you will need to enable 
   the iconv and/or mbstring extensions in PHP. You will need to build 
   PHP with the following configure options:

     --with-iconv
     --enable-mbstring

   iconv should be available on all POSIX-compliant systems. To enable 
   this on a Windows system you will need to install the iconv.dll file 
   bundled with the PHP/Win32 binary package.

   You should refer to the iconv and mbstring reference pages of the 
   PHP manual for information on which character encodings are supported 
   by which extension.

7. SmartSieve uses the PEAR Log class for writing to it's log file. If
   you want to enable SmartSieve's logging facility you will need to
   install the PEAR Log class:

     /usr/local/php/bin/pear install Log


INSTALLING SMARTSIEVE

SmartSieve is a set of PHP scripts which do not require any 
compilation. You need only move the entire source tree as it comes 
in the distribution directly under a web accessible directory. The 
location of this depends on your web server's configuration. 

$ cd /yourwebroot/
$ tar -xzf somewhere/smartsieve-x.x.x.tar.gz
$ mv smartsieve-x.x.x smartsieve

You should make sure that your web server will handle requests 
for PHP scripts correctly. For Apache, the httpd.conf file should 
contain the following lines:

AddType application/x-httpd-php .php
DirectoryIndex index.php

If possible, you should also make sure your web server will honour 
.htaccess files containing Limit directives, at least for the 
SmartSieve directory. See the Apache documentation on the 
AllowOverride directive for details on doing this with Apache.

Take a look at the PHP configuration on your server. You can either 
look at your php.ini file, or create a php script under your web 
server's webroot containing the following:

<?php phpinfo(); ?>

If you are using PEAR's Rc4 or HCEMD5 library for encryption make sure 
the location of these files is included in the include_path.
Make sure that magic_quotes_runtime is set to 'Off'.

SmartSieve uses PHP's native support for session handling. PHP will 
usually save session data in files under /tmp. Although SmartSieve 
will encrypt passwords during use, you should make sure session.save_path 
is set to a directory which only the web server can read and write to.

Edit the SmartSieve configuration files as necessary. They can be 
found under conf/. You will at least need to add entries for each of 
the mail servers you wish to access in conf/servers.php.

You should now be able to access SmartSieve by pointing a web browser 
at http://yourserver/smartsieve/.


PROBLEMS

If you encounter any problems with SmartSieve, you may be able to 
get assistance from one of the following sources:

There is a mailing list for the SmartSieve project. You can view the 
list archives, subscribe or get further information at:

http://lists.sourceforge.net/lists/listinfo/smartsieve-general

There is a support request tracker for the SmartSieve project. You 
can browse the tracker at:

http://sourceforge.net/tracker/?atid=501286&group_id=62641&func=browse

Please report any bugs by using the bug tracker, at:

https://sourceforge.net/tracker/?group_id=62641&atid=501285


$Id: INSTALL,v 1.14 2007/09/25 14:49:36 stephengrier Exp $
