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