1 <!DOCTYPE html PUBLIC
"-//W3C//DTD XHTML 1.0 Strict//EN"
2 "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
4 <html xmlns=
"http://www.w3.org/1999/xhtml">
6 <meta http-equiv=
"Content-Type" content=
7 "text/html; charset=us-ascii" />
10 <!-- Copyright 2004-2012 Double Precision, Inc. See COPYING for -->
11 <!-- distribution information. -->
15 <h1>Table of Contents
</h1>
17 <p>In this document (see INSTALL.html for the formatted version
18 of this INSTALL file):
</p>
21 <li><a onclick=
"" href=
"#Requirements">Requirements
</a></li>
23 <li><a onclick=
"" href=
"#Installation">Installation
26 <li><a onclick=
"" href=
"#deps">Dependencies
</a></li>
28 <li><a onclick=
"" href=
"#What">What gets installed
</a></li>
30 <li><a onclick=
"" href=
"#manpage">For more information
</a></li>
32 <li><a onclick=
"" href=
"#Starting">Starting and stopping the
33 authentication daemon
</a></li>
35 <li><a onclick=
"" href=
"#Building">Building RPMs
</a></li>
37 <li><a onclick=
"" href=
"#Guidelines">Guidelines for using other
38 package managers
</a></li>
41 <h2><a name=
"Requirements" id=
42 "Requirements">Requirements
</a></h2>
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>
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>
52 <li>The GNU linker (
<a onclick=
"" href=
53 "http://www.gnu.org/software/binutils/">http://www.gnu.org/software/binutils/
</a>)
</li>
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>
62 <li>GNU make (
<a onclick=
"" href=
63 "http://www.gnu.org/software/make/">http://www.gnu.org/software/make/
</a>)
</li>
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>
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>
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>
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
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>
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
101 <li>Install a recent version of the GNU linker
</li>
103 <li>Install the current version of Libtool
</li>
105 <li>Install the current version of gcc
</li>
108 <h2><a name=
"Installation" id=
"Installation">Installation
111 <p>The following sequence of commands should be sufficient to
112 install courier-authlib in most cases:
</p>
114 ./configure [options] [variable=value]*...
117 make install-migrate # Only if upgrading from pre-authlib Courier packages
118 make install-configure
122 <p><strong>NOTE:
</strong> On the BSD family, GNU make is
123 usually the 'gmake' command. Use the 'gmake' command, instead
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
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>
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
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>
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>
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>
178 <h3>Configuration options
</h3>
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>
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>
190 <h4><code>--without-stdheaderdir
</code></h4>
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>
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>
205 <h4><code>--with-mailuser=
<em>userid
</em>,
206 --with-mailgroup=
<em>groupid
</em></code></h4>
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>
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
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>
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>
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,
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,
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
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
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>
256 <h4><code>VARIABLE=
</code><em><code>value
</code></em></h4>
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>
264 ./configure --with-mailuser=mail --with-mailgroup=mail \
265 CC=/opt/fsf/bin/gcc LDFLAGS=-L/opt/fsf/lib \
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>
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>
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>
297 <h2><a name=
"deps" id=
"Dependencies">Dependencies
</a></h2>
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>
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>
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>
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
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>
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>
345 <h2><a name=
"What" id=
"What">What gets installed
</a></h2>
348 <li><code>/usr/local/etc/authlib
</code> - the configuration
351 <li><code>/usr/local/sbin
</code> - the authdaemond startup
352 script; several utility programs (courierlogger, authconfig,
353 authtest, authenumerate); and userdb scripts.
</li>
355 <li><code>/usr/local/lib/courier-authlib
</code> - various
356 authentication modules, as shared libraries.
</li>
358 <li><code>/usr/local/libexec/courier-authlib
</code> - some
359 miscellaneous stuff.
</li>
361 <li><code>/usr/local/var/authdaemon
</code> - a subdirectory
362 that contains the filesystem socket which authdaemond listens
365 <li><code>/usr/local/include
</code> - a header file that
366 Courier packages will use to build against
367 courier-authlib.
</li>
370 <p>Toolchain options to the
<code>configure
</code> script may be
371 used to select alternative installation directories for these
374 <h3>Post-installation cleanup
</h3>
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>
380 <p><code>rm -rf /usr/local/lib/courier-authlib/*.a
</code></p>
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>
388 <h2><a name=
"manpage" id=
"manpage">For more information
</a></h2>
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>
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>
401 <h2><a name=
"Starting" id=
"Starting">Starting and stopping the
402 authentication daemon
</a></h2>
404 <p>The following command must be added to your system startup
405 script, in order to initialize the authentication library when
408 /usr/local/sbin/authdaemond start
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>
420 <h2><a name=
"Building" id=
"Building">Building RPMs
</a></h2>
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>
428 <p><strong>NOTE:
</strong></p>
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>
443 <h2><a name=
"Guidelines" id=
"Guidelines">Guidelines for using
444 other package managers
</a></h2>
446 <p>The recommended way to build packages can be inferred from the
447 RPM build script. It is summarized here for convenience:
</p>
450 <li>Decide whether or not Courier-specific userid and groupid
451 needs to be created, and, if so, make the necessary
454 <li>Ensure that all prerequisite development libraries are
457 <li>Run the
<code>configure
</code> script, run
458 <code>make
</code>, then
<code>make install
</code> as
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>
470 <li>The
"<code>authdaemond</code>",
471 "<code>authenumerate</code>", and
"<code>authtest</code>"
472 commands can be renamed, to avoid name clashes.
</li>
474 <li>Remove all static libraries from
475 <code>%libdir%/courier-authlib
</code>.
</li>
478 <p>Now, create the installable packages, as follows:
</p>
481 <li><code>%libdir%/courier-authlib/libauthldap*
</code> goes
482 into the LDAP subpackage.
</li>
484 <li><code>%libdir%/courier-authlib/libauthmysql*
</code> goes
485 into the MySQL subpackage.
</li>
487 <li><code>%libdir%/courier-authlib/libauthsqlite*
</code> goes
488 into the SQLite subpackage.
</li>
490 <li><code>%libdir%/courier-authlib/libauthpgsql*
</code> goes
491 into the PostgreSQL subpackage.
</li>
493 <li><code>%libdir%/courier-authlib/libauthuserdb*
</code> goes
494 into the userdb subpackage.
</li>
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>