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 |
15 | INSTALL 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 |
32 | following software should be installed before building the Courier |
33 | authentication 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 |
54 | strict required, but Libtool should be installed unless a good -- a very-very |
55 | good -- reason exists not to. If Libtool is not installed, a copy of Libtool |
56 | in courier-authlib's source will be used. However, this may cause problems |
57 | later down the road, if either another Libtool-using package is installed |
58 | later, 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 |
61 | build script uses some GNU linker-specific options. It's possible to manually |
62 | specify the native linker's equivalent options manually, if they exist. If |
63 | the native linker does not have the equivalent options, the GNU linker will |
64 | have to be installed.</p> |
65 | |
66 | <p>On the other hand, GNU make will be required in almost every case. |
67 | SYSV-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 |
70 | basic C compiler, GNU make and libtool, are really needed to build |
71 | courier-authlib. Still, try the following before giving up if problems occur |
72 | when 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 |
82 | courier-authlib in most cases:</p> |
83 | <pre>./configure [options] [variable=value]*... |
84 | make |
85 | make install |
86 | make install-migrate |
87 | make 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 |
105 | package versions: Courier 0.48, Courier-IMAP 4.0, SqWebMail 5.0. When |
106 | upgrading from earlier versions of these packages, install the |
107 | Courier-authlib package first, then upgrade the existing package.</p> |
108 | |
109 | <p>The '<code>make install-migrate</code>' command imports the authentication |
110 | configuration from earlier versions of these packages. '<code>make |
111 | install-migrate</code>' is not needed otherwise.</p> |
112 | |
113 | <p>The '<code>make install-migrate</code>' command searches all the known |
114 | default installation directories for Courier, Courier-IMAP, and SqWebMail, |
115 | and imports the older configuration files. If the older versions of these |
116 | packages are installed in some unusual, non-standard, directories, the |
117 | <code>make install-migrate</code> command won't find them. Instead, copy |
118 | those 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 |
121 | COPY</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 |
125 | installation steps, and after upgrading Courier, Courier-IMAP, or SqWebMail |
126 | to the new versions, to avoid future confusion the old copies of these |
127 | configuration files (including the <code>.dist</code> files), should be |
128 | removed from Courier/Courier-IMAP/SqWebMail's configuration directory. They |
129 | now 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 |
134 | and updates the configuration files; this command must be executed when |
135 | installing Courier-authlib for the first time, and when upgrading from an |
136 | older 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 |
142 | toolchain options. The default installation directories should be sufficient, |
143 | though.</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 |
147 | options 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 |
154 | directory is usually in the compiler's search path for header files. This |
155 | option 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 |
160 | installation directory, and the new directory is also not searched by the |
161 | compiler, 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 |
167 | groupname. These two options should be used before installing Courier for the |
168 | first time. These options are not required before installing Courier-IMAP or |
169 | SqWebMail.</p> |
170 | |
171 | <p>These options specify the user/group that will own the configuration |
172 | files, and the socket that authentication daemon process listens on. This is |
173 | a key part of Courier's security model.</p> |
174 | |
175 | <p>These options should not be necessary if upgrading from an earlier version |
176 | of Courier and/or this authentication library. The default userid and groupid |
177 | are 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 |
193 | highly recommended to create a "courier" userid and groupid, so that |
194 | specifying these options will not be necessary.</p> |
195 | |
196 | <p>This configure script descends from the old authentication library that |
197 | was included in the older Courier, Courier-IMAP, and SqWebMail packages. As |
198 | such, it also has many other undocumented options that manually disable |
199 | specific authentication modules.</p> |
200 | |
201 | <p><strong>These options are no longer officially documented.</strong> |
202 | Individual 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 |
208 | script, or by providing the environment variables as parameters to the |
209 | configure 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 |
218 | compiler that will be used to compile the authentication library. For some |
219 | reason, 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 |
221 | default. Therefore, the compiler needs the "<code>-L/opt/fsf/lib</code>" to |
222 | properly 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 |
226 | the <code>PATH</code> environment variable, prior to running the |
227 | <code>configure</code> script. The <code>configure</code> script searches for |
228 | all needed software in the current <code>PATH</code>. Explicitly pointing |
229 | configure to something, like <code>CC</code>, is only needed if the program |
230 | is not already in the default PATH.</p> |
231 | |
232 | <p>Finally, Courier authentication library must be built with GNU make. On |
233 | this example system the <code>make</code> command is the old SysV-derived |
234 | make, which will not work. GNU make is installed here as the |
235 | "<code>gmake</code>" command. The <code>configure</code> script will |
236 | ordinarily find the <code>make</code> command and be happy with it, by |
237 | mistake. Explicitly setting <code>MAKE</code> to <code>gmake</code> fixes |
238 | that (and the human operator also needs to invoke the <code>gmake</code> |
239 | command 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 |
244 | support for garden-variety authentication against system accounts (from the |
245 | system's password file, <code>/etc/passwd</code>).</p> |
246 | |
247 | <p>If the <code>configure</code> script detects that certain optional |
248 | software components are installed, additional authentication modules will be |
249 | built and installed. This chapter describes what needs to be installed in |
250 | order 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 |
297 | select 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 |
302 | static 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 |
308 | static versions of the shared libraries are not used. They are installed by |
309 | default, via libtool, but are not really needed. On most platforms the |
310 | libtool 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 |
315 | href="README_authlib.html"><code>README_authlib.html</code></a> file for |
316 | details on setting up the authentication modules. The |
317 | <code>README_authlib.html</code> file gets assembled as part of the build |
318 | process.</p> |
319 | |
320 | <p>Before proceding to install any other packages, be sure to verify that the |
321 | authentication library is working by running the <code>authtest</code> |
322 | command, as documented in the <code>README_authlib.html</code> file.</p> |
323 | |
324 | <h2><a name="Starting" id="Starting">Starting and stopping the authentication |
325 | daemon</a></h2> |
326 | |
327 | <p>The following command must be added to your system startup script, in |
328 | order 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 |
334 | restart</code>" command to reconfigure the daemon process. Systems that use |
335 | SYSV-derived initscripts can use the "<code>courier-authlib.sysvinit</code>" |
336 | script, 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> |
342 | for instructions on building binary RPMs from the source tarball. Those |
343 | instructions 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 |
360 | managers</a></h2> |
361 | |
362 | <p>The recommended way to build packages can be inferred from the RPM build |
363 | script. 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> |