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