Import Debian changes 0.69.0-2
[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=us-ascii" />
8
9 <title>INSTALL</title>
10 <!-- Copyright 2004-2012 Double Precision, Inc. See COPYING for -->
11 <!-- distribution information. -->
12 </head>
13
14 <body>
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=
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>
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>
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>
78 </ul>
79
80 <p>Courier-authlib uses Libtool to build shared libraries.
81 Libtool must be installed, together with its <tt>libltdl</tt>
82 library and its header files.</p>
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]*...
115 make
116 make install
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 \
265 CC=/opt/fsf/bin/gcc LDFLAGS=-L/opt/fsf/lib \
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
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>
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,
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>
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
461 <li>Copy the "<code>sysconftool</code>" script somewhere into
462 the installation tree. A good place would be
463 <code>%libexecdir%/courier-authlib</code>. This is the
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
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/libauthsqlite*</code> goes
488 into the SQLite subpackage.</li>
489
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>
501 </body>
502 </html>