This tutorial provides basic directions for troubleshooting the Courier IMAP server configuration. This information should also work with other IMAP servers, but the examples reflect output from the Courier IMAP server.
The starting point: the Courier IMAP server has just been installed, you start your favorite IMAP mail reader, enter what you think is the correct server configuration, and it does not work. Either your mail software hangs, shows nothing at all, or complains with an error message.
There can be many possible reasons, but all of them can be reduced into two categories: a problem with the IMAP server's configuration, or a problem with the mail software's configuration. It may very well be that the server is running properly, however the IMAP configuration in many mail readers often has confusing configuration options, and the correct settings may not be obvious.
This tutorial provides step-by-step directions for verifying the Courier IMAP server's basic operation. The following directions should establish whether the server is running correctly, and if not, what the problem might be.
The first step is to check if the Courier IMAP server is accepting connections. Open a terminal window and type:
telnethostname143
Replace hostname
with the IMAP server's
DNS name. This expected
results would look like this:
$ telnet imap.example.com 143 Trying 10.0.0.12... Connected to imap.example.com. Escape character is '^]'. * OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THRE AD=REFERENCES SORT QUOTA IDLE AUTH=CRAM-MD5 SMAP1 KEYWORDS ACL ACL2=UNION STARTT LS XMAGICTRASH] Courier-IMAP ready. Copyright 1998-2008 Double Precision, Inc. See COPYING for distribution information.
This shows that the IMAP server is running and accepting connections. Your IMAP server may give a slightly difference response. If, on the other hand, the connection fails:
$ telnet imap.example.com 143 Trying 10.0.0.12... telnet: connect to address 10.0.0.12: Connection refused
There are many reasons for a failed connection, but the two most common are:
The IMAP server is not running. Log on to the server and check if the process is running:
# ps -ef | grep imap root 30440 30439 0 Jul16 ? 00:00:00 /usr/lib/courier-imap/libexec/co uriertcpd -address=0 -maxprocs=40 -maxperip=10 -nodnslookup -noidentlookup 143 / usr/lib/courier-imap/sbin/imaplogin /usr/lib/courier-imap/bin/imapd Maildir
Note that without active IMAP connections only the “couriertcpd” process is running. Different IMAP servers will use different process names. Another (and even better) way is to check if anything is listening on port 143:
# /sbin/fuser -n tcp 143 143/tcp: 30440
This indicates that process 30440 has port 143 open. This is a fairly good indication that the IMAP server is running.
If the telnet connection fails, but the IMAP server seems to be running, this is usually because of a firewall getting in the way. Investigate any firewall settings on the IMAP server's host, and any intervening network devices, and make any necessary adjustments to open up port 143.
Establishing a successful connection to the IMAP server does not eliminate all potential sources of configuration errors. The next step is to proceed and attempt to log in:
$ telnet imap.example.com 143 Trying 10.0.0.12... Connected to imap.example.com. Escape character is '^]'. * OK [CAPABILITY IMAP4rev1 UIDPLUS CHILDREN NAMESPACE THREAD=ORDEREDSUBJECT THRE AD=REFERENCES SORT QUOTA IDLE AUTH=CRAM-MD5 SMAP1 KEYWORDS ACL ACL2=UNION STARTT LS XMAGICTRASH] Courier-IMAP ready. Copyright 1998-2008 Double Precision, Inc. See COPYING for distribution information. 0 login testuser testpass
IMAP commands begin
with an arbitrary label. This example uses the label
“0”. Use the command “0 login username password”
to check if the IMAP
server can process a login request and open the mailbox. A
succesful login looks like this:
... 0 login testuser testpass 0 OK LOGIN Ok.
Other IMAP servers may
respond with a slightly different message after the
“OK”. An error message
should be self-evident:
... 0 login testuser testpass 0 NO Login failed.
There are many reasons for a login failure message from the Courier IMAP server. The most common reasons are:
courier-authlib
isn't running. Check that its processes are running.
The installation instructions for courier-authlib contain directions
for checking that it's properly configured. See
courier-authlib's
INSTALL file for more
information.
The password is wrong, or the login ID does not exist.
The login account's entry specifies the login ID's
home directory, and the login ID's numeric system
uid and
gid, but that
information is incorrect or doesn't match the login
ID's actual home directory or uid/gid. It may not exist
at all.
The actual error message should provide some indication as to what the problem is. Also, look in syslog for any additional diagnostic information. After making the necessary corrections, repeat the manual login process and check that the login command succeeds.
Some IMAP servers may be configured to accept encrypted connections only, and all login commands will fail, unless they are encrypted. If this is the case, no further progress can be made in troubleshooting IMAP login problems, unless the IMAP server is temporarily reconfigured to allow unencrypted logins.
Other configuration problems may still exist even if the login command succeeds. The next step is to try to open the incoming mail folder:
... 0 login testuser testpass 0 OK LOGIN Ok. 0 select inbox * FLAGS (\Draft \Answered \Flagged \Deleted \Seen \Recent) * OK [PERMANENTFLAGS (\* \Draft \Answered \Flagged \Deleted \Seen)] Limited * 0 EXISTS * 0 RECENT * OK [UIDVALIDITY 1129891669] Ok * OK [MYRIGHTS "acdilrsw"] ACL 0 OK [READ-WRITE] Ok
The command “0 select inbox” opens the
incoming mail folder. The above example shows a typical
successful response from the Courier IMAP server. The actual
responses from different IMAP servers vary slight, the above is a
general example. An obvious error message from the
Courier IMAP server in
response to this command indicates a corrupt mailbox. The
most common reason is that the mailbox's system uid and gid is wrong and does not
match the login ID's record in courier-authlib
One last thing to check is to retrieve the list of existing IMAP folders:
... 0 LIST "" "*" * LIST (\Unmarked \HasChildren) "." "INBOX" * LIST (\HasChildren) "." "INBOX.Sent" * LIST (\HasNoChildren) "." "INBOX.Drafts" ... 0 OK LIST completed
The command “0 LIST "" "*"” retrieves the list of all folder names. The actual response to the command, of course, varies with different servers.
The Courier IMAP server places virtual shared folders in a separate namespace. This LIST command will not show virtual shared folders. A slightly different command is required:
... 0 LIST "" "#shared.*" * LIST (\HasNoChildren) "." "#shared.postmaster.Calendar" * LIST (\Noselect \HasChildren) "." "#shared.postmaster" 0 OK LIST completed
The command “0 LIST ""
"#shared.*"” retrieves
the names of folders in the “#shared” namespace. Use
this command to check if virtual shared folders are properly
set up and which ones are visible to the login ID. Setting up
the Courier IMAP server
virtual shared folders is a somewhat complicated process.
Running this command shows which virtual shared folders are
accessible. If no actual “#shared” folders appear
in response to this command, it means that no virtual shared
folders are accessible by this login ID.
If the above commands produce the expected responses from the IMAP server, that indicates that the IMAP server's major functions are properly working. Any problems with IMAP mail reader is probably due to a configuration issue with the mail reader, and the IMAP mail reader's forums or newsgroups will probably be the best place to ask for assistance with properly configuring the software.