Courier-IMAP|Home|Features|Download|Documentation|Wiki|Links

Tutorial: troubleshooting IMAP server configuration

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.

Connecting to the Courier IMAP server server

The first step is to check if the Courier IMAP server is accepting connections. Open a terminal window and type:

telnet hostname 143

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.

Logging in

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.

Note

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.

Opening the incoming mail folder

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

Obtaining a list of all mail folders

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.

Conclusion

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.