d9898ee8 |
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). |