Current File : //usr/local/share/courier-imap/man/man8/imapd.8
'\" t
.\"<!-- Copyright 1998 - 2007 Double Precision, Inc. See COPYING for -->
.\"<!-- distribution information. -->
.\" Title: imapd
.\" Author: Sam Varshavchik
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\" Date: 07/24/2017
.\" Manual: Double Precision, Inc.
.\" Source: Courier Mail Server
.\" Language: English
.\"
.TH "IMAPD" "8" "07/24/2017" "Courier Mail Server" "Double Precision, Inc."
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
imapd \- The Courier IMAP server
.SH "SYNOPSIS"
.HP \w'\fB/usr/local/libexec/courier-imap/couriertcpd\fR\ 'u
\fB/usr/local/libexec/courier-imap/couriertcpd\fR {couriertcpd\ options} {/usr/local/sbin/imaplogin} [\fImodules\fR...] {/usr/local/bin/imapd} {\&./Maildir}
.HP \w'\fB/usr/local/bin/imapd\fR\ 'u
\fB/usr/local/bin/imapd\fR {\&./Maildir}
.SH "DESCRIPTION"
.PP
\fBimapd\fR
is the
Courier
IMAP server that provides IMAP access to Maildir mailboxes\&. Normally you don\*(Aqt have to worry about it, as
\fBimapd\fR
runs automatically after receiving a network connection, accompanied by the appropriate userid and password\&.
.PP
\fBcouriertcpd\fR
opens network ports that receive incoming IMAP connections\&. After an incoming network connections is established,
\fBcouriertcpd\fR
runs the command specified by its first argument, which is
\fBimaplogin\fR
passing the remaining arguments to
\fBimaplogin\fR\&.
\fBimaplogin\fR
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
\m[blue]\fB\fBauthlib\fR(7)\fR\m[]\&\s-2\u[1]\d\s+2
manual page\&.
.PP
The last daisy\-chained command is
\fBimapd\fR, which is the actual IMAP server, which is started from the logged\-in account\*(Aqs home directory\&. The sole argument to
\fBimapd\fR
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
\fBMAILDIR\fR
environment variable\&.
.PP
\fBimapd\fR
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
\fBMAILDIR\fR
environment variable, then attempts to talk IMAP on standard input and output\&.
.PP
\fBimapd\fR
implements IMAP4REV1, as defined by
\m[blue]\fBRFC 2060\fR\m[]\&\s-2\u[2]\d\s+2\&.
.SH "FILES AND ENVIRONMENT VARIABLES"
.PP
\fBAUTH*\fR
.RS 4
\fBimapd\fR
examines several environment variables whose names start with AUTH \- these environment variables are set by
\fBimaplogin\fR
and the authentication modules\&. Their absence tells
\fBimapd\fR
that it\*(Aqs running from the command line\&.
.RE
.PP
\fBMAILDIR\fR
.RS 4
\fBMAILDIR\fR
\- if defined,
\fBimapd\fR
changes its directory to the one specified by this environment variable\&. Otherwise
\fBimapd\fR
changes its directory to the one specified on the command line\&.
.RE
.PP
`\fBpwd\fR`/\&.
.RS 4
The current directory is assumed to be the main INBOX Maildir\&.
.RE
.PP
`\fBpwd\fR`/\&.\fIfolder\fR
.RS 4
Maildir folders, each one containing their own tmp, new, cur, etc\&.\&.\&.
.RE
.PP
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
\fBcouriertcpd\fR\&.
.SS "Realtime concurrent folder status updates"
.PP
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\*(Aqs contents\&.
.PP
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\*(Aqs contents\&. No provisions exists to notify the mail client immediately when the folder\*(Aqs contents are modified by another mail client\&.
.PP
The
IDLE
extension to the base IMAP protocol provides a delivery mechanism for notifying mail clients of changes to the mail folder\*(Aqs contents\&. Although at this time it\*(Aqs 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:
.PP
Gamin or FAM
.RS 4
Either
\m[blue]\fBGamin\fR\m[]\&\s-2\u[3]\d\s+2
or
\m[blue]\fBFAM\fR\m[]\&\s-2\u[4]\d\s+2
must be properly installed and configured prior to installing the
Courier
IMAP server\&.
.sp
Gamin/FAM
is an application library that provides an interface to the operating system\*(Aqs 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\*(Aqs web site reports that
FAM
succesfully builds (in polling mode) on FreeBSD and Solaris\&.
.sp
FAM
(but not
Gamin) also works with NFS filesystems\&. On NFS clients
\fBfam\fR
transparently forwards file monitoring requests to a peer
\fBfam\fR
process on the NFS server\&.
.sp
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\*(Aqs or
FAM\*(Aqs 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\&.
.RE
.PP
IDLE IMAP capability
.RS 4
IDLE
must be listed in the
\fBIMAP_CAPABILITY\fR
setting in the
/usr/local/etc/courier-imap/imapd
configuration file\&.
.RE
.PP
\fBIMAP_USELOCKS\fR
.RS 4
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\&.
.sp
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\&.
.RE
.PP
An IMAP mail client that fully supports the IDLE protocol extension\&.
.RS 4
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\&.
.RE
.PP
\fBIMAP_ENHANCEDIDLE\fR
.RS 4
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
extension even if
FAM
or
Gamin
is not available, or without enabling either the
\fBIMAP_USELOCKS\fR
and/or
\fBIMAP_ENHANCEDIDLE\fR
settings\&. The resulting consequences are described are as follows:
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
Without
\fBIMAP_USERLOCKS\fR
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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.2
.\}
Without
FAM
or
Gamin, and
\fBIMAP_ENHANCEDIDLE\fR
set, the
Courier
IMAP server will manually check for changes to the folder\*(Aqs contents every 60 seconds, in IDLE mode (instead of in real time)\&.
.RE
.RE
.SS "Verifying realtime concurrent folder status updates"
.PP
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\*(Aqs 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\&.
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
.PP
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\&.
.sp .5v
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 1.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 1." 4.2
.\}
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:
.sp
.if n \{\
.RS 4
.\}
.nf
S:* OK Courier\-IMAP ready\&. Copyright 1998\-2002 Double Precision, Inc\&.
See COPYING for distribution information\&.
C:a login \fIuserid\fR \fIpassword\fR
S:a OK LOGIN Ok\&.
C:a SELECT INBOX
S:* FLAGS (\eDraft \eAnswered \eFlagged \eDeleted \eSeen \eRecent)
* OK [PERMANENTFLAGS (\eDraft \eAnswered \eFlagged \eDeleted \eSeen)]
Limited
* 2 EXISTS
* 0 RECENT
* OK [UIDVALIDITY 939609418] Ok
a OK [READ\-WRITE] Ok
C:a IDLE
S:+ entering ENHANCED idle mode
.fi
.if n \{\
.RE
.\}
.if n \{\
.sp
.\}
.RS 4
.it 1 an-trap
.nr an-no-space-flag 1
.nr an-break-flag 1
.br
.ps +1
\fBNote\fR
.ps -1
.br
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
/usr/local/etc/courier-imap/imapd
for the duration of this test\&.
.sp .5v
.RE
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 2.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 2." 4.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
\fBldd\fR(1)
to verify that the
\fBimapd\fR
executable is linked with the
libfam
library), and verify the settings in the
/usr/local/etc/courier-imap/imapd\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 3.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 3." 4.2
.\}
Open another terminal window, connect to the server, and modify the flags of one of the messages:
.sp
.if n \{\
.RS 4
.\}
.nf
S:* OK Courier\-IMAP ready\&. Copyright 1998\-2002 Double Precision, Inc\&.
See COPYING for distribution information\&.
C:a login \fIuserid\fR \fIpassword\fR
S:a OK LOGIN Ok\&.
C:a SELECT INBOX
S:* FLAGS (\eDraft \eAnswered \eFlagged \eDeleted \eSeen \eRecent)
* OK [PERMANENTFLAGS (\eDraft \eAnswered \eFlagged \eDeleted \eSeen)]
Limited
* 2 EXISTS
* 0 RECENT
* OK [UIDVALIDITY 939609418] Ok
a OK [READ\-WRITE] Ok
C:STORE 1 +FLAGS (\eDeleted)
* 1 FETCH (FLAGS (\eDeleted))
a OK STORE completed\&.
.fi
.if n \{\
.RE
.\}
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 4.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 4." 4.2
.\}
The last command sets the
\eDeleted
flag on the first message in the folder\&. Immediately after entering the last command, "* 1 FETCH (FLAGS (\eDeleted))" 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\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 5.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 5." 4.2
.\}
Verify that all terminal windows reliably receive folder status updates in real time by alternatively entering the commands "a STORE 1 \-FLAGS (\eDeleted)" and "a STORE 1 +FLAGS (\eDeleted)", to toggle the deleted flag on the first message\&. Observe that the message is received by all terminal windows quickly, and reliably\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 6.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 6." 4.2
.\}
With the
\eDeleted
flag set on the first message, enter the
\fBEXPUNGE\fR
command, which removes the deleted message from the folder:
.sp
.if n \{\
.RS 4
.\}
.nf
C:a EXPUNGE
S:* 1 EXPUNGE
* 2 EXISTS
* 0 RECENT
S:a OK EXPUNGE completed
.fi
.if n \{\
.RE
.\}
.sp
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)\&.
.RE
.sp
.RS 4
.ie n \{\
\h'-04' 7.\h'+01'\c
.\}
.el \{\
.sp -1
.IP " 7." 4.2
.\}
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:
.sp
.if n \{\
.RS 4
.\}
.nf
* 3 EXISTS
* 0 RECENT
* 3 FETCH (FLAGS ())
.fi
.if n \{\
.RE
.\}
.sp
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
\eRecent
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\&.
.RE
.SH "SEE ALSO"
.PP
\m[blue]\fB\fBauthlib\fR(7)\fR\m[]\&\s-2\u[1]\d\s+2,
\m[blue]\fB\fBuserdb\fR(8)\fR\m[]\&\s-2\u[5]\d\s+2
.SH "AUTHOR"
.PP
\fBSam Varshavchik\fR
.RS 4
Author
.RE
.SH "NOTES"
.IP " 1." 4
\fBauthlib\fR(7)
.RS 4
\%http://www.courier-mta.org/authlib.html
.RE
.IP " 2." 4
RFC 2060
.RS 4
\%http://www.rfc-editor.org/rfc/rfc2060.txt
.RE
.IP " 3." 4
Gamin
.RS 4
\%http://www.gnome.org/~veillard/gamin/
.RE
.IP " 4." 4
FAM
.RS 4
\%http://oss.sgi.com/projects/fam/
.RE
.IP " 5." 4
\fBuserdb\fR(8)
.RS 4
\%http://www.courier-mta.org/userdb.html
.RE
Mini Shell