====================
 Installing IMP 4.1
====================

:Last update:   $Date: 2006/02/05 07:17:14 $
:Revision:      $Revision: 1.57.6.13 $
:Contact:       imp@lists.horde.org

.. contents:: Contents
.. section-numbering::

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/

Or use the mirror closest to you:

   http://www.horde.org/mirrors.php

Bleeding-edge development versions of IMP are available via CVS; see the file
`horde/docs/HACKING`_ in the Horde distribution, or the website
http://www.horde.org/source/, for information on accessing the Horde CVS
repository.


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
   before installing IMP.

   .. Important:: IMP 4.0 requires version 3.0+ of the Horde Framework -
                  earlier versions of Horde will **not** work.

   .. _`Horde Application Framework`: http://www.horde.org/horde/

   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.

   .. Important:: Be sure to have completed all of the steps in the
                  `horde/docs/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`` configure option).
      If using either TLS or SSL to connect to the IMAP/POP server, OpenSSL
      support is **required** in PHP. See `OpenSSL Support`_ below.

      .. 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.

      .. Tip:: If running the webserver changerooted (i.e. the default setting
               on OpenBSD), you may need additional configuration on your
               system to ensure the c-client library works properly.
               See: `Configuring c-client for changerooted webservers`_

      .. _`Configuring c-client for changerooted webservers`: http://lists.horde.org/archives/imp/Week-of-Mon-20050321/041502.html

   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.

   The following PHP options are **RECOMMENDED** to enable advanced features in
   IMP:

.. _`OpenSSL Support`:

   a. OpenSSL support ``--with-openssl``

      The OpenSSL module is used by IMP to provide S/MIME functionality.
      Without the module, S/MIME options will be disabled.

      Additionally, the OpenSSL module is REQUIRED if using either TLS or SSL
      to connect to the IMAP/POP server.

      See http://www.php.net/openssl for information on compiling OpenSSL
      into PHP.

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.

   b. Auth_SASL [OPTIONAL]

      Auth_SASL is required if your IMAP server uses CRAM-MD5 or DIGEST-MD5
      authentication.

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 and is required to allow messages to be flagged. 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.

   Ingo 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. Gollem, the Horde file manager.

   Gollem is the Horde file management application, designed to be
   integrated with other Horde applications to provide a unified interface to
   access VFS filesystems throughout the Horde suite.

   Gollem is available from:

      http://www.horde.org/gollem/

      ftp://ftp.horde.org/pub/gollem/

   Gollem allows a user to attach files from various VFS filesystems to
   outgoing messages in IMP.

   You must use the 1.x branch of Gollem with IMP 4.x.

6. 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.net/

   aspell version 0.50, or higher, is recommended.


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-x.y.z.tar.gz
   mv imp-x.y.z 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 default settings here should be okay, but you can change
      them if desired.  If you have changed the location of IMP relative to
      Horde, either in the URL, in the filesystem or both, you must update the
      ``fileroot`` and ``webroot`` settings to their correct values.

   b. Enable IMP authentication [OPTIONAL]

      If you would prefer that your users authenticate directly with IMP,
      without having to authenticate through Horde first, load the
      ``Administration/Configuration/Authentication`` page and from the ``What
      backend should we use for authenticating users to Horde`` pulldown menu
      select ``Let a Horde application handle authentication``.  (Please see
      the second note below.) Select ``imp`` from the ``The application which
      is providing authentication`` pulldown menu.

      .. Note:: **You will have to log in twice if you don't do this** -- Once
                to Horde and a second time to IMP.

      .. Note:: If this is a new install, you will not be able to configure
                IMP using the Horde Administration/Configuration page if you
                first enabled IMP authentication for Horde.  You must set
                Horde to use another authentication method (refer to the
                `horde/docs/INSTALL`_ file), configure IMP, then reset Horde
                to use IMP authentication.  One way to reset Horde in order to
                reach the Administration page is to replace the Horde
                configuration file ``conf.php`` with the original in
                ``horde/config/conf.php.dist``.  You should of course back up
                your current settings since they will otherwise be permanently
                lost.

2. Configuring IMP

   To configure IMP, change to the ``imp/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

   Or on Windows::

      copy *.dist *.

   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 (``servers.php``, and
   ``mime_drivers.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 login to Horde as a Horde Administrator to finish the
   configuration of IMP.  Use the Horde ``Administration`` menu item to get to
   the administration page, and then click on the ``Configuration`` icon to
   get the configuration page.  Select ``Mail`` from the selection list of
   applications.  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, go back to ``Configuration`` and choose one of the other methods
   to create the configuration 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), see the ``horde/po/README`` file, 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 this change 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.

   * By default, IMP is configured to NOT display text/html message parts
     inline.  This is done for various security reasons.  If you would like
     to see text/html parts inline, you must make this change in
     ``imp/config/mime_drivers.php``::

     $mime_drivers['imp']['html']['inline'] = true;

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

   Once you have configured IMP, bring up the included test page in your Web
   browser to ensure that all necessary prerequisites have been met.  See the
   `horde/docs/INSTALL`_ document for further details on Horde test
   scripts. If you installed IMP as described above, the URL to the test page
   would be::

      http://your-server/horde/imp/test.php

   The test script will also allow you to test your connection to the mail
   server and provide some auto-detected configuration parameters that can
   then be inserted into the server configuration located in
   ``imp/config/servers.php``.

   Next, 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.
   - Deleting mail.
   - Flagging mail (if using IMAP).
   - Changing folders (if using IMAP).

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 occasional
appearances 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


.. _README: ?f=README.html
.. _`horde/docs/HACKING`: ../../horde/docs/?f=HACKING.html
.. _`horde/docs/INSTALL`: ../../horde/docs/?f=INSTALL.html
.. _`horde/docs/PERFORMANCE`: ../../horde/docs/?f=PERFORMANCE.html
.. _`horde/docs/SECURITY`: ../../horde/docs/?f=SECURITY.html
.. _`horde/docs/TRANSLATIONS`: ../../horde/docs/?f=TRANSLATIONS.html