Courier Authentication Library

   The Courier Authentication Library is a required component that must be
   set up before installing other Courier packages: the Courier Mail Server
   or its components (Courier-IMAP, SqWebMail, or maildrop).

   The authentication library used to be included as a part of these
   packages, it is now a standalone library.

   Upgrading from older versions of Courier packages that used to include
   this authentication library internally should be as simple as:

 ./configure
 make
 make install
 make install-migrate
 make install-configure

Requirements

   The Courier authentication library should not have any more requirements
   than the older Courier packages it used to be a part of. There may be an
   exception on some less-common platforms. They may require some additional
   stuff to be loaded before courier-authlib can be installed. This is
   because courier-authlib now uses libtool, which is a new requirement.
   Courier-authlib now uses shared libraries in the place of separate
   authdaemond binaries in the previous versions. Some less-common platforms
   may require additional software to be installed because of that, see
   INSTALL for more information.

The pluses

   This new, self-sustaining Courier authentication library offers the
   following benefits:

     * Upgrading from Courier-IMAP or SqWebMail to the full Courier package
       does not require authentication re-configuration.
     * Consolidated documentation. Instructions for setting up MySQL,
       PostgreSQL, and the rest, are currently duplicated twice, making it a
       maintenance pain. Now, the documentation will be in one place, and can
       be easily improved, and overhauled. There will be an initial hump to
       ride over, to reconcile the minor differences in the authentication
       documentation in Courier, Courier-IMAP, and SqWebMail. Going forward,
       though, everything will be in one place.
     * The authentication API appears to be fairly stable and robust. It will
       not be necessary to update the courier-authlib package with every
       upgrade. Updates to courier-authlib are expected to be very
       infrequent.
     * There is a small minority of established systems that use the
       standalone SqWebMail and Courier-IMAP packages. The consolidated
       courier-authlib library will, as a bonus, provide an official way to
       use only one set of config files, in this configuration.

The minuses

   I can only see one possible drawback. Only the daemonized configuration
   will now be possible. This new version of the Courier authentication
   library is, for all intents and purposes, the daemonized configuration of
   the previous authentication library. The non-daemonized version of the
   authentication library is no longer implemented. That code has been
   removed for the simple reason that it can no longer be implemented, as a
   standalone library. It's been clearly shown that the daemonized
   configuration is the more flexible configuration, and is the only way to
   go. The daemonized configuration was the default configuration for several
   years.

   I can only see the following minuses from losing the non-daemonized
   configuration. I believe the minuses are greatly outranked by the pluses.

     * There are some third party configuration libraries that only work in a
       non-daemonized configuration. I'm aware of one such library, vmailmgr.
       Unless it's been updated to work in daemonized mode, it will no longer
       work.
     * There are also some other third-party hacks that also only work in a
       non-daemonized configuration. There's at least one relay-after-imap or
       relay-after-pop hack for qmail, that only works in a daemonized
       configuration. I believe that relay-after-X hacks have been obsolete
       for several years now. Every mail client worth mentioning these days
       implemented authenticated SMTP, and the relay-after-X hacks need to
       go.

   Currently, there are also some borderline configurations possible in a
   non-daemonized configuration, such as using different authentication
   modules completely for imap and pop3, or different authentication modules
   for non-encrypted and encrypted connections. This will no longer be
   possible, but I doubt that there's any valid reason to use such an unusual
   setup.

Testing

   The 'make install-migrate' command tries to import the authentication
   configuration from any existing installed Courier package. The
   configuration files for courier-authlib will end up in
   /usr/local/lib/courier-authlib/etc/authlib. The existing Courier packages
   don't really know how to use courier-authlib just yet. This will be the
   next step.

   However, after installing courier-authlib you should be able to do some
   rudimentary testing by running 'authdaemond start' (where authdaemond is
   what's in the /usr/local/lib/courier-authlib/sbin directory). The
   following commands should now work (make sure the authdaemond and authtest
   programs are the ones from /usr/local/lib/courier-authlib/sbin directory,
   and not any existing Courier directory):

 authtest userid
 authtest userid password
 authtest userid password newpassword
 authenumerate

   The first command displays the account's home directory, userid, groupid,
   and other related data. The second command verifies whether the password
   is valid, or not. The third command changes the password on the account
   (be careful with that).

   The goal is that everything should work automatically. In some cases, it
   might be necessary to modify the new authdaemonrc configuration file
   (unlike all othe configuration files, the install-migrate script won't
   copy the existing authdaemonrc, a new one will be installed). Manually
   edit it, and remove all authentication modules that are not needed,
   leaving only the actual ones that are used.

Debugging

   To generate additional debugging messages, edit the authdaemond startup
   script (installed in /usr/local/bin by default), and add the following to
   the script:

 DEBUG_LOGIN=2
 export DEBUG_LOGIN

   Debugging messages from the authentication daemon processes will be sent
   to the syslog facility, and recorded in whatever log file syslog is
   configured to use (usually /var/log/messages or /var/log/maillog).