/usr/share/doc/courier-authlib/README.authdebug.html is in courier-authlib 0.66.1-1+b1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 | <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content="" />
<title>Debugging authentication problems</title>
</head>
<body bgcolor="#FFFFFF">
<h1 align="center">Debugging authentication problems</h1>
<p>A common problem after installing the Courier authentication
library is that authentication, using authtest, doesn't work.
This document shows how to use courier's debugging features to
pinpoint the problem.</p>
<h2>1. Turn on debugging</h2>
<p>For courier-imap, you need to set one of the following values
in /etc/courier/authdaemonrc:</p>
<pre>
DEBUG_LOGIN=1 # turn on authentication debugging
DEBUG_LOGIN=2 # turn on authentication debugging AND show passwords
</pre>
<p>This setting is located at the very end of the configuration
file.</p>
<p>After changing this setting, restart the authentication daemon
by running the "authdaemond stop" and "authdaemond start"
commands.</p>
<p>At this point, all debugging output goes to syslog at level
'debug', which is normally not shown. You will probably need to
change your <code>/etc/syslog.conf</code> file to be able to see
these messages. If you have an existing entry which says
"mail.info" (which means facility 'mail', level 'info' or higher)
then you can just change this to "mail.debug". Alternatively you
can add a new entry like this:</p>
<pre>
*.debug /var/log/debug
</pre>
<p>Don't forget to create this file, and to send a HUP signal to
syslogd to make it re-read its configuration:</p>
<pre>
# touch /var/log/debug
# killall -1 syslogd
</pre>
<p>If you don't want to mess around with your syslog
configuration, you can also start <code>authdaemond</code>
manually, and log its output to a file:</p>
<p><code>/usr/lib/courier/courier-authlib/authdaemond >filename
2>&1</code></p>
<h2>2. Issue a manual login</h2>
<p>You can use the authtest command to verify authentication, or
go ahead and install Courier-IMAP.</p>
<p>For courier-imap, you will get much better information by not
using a mail client and manually logging in using 'telnet'. The
transcript of this telnet session may give useful information as
to what is going on. If you are going to report a problem to the
mailing list, you should certainly include this transcript as
well as the corresponding debugging output.</p>
<pre>
-- to debug POP3 --
# telnet x.x.x.x 110
user USERNAME
pass PASSWORD
stat
quit
-- to debug IMAP --
# telnet x.x.x.x 143
a login USERNAME PASSWORD
a examine inbox
a logout
-- to debug POP3 over SSL --
# openssl s_client -connect x.x.x.x:995
(then use same commands as POP3 example)
-- to debug IMAP over SSL --
# openssl s_client -connect x.x.x.x:993
(then use same commands as IMAP example)
</pre>
<p>This isn't an option for sqwebmail of course - just login
through the web interface and check the authentication debug log
which is generated.</p>
<h2>3. Interpret the debug output</h2>
<p>First, a brief explanation of courier's authentication system.
There are a number of standalone <b>authentication modules</b>.
An authentication module exists for every authentication method.
Each authentication module is installed as a shared library. When
<strong>authdaemond</strong> starts, it attempts to load and
initialize the authentication modules, logging the following
messages to syslog:</p>
<pre>
Oct 17 11:25:37 commodore authdaemond: modules="authuserdb authpam authpgsql authldap authmysql authcustom", daemons=5
Oct 17 11:25:37 commodore authdaemond: Installing libauthuserdb
Oct 17 11:25:37 commodore authdaemond: Installation complete: authuserdb
Oct 17 11:25:37 commodore authdaemond: Installing libauthpam
Oct 17 11:25:37 commodore authdaemond: Installation complete: authpam
Oct 17 11:25:37 commodore authdaemond: Installing libauthpgsql
Oct 17 11:25:37 commodore authdaemond: libauthpgsql.so: cannot open shared object file: No such file or directory
Oct 17 11:25:37 commodore authdaemond: Installing libauthldap
Oct 17 11:25:37 commodore authdaemond: libauthldap.so: cannot open shared object file: No such file or directory
Oct 17 11:25:37 commodore authdaemond: Installing libauthmysql
Oct 17 11:25:37 commodore authdaemond: libauthmysql.so: cannot open shared object file: No such file or directory
Oct 17 11:25:37 commodore authdaemond: Installing libauthcustom
Oct 17 11:25:37 commodore authdaemond: Installation complete: authcustom
</pre>
<p>The first message lists all authentication modules that were
compiled, and indicates that <strong>authdaemond</strong> will
spawn five processes to handle all authentication requests. This
is followed by messages indicating that indicate which
authentication modules were installed.</p>
<p>In this example, authdaemond did not load the authpgsql,
authldap, and authmysql modules. That's because in this case the
Courier authentication library is installed by the system's
package manager. The LDAP, MySQL, and PostgreSQL support was
placed into optional sub-packages which are not installed. Even
though all of these modules were initially compiled, the optional
authentication modules were not installed.</p>
<p>This is normal. authdaemond will simply ignore any
authentication module it cannot find, and will activate only
those modules that are available. When an authentication request
comes in, all of the modules will be executed, one after the
other, resulting in one of three conditions:</p>
<dl>
<dt>ACCEPT</dt>
<dd>The user was authenticated successfully</dd>
<dt>REJECT</dt>
<dd>The module did not know this username, or the user gave
invalid credentials. The request is passed to the next
module.</dd>
<dt>TEMPFAIL</dt>
<dd>The module suffered an internal failure, such as inability
to contact an external database. The login is rejected, and no
further modules are tried.</dd>
</dl>
<p>In a typical Courier installation the authentication request
is sent, via a filesystem socket, to a pool of <b>authdaemond</b>
processes (note the extra "d" on the end) which perform the
actual work. authdaemond, in turn, contains other authentication
modules such as authpam, authmysql, and so on.</p>
<p>If <code>authdaemond</code> is running successfully, then it
will in turn run each of the modules it is linked against. If any
one returns REJECT then the next is tried; if any returns
TEMPFAIL or ACCEPT then no further modules are tried.</p>
<p>So a typical example might look like this:</p>
<pre>
Apr 14 14:07:15 billdog authdaemond: received auth request, service=pop3, authtype=login
Apr 14 14:07:15 billdog authdaemond: authcustom: trying this module
Apr 14 14:07:15 billdog authdaemond: authcustom: nothing implemented in do_auth_custom()
Apr 14 14:07:15 billdog authdaemond: authcustom: REJECT - try next module
Apr 14 14:07:15 billdog authdaemond: authcram: trying this module
Apr 14 14:07:15 billdog authdaemond: cram: only supports authtype=cram-*
Apr 14 14:07:15 billdog authdaemond: authcram: REJECT - try next module
Apr 14 14:07:15 billdog authdaemond: authuserdb: trying this module
Apr 14 14:07:15 billdog authdaemond: userdb: opened /etc/userdb.dat
Apr 14 14:07:15 billdog authdaemond: userdb: looking up 'brian'
Apr 14 14:07:15 billdog authdaemond: userdb: entry not found
Apr 14 14:07:15 billdog authdaemond: authuserdb: REJECT - try next module
Apr 14 14:07:15 billdog authdaemond: authpam: trying this module
Apr 14 14:07:15 billdog authdaemond: authpam: sysusername=brian, sysuserid=<null>, sysgroupid=1001, homedir=/home/brian, address=brian, fullname=Brian Candler, maildir=<null>, quota=<null>, options=<null>
Apr 14 14:07:15 billdog authdaemond: pam_service=pop3, pam_username=brian
Apr 14 14:07:15 billdog authdaemond: dopam successful
Apr 14 14:07:15 billdog authdaemond: authpam: ACCEPT, username brian
</pre>
<p>What's happening here?</p>
<ul>
<li>The request was received by 'authdaemond'</li>
<li>It tries 'authcustom' - this module does nothing unless you
have customised it yourself, so it REJECTs the request</li>
<li>It tried 'authcram', but since this was a request with
authtype=login (rather than authtype=cram-md5, say), this
module cannot handle it so it REJECTs</li>
<li>'authuserdb' has a go. In this case there is an
/etc/userdb.dat file for it to look in, but the requested
username 'brian' does not exist in there, so it REJECTs</li>
<li>'authpam' has a go. It finds the username and home
directory in /etc/passwd, and then calls the PAM subsystem to
authenticate. The authentication is successful.</li>
</ul>
<p>So, in principle, debugging is straightforward. Watch the
modules operate, search for the one which you <i>think</i> should
be authenticating the user, and if it is not, check for REJECT
(user not known or password mismatch) or TEMPFAIL (internal
error) status. Additional messages should indicate why this
status was returned.</p>
<h2>4. Read the documentation</h2>
<p>Most of the configuration files like authldaprc, authmysql are
well documented with comments.</p>
<p>For the nitty-gritty details of authentication modules, see
<a href="http://www.courier-mta.org/authlib.html">man
authlib</a>. There is probably a copy of this manpage installed
on your system; if that command doesn't work, try one of
these:</p>
<pre>
# man -M /usr/man authlib
or
# cd /path/to/sources
# cd authlib
# nroff -mandoc authlib.7.in | less
</pre>
<p>If you are using userdb authentication, you definitely need to
read <a href="makeuserdb.html">man makeuserdb</a>, <a href=
"userdb.html">man userdb</a>, and <a href="userdbpw.html">man
userdbpw</a>.</p>
<h2>5. Use the mailing list</h2>
<p>Please read through the common problems and solutions at the
bottom of this document. The next thing to do, of course, is
search the web to see if your particular problem has been seen
before and solved. <a href="http://www.google.com">Google</a> is
very good for this.</p>
<p>If you still cannot work out what the problem is, then you can
ask on the appropriate <a href=
"http://www.courier-mta.org/links.html">mailing list</a>. But
before you post, please gather together all the following
information:</p>
<ul>
<li>The operating system and version you are running</li>
<li>The versions of packages you have installed</li>
<li>The <code>./configure</code> command line you gave to build
it</li>
<li>If you didn't build it yourself, where you got the package
from (and if possible, find out from the packager what options
they used to build it)</li>
<li>The versions of any other relevant software which you are
linking against, e.g. openldap, mysql, pgsql</li>
<li>The transcript of the 'telnet' session you used to manually
test server connections</li>
<li>The corresponding debug output which was generated for that
session</li>
<li>The contents of relevant configuration files, e.g.
authldaprc, authmysqlrc, imapd, pop3d</li>
<li>A copy of the database entry you are trying to authenticate
against: e.g. the line from your userdb file, an LDAP entry, a
row from your mysql table, the line in /etc/password, etc.</li>
</ul>
<p>If you include all this, you are <i>much</i> more likely to
get a helpful response.</p>
<hr />
<h2>Frequently seen authentication problems and solutions</h2>
<p>See also the <a href=
"http://www.courier-mta.org/FAQ.html">Courier MTA FAQ</a></p>
<h3>When I try to login with POP3 using telnet, the server
disconnects immediately after the "PASS" command, without giving
a -ERR response</h3>
<p>The reason for this error will probably be found in your mail
logs. Usually it indicates either that the home directory does
not exist (chdir failed), or the Maildir has not been created.
See 'man maildirmake'.</p>
<h3>PAM authentication says "pam_start failed, result 4 [Hint:
bad PAM configuration?]"</h3>
<p>Probably your PAM configuration is bad. If you have
/etc/pam.d/other, then try simply removing /etc/pam.d/pop3 and
/etc/pam.d/imap and see if it works (this is sufficient for
FreeBSD). Otherwise, try copying one of your existing
/etc/pam.d/xxx files to /etc/pam.d/pop3, imap or webmail
respectively.<br />
The result value is a PAM_XXXX constant from
<code>/usr/include/security/pam_constants.h</code> (this file may
be in a different location on your system). Under FreeBSD, 4 is
PAM_SYSTEM_ERR.</p>
<h3>When I connect on the SSL ports (995 or 993), the server
accepts the connection but then immediately disconnects</h3>
<p>You probably didn't install any SSL certificates. Courier-imap
comes with scripts you can run to do this for you:</p>
<pre>
# /usr/sbin/mkimapdcert
# /usr/sbin/mkpop3dcert
</pre>
<h3>I expected the authentication library to compile authmysql
(or some other module), but it's not there</h3>
<p>If the mysql authentication module did not compile, then
perhaps ./configure was unable to find your mysql libraries (you
can read through the file 'config.log' in the source directory to
see what it found). You may need to force it to look in the right
place, as follows:</p>
<pre>
# ./configure --with-authmsql --with-mysql-libs=/usr/local/mysql/lib \
--with-mysql-includes=/usr/local/mysql/include
</pre>
<p>On some systems (e.g. FreeBSD), the mysqlclient library
depends on the math and compression libraries. For these systems,
try:</p>
<pre>
# LDFLAGS="-lm -lz" ./configure --with-authmysql ... same as before
</pre>
<h3>The POP3/IMAP server says "Temporary problem, please try
again later" when a bad password is entered</h3>
<p><code>authdaemond</code> tries each of the configured
authentication modules in turn, until either one accepts the
login, or they have all rejected it (in which case the usual
"Login failed" error is returned, and the user can try
again).</p>
<p>However, if one of these modules is unable to run because some
resource is not available, then it gives a "temporary failure"
response and no further modules are tried. You should find the
exact cause in your mail logs, but typically it means that you
have a module like 'authmysql' in your module list, but the mysql
database is not running.</p>
<p>So unless you actually do have account data in mysql (in which
case you need to fix your mysql setup), you should remove
'authmysql' and any other modules you do not use from
<code>authmodulelist</code> in <code>authdaemonrc</code>.</p>
</body>
</html>
|