<?xml version="1.0"?>
<html xmlns="http://www.w3.org/1999/xhtml"><head><meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/><title>imapd</title><link rel="stylesheet" type="text/css" href="style.css"/><meta name="generator" content="DocBook XSL Stylesheets Vsnapshot"/><link rel="home" href="#imapd" title="imapd"/><link xmlns="" rel="stylesheet" type="text/css" href="manpage.css"/><meta xmlns="" name="MSSmartTagsPreventParsing" content="TRUE"/><link xmlns="" rel="icon" href="icon.gif" type="image/gif"/><!--

Copyright 1998 - 2009 S. Varshavchik.  See COPYING for distribution
information.

--></head><body><div class="refentry"><a id="imapd" shape="rect"> </a><div class="titlepage"/><div class="refnamediv"><h2>Name</h2><p>imapd — The <span class="application">Courier</span> IMAP server</p></div><div class="refsynopsisdiv"><h2>Synopsis</h2><div class="cmdsynopsis"><p><code class="command">@libexecdir@/couriertcpd</code>  {couriertcpd options} {@prefix@/sbin/imaplogin} [<em class="replaceable"><code>modules</code></em>...] {@prefix@/bin/imapd} {./Maildir}</p></div><div class="cmdsynopsis"><p><code class="command">@prefix@/bin/imapd</code>  {./Maildir}</p></div></div><div class="refsect1"><a id="imapd_description" shape="rect"> </a><h2>DESCRIPTION</h2><p>
<span class="command"><strong>imapd</strong></span> is the <span class="application">Courier</span>
IMAP server that provides IMAP access to
Maildir mailboxes.
Normally you don't have to worry about it, as <span class="command"><strong>imapd</strong></span>
runs automatically after receiving a network connection, accompanied by
the appropriate userid and password.</p><p>
<span class="command"><strong>couriertcpd</strong></span> opens network ports that receive incoming
IMAP connections.
After an incoming network connections is established,
<span class="command"><strong>couriertcpd</strong></span>
runs the command specified by its first argument, which is
<span class="command"><strong>imaplogin</strong></span> passing the remaining arguments to
<span class="command"><strong>imaplogin</strong></span>.
<span class="command"><strong>imaplogin</strong></span> reads the IMAP login userid and password,
then runs the modules specified by its remaining options, which
are <span class="application">Courier</span>
server authentication modules described in the
<a class="ulink" href="authlib.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">authlib</span>(3)</span></a>
manual page.</p><p>
The last daisy-chained command is
<span class="command"><strong>imapd</strong></span>, which is the actual IMAP server,
which is started from the logged-in account's home directory.
The sole argument to <span class="command"><strong>imapd</strong></span> is the pathname
to the default IMAP mailbox, which is usually
<code class="filename">./Maildir</code>.
Some authentication modules are capable of specifying a different
filename, by setting the <code class="envar">MAILDIR</code> environment variable.
</p><p>
<span class="command"><strong>imapd</strong></span> may also be invoked from the shell prompt, in which
case it issues a <code class="literal">PREAUTH</code> response, then changes the
current directory to either its
argument, or the contents of the <code class="envar">MAILDIR</code> environment
variable, then attempts to talk IMAP on standard input and output.</p><p>
<span class="command"><strong>imapd</strong></span> implements IMAP4REV1, as defined by
<a class="ulink" href="http://www.rfc-editor.org/rfc/rfc2060.txt" target="_top" shape="rect">RFC 2060</a>.</p></div><div class="refsect1"><a id="imapd_files_and_environment_variables" shape="rect"> </a><h2>FILES AND ENVIRONMENT VARIABLES</h2><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="envar">AUTH*</code></span></dt><dd>
<span class="command"><strong>imapd</strong></span> examines several environment variables whose
names start with AUTH - these environment variables are set by
<span class="command"><strong>imaplogin</strong></span> and the authentication modules.
Their absence tells
<span class="command"><strong>imapd</strong></span> that it's running from the command line.
</dd><dt><span class="term"><code class="envar">MAILDIR</code></span></dt><dd>
<code class="envar">MAILDIR</code> - if defined,
<span class="command"><strong>imapd</strong></span> changes its directory to the
one specified by this environment variable.
Otherwise <span class="command"><strong>imapd</strong></span> changes
its directory to the one specified on the command line.</dd><dt><span class="term"><code class="filename">`<span class="command"><strong>pwd</strong></span>`/.</code></span></dt><dd>
The current directory is assumed to be the main INBOX
Maildir.</dd><dt><span class="term"><code class="filename">`<span class="command"><strong>pwd</strong></span>`/.<em class="replaceable"><code>folder</code></em></code></span></dt><dd>
Maildir folders, each one containing their own
tmp, new, cur, etc...</dd></dl></div><p>
Other environment variables are initialized from the
<code class="filename">@sysconfdir@/imapd</code> and
<code class="filename">@sysconfdir@/imapd-ssl</code> configuration files.
These files are loaded into the environment by the system startup script
that runs <span class="command"><strong>couriertcpd</strong></span>.</p><div class="refsect2"><a id="imapd_realtime_concurrent_folder_status_updates" shape="rect"> </a><h3>Realtime concurrent folder status updates</h3><p>
The <span class="application">Courier</span> 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.</p><p>
The <code class="literal">IDLE</code> extension to the base IMAP protocol provides
a delivery mechanism for notifying mail clients of changes to the mail
folder's contents.</p><div class="variablelist"><dl class="variablelist"><dt><span class="term"><code class="literal">IDLE</code> IMAP capability</span></dt><dd><p>
<code class="literal">IDLE</code>
must be listed in the
<code class="envar">IMAP_CAPABILITY</code>
setting in the <code class="filename">@sysconfdir@/imapd</code>
configuration file.</p></dd><dt><span class="term"><code class="envar">IMAP_USELOCKS</code></span></dt><dd><p>
This setting in <code class="filename">@sysconfdir@/imapd</code>
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.</p><p>
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.</p></dd><dt><span class="term">An IMAP mail client that fully supports the
<code class="literal">IDLE</code>
protocol extension.</span></dt><dd><p>
Of course, an IMAP client that supports the <code class="literal">IDLE</code>
protocol extension is required.</p></dd><dt/><dd><p>
Without <code class="envar">IMAP_USERLOCKS</code> 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.</p><p>
Without inotify kernel interface, the
<span class="application">Courier</span> IMAP server will
manually check for changes to the folder's contents every 60 seconds,
in IDLE mode (instead of in real time).
</p></dd></dl></div></div><div class="refsect2"><a id="imapd_verifying_realtime_concurrent_folder_status_updates" shape="rect"> </a><h3>Verifying realtime concurrent folder status updates</h3><p>
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 "<code class="literal">C:</code>" to indicate IMAP
client commands that must be entered, and "<code class="literal">S:</code>" to
indicate the expected replies from the server.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
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.</p></div><div class="orderedlist"><ol class="orderedlist" type="1"><li class="listitem"><p>
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:
</p><pre class="programlisting" xml:space="preserve">
S:* OK Courier-IMAP ready. Copyright 1998-2021 S. Varshavchik.
  See COPYING for distribution information.
C:a login <em class="replaceable"><code>userid</code></em> <em class="replaceable"><code>password</code></em>
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 idle mode
</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>
The default <span class="application">Courier</span> IMAP server
configuration permits a maximum of four
connections from the same IP address.
It may be necessary to adjust this setting in
<code class="filename">@sysconfdir@/imapd</code>
for the duration of this test.</p></div></li><li class="listitem"><p>
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.</p></li><li class="listitem"><p>
Open another terminal window, connect to the server, and modify the flags
of one of the messages:</p><pre class="programlisting" xml:space="preserve">
S:* OK Courier-IMAP ready. Copyright 1998-2021 S. Varshavchik.
  See COPYING for distribution information.
C:a login <em class="replaceable"><code>userid</code></em> <em class="replaceable"><code>password</code></em>
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.
</pre></li><li class="listitem"><p>
The last command sets the <code class="literal">\Deleted</code> flag on the first
message in the folder.
Immediately after entering the last command,
"<code class="literal">* 1 FETCH (FLAGS (\Deleted))</code>" should also appear
in all other terminal windows.
</p></li><li class="listitem"><p>
Verify that all terminal windows reliably receive folder status updates in
real time by alternatively entering the commands
"<code class="literal">a STORE 1 -FLAGS (\Deleted)</code>"
and
"<code class="literal">a STORE 1 +FLAGS (\Deleted)</code>",
to toggle the deleted flag on the first message.
Observe that the message is received by all terminal windows quickly,
and reliably.</p></li><li class="listitem"><p>
With the <code class="literal">\Deleted</code> flag set on the first message,
enter the <span class="command"><strong>EXPUNGE</strong></span> command, which removes the deleted
message from the folder:</p><pre class="programlisting" xml:space="preserve">
C:a EXPUNGE
S:* 1 EXPUNGE
  * 2 EXISTS
  * 0 RECENT
S:a OK EXPUNGE completed
</pre><p>
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 <code class="literal">RECENT</code> message, which is
fine).
</p></li><li class="listitem"><p>
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:
</p><pre class="programlisting" xml:space="preserve">
* 3 EXISTS
* 0 RECENT
* 3 FETCH (FLAGS ())
</pre><p>
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 <code class="literal">RECENT</code>
count,
and one of the terminal windows should include a
<code class="literal">\Recent</code> flag in the untagged
<code class="literal">FLAGS</code> message.
These difference are acceptable; the important thing is to make sure that
all terminal windows have the same <code class="literal">EXISTS</code> message.
</p></li></ol></div></div></div><div class="refsect1"><a id="imapd_see_also" shape="rect"> </a><h2>SEE ALSO</h2><p>
<a class="ulink" href="authlib.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">authlib</span>(3)</span></a>,

<a class="ulink" href="userdb.html" target="_top" shape="rect"><span class="citerefentry"><span class="refentrytitle">userdb</span>(8)</span></a></p></div></div></body></html>
