NEWS

   1                          Courier Authentication Library
   2
   3    The Courier Authentication Library is a required component that must be
   4    set up before installing other Courier packages: the Courier Mail Server
   5    or its components (Courier-IMAP, SqWebMail, or maildrop).
   6
   7    The authentication library used to be included as a part of these
   8    packages, it is now a standalone library.
   9
  10    Upgrading from older versions of Courier packages that used to include
  11    this authentication library internally should be as simple as:
  12
  13  ./configure
  14  make
  15  make install
  16  make install-migrate
  17  make install-configure
  18
  19 Requirements
  20
  21    The Courier authentication library should not have any more requirements
  22    than the older Courier packages it used to be a part of. There may be an
  23    exception on some less-common platforms. They may require some additional
  24    stuff to be loaded before courier-authlib can be installed. This is
  25    because courier-authlib now uses libtool, which is a new requirement.
  26    Courier-authlib now uses shared libraries in the place of separate
  27    authdaemond binaries in the previous versions. Some less-common platforms
  28    may require additional software to be installed because of that, see
  29    INSTALL for more information.
  30
  31 The pluses
  32
  33    This new, self-sustaining Courier authentication library offers the
  34    following benefits:
  35
  36      * Upgrading from Courier-IMAP or SqWebMail to the full Courier package
  37        does not require authentication re-configuration.
  38      * Consolidated documentation. Instructions for setting up MySQL,
  39        PostgreSQL, and the rest, are currently duplicated twice, making it a
  40        maintenance pain. Now, the documentation will be in one place, and can
  41        be easily improved, and overhauled. There will be an initial hump to
  42        ride over, to reconcile the minor differences in the authentication
  43        documentation in Courier, Courier-IMAP, and SqWebMail. Going forward,
  44        though, everything will be in one place.
  45      * The authentication API appears to be fairly stable and robust. It will
  46        not be necessary to update the courier-authlib package with every
  47        upgrade. Updates to courier-authlib are expected to be very
  48        infrequent.
  49      * There is a small minority of established systems that use the
  50        standalone SqWebMail and Courier-IMAP packages. The consolidated
  51        courier-authlib library will, as a bonus, provide an official way to
  52        use only one set of config files, in this configuration.
  53
  54 The minuses
  55
  56    I can only see one possible drawback. Only the daemonized configuration
  57    will now be possible. This new version of the Courier authentication
  58    library is, for all intents and purposes, the daemonized configuration of
  59    the previous authentication library. The non-daemonized version of the
  60    authentication library is no longer implemented. That code has been
  61    removed for the simple reason that it can no longer be implemented, as a
  62    standalone library. It's been clearly shown that the daemonized
  63    configuration is the more flexible configuration, and is the only way to
  64    go. The daemonized configuration was the default configuration for several
  65    years.
  66
  67    I can only see the following minuses from losing the non-daemonized
  68    configuration. I believe the minuses are greatly outranked by the pluses.
  69
  70      * There are some third party configuration libraries that only work in a
  71        non-daemonized configuration. I'm aware of one such library, vmailmgr.
  72        Unless it's been updated to work in daemonized mode, it will no longer
  73        work.
  74      * There are also some other third-party hacks that also only work in a
  75        non-daemonized configuration. There's at least one relay-after-imap or
  76        relay-after-pop hack for qmail, that only works in a daemonized
  77        configuration. I believe that relay-after-X hacks have been obsolete
  78        for several years now. Every mail client worth mentioning these days
  79        implemented authenticated SMTP, and the relay-after-X hacks need to
  80        go.
  81
  82    Currently, there are also some borderline configurations possible in a
  83    non-daemonized configuration, such as using different authentication
  84    modules completely for imap and pop3, or different authentication modules
  85    for non-encrypted and encrypted connections. This will no longer be
  86    possible, but I doubt that there's any valid reason to use such an unusual
  87    setup.
  88
  89 Testing
  90
  91    The 'make install-migrate' command tries to import the authentication
  92    configuration from any existing installed Courier package. The
  93    configuration files for courier-authlib will end up in
  94    /usr/local/lib/courier-authlib/etc/authlib. The existing Courier packages
  95    don't really know how to use courier-authlib just yet. This will be the
  96    next step.
  97
  98    However, after installing courier-authlib you should be able to do some
  99    rudimentary testing by running 'authdaemond start' (where authdaemond is
 100    what's in the /usr/local/lib/courier-authlib/sbin directory). The
 101    following commands should now work (make sure the authdaemond and authtest
 102    programs are the ones from /usr/local/lib/courier-authlib/sbin directory,
 103    and not any existing Courier directory):
 104
 105  authtest userid
 106  authtest userid password
 107  authtest userid password newpassword
 108  authenumerate
 109
 110    The first command displays the account's home directory, userid, groupid,
 111    and other related data. The second command verifies whether the password
 112    is valid, or not. The third command changes the password on the account
 113    (be careful with that).
 114
 115    The goal is that everything should work automatically. In some cases, it
 116    might be necessary to modify the new authdaemonrc configuration file
 117    (unlike all othe configuration files, the install-migrate script won't
 118    copy the existing authdaemonrc, a new one will be installed). Manually
 119    edit it, and remove all authentication modules that are not needed,
 120    leaving only the actual ones that are used.
 121
 122 Debugging
 123
 124    To generate additional debugging messages, edit the authdaemond startup
 125    script (installed in /usr/local/bin by default), and add the following to
 126    the script:
 127
 128  DEBUG_LOGIN=2
 129  export DEBUG_LOGIN
 130
 131    Debugging messages from the authentication daemon processes will be sent
 132    to the syslog facility, and recorded in whatever log file syslog is
 133    configured to use (usually /var/log/messages or /var/log/maillog).