Table of Contents

   In this document (see INSTALL.html for the formatted version of this
   INSTALL file):

     • [1]Requirements
     • [2]Installation overview
     • [3]Dependencies
     • [4]What gets installed
     • [5]For more information
     • [6]Starting and stopping the authentication daemon
     • [7]Guidelines for using other package managers

Requirements

   See the README file for a general description of this library. The
   following software should be installed before building the Courier
   authentication library:

     • gcc that supports at least C++17 ([8]http://www.gnu.org/software/gcc/)
     • The GNU linker ([9]http://www.gnu.org/software/binutils/)
     • Libtool ([10]http://www.gnu.org/software/libtool/). Additionally,
       libtool's libltdl library, and its development files, must be
       installed. On some platforms this is a separate package. On Fedora,
       this is the libtool-ltdl-devel package, for example.
     • GNU make ([11]http://www.gnu.org/software/make/)
     • The "expect" command. expect is usually included with most systems.
       Expect can be downloaded from http://expect.nist.gov/ if it's not
       installed on your system. This utility is used to change system login
       passwords, by scripting the passwd command. If you do not have expect
       installed you will not be able to change system login passwords.
       However non-system authentication modules (LDAP, PostgreSQL, and
       others) will work.
     • Courier Unicode Library. Before installing this package, download and
       install [12]https://www.courier-mta.org/unicode/.

   Courier-authlib uses Libtool to build shared libraries. Libtool must be
   installed, together with its libltdl library and its header files.

   On non-Linux platforms the GNU linker is also required. Courier-authlib's
   build script uses some GNU linker-specific options. It's possible to
   manually specify the native linker's equivalent options manually, if they
   exist. If the native linker does not have the equivalent options, the GNU
   linker will have to be installed.

   On the other hand, GNU make will be required in almost every case.
   SYSV-derived make variants (probably) will not work.

   The same line of logic also applies to gcc. So, strictly speaking, only a
   basic C++ compiler, GNU make and libtool, are really needed to build
   courier-authlib. Still, try the following before giving up if problems
   occur when building this package:

    1. Install a recent version of the GNU linker
    2. Install the current version of Libtool
    3. Install the current version of gcc

Installation overview

  rpm and deb packages

   These are not the same packages as the ones from the distributions'
   repositories. These packages carry a higher internal revision level in
   order to prevent them from getting upgraded by the distributions'
   packages. This packaging exists in order to have a convenient way of
   updating after a release without waiting for the distributions' packages
   to get built.

   NOTE: If a distribution package is already installed it should be removed
   completely before switching to the upstream version (dnf remove or apt
   purge). Preserve any existing configuration files, beforehand, in order to
   restore it after switching packages. This applies to all Courier packages.
   A switch to this courier-authlib package requires switching to the
   courier-unicode package too.

   NOTE: These packages use their own, generic, installation layout that may
   deviate slightly from the package installation conventions preferred by
   the distributions.

  rpm

   Run dnf install rpm-build if it's not installed already, then:

 rpmbuild -ta courier-authlib-VERSION.tar.bz2

   If this fails due to any missing dependencies, install them. This builds:
   the main (runtime libraries); a subpackage for each authentication module
   (LDAP, MariaDB/MySQL, etc...); the development (link libraries, header
   files) package. All development libraries needed to build all
   authentication modules must be installed to build the rpms, but do not
   need to be installed at runtime unless the corresponding authentication
   module rpm is also installed.

   This creates rpms that can be installed with "rpm -U":

     • The "courier-authlib" package with the commands and standard
       authentication modules.
     • The "courier-authlib-devel" package with development libraries and
       header files.
     • The "courier-authlib-config-username-groupname package. This is a
       metapackage that captures the user/group used by the authentication
       library (daemon/daemon) by default. The dependencies on the
       metapackage are set up in a way to prevent unitended updates to an
       incompatible newer version that's configured with different user and
       group names.
     • Other "courier-authlib-name" authentication modules.

    Rocky/RHEL 8/9 notes

   Courier packages require C++17 support, but the default version of gcc
   does not fully support it, and a newer gcc is needed:

 dnf install --enablerepo=crb -y gcc-toolset-14
 scl enable gcc-toolset-14 "rpmbuild -ta courier-authlib-VERSION.tar.bz2"

    Using non-default courier username and groupname

   Pass --define "mailuser courier" and --define "mailgroup courier" options
   to rpmbuild to build the library with a non-default user and group name.

  deb

   Run "apt install devscripts debhelper", if they're not installed already.
   Create an empty directory and copy/move the tarball into it:

 $ mkdir tmp
 $ mv courier-authlib-VERSION.tar.bz2 tmp
 $ cd tmp

   Unpack the tarball and cd into the unpacked subdirectory:

 $ tar xvf courier-authlib-VERSION.tar.bz2
 $ cd courier-authlib-VERSION

   Run the courier-debuild script, which is a wrapper for debuild, and
   forwards its parameters to it:

 $ ./courier-debuild -us -uc

   NOTE: the above steps must be followed strictly. The courier-debuild
   script expects the distributed tarball in its parent directory.

   This eventually produces a deb subdirectory with .deb packages that can be
   installed with "dpkg -i":

     • The "libcourier-auth" package with the commands and standard
       authentication modules; and "libcourier-auth-<N>" with versioned
       client shared libraries.
     • The "libcourier-auth-dev" package with development libraries and
       header files.
     • Other "libcourier-auth-name" authentication modules.
     • The "libcourier-auth-config-mailuser-mailgroup" package. This package
       sets up the reserved user and group id the library and the rest of the
       Courier packages use. When the built .deb packages get manually
       installed directly with dpkg this "config" package must get installed
       first, by itself, followed by the rest of the packages. Higher level
       tools, like apt should figure this out by themselves.

   NOTE: if the courier-debuild script stops with an error complaining about
   missing dependencies, then use "apt install" to install them, then try
   again.

 $ DEBGCC=10 ./courier-debuild -us -uc

   Setting the DEBGCC environment variable selects a non-default gcc version.

   NOTE: All Courier packages should be built with the same version of gcc,
   which is selected by the DEBGCC environment variable before running
   courier-debuild. [13]See courier-unicode's INSTALL for more information.

    Using non-default courier username and groupname

 $ mailuser=courier mailgroup=courier ./courier-debuild -us -uc

   Setting the mailuser and mailgroup environment builds the library with a
   non-default user and group name.

    Ubuntu and Debian

   Courier packages require C++17 support, but the default version of gcc on
   Ubuntu 20 does not fully support it, and a newer gcc is needed:

 $ sudo apt install -y gcc-10 g++-10
 $ DEBGCC=10 ./courier-debuild -us -uc

   make check requires both the ISO-8859-1 based en_US locale in addition to
   the default en_US.UTF-8, on all versions of Ubuntu and Debian.

  Maintainer Mode (see README in the git repository to set up)

   make rpm or make deb, as appropriate, will:

    1. Increment an internal release number.

    2. Run make dist.

    3. Proceed and build a new release, creating the native packages in the
       rpm or deb subdirectory.

    4. Execute either $HOME/bin/rpmrepos.sh or $HOME/bin/debrepos.sh. This
       can be a script that does nothing, or it's intended to be the
       maintainer's script that pushes out the packages to a repository.

  Manual installation

   The following sequence of commands should be sufficient to install
   courier-authlib in most cases:

 ./configure [options] [variable=value]*...
 make
 make install
 make install-configure

   > NOTE: On the BSD family, GNU make is usually the 'gmake' command. Use
   > the 'gmake' command, instead of 'make'.

   The 'make install-configure' command is required; it installs and updates
   the configuration files; this command must be executed when installing
   courier-authlib for the first time, and when upgrading from an older
   version.

  Configuration options

   The configure script takes the usual autoconf options: --prefix, --bindir,
   and the rest of the usual toolchain options. The default installation
   directories should be sufficient, though.

   DO NOT USE the --disable-static, or --enable-static=no option. Both static
   and shared library options must be enabled for courier-authlib to build
   properly (but see "Post-installation cleanup" below).

    --without-stdheaderdir

   The default configuration installs development files in /usr/local/include
   (see "What gets installed", below). This directory is usually in the
   compiler's search path for header files. This option must be specified if
   the compiler does NOT search for header files in /usr/local/include by
   default.

   This option must also be specified if other configuration options (such as
   --prefix or --includedir) specify a different installation directory, and
   the new directory is also not searched by the compiler, by default

    --with-mailuser=userid, --with-mailgroup=groupid

   "userid" is a reserved system username, "groupid" is a reserved system
   groupname. These two options should be used before installing Courier for
   the first time. These options are not required before installing
   Courier-IMAP or SqWebMail.

   These options specify the user/group that will own the configuration
   files, and the socket that authentication daemon process listens on. This
   is a key part of Courier's security model.

   These options should not be necessary if upgrading from an earlier version
   of Courier and/or this authentication library. The default userid and
   groupid are computed as follows:

     • If an earlier version of the Courier authentication library is already
       installed in the same directory, the userid and the groupid is the
       same as the earlier version, otherwise:
     • The userid is the first userid from the following list which exists in
       the system: courier, daemon, adm, bin, root; and the groupid is the
       first groupid from the following list which exists in the system:
       courier, daemon, adm, sys, root.

   When installing Courier authentication library for the first time, it is
   highly recommended to create a "courier" userid and groupid, so that
   specifying these options will not be necessary.

    VARIABLE=value

   Environment variables may be set either before running the configure
   script, or by providing the environment variables as parameters to the
   configure script. Example:

   ./configure --with-mailuser=mail --with-mailgroup=mail \
        CC=gcc-10 CXX=g++-10 LDFLAGS=-L/opt/fsf/lib \
        MAKE=gmake

   The CC and CXX environment variables specify the C compiler that will be
   used to compile the authentication library. LDFLAGS specifies additiona
   linker flags, etc...

Dependencies

   On a minimum, bare-bones system, the Courier authentication library builds
   support for garden-variety authentication against system accounts (from
   the system's password file, /etc/passwd).

   If the configure script detects that certain optional software components
   are installed, additional authentication modules will be built and
   installed. This chapter describes what needs to be installed in order to
   build the optional authentication modules.

   > NOTE: In all cases, it is not sufficient to install the runtime support
   > libraries for the following components. In order to build the
   > authentication modules the DEVELOPMENT LIBRARIES for the following
   > software packages must be installed. The development libraries are
   > usually a separate package, that must be installed in addition to the
   > package that adds alleged support for the following software libraries.

     • GDBM or Berkeley DB library - The userdb authentication module will be
       built if either library is installed. The userdb authentication module
       includes Perl scripts that maintain a list of available accounts in
       plain text files. A Perl script then compiles the account list into a
       binary database, either GDBM or DB, which is then used to look up
       account information.
     • OpenLDAP - The LDAP authentication modules requires OpenLDAP client
       libraries to be installed. Sometimes there's some confusion when
       commercial LDAP servers are used, which come with their own
       development toolkits, which use a different API than OpenLDAP. Even if
       a commercial LDAP server is used to provide LDAP services, OpenLDAP is
       still required to enable LDAP services in Courier.
     • MariaDB/MySQL, PostgreSQL, and SQLite - The MariaDB, PostgreSQL, and
       SQLite authentication modules require, obviously,
       MariaDB/PostgreSQL/SQLite development libraries.

What gets installed

     • /usr/local/etc/authlib - the configuration files.
     • /usr/local/sbin - the authdaemond startup script; several utility
       programs (courierlogger, authconfig, authtest, authenumerate); and
       userdb scripts.
     • /usr/local/lib/courier-authlib - various authentication modules, as
       shared libraries.
     • /usr/local/libexec/courier-authlib - some miscellaneous stuff.
     • /usr/local/var/authdaemon - a subdirectory that contains the
       filesystem socket which authdaemond listens on.
     • /usr/local/include - a header file that Courier packages will use to
       build against courier-authlib.

   Toolchain options to the configure script may be used to select
   alternative installation directories for these components.

  Post-installation cleanup

   On most systems, after running make install-configure all static libraries
   can be removed from the /usr/local/lib/courier-authlib directory:

   rm -rf /usr/local/lib/courier-authlib/*.a

   The Courier authentication library uses only the shared libraries. The
   static versions of the shared libraries are not used. They are installed
   by default, via libtool, but are not really needed. On most platforms the
   libtool files, "*.la" can also be removed. Do not remove any soft links.

For more information

   Following "make install", see the [14]README_authlib.html file for details
   on setting up the authentication modules. The README_authlib.html file
   gets assembled as part of the build process.

   Before proceding to install any other packages, be sure to verify that the
   authentication library is working by running the authtest command, as
   documented in the README_authlib.html file.

Starting and stopping the authentication daemon

   Arrangements must be made to run the courier-authlib.sysvinit script with
   "start" and "stop" parameters at system startup and shutdown. make install
   does not install this script from the source directory, it needs to be
   installed manually.

Guidelines for using other package managers

   The recommended way to build packages can be inferred from the RPM build
   script. It is summarized here for convenience:

     • Decide whether or not Courier-specific userid and groupid needs to be
       created, and, if so, make the necessary arrangements.
     • Ensure that all prerequisite development libraries are available.
     • Run the configure script, run make, then make install as usual.
     • Copy the "sysconftool" script somewhere into the installation tree. A
       good place would be %libexecdir%/courier-authlib. This is the 'make
       install-upgrade' command. Don't run this at build time. Instead,
       arrange for the package installation script to run the "sysconftool
       %sysconfdir%/authlib/*.dist" after the package is installed OR
       UPGRADED.
     • The "authdaemond", "authenumerate", and "authtest" commands can be
       renamed, to avoid name clashes.
     • There are two types of libraries that get installed in %libdir%:
         1. Common libraries that application link with, libcourier*.
         2. Dynamically-loaded authentication modules: libauth*.

       Remove all static libraries from %libdir%/courier-authlib. Keep the
       *.la and *.so for libcourier*, and include them in a devel subpackage.
       Remove *.la and *.so for all libauth* libraries, they are not needed.

   Now, create the installable packages, as follows:

     • %libdir%/courier-authlib/libauthldap* goes into the LDAP subpackage.
     • %libdir%/courier-authlib/libauthmysql* goes into the MariaDB/MySQL
       subpackage.
     • %libdir%/courier-authlib/libauthsqlite* goes into the SQLite
       subpackage.
     • %libdir%/courier-authlib/libauthpgsql* goes into the PostgreSQL
       subpackage.
     • %libdir%/courier-authlib/libauthuserdb* goes into the userdb
       subpackage.
     • Everything else can go into the main package. Optionally, the
       courierauthconfig binary, stuff in %includedir%, and in %mandir%/man3,
       can go into a devel subpackage.