|
|
IMP Documentation
Installing IMP 4.3
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.
To function properly, IMP requires the following:
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.
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/
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.
The following PHP capabilities:
IMAP and POP3 support --with-imap
IMP requires the PHP imap extension to provide IMAP and/or POP3
support. To compile the imap extension, the UW-IMAP c-client libray
must be present on your system. For help with compiling the imap
extension ninto PHP, you can view the PHP imap manual entry:
http://www.php.net/imap
Because installation of the imap extension can be a non-trivial matter,
further configuration help/advice follows.
The UW-IMAP c-client library is available from
ftp://ftp.cac.washington.edu/imap/
The most recent code is normally located in a file named 'imap.tar.Z'.
After building the c-client library (instructions are at the top of
the Makefile in the base directory of the UW imap package), you may
need to rename the compiled library file so the local build system can
find it. For example, compilation of c-client results in a file named
'c-client.a' in the 'c-client' directory. On Linux (at least) this file
needs to be renamed or linked to libc-client.a, e.g.:
ln -s c-client.a libc-client.a
IMP can use IMAP-SSL and POP3-SSL if available. SSL support needs to be
built-in to both the c-client library and the PHP extension (see the
--with-imap-ssl configure option to PHP).
If using TLS or SSL to connect to the IMAP/POP3 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.
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:
In your php.ini file, the following line must be present:
file_uploads = On
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).
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.
See the File Uploads FAQ entry for further information.
The following PHP options are RECOMMENDED to enable advanced features
in IMP:
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.
tidy --with-tidy (PHP 5+ only)
The tidy PHP extension is required if you want IMP to sanitize the
output of HTML messages before displaying to the user and if you want
to clean and repair outgoing HTML messages composed via the HTML
composition mode. See imp/config/mime_drivers.php.dist for
further instructions on how to enable this feature.
The following PEAR modules:
(See horde/docs/INSTALL for instructions on installing PEAR modules)
Auth_SASL [OPTIONAL]
Auth_SASL is required if your IMAP server uses CRAM-MD5 or DIGEST-MD5
authentication.
HTTP_Request [OPTIONAL]
HTTP_Request is used in the HTML composition mode to download remote
images contained in the message and store them in the body of the
outgoing messages. Without HTTP_Request, the message will be sent
with the images linked to the remote images, with no guarantee that
the remote images will still be accessible when the recipient of the
message views that message.
The following PECL modules:
(See horde/docs/INSTALL for instructions on installing PECL modules)
idn [OPTIONAL]
idn is required in order to handle Internationalized Domain Names
(see RFC 3490).
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://www.imap.org/imap.vs.pop.brief.html
Freely available IMAP servers (for *nix systems) that have been verified
to work with IMP include:
The following items are not required, but are strongly RECOMMENDED:
Sendmail or equivalent.
While Horde can send 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.
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.
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).
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.
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.
aspell - Spelling Checker
Aspell, a comand-line program, is used as IMP's spell-checking engine.
You must install and configure aspell to use IMP's spell-check feature.
Version 0.60 or higher is REQUIRED.
You can obtain aspell from:
http://aspell.sourceforge.net/
A web server with PATH_INFO support.
IMP requires a web server that correctly sets the PATH_INFO environment
variable for all PHP scripts for several features. Every modern web server
supports this, but you might have to enable this feature in the web server
configuration. e.g. Apache servers require:
AcceptPathInfo On
If the webserver does not provide PATH_INFO information, IMP attempts to
create the information using other server variables, but this process is
slower and less reliable.
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 Horde for IMP
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.
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/Setup/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/Setup 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.
Creating the database table
The specific steps to create the IMP database table depend on which
database you've chosen to use.
First, look in scripts/sql/ to see if a script already exists
for your database type. If so, you should be able to simply execute that
script as superuser in your database. (Note that executing the script as
the "horde" user will probably fail when granting privileges.)
If such a script does not exist, you'll need to build your own, using the
file imp.sql as a starting point. If you need assistance in creating
databases, you may wish to let us know on the IMP mailing list.
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 the following exceptions, the defaults will be correct
for most sites.
servers.php
You must be sure to list your IMAP/POP3 server names and
configuration information in servers.php (unless you allow
users to choose any server).
motd.php
You should either provide your own message-of-the-day type
information, or remove motd.php.
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 Setup 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 Setup 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;
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.
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).
Tuning IMP (Performance)
See horde/docs/PERFORMANCE.
IMP Specific Performance Information
As of IMP 4.2, IMP can now use persistent caching on the server side to
store information about user's messages. This results in much reduced
IMAP server traffic and requires the server to parse the structure of every
message only once. The tradeoff is your cache backend must be able to
handle the potentially large amounts of cached data this option will
produce.
To use this caching, you must have a Cache System configured in Horde's
Administration/Setup screen and have the relevant settings enabled in
IMP's setup screen (Administration/Setup/Webmail/Mailbox and Fetchmail.
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 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/support.php
Thanks for using IMP!
The IMP team
|
