IMAPD(8)                    Double Precision, Inc.                    IMAPD(8)



NAME
       imapd - The Courier IMAP server

SYNOPSIS
       /usr/local/libexec/couriertcpd {couriertcpd options}
                                      {/usr/local/sbin/imaplogin} [modules...]
                                      {/usr/local/bin/imapd} {./Maildir}

       /usr/local/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)
           [set $man.base.url.for.relative.links]/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)
           [set $man.base.url.for.relative.links]/userdb.html



Courier Mail Server               04/04/2011                          IMAPD(8)
