| |
IMAPD(8) IMAPD(8)
NAME
imapd - Courier-IMAP server
SYNOPSIS
/usr/local/libexec/courier-imap/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 authentication modules described in the
authlib(7) 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.
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
/usr/local/etc/courier-imap/imapd and /usr/local/etc/courier-
imap/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 /usr/local/etc/courier-imap/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 mecha-
nism for notifying mail clients of changes to the mail folder's con-
tents. 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:
FAM The File Alteration Monitor package, FAM, must be properly
installed and configured prior to installing Courier-IMAP.
FAM is an application library that provides an interface to the
operating system's kernel that applications can use to be noti-
fied when specific files or directories are changed, and
Courier-IMAP leverages this API to implement realtime concurrent
folder status updates. According to the most recently available
documentation, FAM builds and runs on Linux and IRIX. FAM
should also build on other platform, 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 also works with NFS filesystems. On NFS clients fam trans-
parently forwards file monitoring requests to a peer fam process
on the NFS server.
Installation and configuration of FAM is beyond the scope of
this document. This documentation presumes that FAM is succes-
fully installed. Use the resources and tools on FAM's web site
for assistance with setting up FAM. Systems that use GNOME or
KDE desktops already have FAM installed, as FAM is used by the
current versions of both desktops.
IDLE IMAP capability
IDLE must be listed in the IMAP_CAPABILITY setting in the
/usr/local/etc/courier-imap/imapd configuration file. This is
the default setting in new Courier-IMAP 1.6.0/Courier 0.40
installs. The default setting in previous versions of the
server does not include the IDLE capability. When upgrading
from the previous version the IDLE capability must be manually
added.
IMAP_USELOCKS
This setting in /usr/local/etc/courier-imap/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 exten-
sion 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 /usr/local/etc/courier-imap/imapd actually
enables concurrent realtime folder status updates using the IDLE
extension. Note that it is possible to enable the IDLE exten-
sion even if FAM 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 incor-
rectly 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 situ-
ation.
2. Without FAM, and IMAP_ENHANCEDIDLE set, the Courier-IMAP
server will manually check for changes to the folder's con-
tents 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 nor-
mal, 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 maxi-
mum of four connections from the same IP address. It may be neces-
sary to adjust this setting in /usr/local/etc/courier-imap/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 was set up prior to installing
Courier-IMAP (use ldd(1) to verify that the imapd executable is
linked with the libfam library), and verify the settings in the
/usr/local/etc/courier-imap/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 win-
dows. 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 fol-
lowing 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 win-
dows 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), userdb(8)
Double Precision, Inc. 19 February 2004 IMAPD(8)
|