INSTALL.html

   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>