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