Commit | Line | Data |
---|---|---|
dd184caf | 1 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" |
2 | "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> | |
3 | ||
d9898ee8 | 4 | <html xmlns="http://www.w3.org/1999/xhtml"> |
5 | <head> | |
dd184caf | 6 | <meta http-equiv="Content-Type" content= |
b0322a85 | 7 | "text/html; charset=us-ascii" /> |
dd184caf | 8 | |
d9898ee8 | 9 | <title>INSTALL</title> |
b0322a85 | 10 | <!-- Copyright 2004-2012 Double Precision, Inc. See COPYING for --> |
d9898ee8 | 11 | <!-- distribution information. --> |
12 | </head> | |
13 | ||
14 | <body> | |
dd184caf | 15 | <h1>Table of Contents</h1> |
16 | ||
17 | <p>In this document (see INSTALL.html for the formatted version | |
18 | of this INSTALL file):</p> | |
19 | ||
20 | <ul> | |
21 | <li><a onclick="" href="#Requirements">Requirements</a></li> | |
22 | ||
23 | <li><a onclick="" href="#Installation">Installation | |
24 | overview</a></li> | |
25 | ||
26 | <li><a onclick="" href="#deps">Dependencies</a></li> | |
27 | ||
28 | <li><a onclick="" href="#What">What gets installed</a></li> | |
29 | ||
30 | <li><a onclick="" href="#manpage">For more information</a></li> | |
31 | ||
32 | <li><a onclick="" href="#Starting">Starting and stopping the | |
33 | authentication daemon</a></li> | |
34 | ||
35 | <li><a onclick="" href="#Building">Building RPMs</a></li> | |
36 | ||
37 | <li><a onclick="" href="#Guidelines">Guidelines for using other | |
38 | package managers</a></li> | |
39 | </ul> | |
40 | ||
41 | <h2><a name="Requirements" id= | |
42 | "Requirements">Requirements</a></h2> | |
43 | ||
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> | |
47 | ||
48 | <ul> | |
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> | |
51 | ||
52 | <li>The GNU linker (<a onclick="" href= | |
53 | "http://www.gnu.org/software/binutils/">http://www.gnu.org/software/binutils/</a>)</li> | |
54 | ||
55 | <li>Libtool (<a onclick="" href= | |
b0322a85 CE |
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> | |
dd184caf | 61 | |
62 | <li>GNU make (<a onclick="" href= | |
63 | "http://www.gnu.org/software/make/">http://www.gnu.org/software/make/</a>)</li> | |
64 | ||
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> | |
74 | </ul> | |
75 | ||
76 | <p>Courier-authlib uses Libtool to build shared libraries. | |
b0322a85 CE |
77 | Libtool must be installed, together with its <tt>libltdl</tt> |
78 | library and its header files.</p> | |
dd184caf | 79 | |
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 | |
85 | be installed.</p> | |
86 | ||
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> | |
89 | ||
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 | |
94 | package:</p> | |
95 | ||
96 | <ol> | |
97 | <li>Install a recent version of the GNU linker</li> | |
98 | ||
99 | <li>Install the current version of Libtool</li> | |
100 | ||
101 | <li>Install the current version of gcc</li> | |
102 | </ol> | |
103 | ||
104 | <h2><a name="Installation" id="Installation">Installation | |
105 | overview</a></h2> | |
106 | ||
107 | <p>The following sequence of commands should be sufficient to | |
108 | install courier-authlib in most cases:</p> | |
109 | <pre> | |
110 | ./configure [options] [variable=value]*... | |
d9898ee8 | 111 | make |
112 | make install | |
dd184caf | 113 | make install-migrate # Only if upgrading from pre-authlib Courier packages |
114 | make install-configure | |
115 | </pre> | |
116 | ||
117 | <blockquote> | |
118 | <p><strong>NOTE:</strong> On the BSD family, GNU make is | |
119 | usually the 'gmake' command. Use the 'gmake' command, instead | |
120 | of 'make'.</p> | |
121 | </blockquote> | |
122 | ||
123 | <blockquote> | |
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 | |
132 | appears.</p> | |
133 | </blockquote> | |
134 | ||
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> | |
140 | ||
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 | |
144 | otherwise.</p> | |
145 | ||
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> | |
158 | ||
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> | |
168 | ||
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> | |
173 | ||
174 | <h3>Configuration options</h3> | |
175 | ||
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> | |
180 | ||
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> | |
185 | ||
186 | <h4><code>--without-stdheaderdir</code></h4> | |
187 | ||
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> | |
194 | ||
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> | |
200 | ||
201 | <h4><code>--with-mailuser=<em>userid</em>, | |
202 | --with-mailgroup=<em>groupid</em></code></h4> | |
203 | ||
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> | |
208 | ||
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 | |
212 | model.</p> | |
213 | ||
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> | |
217 | ||
218 | <ul> | |
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> | |
222 | ||
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, | |
227 | otherwise:</li> | |
228 | ||
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, | |
233 | root.</li> | |
234 | </ul> | |
235 | ||
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 | |
239 | necessary.</p> | |
240 | ||
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 | |
245 | modules.</p> | |
246 | ||
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> | |
251 | ||
252 | <h4><code>VARIABLE=</code><em><code>value</code></em></h4> | |
253 | ||
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> | |
257 | ||
258 | <blockquote> | |
259 | <pre> | |
260 | ./configure --with-mailuser=mail --with-mailgroup=mail \ | |
d9898ee8 | 261 | CC=/opt/fsf/bin/gcc LDFLAGS=-L/opt/fsf/lib \ |
dd184caf | 262 | MAKE=gmake |
263 | </pre> | |
264 | </blockquote> | |
265 | ||
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> | |
274 | ||
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> | |
282 | ||
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> | |
292 | ||
293 | <h2><a name="deps" id="Dependencies">Dependencies</a></h2> | |
294 | ||
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> | |
299 | ||
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> | |
305 | ||
306 | <blockquote> | |
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> | |
315 | </blockquote> | |
316 | ||
317 | <ul> | |
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 | |
325 | information.</li> | |
326 | ||
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> | |
334 | ||
b0322a85 CE |
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> | |
dd184caf | 339 | </ul> |
340 | ||
341 | <h2><a name="What" id="What">What gets installed</a></h2> | |
342 | ||
343 | <ul> | |
344 | <li><code>/usr/local/etc/authlib</code> - the configuration | |
345 | files.</li> | |
346 | ||
347 | <li><code>/usr/local/sbin</code> - the authdaemond startup | |
348 | script; several utility programs (courierlogger, authconfig, | |
349 | authtest, authenumerate); and userdb scripts.</li> | |
350 | ||
351 | <li><code>/usr/local/lib/courier-authlib</code> - various | |
352 | authentication modules, as shared libraries.</li> | |
353 | ||
354 | <li><code>/usr/local/libexec/courier-authlib</code> - some | |
355 | miscellaneous stuff.</li> | |
356 | ||
357 | <li><code>/usr/local/var/authdaemon</code> - a subdirectory | |
358 | that contains the filesystem socket which authdaemond listens | |
359 | on.</li> | |
360 | ||
361 | <li><code>/usr/local/include</code> - a header file that | |
362 | Courier packages will use to build against | |
363 | courier-authlib.</li> | |
364 | </ul> | |
365 | ||
366 | <p>Toolchain options to the <code>configure</code> script may be | |
367 | used to select alternative installation directories for these | |
368 | components.</p> | |
369 | ||
370 | <h3>Post-installation cleanup</h3> | |
371 | ||
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> | |
375 | ||
376 | <p><code>rm -rf /usr/local/lib/courier-authlib/*.a</code></p> | |
377 | ||
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> | |
383 | ||
384 | <h2><a name="manpage" id="manpage">For more information</a></h2> | |
385 | ||
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> | |
391 | ||
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> | |
396 | ||
397 | <h2><a name="Starting" id="Starting">Starting and stopping the | |
398 | authentication daemon</a></h2> | |
399 | ||
400 | <p>The following command must be added to your system startup | |
401 | script, in order to initialize the authentication library when | |
402 | booting:</p> | |
403 | <pre> | |
404 | /usr/local/sbin/authdaemond start | |
405 | </pre> | |
406 | ||
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> | |
415 | ||
416 | <h2><a name="Building" id="Building">Building RPMs</a></h2> | |
417 | ||
418 | <p>See <a onclick= | |
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> | |
422 | ||
423 | <blockquote> | |
424 | <p><strong>NOTE:</strong></p> | |
425 | ||
426 | <p>RPM will refuse to build the Courier authentication library | |
427 | unless all prerequisite development libraries for LDAP, MySQL, | |
b0322a85 CE |
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> | |
dd184caf | 437 | </blockquote> |
438 | ||
439 | <h2><a name="Guidelines" id="Guidelines">Guidelines for using | |
440 | other package managers</a></h2> | |
441 | ||
442 | <p>The recommended way to build packages can be inferred from the | |
443 | RPM build script. It is summarized here for convenience:</p> | |
444 | ||
445 | <ul> | |
446 | <li>Decide whether or not Courier-specific userid and groupid | |
447 | needs to be created, and, if so, make the necessary | |
448 | arrangements.</li> | |
449 | ||
450 | <li>Ensure that all prerequisite development libraries are | |
451 | available.</li> | |
452 | ||
453 | <li>Run the <code>configure</code> script, run | |
454 | <code>make</code>, then <code>make install</code> as | |
455 | usual.</li> | |
456 | ||
8d138742 CE |
457 | <li>Copy the "<code>sysconftool</code>" script somewhere into |
458 | the installation tree. A good place would be | |
dd184caf | 459 | <code>%libexecdir%/courier-authlib</code>. This is the |
8d138742 CE |
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 | |
dd184caf | 464 | installed <strong>OR UPGRADED</strong>.</li> |
465 | ||
466 | <li>The "<code>authdaemond</code>", | |
467 | "<code>authenumerate</code>", and "<code>authtest</code>" | |
468 | commands can be renamed, to avoid name clashes.</li> | |
469 | ||
470 | <li>Remove all static libraries from | |
471 | <code>%libdir%/courier-authlib</code>.</li> | |
472 | </ul> | |
473 | ||
474 | <p>Now, create the installable packages, as follows:</p> | |
475 | ||
476 | <ul> | |
477 | <li><code>%libdir%/courier-authlib/libauthldap*</code> goes | |
478 | into the LDAP subpackage.</li> | |
479 | ||
480 | <li><code>%libdir%/courier-authlib/libauthmysql*</code> goes | |
481 | into the MySQL subpackage.</li> | |
482 | ||
b0322a85 CE |
483 | <li><code>%libdir%/courier-authlib/libauthsqlite*</code> goes |
484 | into the SQLite subpackage.</li> | |
485 | ||
dd184caf | 486 | <li><code>%libdir%/courier-authlib/libauthpgsql*</code> goes |
487 | into the PostgreSQL subpackage.</li> | |
488 | ||
489 | <li><code>%libdir%/courier-authlib/libauthuserdb*</code> goes | |
490 | into the userdb subpackage.</li> | |
491 | ||
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> | |
496 | </ul> | |
d9898ee8 | 497 | </body> |
498 | </html> |