d9898ee8 |
1 | Courier Authentication Library |
2 | |
64ff59ba |
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. |
d9898ee8 |
9 | |
10 | Upgrading from older versions of Courier packages that used to include |
64ff59ba |
11 | this authentication library internally should be as simple as: |
d9898ee8 |
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 |
64ff59ba |
86 | possible, but I doubt that there's any valid reason to use such an unusual |
d9898ee8 |
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). |