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.9 and 5.0.2. Note that PHP-4.1.1 and earlier are vulnerable to a remote vulnerability in the way it handles multipart/form-data. The latest 4.3.x or 5.0.x versions are recommended. Note: php-4.2 and above install with register_globals set to off by default. SmartSieve is no longer dependent on the value of register_globals and should work fine if this is set 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://asg.web.cmu.edu/cyrus/imapd). 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. 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: 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 certainly 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.12 2004/11/05 11:14:02 stephengrier Exp $