Table of Contents

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

• Requirements
• Installation overview
• Dependencies
• What gets installed
• For more information
• Starting and stopping the authentication daemon
• 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:

• The current version of gcc (http://www.gnu.org/software/gcc/)
• The GNU linker (http://www.gnu.org/software/binutils/)
• Libtool (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 (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 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.

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:

  
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.
  
  
  
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. See
  courier-unicode's INSTALL for more
  information.
  
Using non-default courier username and groupname
  
  
Setting the mailuser and mailgroup environment builds the library with a
  non-default user and group name.
  
Maintainer Mode (see README in the git repository to set
  up)
  
make rpm or make
  deb, as appropriate, will:
  

    

      
Increment an internal release number.
    
    

      
Run make dist.
    
    

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

      
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
  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%:
      

        
Common libraries that application link with,
        libcourier*.
        
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.