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>
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>
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
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>
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
97 <li>Install a recent version of the GNU linker
</li>
99 <li>Install the current version of Libtool
</li>
101 <li>Install the current version of gcc
</li>
104 <h2><a name=
"Installation" id=
"Installation">Installation
107 <p>The following sequence of commands should be sufficient to
108 install courier-authlib in most cases:
</p>
110 ./configure [options] [variable=value]*...
113 make install-migrate # Only if upgrading from pre-authlib Courier packages
114 make install-configure
118 <p><strong>NOTE:
</strong> On the BSD family, GNU make is
119 usually the 'gmake' command. Use the 'gmake' command, instead
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
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>
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
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>
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>
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>
174 <h3>Configuration options
</h3>
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>
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>
186 <h4><code>--without-stdheaderdir
</code></h4>
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>
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>
201 <h4><code>--with-mailuser=
<em>userid
</em>,
202 --with-mailgroup=
<em>groupid
</em></code></h4>
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>
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
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>
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>
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,
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,
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
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
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>
252 <h4><code>VARIABLE=
</code><em><code>value
</code></em></h4>
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>
260 ./configure --with-mailuser=mail --with-mailgroup=mail \
261 CC=/opt/fsf/bin/gcc LDFLAGS=-L/opt/fsf/lib \
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>
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>
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>
293 <h2><a name=
"deps" id=
"Dependencies">Dependencies
</a></h2>
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>
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>
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>
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
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>
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>
341 <h2><a name=
"What" id=
"What">What gets installed
</a></h2>
344 <li><code>/usr/local/etc/authlib
</code> - the configuration
347 <li><code>/usr/local/sbin
</code> - the authdaemond startup
348 script; several utility programs (courierlogger, authconfig,
349 authtest, authenumerate); and userdb scripts.
</li>
351 <li><code>/usr/local/lib/courier-authlib
</code> - various
352 authentication modules, as shared libraries.
</li>
354 <li><code>/usr/local/libexec/courier-authlib
</code> - some
355 miscellaneous stuff.
</li>
357 <li><code>/usr/local/var/authdaemon
</code> - a subdirectory
358 that contains the filesystem socket which authdaemond listens
361 <li><code>/usr/local/include
</code> - a header file that
362 Courier packages will use to build against
363 courier-authlib.
</li>
366 <p>Toolchain options to the
<code>configure
</code> script may be
367 used to select alternative installation directories for these
370 <h3>Post-installation cleanup
</h3>
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>
376 <p><code>rm -rf /usr/local/lib/courier-authlib/*.a
</code></p>
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>
384 <h2><a name=
"manpage" id=
"manpage">For more information
</a></h2>
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>
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>
397 <h2><a name=
"Starting" id=
"Starting">Starting and stopping the
398 authentication daemon
</a></h2>
400 <p>The following command must be added to your system startup
401 script, in order to initialize the authentication library when
404 /usr/local/sbin/authdaemond start
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>
416 <h2><a name=
"Building" id=
"Building">Building RPMs
</a></h2>
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>
424 <p><strong>NOTE:
</strong></p>
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>
439 <h2><a name=
"Guidelines" id=
"Guidelines">Guidelines for using
440 other package managers
</a></h2>
442 <p>The recommended way to build packages can be inferred from the
443 RPM build script. It is summarized here for convenience:
</p>
446 <li>Decide whether or not Courier-specific userid and groupid
447 needs to be created, and, if so, make the necessary
450 <li>Ensure that all prerequisite development libraries are
453 <li>Run the
<code>configure
</code> script, run
454 <code>make
</code>, then
<code>make install
</code> as
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>
466 <li>The
"<code>authdaemond</code>",
467 "<code>authenumerate</code>", and
"<code>authtest</code>"
468 commands can be renamed, to avoid name clashes.
</li>
470 <li>Remove all static libraries from
471 <code>%libdir%/courier-authlib
</code>.
</li>
474 <p>Now, create the installable packages, as follows:
</p>
477 <li><code>%libdir%/courier-authlib/libauthldap*
</code> goes
478 into the LDAP subpackage.
</li>
480 <li><code>%libdir%/courier-authlib/libauthmysql*
</code> goes
481 into the MySQL subpackage.
</li>
483 <li><code>%libdir%/courier-authlib/libauthsqlite*
</code> goes
484 into the SQLite subpackage.
</li>
486 <li><code>%libdir%/courier-authlib/libauthpgsql*
</code> goes
487 into the PostgreSQL subpackage.
</li>
489 <li><code>%libdir%/courier-authlib/libauthuserdb*
</code> goes
490 into the userdb subpackage.
</li>
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>