[Sommaire] [Imprimer]

   1  ====================
   2   Installing IMP 4.1
   3  ====================
   4  
   5  :Last update:   $Date: 2006/12/22 01:37:25 $
   6  :Revision:      $Revision: 1.57.6.14 $
   7  :Contact:       imp@lists.horde.org
   8  
   9  .. contents:: Contents
  10  .. section-numbering::
  11  
  12  This document contains instructions for installing the IMP web-based mail
  13  client on your system.
  14  
  15  For information on the capabilities and features of IMP, see the file README_
  16  in the top-level directory of the IMP distribution.
  17  
  18  
  19  Obtaining IMP
  20  =============
  21  
  22  IMP can be obtained from the Horde website and FTP server, at
  23  
  24     http://www.horde.org/imp/
  25  
  26     ftp://ftp.horde.org/pub/imp/
  27  
  28  Or use the mirror closest to you:
  29  
  30     http://www.horde.org/mirrors.php
  31  
  32  Bleeding-edge development versions of IMP are available via CVS; see the file
  33  `horde/docs/HACKING`_ in the Horde distribution, or the website
  34  http://www.horde.org/source/, for information on accessing the Horde CVS
  35  repository.
  36  
  37  
  38  Prerequisites
  39  =============
  40  
  41  To function properly, IMP **requires** the following:
  42  
  43  1. A working Horde installation.
  44  
  45     IMP runs within the `Horde Application Framework`_, a set of common tools
  46     for Web applications written in PHP.  You must install Horde before
  47     before installing IMP.
  48  
  49     .. Important:: IMP 4.0 requires version 3.0+ of the Horde Framework -
  50                    earlier versions of Horde will **not** work.
  51  
  52     .. _`Horde Application Framework`: http://www.horde.org/horde/
  53  
  54     The Horde Framework can be obtained from the Horde website and FTP server,
  55     at
  56  
  57        http://www.horde.org/horde/
  58  
  59        ftp://ftp.horde.org/pub/horde/
  60  
  61     Many of IMP's prerequisites are also Horde prerequisites.
  62  
  63     .. Important:: Be sure to have completed all of the steps in the
  64                    `horde/docs/INSTALL`_ file for the Horde Framework before
  65                    installing IMP.
  66  
  67  2. The following PHP capabilities:
  68  
  69     a. IMAP and POP3 support ``--with-imap``
  70  
  71        IMP **requires** the UW-IMAP c-client library to provide IMAP and/or
  72        POP3 support.  The c-client library is available from
  73  
  74           ftp://ftp.cac.washington.edu/imap/
  75  
  76        IMP **requires** IMAP and POP3 support in PHP, and can use IMAP-SSL and
  77        POP3-SSL if available (see the ``--with-imap-ssl`` configure option).
  78        If using either TLS or SSL to connect to the IMAP/POP server, OpenSSL
  79        support is **required** in PHP. See `OpenSSL Support`_ below.
  80  
  81        .. Tip:: If you notice strange behavior when running IMP (e.g. blank
  82                 screens when accessing certain messages, blank message bodies)
  83                 you should always try recompiling PHP with a different version
  84                 of c-client.  The different versions of the c-client library and
  85                 PHP do not always work well together, and often all it takes is
  86                 to recompile with a different c-client version and the problems
  87                 will go away.
  88  
  89        .. Tip:: If running the webserver changerooted (i.e. the default setting
  90                 on OpenBSD), you may need additional configuration on your
  91                 system to ensure the c-client library works properly.
  92                 See: `Configuring c-client for changerooted webservers`_
  93  
  94        .. _`Configuring c-client for changerooted webservers`: http://lists.horde.org/archives/imp/Week-of-Mon-20050321/041502.html
  95  
  96     b. File Upload Support
  97  
  98        File upload support is **required** to allow attachments in mail
  99        composition and to allow various importing features to work (e.g.
 100        importing PGP or S/MIME keys, importing mbox files).  To enable file
 101        upload support:
 102  
 103            1. In your php.ini file, the following line **must** be present::
 104  
 105                  file_uploads = On
 106  
 107            2. Your temporary upload directory **must** be writable to the user
 108               the web server is running as.  If you leave the configuration
 109               option ``upload_tmp_dir`` blank in ``php.ini``, PHP will use the
 110               default directory compiled into it (normally ``/tmp`` on
 111               Unix-like systems).
 112  
 113            3. Set the maximum size of the uploaded files via the
 114               ``upload_max_filesize`` configuration option in ``php.ini``.  For
 115               example, to allow 5 MB attachments, place the following line in
 116               your ``php.ini`` file::
 117  
 118                  upload_max_filesize = 5M
 119  
 120         If either ``file_uploads`` is turned off, or your temporary upload
 121         directory is *not* writable by the server, all file upload
 122         functionality will be disabled by Horde/IMP and will not be available
 123         to the user.
 124  
 125     The following PHP options are **RECOMMENDED** to enable advanced features in
 126     IMP:
 127  
 128  .. _`OpenSSL Support`:
 129  
 130     a. OpenSSL support ``--with-openssl``
 131  
 132        The OpenSSL module is used by IMP to provide S/MIME functionality.
 133        Without the module, S/MIME options will be disabled.
 134  
 135        Additionally, the OpenSSL module is REQUIRED if using either TLS or SSL
 136        to connect to the IMAP/POP server.
 137  
 138        See http://www.php.net/openssl for information on compiling OpenSSL
 139        into PHP.
 140  
 141  3. The following PEAR modules:
 142     (See `horde/docs/INSTALL`_ for instructions on installing PEAR modules)
 143  
 144     a. HTTP_Request [OPTIONAL]
 145  
 146        HTTP_Request is required to use the HTML composition mode.
 147  
 148     b. Auth_SASL [OPTIONAL]
 149  
 150        Auth_SASL is required if your IMAP server uses CRAM-MD5 or DIGEST-MD5
 151        authentication.
 152  
 153  4. At least one IMAP or POP3 server.
 154  
 155     While IMP is an application that is installed on a Web server and is run
 156     from a Web browser, it is only an IMAP and POP3 *client*, like Eudora or
 157     Outlook Express.  You must have access to an IMAP or POP3 server (or
 158     multiple servers) on which your users' mail is stored in order to use IMP.
 159  
 160     IMAP is recommended over POP3 in order to let users maintain mail folders
 161     other than INBOX and is required to allow messages to be flagged. IMAP is
 162     also *much* faster than POP3 in displaying a mailbox of messages.  In
 163     short, do not use POP3 unless IMAP is not available.
 164  
 165     Freely available IMAP servers (for \*nix systems) that have been verified
 166     to work with IMP include:
 167  
 168     - UW-IMAP (ftp://ftp.cac.washington.edu/imap/)
 169     - Courier-IMAP (http://www.inter7.com/courierimap.html)
 170     - Cyrus (http://asg.web.cmu.edu/cyrus/)
 171     - Dovecot (http://dovecot.procontrol.fi/)
 172  
 173  The following items are not required, but are strongly **RECOMMENDED**:
 174  
 175  1. Sendmail or equivalent.
 176  
 177     While Horde can inject mail via either a local sendmail or a remote SMTP
 178     server, sendmail is recommended for use with IMP for improved performance
 179     and error handling/reporting, as well as a more accurate mail envelope.
 180  
 181     The mail transport settings are set in the Horde configuration, so further
 182     documentation can be found there.
 183  
 184  2. Turba, the Horde contacts manager.
 185  
 186     Turba is the Horde contact management application, designed to be
 187     integrated with other Horde applications to provide a unified interface to
 188     contact management throughout the Horde suite.
 189  
 190     Turba is available from:
 191  
 192        http://www.horde.org/turba/
 193  
 194        ftp://ftp.horde.org/pub/turba/
 195  
 196     Turba provides a local address book and an LDAP directory search function
 197     to IMP.
 198  
 199     You must use the 2.x branch of Turba with IMP 4.x.
 200  
 201  3. Ingo, the Horde mail filters manager.
 202  
 203     Ingo is the Horde mail filters management application, designed to be
 204     integrated with other Horde applications to provide a unified interface to
 205     filter management throughout the Horde suite.
 206  
 207     Ingo is available from:
 208  
 209        http://www.horde.org/ingo/
 210  
 211        ftp://ftp.horde.org/pub/ingo/
 212  
 213     Ingo provides the mail filtering interfaces to IMP - there is no built-in
 214     filtering in IMP.
 215  
 216     You must use the 1.x branch of Ingo with IMP 4.x.
 217  
 218     To use IMAP client-side filtering (i.e. the filtering provided by IMP 3.x),
 219     ingo should use the ``null`` driver and the ``imap`` script settings (set
 220     in ``ingo/config/backends.php``).
 221  
 222  4. Nag, the Horde tasks manager.
 223  
 224     Nag is the Horde tasks management application, designed to be integrated
 225     with other Horde applications to provide a unified interface to task
 226     management throughout the Horde suite.
 227  
 228     Nag is available from:
 229  
 230        http://www.horde.org/nag/
 231  
 232        ftp://ftp.horde.org/pub/nag/
 233  
 234     If nag is available on your system, users can easily create new tasks from
 235     individual email messages.
 236  
 237     You must use the 2.x branch of Nag with IMP 4.x.
 238  
 239  5. Gollem, the Horde file manager.
 240  
 241     Gollem is the Horde file management application, designed to be
 242     integrated with other Horde applications to provide a unified interface to
 243     access VFS filesystems throughout the Horde suite.
 244  
 245     Gollem is available from:
 246  
 247        http://www.horde.org/gollem/
 248  
 249        ftp://ftp.horde.org/pub/gollem/
 250  
 251     Gollem allows a user to attach files from various VFS filesystems to
 252     outgoing messages in IMP.
 253  
 254     You must use the 1.x branch of Gollem with IMP 4.x.
 255  
 256  6. Ispell, or a drop-in replacement.
 257  
 258     Ispell, or its enhanced cousin aspell, is used as IMP's spell-checking
 259     engine.  You must install one of these, or a similar program with an
 260     ispell-compatible interface, to use IMP's spell-check feature.
 261  
 262     The differences between ispell and aspell are subtle but important.  The
 263     author of ispell writes:
 264  
 265        [Aspell's] primary advantage is that it is better at making suggestions
 266        when a word is seriously misspelled.  For example, when given "trubble",
 267        ispell will suggest only "rubble", where aspell suggests "trouble" (as
 268        its first choice) as well as "dribble", "rubble", and a lot of other
 269        words.  Its disadvantage is that the approximate-matching algorithm is
 270        specific to English.
 271  
 272     As IMP supports multiple languages, the languages required by your user
 273     base will probably provide an incentive to use one or the other.  You can
 274     obtain International Ispell from:
 275  
 276        http://fmg-www.cs.ucla.edu/fmg-members/geoff/ispell.html
 277  
 278     and aspell from:
 279  
 280        http://aspell.sourceforge.net/
 281  
 282     aspell version 0.50, or higher, is recommended.
 283  
 284  
 285  Installing IMP
 286  ==============
 287  
 288  IMP is written in PHP, and must be installed in a web-accessible directory.
 289  The precise location of this directory will differ from system to system.
 290  Conventionally, IMP is installed directly underneath Horde in the web server's
 291  document tree.
 292  
 293  Since IMP is written in PHP, there is no compilation necessary; simply expand
 294  the distribution where you want it to reside and rename the root directory of
 295  the distribution to whatever you wish to appear in the URL.  For example, with
 296  the Apache web server's default document root of ``/usr/local/apache/htdocs``,
 297  you would type::
 298  
 299     cd /usr/local/apache/htdocs/horde
 300     tar zxvf /path/to/imp-x.y.z.tar.gz
 301     mv imp-x.y.z imp
 302  
 303  and would then find IMP at the URL::
 304  
 305     http://your-server/horde/imp/
 306  
 307  
 308  Configuring IMP
 309  ===============
 310  
 311  1. Configuring Horde for IMP
 312  
 313     a. Register the application
 314  
 315        In ``horde/config/registry.php``, find the ``applications['imp']``
 316        stanza.  The default settings here should be okay, but you can change
 317        them if desired.  If you have changed the location of IMP relative to
 318        Horde, either in the URL, in the filesystem or both, you must update the
 319        ``fileroot`` and ``webroot`` settings to their correct values.
 320  
 321     b. Enable IMP authentication [OPTIONAL]
 322  
 323        If you would prefer that your users authenticate directly with IMP,
 324        without having to authenticate through Horde first, load the
 325        ``Administration/Configuration/Authentication`` page and from the ``What
 326        backend should we use for authenticating users to Horde`` pulldown menu
 327        select ``Let a Horde application handle authentication``.  (Please see
 328        the second note below.) Select ``imp`` from the ``The application which
 329        is providing authentication`` pulldown menu.
 330  
 331        .. Note:: **You will have to log in twice if you don't do this** -- Once
 332                  to Horde and a second time to IMP.
 333  
 334        .. Note:: If this is a new install, you will not be able to configure
 335                  IMP using the Horde Administration/Configuration page if you
 336                  first enabled IMP authentication for Horde.  You must set
 337                  Horde to use another authentication method (refer to the
 338                  `horde/docs/INSTALL`_ file), configure IMP, then reset Horde
 339                  to use IMP authentication.  One way to reset Horde in order to
 340                  reach the Administration page is to replace the Horde
 341                  configuration file ``conf.php`` with the original in
 342                  ``horde/config/conf.php.dist``.  You should of course back up
 343                  your current settings since they will otherwise be permanently
 344                  lost.
 345  
 346  2. Configuring IMP
 347  
 348     To configure IMP, change to the ``imp/config/`` directory of the installed
 349     distribution, and make copies of all of the configuration ``dist`` files
 350     without the ``dist`` suffix::
 351  
 352        cd config/
 353        for foo in *.dist; do cp $foo `basename $foo .dist`; done
 354  
 355     Or on Windows::
 356  
 357        copy *.dist *.
 358  
 359     Documentation on the format and purpose of those files can be found in each
 360     file.  You may edit these files if you wish to customize IMP's appearance
 361     and behavior.  With the following exceptions, the defaults will be correct
 362     for most sites.
 363  
 364     a. servers.php
 365  
 366        You must be sure to list your IMAP/POP3 server names and
 367        configuration information in ``servers.php`` (unless you allow
 368        users to choose any server).
 369  
 370     b. motd.php
 371  
 372        You should either provide your own message-of-the-day type
 373        information, or remove motd.php.
 374  
 375     You must login to Horde as a Horde Administrator to finish the
 376     configuration of IMP.  Use the Horde ``Administration`` menu item to get to
 377     the administration page, and then click on the ``Configuration`` icon to
 378     get the configuration page.  Select ``Mail`` from the selection list of
 379     applications.  Fill in or change any configuration values as needed.  When
 380     done click on ``Generate Mail Configuration`` to generate the ``conf.php``
 381     file.  If your web server doesn't have write permissions to the IMP
 382     configuration directory or file, it will not be able to write the file.  In
 383     this case, go back to ``Configuration`` and choose one of the other methods
 384     to create the configuration file ``imp/config/conf.php``.
 385  
 386     Note for international users: IMP uses GNU gettext to provide local
 387     translations of text displayed by applications; the translations are found
 388     in the ``po/`` directory.  If a translation is not yet available for your
 389     locale (and you wish to create one), see the ``horde/po/README`` file, or
 390     if you're having trouble using a provided translation, please see the
 391     `horde/docs/TRANSLATIONS`_ file for instructions.
 392  
 393     IMP Configuration Pointers
 394  
 395     * If you would like IMP to scan all text messages for UUencoded data, you
 396       must make this change in ``imp/config/mime_drivers.php``::
 397  
 398       $mime_drivers['imp']['plain']['uuencode'] = true;
 399  
 400       Note that this is a performance hit since *every* text body must be
 401       scanned in its entriety to look for uuencoded data.  Therefore, this
 402       feature is disabled by default.
 403  
 404     * By default, IMP is configured to NOT display text/html message parts
 405       inline.  This is done for various security reasons.  If you would like
 406       to see text/html parts inline, you must make this change in
 407       ``imp/config/mime_drivers.php``::
 408  
 409       $mime_drivers['imp']['html']['inline'] = true;
 410  
 411  3. Securing IMP
 412  
 413     Before you can secure IMP, you need a secure Horde installation.  Please
 414     read the file in `horde/docs/SECURITY`_ for Horde security information
 415     before proceeding.
 416  
 417     There are two channels by which, unless steps are taken to avoid it, IMP
 418     encourages users to pass their IMAP and POP3 passwords around the Internet
 419     unencrypted.
 420  
 421     The first channel is between their browser and the Web server.  We strongly
 422     recommend using an SSL-capable Web server to give users the option of
 423     encrypting communications between their browser and the Web server on which
 424     IMP is running; some sites may wish to disable non-SSL access entirely.
 425  
 426     The second channel is between the Web server and their IMAP or POP3 server.
 427     The simplest way to avoid this is to have the mail server running on the
 428     same system as the Web server, and configuring IMP to connect to the IMAP
 429     or POP3 server on ``localhost`` instead of on the Internet hostname.  In
 430     cases where that is not possible, we recommend using IMAP-SSL or POP3-SSL
 431     to ensure that users' passwords remain safe after they have entrusted them
 432     to IMP.
 433  
 434     Other security steps you can take to increase security include:
 435  
 436     * Use session cookies instead or URL based sessions.
 437     * Set your php ``session.entropy_length`` to a larger value (e.g. 16) and
 438       ``session.entropy_file`` to a random source (e.g. ``/dev/urandom``)
 439     * Enable and use the php mycrypt extension.
 440     * If your database, mail server, and web server are on the same host
 441       machine, then:
 442  
 443       * use unix socket database access and disable tcp database access.
 444       * use ``localhost`` for all TCP/IP connections to avoid the network.
 445       * use the command-line sendmail for sending mail if possible.
 446  
 447  4. Testing IMP
 448  
 449     Once you have configured IMP, bring up the included test page in your Web
 450     browser to ensure that all necessary prerequisites have been met.  See the
 451     `horde/docs/INSTALL`_ document for further details on Horde test
 452     scripts. If you installed IMP as described above, the URL to the test page
 453     would be::
 454  
 455        http://your-server/horde/imp/test.php
 456  
 457     The test script will also allow you to test your connection to the mail
 458     server and provide some auto-detected configuration parameters that can
 459     then be inserted into the server configuration located in
 460     ``imp/config/servers.php``.
 461  
 462     Next, use IMP to login to a known working IMAP or POP3 server.  Test at
 463     least the following:
 464  
 465     - Sending mail (via the ``Compose`` item in the menu bar).
 466     - Setting preferences (check to see if they survive after logging out and
 467       back in, if you are using an SQL or LDAP preferences system).
 468     - Reading mail.
 469     - Deleting mail.
 470     - Flagging mail (if using IMAP).
 471     - Changing folders (if using IMAP).
 472  
 473  5. Tuning IMP (Performance)
 474  
 475     See `horde/docs/PERFORMANCE`_.
 476  
 477  
 478  Obtaining Support
 479  =================
 480  
 481  If you encounter problems with IMP, help is available!
 482  
 483  The Horde Frequently Asked Questions List (FAQ), available on the Web at
 484  
 485    http://www.horde.org/faq/
 486  
 487  The Horde Project runs a number of mailing lists, for individual applications
 488  and for issues relating to the project as a whole.  Information, archives, and
 489  subscription information can be found at
 490  
 491    http://www.horde.org/mail/
 492  
 493  Lastly, Horde developers, contributors and users also make occasional
 494  appearances on IRC, on the channel #horde on the Freenode Network
 495  (irc.freenode.net).
 496  
 497  Please keep in mind that IMP is free software written by volunteers.  For
 498  information on reasonable support expectations, please read
 499  
 500    http://www.horde.org/support.php
 501  
 502  Thanks for using IMP!
 503  
 504  The IMP team
 505  
 506  
 507  .. _README: ?f=README.html
 508  .. _`horde/docs/HACKING`: ../../horde/docs/?f=HACKING.html
 509  .. _`horde/docs/INSTALL`: ../../horde/docs/?f=INSTALL.html
 510  .. _`horde/docs/PERFORMANCE`: ../../horde/docs/?f=PERFORMANCE.html
 511  .. _`horde/docs/SECURITY`: ../../horde/docs/?f=SECURITY.html
 512  .. _`horde/docs/TRANSLATIONS`: ../../horde/docs/?f=TRANSLATIONS.html