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= |
7 | "text/html; charset=utf-8" /> | |
8 | ||
d9898ee8 | 9 | <title>INSTALL</title> |
dd184caf | 10 | <meta name="generator" content="Bluefish 1.0.7"/> |
8d138742 | 11 | <!-- $Id: INSTALL.html,v 1.8 2008/08/07 22:40:49 mrsam Exp $ --> |
d9898ee8 | 12 | <!-- Copyright 2004 Double Precision, Inc. See COPYING for --> |
13 | <!-- distribution information. --> | |
14 | </head> | |
15 | ||
16 | <body> | |
dd184caf | 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 | |
dd184caf | 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 \ |
dd184caf | 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 | ||
8d138742 CE |
459 | <li>Copy the "<code>sysconftool</code>" script somewhere into |
460 | the installation tree. A good place would be | |
dd184caf | 461 | <code>%libexecdir%/courier-authlib</code>. This is the |
8d138742 CE |
462 | '<code>make install-upgrade</code>' command. Don't run this at |
463 | build time. Instead, arrange for the package installation | |
464 | script to run the "<code>sysconftool | |
465 | %sysconfdir%/authlib/*.dist</code>" after the package is | |
dd184caf | 466 | installed <strong>OR UPGRADED</strong>.</li> |
467 | ||
468 | <li>The "<code>authdaemond</code>", | |
469 | "<code>authenumerate</code>", and "<code>authtest</code>" | |
470 | commands can be renamed, to avoid name clashes.</li> | |
471 | ||
472 | <li>Remove all static libraries from | |
473 | <code>%libdir%/courier-authlib</code>.</li> | |
474 | </ul> | |
475 | ||
476 | <p>Now, create the installable packages, as follows:</p> | |
477 | ||
478 | <ul> | |
479 | <li><code>%libdir%/courier-authlib/libauthldap*</code> goes | |
480 | into the LDAP subpackage.</li> | |
481 | ||
482 | <li><code>%libdir%/courier-authlib/libauthmysql*</code> goes | |
483 | into the MySQL subpackage.</li> | |
484 | ||
485 | <li><code>%libdir%/courier-authlib/libauthpgsql*</code> goes | |
486 | into the PostgreSQL subpackage.</li> | |
487 | ||
488 | <li><code>%libdir%/courier-authlib/libauthuserdb*</code> goes | |
489 | into the userdb subpackage.</li> | |
490 | ||
491 | <li>Everything else can go into the main package. Optionally, | |
492 | the <code>courierauthconfig</code> binary, stuff in | |
493 | <code>%includedir%</code>, and in <code>%mandir%/man3</code>, | |
494 | can go into a devel subpackage.</li> | |
495 | </ul> | |
d9898ee8 | 496 | </body> |
497 | </html> |