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