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
|
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
<title>INSTALL</title>
<meta name="generator" content="amaya 8.7, see http://www.w3.org/Amaya/" />
<!-- $Id: INSTALL.html,v 1.6 2005/07/02 14:48:57 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
strict 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
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>" and "<code>authmigrate</code>"
scripts somewhere into the installation tree. A good place would be
<code>%libexecdir%/courier-authlib</code>. This is the '<code>make
install-migrate</code>' and '<code>make install-upgrade</code>' commands.
Don't run them at build time. Instead, arrange for the package
installation script to run the <code>authmigrate</code> script first,
then "<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>
<p></p>
</body>
</html>
|
