Commit | Line | Data |
---|---|---|
dd184caf | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | |
3 | ||
d9898ee8 | 4 | <html xmlns="http://www.w3.org/1999/xhtml"> |
5 | <head> | |
dd184caf | 6 | <meta http-equiv="Content-Type" content= |
b0322a85 | 7 | "text/html; charset=us-ascii" /> |
dd184caf | 8 | |
d9898ee8 | 9 | <title>INSTALL</title> |
b0322a85 | 10 | <!-- Copyright 2004-2012 Double Precision, Inc. See COPYING for --> |
d9898ee8 | 11 | <!-- distribution information. --> |
12 | </head> | |
13 | ||
14 | <body> | |
dd184caf | 15 | <h1>Table of Contents</h1> |
16 | ||
17 | <p>In this document (see INSTALL.html for the formatted version | |
18 | of this INSTALL file):</p> | |
19 | ||
20 | <ul> | |
21 | <li><a onclick="" href="#Requirements">Requirements</a></li> | |
22 | ||
23 | <li><a onclick="" href="#Installation">Installation | |
24 | overview</a></li> | |
25 | ||
26 | <li><a onclick="" href="#deps">Dependencies</a></li> | |
27 | ||
28 | <li><a onclick="" href="#What">What gets installed</a></li> | |
29 | ||
30 | <li><a onclick="" href="#manpage">For more information</a></li> | |
31 | ||
32 | <li><a onclick="" href="#Starting">Starting and stopping the | |
33 | authentication daemon</a></li> | |
34 | ||
35 | <li><a onclick="" href="#Building">Building RPMs</a></li> | |
36 | ||
37 | <li><a onclick="" href="#Guidelines">Guidelines for using other | |
38 | package managers</a></li> | |
39 | </ul> | |
40 | ||
41 | <h2><a name="Requirements" id= | |
42 | "Requirements">Requirements</a></h2> | |
43 | ||
44 | <p>See the README file for a general description of this library. | |
45 | The following software should be installed before building the | |
46 | Courier authentication library:</p> | |
47 | ||
48 | <ul> | |
49 | <li>A modern version of gcc (<a onclick="" href= | |
50 | "http://www.gnu.org/software/gcc/">http://www.gnu.org/software/gcc/</a>)</li> | |
51 | ||
52 | <li>The GNU linker (<a onclick="" href= | |
53 | "http://www.gnu.org/software/binutils/">http://www.gnu.org/software/binutils/</a>)</li> | |
54 | ||
55 | <li>Libtool (<a onclick="" href= | |
b0322a85 CE |
56 | "http://www.gnu.org/software/libtool/">http://www.gnu.org/software/libtool/</a>). |
57 | Additional, libtool's <tt>libltdl</tt> library, and its | |
58 | development files, must be installed. On some platforms this is | |
59 | a separate package. On Fedora, this is the | |
60 | <tt>libtool-ltdl-devel</tt> package, for example.</li> | |
dd184caf | 61 | |
62 | <li>GNU make (<a onclick="" href= | |
63 | "http://www.gnu.org/software/make/">http://www.gnu.org/software/make/</a>)</li> | |
64 | ||
65 | <li>The "<code>expect</code>" command. <code>expect</code> is | |
66 | usually included with most systems. <code>Expect</code> can be | |
67 | downloaded from <code>http://expect.nist.gov/</code> if it's | |
68 | not installed on your system. This utility is used to change | |
69 | system login passwords, by scripting the <code>passwd</code> | |
70 | command. If you do not have <code>expect</code> installed you | |
71 | will not be able to change system login passwords. However | |
72 | non-system authentication modules (LDAP, PostgreSQL, and | |
73 | others) will work.</li> | |
d50284c4 CE |
74 | |
75 | <li>Courier Unicode Library. Before installing | |
76 | Courier-IMAP, download and install <a onclick="" href= | |
77 | "http://www.courier-mta.org/unicode/">http://www.courier-mta.org/unicode/</a>.</li> | |
dd184caf | 78 | </ul> |
79 | ||
80 | <p>Courier-authlib uses Libtool to build shared libraries. | |
b0322a85 CE |
81 | Libtool must be installed, together with its <tt>libltdl</tt> |
82 | library and its header files.</p> | |
dd184caf | 83 | |
84 | <p>On non-Linux platforms the GNU linker is also required. | |
85 | Courier-authlib's build script uses some GNU linker-specific | |
86 | options. It's possible to manually specify the native linker's | |
87 | equivalent options manually, if they exist. If the native linker | |
88 | does not have the equivalent options, the GNU linker will have to | |
89 | be installed.</p> | |
90 | ||
91 | <p>On the other hand, GNU make will be required in almost every | |
92 | case. SYSV-derived make variants (probably) will not work.</p> | |
93 | ||
94 | <p>The same line of logic also applies to gcc. So, strictly | |
95 | speaking, only a basic C compiler, GNU make and libtool, are | |
96 | really needed to build courier-authlib. Still, try the following | |
97 | before giving up if problems occur when building this | |
98 | package:</p> | |
99 | ||
100 | <ol> | |
101 | <li>Install a recent version of the GNU linker</li> | |
102 | ||
103 | <li>Install the current version of Libtool</li> | |
104 | ||
105 | <li>Install the current version of gcc</li> | |
106 | </ol> | |
107 | ||
108 | <h2><a name="Installation" id="Installation">Installation | |
109 | overview</a></h2> | |
110 | ||
111 | <p>The following sequence of commands should be sufficient to | |
112 | install courier-authlib in most cases:</p> | |
113 | <pre> | |
114 | ./configure [options] [variable=value]*... | |
d9898ee8 | 115 | make |
116 | make install | |
dd184caf | 117 | make install-migrate # Only if upgrading from pre-authlib Courier packages |
118 | make install-configure | |
119 | </pre> | |
120 | ||
121 | <blockquote> | |
122 | <p><strong>NOTE:</strong> On the BSD family, GNU make is | |
123 | usually the 'gmake' command. Use the 'gmake' command, instead | |
124 | of 'make'.</p> | |
125 | </blockquote> | |
126 | ||
127 | <blockquote> | |
128 | <p><strong>NOTE:</strong> It might appear that the | |
129 | <code>configure</code> script is stuck in an infinite loop. | |
130 | This is only an optical illusion. The <code>configure</code> | |
131 | script takes several minutes to complete. The Courier | |
132 | authentication library consists of many small modules, each | |
133 | with its own configuration script; and all configuration | |
134 | scripts are built from the same template. When they are | |
135 | invoked, one at a time, an illusion of an infinite loop | |
136 | appears.</p> | |
137 | </blockquote> | |
138 | ||
139 | <p>Courier-authlib is a requirement starting with the following | |
140 | Courier package versions: Courier 0.48, Courier-IMAP 4.0, | |
141 | SqWebMail 5.0. When upgrading from earlier versions of these | |
142 | packages, install the Courier-authlib package first, then upgrade | |
143 | the existing package.</p> | |
144 | ||
145 | <p>The '<code>make install-migrate</code>' command imports the | |
146 | authentication configuration from earlier versions of these | |
147 | packages. '<code>make install-migrate</code>' is not needed | |
148 | otherwise.</p> | |
149 | ||
150 | <p>The '<code>make install-migrate</code>' command searches all | |
151 | the known default installation directories for Courier, | |
152 | Courier-IMAP, and SqWebMail, and imports the older configuration | |
153 | files. If the older versions of these packages are installed in | |
154 | some unusual, non-standard, directories, the <code>make | |
155 | install-migrate</code> command won't find them. Instead, copy | |
156 | those configuration files (<code>authdaemonrc</code>, | |
157 | <code>authldaprc</code>, <code>authmysqlprc</code>, | |
158 | <code>authpgsqlprc</code>, and <code>userdb</code>) by hand. | |
159 | <strong>DO NOT COPY</strong> <code>authdaemonrc.dist</code>, | |
160 | <code>authldaprc.dist</code>, <code>authmysqlprc.dist</code>, and | |
161 | <code>authpgsqlprc.dist</code>.</p> | |
162 | ||
163 | <p>After finishing '<code>make install-migrate</code>', the rest | |
164 | of the installation steps, and after upgrading Courier, | |
165 | Courier-IMAP, or SqWebMail to the new versions, to avoid future | |
166 | confusion the old copies of these configuration files (including | |
167 | the <code>.dist</code> files), should be removed from | |
168 | Courier/Courier-IMAP/SqWebMail's configuration directory. They | |
169 | now live in Courier-authlib's configuration directory | |
170 | (<code>/usr/local/etc/authlib</code>, or whatever was specified | |
171 | to the <code>configure</code> script).</p> | |
172 | ||
173 | <p>The '<code>make install-configure</code>' command is required; | |
174 | it installs and updates the configuration files; this command | |
175 | must be executed when installing Courier-authlib for the first | |
176 | time, and when upgrading from an older version.</p> | |
177 | ||
178 | <h3>Configuration options</h3> | |
179 | ||
180 | <p>The configure script takes the usual <code>autoconf</code> | |
181 | options: <code>--prefix</code>, <code>--bindir</code>, and the | |
182 | rest of the usual toolchain options. The default installation | |
183 | directories should be sufficient, though.</p> | |
184 | ||
185 | <p><strong>DO NOT USE</strong> the <code>--disable-static</code>, | |
186 | or <code>--enable-static=no</code> option. Both static and shared | |
187 | library options must be enabled for courier-authlib to build | |
188 | properly (but see "Post-installation cleanup" below).</p> | |
189 | ||
190 | <h4><code>--without-stdheaderdir</code></h4> | |
191 | ||
192 | <p>The default configuration installs development files in | |
193 | <code>/usr/local/include</code> (see "What gets installed", | |
194 | below). This directory is usually in the compiler's search path | |
195 | for header files. This option must be specified if the compiler | |
196 | does NOT search for header files in | |
197 | <code>/usr/local/include</code> by default.</p> | |
198 | ||
199 | <p>This option must also be specified if other configuration | |
200 | options (such as <code>--prefix</code> or | |
201 | <code>--includedir</code>) specify a different installation | |
202 | directory, and the new directory is also not searched by the | |
203 | compiler, by default</p> | |
204 | ||
205 | <h4><code>--with-mailuser=<em>userid</em>, | |
206 | --with-mailgroup=<em>groupid</em></code></h4> | |
207 | ||
208 | <p>"userid" is a reserved system username, "groupid" is a | |
209 | reserved system groupname. These two options should be used | |
210 | before installing Courier for the first time. These options are | |
211 | not required before installing Courier-IMAP or SqWebMail.</p> | |
212 | ||
213 | <p>These options specify the user/group that will own the | |
214 | configuration files, and the socket that authentication daemon | |
215 | process listens on. This is a key part of Courier's security | |
216 | model.</p> | |
217 | ||
218 | <p>These options should not be necessary if upgrading from an | |
219 | earlier version of Courier and/or this authentication library. | |
220 | The default userid and groupid are computed as follows:</p> | |
221 | ||
222 | <ul> | |
223 | <li>If an earlier version of the Courier authentication library | |
224 | is already installed in the same directory, the userid and the | |
225 | groupid is the same as the earlier version, otherwise:</li> | |
226 | ||
227 | <li>If an earlier version of the Courier package is installed | |
228 | (only the Courier package, the Courier-IMAP and SqWebMail | |
229 | packages do not carry this information), the userid and the | |
230 | groupid is the same as the ones used to configure Courier, | |
231 | otherwise:</li> | |
232 | ||
233 | <li>The userid is the first userid from the following list | |
234 | which exists in the system: courier, daemon, adm, bin, root; | |
235 | and the groupid is the first groupid from the following list | |
236 | which exists in the system: courier, daemon, adm, sys, | |
237 | root.</li> | |
238 | </ul> | |
239 | ||
240 | <p>When installing Courier authentication library for the first | |
241 | time, it is highly recommended to create a "courier" userid and | |
242 | groupid, so that specifying these options will not be | |
243 | necessary.</p> | |
244 | ||
245 | <p>This configure script descends from the old authentication | |
246 | library that was included in the older Courier, Courier-IMAP, and | |
247 | SqWebMail packages. As such, it also has many other undocumented | |
248 | options that manually disable specific authentication | |
249 | modules.</p> | |
250 | ||
251 | <p><strong>These options are no longer officially | |
252 | documented.</strong> Individual modules can be disabled after | |
253 | installation, by editing the <code>authdaemonrc</code> | |
254 | configuration file.</p> | |
255 | ||
256 | <h4><code>VARIABLE=</code><em><code>value</code></em></h4> | |
257 | ||
258 | <p>Environment variables may be set either before running the | |
259 | configure script, or by providing the environment variables as | |
260 | parameters to the configure script. Example:</p> | |
261 | ||
262 | <blockquote> | |
263 | <pre> | |
264 | ./configure --with-mailuser=mail --with-mailgroup=mail \ | |
d9898ee8 | 265 | CC=/opt/fsf/bin/gcc LDFLAGS=-L/opt/fsf/lib \ |
dd184caf | 266 | MAKE=gmake |
267 | </pre> | |
268 | </blockquote> | |
269 | ||
270 | <p>The <code>CC</code> environment variable specifies the name of | |
271 | the C compiler that will be used to compile the authentication | |
272 | library. For some reason, on this oddball system some system | |
273 | libraries are installed in <code>/opt/fsf/lib</code>, and the | |
274 | compiler doesn't search this directory by default. Therefore, the | |
275 | compiler needs the "<code>-L/opt/fsf/lib</code>" to properly link | |
276 | all programs, and this option is specified in the | |
277 | <code>LDFLAGS</code> environment variable.</p> | |
278 | ||
279 | <p>Another possibility is to add the <code>/opt/fsf/bin</code> | |
280 | directory to the <code>PATH</code> environment variable, prior to | |
281 | running the <code>configure</code> script. The | |
282 | <code>configure</code> script searches for all needed software in | |
283 | the current <code>PATH</code>. Explicitly pointing configure to | |
284 | something, like <code>CC</code>, is only needed if the program is | |
285 | not already in the default PATH.</p> | |
286 | ||
287 | <p>Finally, Courier authentication library must be built with GNU | |
288 | make. On this example system the <code>make</code> command is the | |
289 | old SysV-derived make, which will not work. GNU make is installed | |
290 | here as the "<code>gmake</code>" command. The | |
291 | <code>configure</code> script will ordinarily find the | |
292 | <code>make</code> command and be happy with it, by mistake. | |
293 | Explicitly setting <code>MAKE</code> to <code>gmake</code> fixes | |
294 | that (and the human operator also needs to invoke the | |
295 | <code>gmake</code> command also).</p> | |
296 | ||
297 | <h2><a name="deps" id="Dependencies">Dependencies</a></h2> | |
298 | ||
299 | <p>On a minimum, bare-bones system, the Courier authentication | |
300 | library builds support for garden-variety authentication against | |
301 | system accounts (from the system's password file, | |
302 | <code>/etc/passwd</code>).</p> | |
303 | ||
304 | <p>If the <code>configure</code> script detects that certain | |
305 | optional software components are installed, additional | |
306 | authentication modules will be built and installed. This chapter | |
307 | describes what needs to be installed in order to build the | |
308 | optional authentication modules.</p> | |
309 | ||
310 | <blockquote> | |
311 | <p><strong>NOTE:</strong> In all cases, it is not sufficient to | |
312 | install the runtime support libraries for the following | |
313 | components. In order to build the authentication modules the | |
314 | <strong>DEVELOPMENT LIBRARIES</strong> for the following | |
315 | software packages must be installed. The development libraries | |
316 | are usually a separate package, that must be installed in | |
317 | addition to the package that adds alleged support for the | |
318 | following software libraries.</p> | |
319 | </blockquote> | |
320 | ||
321 | <ul> | |
322 | <li><strong>GDBM or Berkeley DB library</strong> - The | |
323 | <code>userdb</code> authentication module will be built if | |
324 | either library is installed. The <code>userdb</code> | |
325 | authentication module includes Perl scripts that maintain a | |
326 | list of available accounts in plain text files. A Perl script | |
327 | then compiles the account list into a binary database, either | |
328 | GDBM or DB, which is then used to look up account | |
329 | information.</li> | |
330 | ||
331 | <li><strong>OpenLDAP</strong> - The LDAP authentication modules | |
332 | requires OpenLDAP client libraries to be installed. Sometimes | |
333 | there's some confusion when commercial LDAP servers are used, | |
334 | which come with their own development toolkits, which use a | |
335 | different API than OpenLDAP. Even if a commercial LDAP server | |
336 | is used to provide LDAP services, OpenLDAP is still required to | |
337 | enable LDAP services in Courier.</li> | |
338 | ||
b0322a85 CE |
339 | <li><strong>MySQL</strong>, <strong>PostgreSQL</strong>, and |
340 | <strong>SQLite</strong> - The MySQL, PostgreSQL, and SQLite | |
341 | authentication modules require, obviously, | |
342 | MySQL/PostgreSQL/SQLite development libraries.<br /></li> | |
dd184caf | 343 | </ul> |
344 | ||
345 | <h2><a name="What" id="What">What gets installed</a></h2> | |
346 | ||
347 | <ul> | |
348 | <li><code>/usr/local/etc/authlib</code> - the configuration | |
349 | files.</li> | |
350 | ||
351 | <li><code>/usr/local/sbin</code> - the authdaemond startup | |
352 | script; several utility programs (courierlogger, authconfig, | |
353 | authtest, authenumerate); and userdb scripts.</li> | |
354 | ||
355 | <li><code>/usr/local/lib/courier-authlib</code> - various | |
356 | authentication modules, as shared libraries.</li> | |
357 | ||
358 | <li><code>/usr/local/libexec/courier-authlib</code> - some | |
359 | miscellaneous stuff.</li> | |
360 | ||
361 | <li><code>/usr/local/var/authdaemon</code> - a subdirectory | |
362 | that contains the filesystem socket which authdaemond listens | |
363 | on.</li> | |
364 | ||
365 | <li><code>/usr/local/include</code> - a header file that | |
366 | Courier packages will use to build against | |
367 | courier-authlib.</li> | |
368 | </ul> | |
369 | ||
370 | <p>Toolchain options to the <code>configure</code> script may be | |
371 | used to select alternative installation directories for these | |
372 | components.</p> | |
373 | ||
374 | <h3>Post-installation cleanup</h3> | |
375 | ||
376 | <p>On most systems, after running <code>make | |
377 | install-configure</code> all static libraries can be removed from | |
378 | the <code>/usr/local/lib/courier-authlib</code> directory:</p> | |
379 | ||
380 | <p><code>rm -rf /usr/local/lib/courier-authlib/*.a</code></p> | |
381 | ||
382 | <p>The Courier authentication library uses only the shared | |
383 | libraries. The static versions of the shared libraries are not | |
384 | used. They are installed by default, via libtool, but are not | |
385 | really needed. On most platforms the libtool files, "*.la" can | |
386 | also be removed. Do not remove any soft links.</p> | |
387 | ||
388 | <h2><a name="manpage" id="manpage">For more information</a></h2> | |
389 | ||
390 | <p>Following "<code>make install</code>", see the <a href= | |
391 | "README_authlib.html"><code>README_authlib.html</code></a> file | |
392 | for details on setting up the authentication modules. The | |
393 | <code>README_authlib.html</code> file gets assembled as part of | |
394 | the build process.</p> | |
395 | ||
396 | <p>Before proceding to install any other packages, be sure to | |
397 | verify that the authentication library is working by running the | |
398 | <code>authtest</code> command, as documented in the | |
399 | <code>README_authlib.html</code> file.</p> | |
400 | ||
401 | <h2><a name="Starting" id="Starting">Starting and stopping the | |
402 | authentication daemon</a></h2> | |
403 | ||
404 | <p>The following command must be added to your system startup | |
405 | script, in order to initialize the authentication library when | |
406 | booting:</p> | |
407 | <pre> | |
408 | /usr/local/sbin/authdaemond start | |
409 | </pre> | |
410 | ||
411 | <p>Similarly, the authentication library can be stopped by the | |
412 | "<code>authdaemond stop</code>" command. After editing the | |
413 | <code>authdaemonrc</code> configuration file use | |
414 | "<code>authdaemond restart</code>" command to reconfigure the | |
415 | daemon process. Systems that use SYSV-derived initscripts can use | |
416 | the "<code>courier-authlib.sysvinit</code>" script, which gets | |
417 | built in the source directory, to start and stop | |
418 | <code>authdaemond</code> when the system boots or halts.</p> | |
419 | ||
420 | <h2><a name="Building" id="Building">Building RPMs</a></h2> | |
421 | ||
422 | <p>See <a onclick= | |
423 | ""><code>http://www.courier-mta.org/FAQ.html#rpm</code></a> for | |
424 | instructions on building binary RPMs from the source tarball. | |
425 | Those instructions will work for this package.</p> | |
426 | ||
427 | <blockquote> | |
428 | <p><strong>NOTE:</strong></p> | |
429 | ||
430 | <p>RPM will refuse to build the Courier authentication library | |
431 | unless all prerequisite development libraries for LDAP, MySQL, | |
b0322a85 CE |
432 | PostgreSQL, and SQLite are installed. <strong>Do not try to |
433 | hack the RPM build script to ignore these | |
434 | dependencies!</strong> For simplicity's and maintainability | |
435 | sake the RPM build script creates all available authentication | |
436 | modules. All extra authentication modules will be built as | |
437 | <em>optional</em> subpackages. They do not have to be installed | |
438 | at runtime. Install the LDAP, MySQL, PostgreSQL, and SQLite | |
439 | development libraries only for the duration of building binary | |
440 | RPMs. They can be uninstalled afterwards.</p> | |
dd184caf | 441 | </blockquote> |
442 | ||
443 | <h2><a name="Guidelines" id="Guidelines">Guidelines for using | |
444 | other package managers</a></h2> | |
445 | ||
446 | <p>The recommended way to build packages can be inferred from the | |
447 | RPM build script. It is summarized here for convenience:</p> | |
448 | ||
449 | <ul> | |
450 | <li>Decide whether or not Courier-specific userid and groupid | |
451 | needs to be created, and, if so, make the necessary | |
452 | arrangements.</li> | |
453 | ||
454 | <li>Ensure that all prerequisite development libraries are | |
455 | available.</li> | |
456 | ||
457 | <li>Run the <code>configure</code> script, run | |
458 | <code>make</code>, then <code>make install</code> as | |
459 | usual.</li> | |
460 | ||
8d138742 CE |
461 | <li>Copy the "<code>sysconftool</code>" script somewhere into |
462 | the installation tree. A good place would be | |
dd184caf | 463 | <code>%libexecdir%/courier-authlib</code>. This is the |
8d138742 CE |
464 | '<code>make install-upgrade</code>' command. Don't run this at |
465 | build time. Instead, arrange for the package installation | |
466 | script to run the "<code>sysconftool | |
467 | %sysconfdir%/authlib/*.dist</code>" after the package is | |
dd184caf | 468 | installed <strong>OR UPGRADED</strong>.</li> |
469 | ||
470 | <li>The "<code>authdaemond</code>", | |
471 | "<code>authenumerate</code>", and "<code>authtest</code>" | |
472 | commands can be renamed, to avoid name clashes.</li> | |
473 | ||
474 | <li>Remove all static libraries from | |
475 | <code>%libdir%/courier-authlib</code>.</li> | |
476 | </ul> | |
477 | ||
478 | <p>Now, create the installable packages, as follows:</p> | |
479 | ||
480 | <ul> | |
481 | <li><code>%libdir%/courier-authlib/libauthldap*</code> goes | |
482 | into the LDAP subpackage.</li> | |
483 | ||
484 | <li><code>%libdir%/courier-authlib/libauthmysql*</code> goes | |
485 | into the MySQL subpackage.</li> | |
486 | ||
b0322a85 CE |
487 | <li><code>%libdir%/courier-authlib/libauthsqlite*</code> goes |
488 | into the SQLite subpackage.</li> | |
489 | ||
dd184caf | 490 | <li><code>%libdir%/courier-authlib/libauthpgsql*</code> goes |
491 | into the PostgreSQL subpackage.</li> | |
492 | ||
493 | <li><code>%libdir%/courier-authlib/libauthuserdb*</code> goes | |
494 | into the userdb subpackage.</li> | |
495 | ||
496 | <li>Everything else can go into the main package. Optionally, | |
497 | the <code>courierauthconfig</code> binary, stuff in | |
498 | <code>%includedir%</code>, and in <code>%mandir%/man3</code>, | |
499 | can go into a devel subpackage.</li> | |
500 | </ul> | |
d9898ee8 | 501 | </body> |
502 | </html> |