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

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:

               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:STORE 1 +FLAGS (\Deleted)
               * 1 FETCH (FLAGS (\Deleted))
               a OK STORE completed.

        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.

SEE ALSO

       authlib(7)[1], userdb(8)[5]

AUTHOR

       Sam Varshavchik
           Author

NOTES

        1. authlib(7)
           http://www.courier-mta.org/authlib.html

        2. RFC 2060
           http://www.rfc-editor.org/rfc/rfc2060.txt

        3. Gamin
           http://www.gnome.org/~veillard/gamin/

        4. FAM
           http://oss.sgi.com/projects/fam/

        5. userdb(8)
           http://www.courier-mta.org/userdb.html