INSTALL

# 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
- Building RPMs
- 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:

- A modern 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/)
- 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-authlib uses Libtool to build shared libraries. Libtool is not strictly required, but Libtool should be installed unless a good -- a very-very good -- reason exists not to. If Libtool is not installed, a copy of Libtool in courier-authlib's source will be used. However, this may cause problems later down the road, if either another Libtool-using package is installed later, or if Libtool itself is installed. Bottom line: install Libtool.

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

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

    ./configure [options] [variable=value]*...
    make
    make install
    make install-migrate      # Only if upgrading from pre-authlib Courier packages
    make install-configure

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

> NOTE: It might appear that the `configure` script is stuck in an infinite loop. This is only an optical illusion. The `configure` script takes several minutes to complete. The Courier authentication library consists of many small modules, each with its own configuration script; and all configuration scripts are built from the same template. When they are invoked, one at a time, an illusion of an infinite loop appears.

Courier-authlib is a requirement starting with the following Courier package versions: Courier 0.48, Courier-IMAP 4.0, SqWebMail 5.0. When upgrading from earlier versions of these packages, install the Courier-authlib package first, then upgrade the existing package.

The '`make install-migrate`' command imports the authentication configuration from earlier versions of these packages. '`make install-migrate`' is not needed otherwise.

The '`make install-migrate`' command searches all the known default installation directories for Courier, Courier-IMAP, and SqWebMail, and imports the older configuration files. If the older versions of these packages are installed in some unusual, non-standard, directories, the `make install-migrate` command won't find them. Instead, copy those configuration files (`authdaemonrc`, `authldaprc`, `authmysqlprc`, `authpgsqlprc`, and `userdb`) by hand. DO NOT COPY `authdaemonrc.dist`, `authldaprc.dist`, `authmysqlprc.dist`, and `authpgsqlprc.dist`.

After finishing '`make install-migrate`', the rest of the installation steps, and after upgrading Courier, Courier-IMAP, or SqWebMail to the new versions, to avoid future confusion the old copies of these configuration files (including the `.dist` files), should be removed from Courier/Courier-IMAP/SqWebMail's configuration directory. They now live in Courier-authlib's configuration directory (`/usr/local/etc/authlib`, or whatever was specified to the `configure` script).

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:
- If an earlier version of the Courier package is installed (only the Courier package, the Courier-IMAP and SqWebMail packages do not carry this information), the userid and the groupid is the same as the ones used to configure Courier, 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.

This configure script descends from the old authentication library that was included in the older Courier, Courier-IMAP, and SqWebMail packages. As such, it also has many other undocumented options that manually disable specific authentication modules.

These options are no longer officially documented. Individual modules can be disabled after installation, by editing the `authdaemonrc` configuration file.

#### `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=/opt/fsf/bin/gcc LDFLAGS=-L/opt/fsf/lib \
>          MAKE=gmake

The `CC` environment variable specifies the name of the C compiler that will be used to compile the authentication library. For some reason, on this oddball system some system libraries are installed in `/opt/fsf/lib`, and the compiler doesn't search this directory by default. Therefore, the compiler needs the "`-L/opt/fsf/lib`" to properly link all programs, and this option is specified in the `LDFLAGS` environment variable.

Another possibility is to add the `/opt/fsf/bin` directory to the `PATH` environment variable, prior to running the `configure` script. The `configure` script searches for all needed software in the current `PATH`. Explicitly pointing configure to something, like `CC`, is only needed if the program is not already in the default PATH.

Finally, Courier authentication library must be built with GNU make. On this example system the `make` command is the old SysV-derived make, which will not work. GNU make is installed here as the "`gmake`" command. The `configure` script will ordinarily find the `make` command and be happy with it, by mistake. Explicitly setting `MAKE` to `gmake` fixes that (and the human operator also needs to invoke the `gmake` command also).

## 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.
- MySQL/PostgreSQL - The MySQL and PostgreSQL authentication modules require, obviously, MySQL/PostgreSQL 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

The following command must be added to your system startup script, in order to initialize the authentication library when booting:

    /usr/local/sbin/authdaemond start

Similarly, the authentication library can be stopped by the "`authdaemond stop`" command. After editing the `authdaemonrc` configuration file use "`authdaemond restart`" command to reconfigure the daemon process. Systems that use SYSV-derived initscripts can use the "`courier-authlib.sysvinit`" script, which gets built in the source directory, to start and stop `authdaemond` when the system boots or halts.

## Building RPMs

See `http://www.courier-mta.org/FAQ.html#rpm` for instructions on building binary RPMs from the source tarball. Those instructions will work for this package.

> NOTE:

> RPM will refuse to build the Courier authentication library unless all prerequisite development libraries for LDAP, MySQL, and PostgreSQL are installed. Do not try to hack the RPM build script to ignore these dependencies! For simplicity's and maintainability sake the RPM build script creates all available authentication modules. All extra authentication modules will be built as optional subpackages. They do not have to be installed at runtime. Install the LDAP, MySQL, and PostgreSQL development libraries only for the duration of building binary RPMs. They can be uninstalled afterwards.

## 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.
- Remove all static libraries from `%libdir%/courier-authlib`.

Now, create the installable packages, as follows:

- `%libdir%/courier-authlib/libauthldap*` goes into the LDAP subpackage.
- `%libdir%/courier-authlib/libauthmysql*` goes into the MySQL 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.