Skip to content

Latest commit

 

History

History
357 lines (245 loc) · 13.5 KB

INSTALL.rst

File metadata and controls

357 lines (245 loc) · 13.5 KB

Installing IMP H5

Contact: [email protected]

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.

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.

    Important

    IMP H5 requires version 5.0+ of the Horde Framework - earlier versions of Horde will not work.

    Important

    Be sure to have completed all of the steps in the horde/doc/INSTALL file for the Horde Framework before installing IMP. Many of IMP's prerequisites are also Horde prerequisites. Additionally, many of IMP's optional features are configured via the Horde install.

  2. The following PHP capabilities:

    1. 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). See horde/doc/INSTALL for instructions on how to enable file upload support.

    2. OpenSSL support --with-openssl

      The OpenSSL PHP extension is used by IMP to provide S/MIME support. Without the extension, all S/MIME options will be disabled.

      Additionally, the OpenSSL PHP extension is REQUIRED if using TLS or SSL to connect to the IMAP/POP3 server.

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

  3. 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 Outlook, Apple Mail, or Thunderbird. You must have access to an IMAP or POP3 server(s) on which your users' mail is stored in order to use IMP.

    IMAP is strongly recommended over POP3. See, e.g., http://staff.washington.edu/gray/papers/imap.vs.pop.brief.html

    The Horde Project recommends either Cyrus or Dovecot (see doc/PERFORMANCE for further information). Both are freely available IMAP servers (for *nix systems) that have been verified to work best with IMP both feature and performance wise:

    The IMAP server MUST support IMAP4rev1 (RFC 3501). The POP server MUST support POP3 (RFC 1939/STD 53).

    Note

    If using a POP server, it MUST support the UIDL capability. POP3 support is limited to performing only basic mail actions; on-demand filtering, searching, and sorting will be disabled.

  4. Sendmail or SMTP server.

    Horde/IMP sends mail via either a local sendmail or a remote SMTP server. It is RECOMMENDED that SMTP be used.

    See horde/doc/INSTALL for further information.

The following items are not required, but are strongly RECOMMENDED:

  1. 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/apps/turba

    Turba provides the local address book and an LDAP directory search function to IMP.

  2. 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 mail filter management throughout the Horde suite.

    Ingo is available from:

    http://www.horde.org/apps/ingo

    Ingo provides the mail filtering interfaces to IMP.

  3. A configured VFS backend.

    During composition of messages, it is possible that the PHP session may timeout. If VFS is enabled in Horde, IMP can store the draft message and allow the user to recover the message when they next login.

The following items are not required, but if present will enable advanced features in IMP:

  1. Kronolith, the Horde calendar application.

    Kronolith is the Horde calendar application, designed to be integrated with other Horde applications to provide a unified interface to provide calendar features throughout the Horde suite.

    Kronolith is available from:

    http://www.horde.org/apps/kronolith

    Kronolith allows a user to create/edit calendar events based on attachments to email messages.

    You must use the 4.x branch of Kronolith.

  2. 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/apps/nag

    Nag allows a user to create new tasks from individual email messages.

    You must use the 4.x branch of Nag.

The RECOMMENDED way to install IMP is using the PEAR installer. Alternatively, if you want to run the latest development code or get the latest not yet released fixes, you can install IMP from Git.

First follow the instructions in horde/doc/INSTALL to prepare a PEAR environment for Horde and install the Horde Framework.

When installing IMP through PEAR now, the installer will automatically install any dependencies of IMP too. If you want to install IMP with all optional dependencies, but without the binary PECL packages that need to be compiled, specify both the -a and the -B flag:

pear install -a -B horde/imp

By default, only the required dependencies will be installed:

pear install horde/imp

If you want to install IMP even with all binary dependencies, you need to remove the -B flag. Please note that this might also try to install PHP extensions through PECL that might need further configuration or activation in your PHP configuration:

pear install -a horde/imp

See http://www.horde.org/source/git.php

  1. Configuring Horde for IMP [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 (see the note below about new installs). 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/doc/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

    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.

    Documentation on the format and purpose of the other configuration files in the config/ directory can be found in each file. You may create *.local.php versions of these files if you wish to customize IMP's appearance and behavior. See the header of the configuration files for details and examples. The defaults will be correct for most sites.

    • 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 create a imp/config/mime_drivers.local.php file (or add to the existing mime_drivers.local.php file) with the following content:

      <?php
      $mime_drivers['html']['inline'] = true;
      
  3. Creating the database tables

    Once you finished the configuration in the previous step, you can create all database tables by clicking the DB schema is out of date link in the IMP row of the configuration screen.

    Alternatively, creating the IMP database tables can be accomplished with horde's horde-db-migrate utility. If your database is properly setup in the Horde configuration, you can run the following command:

    horde/bin/horde-db-migrate imp
    
  4. Securing IMP

    Before you can secure IMP, you need a secure Horde installation. Please read the file in horde/doc/SECURITY for Horde security information before proceeding.

    Unless steps are taken to avoid it, there are two channels by which IMP can cause users to pass their IMAP/POP3 passwords across the network unencrypted.

    The first channel is between the 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, it is highly recommended that the mail server be located on a private, secure network. Alternatively, the mail server can be accessed via TLS to ensure that users' passwords remain safe after they have entrusted them to IMP (this is the default configuration).

    Other security steps you can take to increase security include:

    • Use session cookies instead of 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)
    • 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, or run all services on a local, private network.
  5. Testing IMP

    Once you have configured IMP, bring up the Horde test page in your Web browser to ensure that all necessary prerequisites have been met. See the horde/doc/INSTALL document for further details on the Horde test script.

    The test script will also allow you to test your connection to the mail server and provide some auto-detected configuration parameters that can be used to configure the mail server in imp/config/backends.local.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 mailboxes (if using IMAP).
  6. Tuning IMP (Performance)

    See doc/PERFORMANCE.

If you encounter problems with IMP, help is available!

The Horde Frequently Asked Questions List (FAQ), available on the Web at

http://wiki.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/community/mail

Lastly, Horde developers, contributors and users may also be found 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/community/support

Thanks for using IMP!

The IMP team