Ubuntu Manpage: imapd - The Courier IMAP server

Provided by: courier-imap_4.18.1+0.78.0-2ubuntu2_amd64

NAME

       imapd - The Courier IMAP server

SYNOPSIS

       /usr/lib/courier/couriertcpd {couriertcpd options} {/usr/sbin/imaplogin} [modules...] {/usr/bin/imapd}
                                    {./Maildir}

       /usr/bin/imapd {./Maildir}

DESCRIPTION

       imapd is the Courier IMAP server that provides IMAP access to Maildir mailboxes. Normally you don't have
       to worry about it, as imapd runs automatically after receiving a network connection, accompanied by the
       appropriate userid and password.

       couriertcpd opens network ports that receive incoming IMAP connections. After an incoming network
       connections is established, couriertcpd runs the command specified by its first argument, which is
       imaplogin passing the remaining arguments to imaplogin.  imaplogin reads the IMAP login userid and
       password, then runs the modules specified by its remaining options, which are Courier server
       authentication modules described in the authlib(7)[1] manual page.

       The last daisy-chained command is imapd, which is the actual IMAP server, which is started from the
       logged-in account's home directory. The sole argument to imapd is the pathname to the default IMAP
       mailbox, which is usually ./Maildir. Some authentication modules are capable of specifying a different
       filename, by setting the MAILDIR environment variable.

       imapd may also be invoked from the shell prompt, in which case it issues a PREAUTH response, then changes
       the current directory to either its argument, or the contents of the MAILDIR environment variable, then
       attempts to talk IMAP on standard input and output.

       imapd implements IMAP4REV1, as defined by RFC 2060[2].

FILES AND ENVIRONMENT VARIABLES

AUTH*
imapd examines several environment variables whose names start with AUTH - these environment
variables are set by imaplogin and the authentication modules. Their absence tells imapd that it's
running from the command line.

MAILDIR
MAILDIR - if defined, imapd changes its directory to the one specified by this environment variable.
Otherwise imapd changes its directory to the one specified on the command line.

`pwd`/.
The current directory is assumed to be the main INBOX Maildir.

`pwd`/.folder
Maildir folders, each one containing their own tmp, new, cur, etc...

Other environment variables are initialized from the /etc/courier/imapd and /etc/courier/imapd-ssl
configuration files. These files are loaded into the environment by the system startup script that runs
couriertcpd.

Realtime concurrent folder status updates
Setting the IMAP_ENHANCEDIDLE to 1 in /etc/courier/imapd enables realtime concurrent folder status
updates. When relatime folder status updates are enabled all IMAP mail clients that have the same folder
open will be immediately notified of any changes to the folder's contents.

The Courier IMAP server always allows more than one mail client to have the same folder opened. However,
when two or more clients have the same folder opened, the mail clients may not necessarily know when
another client added or removed messages from the folder. The base IMAP protocol specification requires
IMAP mail clients to explicitly check for any changes to the folder's contents. No provisions exists to
notify the mail client immediately when the folder's contents are modified by another mail client.

The IDLE extension to the base IMAP protocol provides a delivery mechanism for notifying mail clients of
changes to the mail folder's contents. Although at this time it's not known to which extent the IDLE
extension is supported by IMAP mail clients, the Courier IMAP server fully implements the IDLE extension
provided that the following requirements are met:

Gamin or FAM
Either Gamin[3] or FAM[4] must be properly installed and configured prior to installing the Courier
IMAP server.

Gamin/FAM is an application library that provides an interface to the operating system's kernel that
applications can use to be notified when specific files or directories are changed, and the Courier
IMAP server leverages this API to implement realtime concurrent folder status updates. According to
the most recently available documentation, Gamin is a Linux-specific library, and FAM builds and runs
on Linux and IRIX. FAM should also build on other platforms, but without a supported kernel monitor
FAM will fall back to a polling mode. At press time, FAM's web site reports that FAM succesfully
builds (in polling mode) on FreeBSD and Solaris.

FAM (but not Gamin) also works with NFS filesystems. On NFS clients fam transparently forwards file
monitoring requests to a peer fam process on the NFS server.

Installation and configuration of Gamin or FAM is beyond the scope of this document. This
documentation presumes that Gamin or FAM is succesfully installed. Use the resources and tools on
Gamin's or FAM's web site for assistance with setting them up. Systems that use GNOME or KDE desktops
already have FAM or Gamin installed, as FAM or Gamin is used by the current versions of both
desktops.

IDLE IMAP capability
IDLE must be listed in the IMAP_CAPABILITY setting in the /etc/courier/imapd configuration file.

IMAP_USELOCKS
This setting in /etc/courier/imapd must be enabled. This setting uses dot-lock files to synchronize
updates to folder indexes between multiple IMAP clients that have the same folder opened.

This setting is safe to use with NFS, as it does not use actual file locking calls, and does not
require the services of the problematic NFS lock daemon.

An IMAP mail client that fully supports the IDLE protocol extension.
Of course, an IMAP client that supports the IDLE protocol extension is required. At press time the
status and extent of IDLE support in most IMAP mail clients is not known.

IMAP_ENHANCEDIDLE
This setting in /etc/courier/imapd actually enables concurrent realtime folder status updates using
the IDLE extension. Note that it is possible to enable the IDLE extension even if FAM or Gamin is not
available, or without enabling either the IMAP_USELOCKS and/or IMAP_ENHANCEDIDLE settings. The
resulting consequences are described are as follows:

1. Without IMAP_USERLOCKS there exists a small possibility that multiple mail clients will receive a
slightly inconsistent folder index if both clients try to update the contents of the folder at
the same time. Usually, the worst case result is that some clients will eventually end up
downloading the same message twice from the server, and caching it incorrectly in the local cache
(if the IMAP client caches message contents). Clearing the local message cache will quickly
eliminate any residual confusion that results from this situation.

2. Without FAM or Gamin, and IMAP_ENHANCEDIDLE set, the Courier IMAP server will manually check for
changes to the folder's contents every 60 seconds, in IDLE mode (instead of in real time).

Verifying realtime concurrent folder status updates
Use the following procedure to verify that realtime concurrent folder status updates are properly
working. It is helpful to be familiar with the IMAP protocol. If that's not the case, just be extra
careful in entering the IMAP protocol commands. The following instructions describe the procedure for
connecting to the IMAP server, and manually issuing IMAP protocol commands, as if they originate from an
IMAP client. The following instructions use "C:" to indicate IMAP client commands that must be entered,
and "S:" to indicate the expected replies from the server.

Note
The actual replies from the server may differ slightly, due to the actual server configuration, and
other minor factors. The following examples have long lines wrapped for readability. Slight observed
differences from the expected replies are normal, but they should still be substantively the same.

1. Prepare a test account with a couple of messages. Open two or three terminal windows. In each window,
connect to the IMAP server, and enter IDLE mode:

S:* OK Courier-IMAP ready. Copyright 1998-2002 Double Precision, Inc.
See COPYING for distribution information.
C:a login userid password
S:a OK LOGIN Ok.
C:a SELECT INBOX
S:* FLAGS (\Draft \Answered \Flagged \Deleted \Seen \Recent)
* OK [PERMANENTFLAGS (\Draft \Answered \Flagged \Deleted \Seen)]
Limited
* 2 EXISTS
* 0 RECENT
* OK [UIDVALIDITY 939609418] Ok
a OK [READ-WRITE] Ok
C:a IDLE
S:+ entering ENHANCED idle mode

Note
The default Courier IMAP server configuration permits a maximum of four connections from the same
IP address. It may be necessary to adjust this setting in /etc/courier/imapd for the duration of
this test.

2. The last message from the server must be "entering ENHANCED idle mode". Otherwise, it means that some
of the necessary prerequisites have not been met. Verify that FAM or Gamin was set up prior to
installing The Courier IMAP server (use ldd(1) to verify that the imapd executable is linked with the
libfam library), and verify the settings in the /etc/courier/imapd.

3. Open another terminal window, connect to the server, and modify the flags of one of the messages:

4. The last command sets the \Deleted flag on the first message in the folder. Immediately after
entering the last command, "* 1 FETCH (FLAGS (\Deleted))" should also appear in all other terminal
windows. On systems where FAM uses the fall-back polling mode this response may appear after a brief
delay of a few seconds. The delay should never exceed 15-20 seconds.

5. Verify that all terminal windows reliably receive folder status updates in real time by alternatively
entering the commands "a STORE 1 -FLAGS (\Deleted)" and "a STORE 1 +FLAGS (\Deleted)", to toggle the
deleted flag on the first message. Observe that the message is received by all terminal windows
quickly, and reliably.

6. With the \Deleted flag set on the first message, enter the EXPUNGE command, which removes the deleted
message from the folder:

C:a EXPUNGE
S:* 1 EXPUNGE
* 2 EXISTS
* 0 RECENT
S:a OK EXPUNGE completed

The lines that begin with the "*" character should also appear in all other terminal windows
(depending on the initial folder state one of the terminal windows may have a different RECENT
message, which is fine).

7. Use a mail client to create and send a test message to the test account. As soon as the mail server
delivers the message, the following messages should appear in every terminal window:

* 3 EXISTS
* 0 RECENT
* 3 FETCH (FLAGS ())

The numbers in these messages may be different, depending upon the initial contents of the test mail
folder. One of the terminal windows should have a different RECENT count, and one of the terminal
windows should include a \Recent flag in the untagged FLAGS message. These difference are acceptable;
the important thing is to make sure that all terminal windows have the same EXISTS message.

AUTHOR

       Sam Varshavchik
           Author

NOTES