/
INSTALL.html
336 lines (336 loc) · 18.7 KB
/
INSTALL.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
<div class="document" id="installing-imp-h5">
<h1 class="title">Installing IMP H5</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<col class="docinfo-content" />
<tbody valign="top">
<tr><th class="docinfo-name">Contact:</th>
<td><a class="first last reference external" href="mailto:imp@lists.horde.org">imp@lists.horde.org</a></td></tr>
</tbody>
</table>
<div class="contents topic" id="contents">
<p class="topic-title first">Contents</p>
<ul class="auto-toc simple">
<li><a class="reference internal" href="#prerequisites" id="id1">1 Prerequisites</a></li>
<li><a class="reference internal" href="#installing-imp" id="id2">2 Installing IMP</a><ul class="auto-toc">
<li><a class="reference internal" href="#installing-with-pear" id="id3">2.1 Installing with PEAR</a></li>
<li><a class="reference internal" href="#installing-from-git" id="id4">2.2 Installing from Git</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuring-imp" id="id5">3 Configuring IMP</a></li>
<li><a class="reference internal" href="#obtaining-support" id="id6">4 Obtaining Support</a></li>
</ul>
</div>
<p>This document contains instructions for installing the IMP web-based mail
client on your system.</p>
<p>For information on the capabilities and features of IMP, see the file <a class="reference external" href="README">README</a>.</p>
<div class="section" id="prerequisites">
<h1><a class="toc-backref" href="#id1">1 Prerequisites</a></h1>
<p>To function properly, IMP <strong>requires</strong> the following:</p>
<ol class="arabic">
<li><p class="first">A working Horde installation.</p>
<p>IMP runs within the <a class="reference external" href="http://www.horde.org/apps/horde">Horde Application Framework</a>, a set of common tools
for web applications written in PHP. You must install Horde before
installing IMP.</p>
<div class="important">
<p class="first admonition-title">Important</p>
<p class="last">IMP H5 requires version 5.0+ of the Horde Framework -
earlier versions of Horde will not work.</p>
</div>
<div class="important">
<p class="first admonition-title">Important</p>
<p class="last">Be sure to have completed all of the steps in the
<a class="reference external" href="../../horde/docs/INSTALL">horde/docs/INSTALL</a> 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.</p>
</div>
</li>
<li><p class="first">The following PHP capabilities:</p>
<ol class="loweralpha">
<li><p class="first">File Upload Support</p>
<p>File upload support is <strong>required</strong> 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
<a class="reference external" href="../../horde/docs/INSTALL">horde/docs/INSTALL</a> for instructions on how to enable file upload
support.</p>
</li>
<li><p class="first">OpenSSL support <tt class="docutils literal"><span class="pre">--with-openssl</span></tt></p>
<p>The OpenSSL PHP extension is used by IMP to provide S/MIME support.
Without the extension, all S/MIME options will be disabled.</p>
<p>Additionally, the OpenSSL PHP extension is REQUIRED if using TLS or SSL
to connect to the IMAP/POP3 server.</p>
<p>See <a class="reference external" href="http://www.php.net/openssl">http://www.php.net/openssl</a> for information on compiling OpenSSL
into PHP.</p>
</li>
</ol>
</li>
<li><p class="first">At least one IMAP or POP3 server.</p>
<p>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 <em>client</em>, 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.</p>
<p>IMAP is <strong>strongly</strong> recommended over POP3. See, e.g.,
<a class="reference external" href="http://staff.washington.edu/gray/papers/imap.vs.pop.brief.html">http://staff.washington.edu/gray/papers/imap.vs.pop.brief.html</a></p>
<p>The Horde Project recommends either Cyrus or Dovecot (see
<a class="reference external" href="PERFORMANCE">docs/PERFORMANCE</a> 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:</p>
<ul class="simple">
<li>Cyrus (<a class="reference external" href="http://www.cyrusimap.org/">http://www.cyrusimap.org/</a>)</li>
<li>Dovecot (<a class="reference external" href="http://www.dovecot.org/">http://www.dovecot.org/</a>)</li>
</ul>
<p>The IMAP server MUST support IMAP4rev1 (<a class="reference external" href="http://www.faqs.org/rfcs/rfc3501.html">RFC 3501</a>).
The POP server MUST support POP3 (<a class="reference external" href="http://www.faqs.org/rfcs/rfc1939.html">RFC 1939</a>/STD 53).</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">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.</p>
</div>
</li>
<li><p class="first">Sendmail or SMTP server.</p>
<p>Horde/IMP sends mail via either a local sendmail or a remote SMTP server.
It is <strong>RECOMMENDED</strong> that SMTP be used.</p>
<p>See <a class="reference external" href="../../horde/docs/INSTALL">horde/docs/INSTALL</a> for further information.</p>
</li>
</ol>
<p>The following items are not required, but are strongly <strong>RECOMMENDED</strong>:</p>
<ol class="arabic">
<li><p class="first">Turba, the Horde contacts manager.</p>
<p>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.</p>
<p>Turba is available from:</p>
<blockquote>
<p><a class="reference external" href="http://www.horde.org/apps/turba">http://www.horde.org/apps/turba</a></p>
</blockquote>
<p>Turba provides the local address book and an LDAP directory search function
to IMP.</p>
</li>
<li><p class="first">Ingo, the Horde mail filters manager.</p>
<p>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.</p>
<p>Ingo is available from:</p>
<blockquote>
<p><a class="reference external" href="http://www.horde.org/apps/ingo">http://www.horde.org/apps/ingo</a></p>
</blockquote>
<p>Ingo provides the mail filtering interfaces to IMP.</p>
</li>
<li><p class="first">A configured VFS backend.</p>
<p>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.</p>
</li>
</ol>
<p>The following items are not required, but if present will enable advanced
features in IMP:</p>
<ol class="arabic">
<li><p class="first">Kronolith, the Horde calendar application.</p>
<p>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.</p>
<p>Kronolith is available from:</p>
<blockquote>
<p><a class="reference external" href="http://www.horde.org/apps/kronolith">http://www.horde.org/apps/kronolith</a></p>
</blockquote>
<p>Kronolith allows a user to create/edit calendar events based on attachments
to email messages.</p>
<p>You must use the 4.x branch of Kronolith.</p>
</li>
<li><p class="first">Nag, the Horde tasks manager.</p>
<p>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.</p>
<p>Nag is available from:</p>
<blockquote>
<p><a class="reference external" href="http://www.horde.org/apps/nag">http://www.horde.org/apps/nag</a></p>
</blockquote>
<p>Nag allows a user to create new tasks from individual email messages.</p>
<p>You must use the 4.x branch of Nag.</p>
</li>
</ol>
</div>
<div class="section" id="installing-imp">
<h1><a class="toc-backref" href="#id2">2 Installing IMP</a></h1>
<p>The <strong>RECOMMENDED</strong> 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.</p>
<div class="section" id="installing-with-pear">
<h2><a class="toc-backref" href="#id3">2.1 Installing with PEAR</a></h2>
<p>First follow the instructions in <a class="reference external" href="../../horde/docs/INSTALL">horde/docs/INSTALL</a> to prepare a PEAR
environment for Horde and install the Horde Framework.</p>
<p>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 <tt class="docutils literal"><span class="pre">-a</span></tt> and the <tt class="docutils literal"><span class="pre">-B</span></tt> flag:</p>
<pre class="literal-block">
pear install -a -B horde/imp
</pre>
<p>By default, only the required dependencies will be installed:</p>
<pre class="literal-block">
pear install horde/imp
</pre>
<p>If you want to install IMP even with all binary dependencies, you need to
remove the <tt class="docutils literal"><span class="pre">-B</span></tt> 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:</p>
<pre class="literal-block">
pear install -a horde/imp
</pre>
</div>
<div class="section" id="installing-from-git">
<h2><a class="toc-backref" href="#id4">2.2 Installing from Git</a></h2>
<p>See <a class="reference external" href="http://www.horde.org/source/git.php">http://www.horde.org/source/git.php</a></p>
</div>
</div>
<div class="section" id="configuring-imp">
<h1><a class="toc-backref" href="#id5">3 Configuring IMP</a></h1>
<ol class="arabic">
<li><p class="first">Configuring Horde for IMP [OPTIONAL]</p>
<p>If you would prefer that your users authenticate directly with IMP, without
having to authenticate through Horde first, load the
<tt class="docutils literal">Administration/Configuration/Authentication</tt> page and from the <tt class="docutils literal">What
backend should we use for authenticating users to Horde</tt> pulldown menu
select <tt class="docutils literal">Let a Horde application handle authentication</tt> (see the note
below about new installs). Select <tt class="docutils literal">imp</tt> from the <tt class="docutils literal">The application which
is providing authentication</tt> pulldown menu.</p>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last"><strong>You will have to log in twice if you don't do this</strong> -- Once to
Horde and a second time to IMP.</p>
</div>
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">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 <a class="reference external" href="../../horde/docs/INSTALL">horde/docs/INSTALL</a>
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 <tt class="docutils literal">conf.php</tt> with the
original in <tt class="docutils literal">horde/config/conf.php.dist</tt>. You should of course
back up your current settings since they will otherwise be
permanently lost.</p>
</div>
</li>
<li><p class="first">Configuring IMP</p>
<p>You must login to Horde as a Horde Administrator to finish the configuration
of IMP. Use the Horde <tt class="docutils literal">Administration</tt> menu item to get to the
administration page, and then click on the <tt class="docutils literal">Configuration</tt> icon to get the
configuration page. Select <tt class="docutils literal">Mail</tt> from the selection list of
applications. Fill in or change any configuration values as needed. When
done click on <tt class="docutils literal">Generate Mail Configuration</tt> to generate the <tt class="docutils literal">conf.php</tt>
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 <tt class="docutils literal">Configuration</tt> and choose one of the other methods
to create the configuration file <tt class="docutils literal">imp/config/conf.php</tt>.</p>
<p>Documentation on the format and purpose of the other configuration files in
the <tt class="docutils literal">config/</tt> directory can be found in each file. You may create
<tt class="docutils literal">*.local.php</tt> 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.</p>
<ul>
<li><p class="first">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
<tt class="docutils literal">imp/config/mime_drivers.local.php</tt> file (or add to the existing
mime_drivers.local.php file) with the following content:</p>
<pre class="literal-block">
<?php
$mime_drivers['html']['inline'] = true;
</pre>
</li>
</ul>
</li>
<li><p class="first">Creating the database tables</p>
<p>Once you finished the configuration in the previous step, you can create all
database tables by clicking the <tt class="docutils literal">DB schema is out of date</tt> link in the
IMP row of the configuration screen.</p>
<p>Alternatively, creating the IMP database tables can be accomplished with
horde's <tt class="docutils literal"><span class="pre">horde-db-migrate</span></tt> utility. If your database is properly setup in
the Horde configuration, you can run the following command:</p>
<pre class="literal-block">
horde/bin/horde-db-migrate imp
</pre>
</li>
<li><p class="first">Securing IMP</p>
<p>Before you can secure IMP, you need a secure Horde installation. Please
read the file in <a class="reference external" href="../../horde/docs/SECURITY">horde/docs/SECURITY</a> for Horde security information
before proceeding.</p>
<p>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.</p>
<p>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.</p>
<p>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 <tt class="docutils literal">localhost</tt> 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).</p>
<p>Other security steps you can take to increase security include:</p>
<ul class="simple">
<li>Use session cookies instead of URL based sessions.</li>
<li>Set your php <tt class="docutils literal">session.entropy_length</tt> to a larger value (e.g. 16) and
<tt class="docutils literal">session.entropy_file</tt> to a random source (e.g. <tt class="docutils literal">/dev/urandom</tt>)</li>
<li>If your database, mail server, and web server are on the same host
machine, then:<ul>
<li>Use unix socket database access and disable TCP database access.</li>
<li>Use <tt class="docutils literal">localhost</tt> for all TCP/IP connections to avoid the network, or
run all services on a local, private network.</li>
</ul>
</li>
</ul>
</li>
<li><p class="first">Testing IMP</p>
<p>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
<a class="reference external" href="../../horde/docs/INSTALL">horde/docs/INSTALL</a> document for further details on the Horde test
script.</p>
<p>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 <tt class="docutils literal">imp/config/backends.local.php</tt>.</p>
<p>Next, use IMP to login to a known working IMAP or POP3 server. Test at
least the following:</p>
<ul class="simple">
<li>Sending mail (via the <tt class="docutils literal">Compose</tt> item in the menu bar).</li>
<li>Setting preferences (check to see if they survive after logging out and
back in, if you are using an SQL or LDAP preferences system).</li>
<li>Reading mail.</li>
<li>Deleting mail.</li>
<li>Flagging mail (if using IMAP).</li>
<li>Changing mailboxes (if using IMAP).</li>
</ul>
</li>
<li><p class="first">Tuning IMP (Performance)</p>
<p>See <a class="reference external" href="PERFORMANCE">docs/PERFORMANCE</a>.</p>
</li>
</ol>
</div>
<div class="section" id="obtaining-support">
<h1><a class="toc-backref" href="#id6">4 Obtaining Support</a></h1>
<p>If you encounter problems with IMP, help is available!</p>
<p>The Horde Frequently Asked Questions List (FAQ), available on the Web at</p>
<blockquote>
<a class="reference external" href="http://wiki.horde.org/FAQ">http://wiki.horde.org/FAQ</a></blockquote>
<p>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</p>
<blockquote>
<a class="reference external" href="http://www.horde.org/community/mail">http://www.horde.org/community/mail</a></blockquote>
<p>Lastly, Horde developers, contributors and users may also be found on IRC,
on the channel #horde on the Freenode Network (irc.freenode.net).</p>
<p>Please keep in mind that IMP is free software written by volunteers. For
information on reasonable support expectations, please read</p>
<blockquote>
<a class="reference external" href="http://www.horde.org/community/support">http://www.horde.org/community/support</a></blockquote>
<p>Thanks for using IMP!</p>
<p>The IMP team</p>
</div>
</div>