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