======================== || INSTALLING IMP 4.0 || ======================== This document contains instructions for installing the IMP web-based mail client on your system. For information on the capabilities and features of IMP, see the file README in the top-level directory of the IMP distribution. OBTAINING IMP ------------- IMP can be obtained from the Horde website and FTP server, at http://www.horde.org/imp/ ftp://ftp.horde.org/pub/imp/ Bleeding-edge development versions of IMP are available via CVS; see the file docs/HACKING in the Horde distribution, or the website http://www.horde.org/source/, for information on accessing the Horde CVS repository. [FIXME note on RPMs here] PREREQUISITES ------------- To function properly, IMP REQUIRES the following: 1. A working Horde installation. IMP runs within the Horde Application Framework, a set of common tools for Web applications written in PHP. You must install Horde before installing IMP. ** IMP 4.0 requires version 3.0+ of the Horde Framework - earlier ** ** versions of Horde will NOT work. ** The Horde Framework can be obtained from the Horde website and FTP server, at http://www.horde.org/horde/ ftp://ftp.horde.org/pub/horde/ Many of IMP's prerequisites are also Horde prerequisites. Be sure to have completed all of the steps in the INSTALL file for the Horde Framework before installing IMP. 2. The following PHP capabilities: a. IMAP and POP3 support (--with-imap) IMP REQUIRES the UW-IMAP c-client library to provide IMAP and/or POP3 support. The c-client library is available from ftp://ftp.cac.washington.edu/imap/ IMP REQUIRES IMAP and POP3 support in PHP, and can use IMAP-SSL and POP3-SSL if available (see the --with-imap-ssl. IMPORTANT NOTE: c-client support is broken in PHP 4.2.2 & 4.2.3. If you are using either of these versions you can not use any 'imap-2002' releases or else IMP will not function properly. If this is your situation, you have 2 options: 1. If using PHP 4.2.3, you can apply this patch: http://lists.horde.org/archives/imp/Week-of-Mon-20021111/026936.html 2. Downgrade to using the 'imap-2001a' source code. The better solution would be to upgrade to PHP 4.3.0+ and c-client version imap-2002+. These newer version have the added benefit of being able to handle malformed MIME headers much better than older versions of c-client (older versions will often segfault PHP when they encounter messages that have invalid MIME headers). TROUBLESHOOTING TIP: If you notice strange behavior when running IMP (e.g. blank screens when accessing certain messages, blank message bodies) you should always try recompiling PHP with a different version of c-client. The different versions of the c-client library and PHP do not always work well together, and often all it takes is to recompile with a different c-client version and the problems will go away. b. File Upload Support File upload support is REQUIRED to allow attachments in mail composition and to allow various importing features to work (e.g. importing PGP or S/MIME keys, importing mbox files). To enable file upload support: 1. In your php.ini file, the following line MUST be present: file_uploads = On 2. Your temporary upload directory MUST be writable to the user the web server is running as. If you leave the configuration option 'upload_tmp_dir' blank in php.ini, PHP will use the default directory compiled into it (normally /tmp on Unix-like systems). 3. Set the maximum size of the uploaded files via the 'upload_max_filesize' configuration option in php.ini. For example, to allow 5 MB attachments, place the following line in your php.ini file: upload_max_filesize = 5M If either file_uploads is turned off, or your temporary upload directory is NOT writable by the server, all file upload functionality will be disabled by Horde/IMP and will not be available to the user. 3. The following PEAR modules: (See horde/docs/INSTALL for instructions on installing PEAR modules) a. HTTP_Request [OPTIONAL] HTTP_Request is required to use the HTML composition mode. 4. At least one IMAP or POP3 server. While IMP is an application that is installed on a Web server and is run from a Web browser, it is only an IMAP and POP3 *client*, like Eudora or Outlook Express. You must have access to an IMAP or POP3 server (or multiple servers) on which your users' mail is stored in order to use IMP. IMAP is recommended over POP3 in order to let users maintain mail folders other than INBOX. IMAP is also *much* faster than POP3 in displaying a mailbox of messages. In short, do not use POP3 unless IMAP is not available. Freely available IMAP servers (for *nix systems) that have been verified to work with IMP include: + UW-IMAP (ftp://ftp.cac.washington.edu/imap/) + Courier-IMAP (http://www.inter7.com/courierimap.html) + Cyrus (http://asg.web.cmu.edu/cyrus/) + Dovecot (http://dovecot.procontrol.fi/) The following items are not required, but are strongly RECOMMENDED: 1. Sendmail or equivalent. While Horde can inject mail via either a local sendmail or a remote SMTP server, sendmail is recommended for use with IMP for improved performance and error handling/reporting, as well as a more accurate mail envelope. The mail transport settings are set in the Horde configuration, so further documentation can be found there. 2. Turba, the Horde contacts manager. Turba is the Horde contact management application, designed to be integrated with other Horde applications to provide a unified interface to contact management throughout the Horde suite. Turba is available from: http://www.horde.org/turba/ ftp://ftp.horde.org/pub/turba/ Turba provides a local address book and an LDAP directory search function to IMP. You must use the 2.x branch of Turba with IMP 4.x. 3. Ingo, the Horde mail filters manager. Ingo is the Horde mail filters management application, designed to be integrated with other Horde applications to provide a unified interface to filter management throughout the Horde suite. Turba is available from: http://www.horde.org/ingo/ ftp://ftp.horde.org/pub/ingo/ Ingo provides the mail filtering interfaces to IMP - there is no built-in filtering in IMP. You must use the 1.x branch of Ingo with IMP 4.x. To use IMAP client-side filtering (i.e. the filtering provided by IMP 3.x), ingo should use the 'null' driver and the 'imap' script settings (set in ingo/config/backends.php). 4. Nag, the Horde tasks manager. Nag is the Horde tasks management application, designed to be integrated with other Horde applications to provide a unified interface to task management throughout the Horde suite. Nag is available from: http://www.horde.org/nag/ ftp://ftp.horde.org/pub/nag/ If nag is available on your system, users can easily create new tasks from individual email messages. You must use the 2.x branch of Nag with IMP 4.x. 5. Ispell, or a drop-in replacement. Ispell, or its enhanced cousin aspell, is used as IMP's spell-checking engine. You must install one of these, or a similar program with an ispell-compatible interface, to use IMP's spell-check feature. The differences between ispell and aspell are subtle but important. The author of ispell writes: [Aspell's] primary advantage is that it is better at making suggestions when a word is seriously misspelled. For example, when given "trubble", ispell will suggest only "rubble", where aspell suggests "trouble" (as its first choice) as well as "dribble", "rubble", and a lot of other words. Its disadvantage is that the approximate-matching algorithm is specific to English. As IMP supports multiple languages, the languages required by your user base will probably provide an incentive to use one or the other. You can obtain International Ispell from http://fmg-www.cs.ucla.edu/fmg-members/geoff/ispell.html and aspell from http://aspell.sourceforge.com/ INSTALLING IMP -------------- IMP is written in PHP, and must be installed in a web-accessible directory. The precise location of this directory will differ from system to system. Conventionally, IMP is installed directly underneath Horde in the web server's document tree. Since IMP is written in PHP, there is no compilation necessary; simply expand the distribution where you want it to reside and rename the root directory of the distribution to whatever you wish to appear in the URL. For example, with the Apache web server's default document root of '/usr/local/apache/htdocs', you would type: cd /usr/local/apache/htdocs/horde tar zxvf /path/to/imp-4.0.tar.gz mv imp-4.0 imp and would then find IMP at the URL http://your-server/horde/imp/ CONFIGURING IMP --------------- 1. Configuring Horde for IMP a. Register the application In horde/config/registry.php, find the applications['imp'] stanza. The 'status' parameter should already be marked '=> 'active''. If you have changed the location of IMP relative to Horde, either in the URL or in the file system or both, you must update the 'fileroot' and 'webroot' settings to their correct values. b. OPTIONAL: Enable IMP authentication If you would prefer that your users authenticate directly with IMP, without having to authenticate through Horde first, uncomment the following Horde auth driver lines in horde/config/horde.php: $conf['auth']['driver'] = 'application'; $conf['auth']['params']['app'] = 'imp'; ** YOU WILL HAVE TO LOG IN TWICE IF YOU DON'T DO THIS -- Once to Horde and a second time to IMP. ** If this is a new install, you will not be able to configure IMP using the Horde Administration/Configuration tool if you first enabled IMP authentication for Horde. You must set Horde to use another authentication method, configure IMP, then reset Horde to use IMP authentication. 2. Configuring IMP. To configure IMP, change to the config/ directory of the installed distribution, and make copies of all of the configuration "dist" files without the "dist" suffix: cd config/ for foo in *.dist; do cp $foo `basename $foo .dist`; done Documentation on the format and purpose of those files can be found in each file. You may edit these files if you wish to customize IMP's appearance and behavior. With two exceptions (conf.php and servers.php) the defaults will be correct for most sites. You must be sure to list your IMAP/POP3 server names and configuration information in servers.php (unless you demand that the user specify his own at login). You must then login to Horde as a Horde Administrator to finish the configuration of IMP. Use the Horde "Administration" menu item to get the the Administration page, and then on the click on the "Configuration" icon to get the Configuration page. Select "Mail" from the selection list of applications, and click on the "Configure" button. Fill in or change any configuration values as needed. When done click on "Generate Mail Configuration" to generate the conf.php file. If your web server doesn't have write permissions to the IMP configuration directory or file, it will not be able to write the file. In this case, cut and paste the returned configuration information into the file imp/config/conf.php. Note for international users: IMP uses GNU gettext to provide local translations of text displayed by applications; the translations are found in the po/ directory. If a translation is not yet available for your locale (and you wish to create one), or if you're having trouble using a provided translation, please see the horde/docs/TRANSLATIONS file for instructions. IMP Configuration Pointers -------------------------- * If you would like IMP to scan all text messages for UUencoded data, you must make change this line in imp/config/mime_drivers.php: $mime_drivers['imp']['plain']['uuencode'] = true; Note that this is a performance hit since *every* text body must be scanned in its entriety to look for uuencoded data. Therefore, this feature is disabled by default. 3. Securing IMP Before you can secure IMP, you need a secure Horde installation. Please read the file in horde/docs/SECURITY for Horde security information before proceeding. There are two channels by which, unless steps are taken to avoid it, IMP encourages users to pass their IMAP and POP3 passwords around the Internet unencrypted. The first channel is between their browser and the Web server. We strongly recommend using an SSL-capable Web server to give users the option of encrypting communications between their browser and the Web server on which IMP is running; some sites may wish to disable non-SSL access entirely. The second channel is between the Web server and their IMAP or POP3 server. The simplest way to avoid this is to have the mail server running on the same system as the Web server, and configuring IMP to connect to the IMAP or POP3 server on "localhost" instead of on the Internet hostname. In cases where that is not possible, we recommend using IMAP-SSL or POP3-SSL to ensure that users' passwords remain safe after they have entrusted them to IMP. Other security steps you can take to increase security include: * Use session cookies instead or URL based sessions. * Set your php session.entropy_length to a larger value (e.g. 16) and session.entropy_file to a random source (e.g. /dev/urandom) * Enable and use the php mycrypt extension. * If your database, mail server, and web server are on the same host machine, then: * use unix socket database access and disable tcp database access. * use 'localhost' for all tcp/ip connections to avoid the network. * use the command-line sendmail for sending mail if possible. 4. Testing IMP Use IMP to login to a known working IMAP or POP3 server. Test at least the following: - Sending mail (via the "Compose" item in the menu bar). - Setting preferences (check to see if they survive after logging out and back in, if you are using an SQL or LDAP preferences system). - Reading mail. - Changing folders. 5. Tuning IMP (Performance) See horde/docs/PERFORMANCE. OBTAINING SUPPORT ----------------- If you encounter problems with IMP, help is available! The Horde Frequently Asked Questions List (FAQ), available on the Web at http://www.horde.org/faq/ The Horde Project runs a number of mailing lists, for individual applications and for issues relating to the project as a whole. Information, archives, and subscription information can be found at http://www.horde.org/mail/ Lastly, Horde developers, contributors and users also make appearanced on IRC, on the channel #horde on the Freenode Network (irc.freenode.net). Please keep in mind that IMP is free software written by volunteers. For information on reasonable support expectations, please read http://www.horde.org/support.php Thanks for using IMP! The IMP team imp@lists.horde.org $Horde: imp/docs/INSTALL,v 1.45 2004/03/11 17:35:39 slusarz Exp $