358 lines
14 KiB
Plaintext
358 lines
14 KiB
Plaintext
===================
|
|
Installing IMP H5
|
|
===================
|
|
|
|
: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_.
|
|
|
|
|
|
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.
|
|
|
|
.. 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/docs/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.
|
|
|
|
.. _`Horde Application Framework`: http://www.horde.org/apps/horde
|
|
|
|
2. The following PHP capabilities:
|
|
|
|
a. 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/docs/INSTALL`_ for instructions on how to enable file upload
|
|
support.
|
|
|
|
b. 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
|
|
`docs/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:
|
|
|
|
- Cyrus (http://www.cyrusimap.org/)
|
|
- Dovecot (http://www.dovecot.org/)
|
|
|
|
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/docs/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.
|
|
|
|
|
|
Installing IMP
|
|
==============
|
|
|
|
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.
|
|
|
|
Installing with PEAR
|
|
~~~~~~~~~~~~~~~~~~~~
|
|
|
|
First follow the instructions in `horde/docs/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
|
|
|
|
Installing from Git
|
|
~~~~~~~~~~~~~~~~~~~
|
|
|
|
See http://www.horde.org/source/git.php
|
|
|
|
|
|
Configuring IMP
|
|
===============
|
|
|
|
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/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
|
|
|
|
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/docs/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/docs/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 `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://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
|
|
|
|
|
|
.. _README: README
|
|
.. _`horde/docs/INSTALL`: ../../horde/docs/INSTALL
|
|
.. _`docs/PERFORMANCE`: PERFORMANCE
|
|
.. _`horde/docs/SECURITY`: ../../horde/docs/SECURITY
|
|
.. _`horde/docs/TRANSLATIONS`: ../../horde/docs/TRANSLATIONS
|
|
.. _`File Uploads`: http://wiki.horde.org/FAQ/Admin/FileUploads
|