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