<html>
<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/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-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="http://www.courier-mta.org/makeuserdb.html">man makeuserdb</a>, <a
href="http://www.courier-mta.org/userdb.html">man userdb</a>, and <a
href="http://www.courier-mta.org/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
<a
href="http://lists.sourceforge.net/mailman/listinfo/courier-imap">courier-imap</a>
or <a href="mailto:sqwebmail-subscribe@inter7.com">sqwebmail</a> mailing
lists. 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 version of courier-imap/sqwebmail 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. vpopmail, openldap, mysql, pgsql</li>
<li>The transcript of the 'telnet' session you used to test
[courier-imap]</li>
<li>The corresponding debug output which was generated for that session</li>
<li>The contents of the 'pop3d' and 'imapd' configuration files
[courier-imap]</li>
<li>The contents of the any other relevant configuration files, e.g.
authldaprc, authmysqlrc</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>I get intermittent authentication problems with vpopmail</h3>
<p>This is a known problem with vpopmail 5.2.1 and earlier. You need to
upgrade to 5.2.2 or later, and then recompile courier-authlib.</p>
<h3>Compiling fails with "cannot find -lvpopmail"</h3>
<p>This is usually a permissions problem on the vpopmail library. Try:</p>
<pre># chmod +rx /home/vpopmail /home/vpopmail/lib</pre>
Alternatively, it might be a problem finding the vpopmail headers or library,
in which case try:
<pre># CPPFLAGS="-I/home/vpopmail/include"; export CPPFLAGS
# LDFLAGS="-L/home/vpopmail/lib"; export LDFLAGS
# ./configure ...</pre>
<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>
