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