INSTALL

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