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