-<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
-@sysconfdir@/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>@libexecdir@/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 @prefix@/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># @prefix@/sbin/mkimapdcert
-# @prefix@/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>
+<!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 @sysconfdir@/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>@libexecdir@/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 @prefix@/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>
+# @prefix@/sbin/mkimapdcert
+# @prefix@/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>
HCoop / hcoop / debian / courier-authlib.git / blobdiff