Merge branch 'debian'
[hcoop/debian/courier-authlib.git] / INSTALL.html
1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3
4 <html xmlns="http://www.w3.org/1999/xhtml">
5 <head>
6 <meta http-equiv="Content-Type" content=
7 "text/html; charset=utf-8" />
8
9 <title>INSTALL</title>
10 <meta name="generator" content="Bluefish 1.0.7"/>
11 <!-- $Id: INSTALL.html,v 1.8 2008/08/07 22:40:49 mrsam Exp $ -->
12 <!-- Copyright 2004 Double Precision, Inc. See COPYING for -->
13 <!-- distribution information. -->
14 </head>
15
16 <body>
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]*...
114 make
115 make install
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 \
264 CC=/opt/fsf/bin/gcc LDFLAGS=-L/opt/fsf/lib \
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>" script somewhere into
460 the installation tree. A good place would be
461 <code>%libexecdir%/courier-authlib</code>. This is the
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
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>
496 </body>
497 </html>