<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="Content-Type" content=
"text/html; charset=utf-8" />
<title>Courier-IMAP</title>
<meta name="MSSmartTagsPreventParsing" content="TRUE" />
<!-- $Id: INSTALL.html.in,v 1.82 2008/06/29 20:18:36 mrsam Exp $-->
</head>
<body text="#000000" bgcolor="#FFFFFF" link="#0000EE" vlink=
"#551A8B" alink="#FF0000">
<!-- Copyright 1998 - 2005 Double Precision, Inc. See COPYING for -->
<!-- distribution information. -->
<h1>Courier-IMAP</h1>
<p>For a general introduction and configuration settings for some
popular IMAP clients, go and read
<code>imap/README(.html)</code>.</p>
<p>In this document:</p>
<ul>
<li><a href="#requirements">Requirements</a></li>
<li><a href="#upgrading">Upgrading</a></li>
<li><a href="#install">Installation</a></li>
<li><a href="#loginexec">Account initialization hook</a></li>
<li><a href="#shared">Using shared folders</a></li>
<li><a href="#crammd5">CRAM-MD5 Authentication</a></li>
<li><a href="#sslcert">Certificate Authentication</a></li>
<li><a href="#imapsend">Sending mail via an IMAP
connection</a></li>
<li><a href="#idle">Realtime folder status updates</a></li>
<li><a href="#options">Account OPTIONS</a></li>
<li><a href="#smap">SMAP</a></li>
</ul>
<h2><a name="requirements" id=
"requirements">Requirements</a></h2>
<p>Now is the good time to read the FAQ, before you start. The
FAQ is located in the file <code>imap/FAQ(.html?)</code>.</p>
<ul>
<li>C++ compiler - A C++ compiler is required. The server is
written in C, but there are some configuration scripts that use
C++ code.</li>
<li>make - The GNU make is recommended. Solaris's make is to be
avoided. xBSD already has a gmake port, install it and use it
(use gmake everywhere this document refers to make).</li>
<li>GDBM/DB - either the GDBM or the Berkeley DB library is
required.</li>
<li><a href="http://www.gnome.org/~veillard/gamin/" target=
"_blank">Gamin</a>
(<tt>http://www.gnome.org/~veillard/gamin/</tt>) or <a href=
"http://oss.sgi.com/projects/fam/" target="_blank">FAM</a>
(<tt>http://oss.sgi.com/projects/fam/</tt>) -- either one -- is
optional. If <code>Gamin</code> or <code>FAM</code> is
installed, it is used for an enhanced IMAP <code>IDLE</code>
implementation that provides real-time folder status updates to
concurrent IMAP clients that have the same folder opened.</li>
<li>The Courier authentication library. Before installing
Courier-IMAP, download and install <a onclick="" href=
"http://www.courier-mta.org/authlib/">http://www.courier-mta.org/authlib/</a>.</li>
</ul>
<h2><a name="upgrading" id="upgrading">UPGRADING</a></h2>
<h3>Upgrading from Courier-IMAP 3, and earlier.</h3>
<p>Beginning with 4.0, the authentication library that used to be
a part of Courier-IMAP's source has been spun off into a
standalone authentication library.</p>
<p>You must download and install the Courier Authentication
Library from <a href=
"http://www.courier-mta.org/authlib/">http://www.courier-mta.org/authlib/</a>
before upgrading. Review the documentation in the
<code>courier-authlib</code> package for more information.</p>
<p>After upgrading to 4.0, or later, to avoid future confusion
the old copies of these configuration files (including the
<code>.dist</code> files), should be removed from Courier-IMAP's
configuration directory. They now live in Courier-authlib's
configuration directory (<code>/usr/local/etc/authlib</code>, or
whatever was specified to Courier-authlib's
<code>configure</code> script).</p>
<h3>Upgrading from Courier-IMAP 1.7.3, and earlier.</h3>
<p>After upgrading from Courier-IMAP 1.7.3, or earlier, any
existing mail in POP3 mailboxes may show up as new mail, by some
mail clients. Other mail clients may end up downloading a second
copy of any message that was left in the mailbox before the
upgrade. This is a one-time event. Courier-IMAP 2.0.0 uses a
different mechanism for generating POP3 message identifiers. Mail
clients that use POP3 identifiers will behave as if all messages,
that were left in the POP3 mailbox before the upgrade, were
removed, and replaced by new messages that happen to be the same
content. Depending on how the POP3 mail client works, it will
either flag all messages in the mailbox as unread, or download a
second copy of the message.</p>
<p>Upgrading from Courier-IMAP 1.3.0, and later versions, is a
straightforward process. Follow the instructions in the <a href=
"#install">INSTALLATION</a> section, below, to install the new
version. The "<code>make install-configure</code>" command
automatically preserves the existing system configuration.
However, note that new versions of Courier-IMAP will often
introduce additional configuration options. After <code>make
install-configure</code> a cursory inspection of configuration
files in <code>/usr/lib/courier-imap/etc</code> (the default location
of the configuration directory) is recommended, in order to
identify any new configuration settings that might need
adjustment.</p>
<h3>Upgrading from Courier-IMAP 1.3.8.2 and earlier</h3>
<p>The default configuration options have slightly changed. The
default configuration script will now always build the
<code>authdaemon</code> module, and build all real authentication
modules inside <code>authdaemond</code>. This is true even with
the <code>authvchkpw</code> module.</p>
<h3>Upgrading from Courier-IMAP 1.2.3 and earlier</h3>
<p>Courier-IMAP 1.3.0 introduced a new configuration file format
that allows configuration files to be automatically upgraded.
Additionally, several existing configuration files have been
renamed in order for their names to be consistent with the
Courier build:</p>
<pre>
Courier-IMAP < 1.3 Courier-IMAP 1.3.0
-------- ---------
imapd.config imapd
imapd-ssl.config imapd-ssl
pop3d.config pop3d
pop3d-ssl.config pop3d-ssl
</pre>
<p>The NEWS file has a detailed explanation of how configuration
files are now installed. Basically, <code>make install</code> now
installs <code>configfilename.dist</code>, and <code>make
install-configure</code> copies <code>configfilename.dist</code>
to <code>configfilename</code>, becoming the actual configuration
file. If there is an existing <code>configfilename</code>, the
old settings in <code>configfilename</code> which are still valid
will be kept in the new <code>configfilename</code>.</p>
<p>This only works as long as both the old and the new
configuration files are in the new format, so this will actually
take effect with your next upgrade Courier-IMAP. If the previous
installed version of Courier-IMAP did not use the new format for
configuration files (1.2.3 and earlier), the old configuration
file is backed up to <code>configfilename.bak</code>.</p>
<p>The recommended procedure for upgrading from versions 1.2.3
and earlier is as follows:</p>
<p>The recommended upgrade procedure is as follows:</p>
<ul>
<li>Back up <code>/usr/lib/courier-imap/etc</code></li>
<li>Follow the installation procedures, below</li>
<li>After installing, manually edit all configuration files.
Restore, by hand, any custom configuration settings.</li>
</ul>
<p>All configuration files are kept in the configuration
directory. Nothing else in <code>/usr/lib/courier-imap</code> is
configurable. Do not simply overwrite 1.3.0 configuration files
with configuration files from the previous version. It's
tempting, but don't do it. It may work, but you will lose the
automatic upgrade capability for future releases.</p>
<h3>Upgrading from Courier-IMAP 1.1 or earlier</h3>
<p>Note that Courier-IMAP 1.2 includes a compatible POP3 server,
and the installation script will also install a POP3 server on
your system. Even though it is installed, you are not required to
use it, but you still need to be aware of its existence. If you
install the RPM build of Courier-IMAP, you're going to get the
POP3 server started at system boot. If you do not need POP3
services, edit both the <code>pop3d.config</code> and
<code>pop3d-ssl.config</code> configuration files, and set
<code>POP3DSTART</code> and <code>POP3DSSLSTART</code> to NO</p>
<h3>Upgrading from Courier-IMAP 1.0 or earlier</h3>
<p>If the server is running, manually stop the server before
installing the new version.</p>
<h2><a name="install" id="install">INSTALLATION</a></h2>
<p>To compile and install the Courier-IMAP server (this is the
short version, a longer version follows):</p>
<pre>
$ ./configure [ options, see below ]
$ make
$ make check # Note - the --enable-workarounds-for-imap-client-bugs
# option to configure will result in make check FAILING.
$ su root
# make install # Or, make install-strip, to strip the executables.
# make install-configure # Install configuration files.
# Start the authdaemond process
</pre>
<blockquote>
<p><b>NOTE</b></p>
<p>You MUST run the <code>configure</code> script as normal
user, not root. Did you extract the tarball as root? It won't
work. Remove the extracted source code. Log in as a normal
user. Extract the source code as a normal user, then run
<code>configure</code>. You will do everything as a normal
user, except for the final step of installing the compiled
software.</p>
</blockquote>
<blockquote>
<p><b>NOTE</b></p>
<p>Courier-IMAP does not use <code>inetd</code> or
<code>xinetd</code>. Any <code>inetd</code> or
<code>xinetd</code> configuration settings for the IMAP and
POP3 ports must be turned off. Courier-IMAP will not start if
<code>inetd</code> or <code>xinetd</code> is listening for IMAP
or POP3 connections.</p>
</blockquote>
<hr />
<p>As mentioned in "Requirements", above, if you are using xBSD,
you must use gmake instead of make.</p>
<hr />
<p>NOTE: The <code>configure</code> script may run as much as
5-10 minutes on slow machines. It may appear that
<code>configure</code> is stuck in a loop, but that's an
illusion. Courier-IMAP is built from a collection of modular
components, each with its own configuration script. The
configuration scripts share a lot of common code, leading to an
initial impression that the same configuration script is being
repeatedly run.</p>
<p>See below for a description of the options to the
<code>configure</code> script.</p>
<p><b>WARNING:</b> set your umask to 022 before running
<code>make install</code> or <code>make install-strip</code>.</p>
<p>You should try <code>make install-strip</code> first. Use
<code>make install</code> if <code>make install-strip</code>
fails.</p>
<p>The configure script accepts certain options, but the defaults
should be fine most of the time. <code>make install</code> puts
everything in <code>/usr/lib/courier-imap</code>. If the directory
<code>/etc/pam.d</code> exists, <code>make install</code> creates
<code>/etc/pam.d/imap</code> and <code>/etc/pam.d/pop3</code>,
overwriting any existing files. If you have some other IMAP
server installed, this means that you will want to save your
existing configuration in
<code>/etc/pam.d/{imap|pop3}</code>.</p>
<p>"<code>make check</code>" performs some internal sanity
checks. If <code>make check</code> fails, something is wrong, and
Courier-IMAP may not work for you reliably. Certain options are
documented to cause <code>make check</code> to fail, due to
different IMAP protocol behavior. If you need to use those
options, first compile Courier-IMAP without them, run make check,
and if all goes well extract the source code again in a different
directory, then build it for the second time using your
options.</p>
<p>After installation, you will need to review the files in
<code>/usr/lib/courier-imap/etc</code> and make any changes you deem
necessary.</p>
<p>After running <code>make install</code> or <code>make
install-strip</code> you will then have to modify your system's
startup scripts to run Courier-IMAP when your system boots.</p>
<p>Use the following command to start the Courier-IMAP
server:</p>
<pre>
$ /usr/lib/courier-imap/libexec/imapd.rc start
</pre>
<p>This assumes that Courier-IMAP is installed in
<code>/usr/lib/courier-imap</code>. Use the following command to stop
Courier-IMAP:</p>
<pre>
$ /usr/lib/courier-imap/libexec/imapd.rc stop
</pre>
<p>You will have to add these commands to your system
startup/shutdown scripts.</p>
<h4>IMAP over SSL</h4>
<p>To add SSL support you have to install OpenSSL or GnuTLS
before installing Courier-IMAP. Download OpenSSL from <a target=
"_blank" href=
"http://www.openssl.org/"><code>http://www.openssl.org/</code></a>,
or GnuTLS from <a target="_blank" href=
"http://www.gnutls.org"><code>http://www.gnutls.org</code></a>.</p>
<p>OpenSSL's support is well-tested, the GnuTLS version is a
relatively new addition, and is considered experimental. Follow
OpenSSL's or GnuTLS's installation instructions, then build
Courier-IMAP.</p>
<blockquote>
<p><b>NOTE:</b> Most systems already have an available OpenSSL
or GnuTLS package. Do not build OpenSSL or GnuTLS yourself, if
a prebuilt package is already available. Just install the
prebuilt package.</p>
</blockquote>
<blockquote>
<p><b>NOTE:</b> The development libraries must be installed in
addition to the runtime package, in order to build
Courier-IMAP. On most systems, the development files (header
files, libraries, etc...) are provided in a separate "devel"
package. The base OpenSSL/GnuTLS package is not sufficient to
build Courier-IMAP, the development libraries must be
installed.</p>
</blockquote>
<p>The OpenSSL library is selected when both OpenSSL and GnuTLS
libraries are found by the <code>configure</code> script. Use the
<code>--with-gnutls</code> option to explicitly select the GnuTLS
library over OpenSSL.</p>
<p>The <code>/usr/lib/courier-imap/etc/imapd-ssl</code> configuration
file sets some additional options for SSL support, which you may
need to adjust. Consult that configuration file for additional
information. Then, you also have to run the
<code>/usr/lib/courier-imap/libexec/imapd-ssl.rc</code> script from
your system startup and shutdown scripts, just like the
<code>/usr/lib/courier-imap/libexec/imapd.rc</code> script. You may
accept both SSL and non-SSL connections by running both
scripts.</p>
<p>Note that SSL requires a valid, signed, X.509 certificate to
be installed where Courier-IMAP expects to find it. The default
location for the X.509 certificate, in PEM format, is
<code>/usr/lib/courier-imap/share/imapd.pem</code>. The X.509
certificate must be signed by a certificate authority that is
known to the IMAP client. You can generate your own self-signed
certificate by running the script
<code>/usr/lib/courier-imap/share/mkimapdcert</code> which will work
too, except that IMAP clients using SSL will display a warning
message the first time they connect to the server. To get rid of
the warning message you'll have to pay for a signed X.509
certificate. The gory details of setting up SSL is beyond the
scope of this document, and you should consult the OpenSSL
documentation for more information.</p>
<p>The <code>mkimapdcert</code> script will not overwrite an
existing <code>imapd.pem</code> certificate, in order to allow
precompiled packages to simply call <code>mkimapdcert</code>
after installation, without worry.</p>
<h4>The bundled POP3 server</h4>
<p>The POP3 server included with Courier-IMAP provides POP3
access to INBOX, and that's about it. Enabling the POP3 server is
very similar to enabling the IMAP server, with the following
differences:</p>
<p>The configuration files are
<code>/usr/lib/courier-imap</code>/etc/pop3dand
<code>/usr/lib/courier-imap</code>/etc/pop3d-ssl.</p>
<p>The startup/shutdown scripts are
<code>/usr/lib/courier-imap</code>/libexec/pop3d.rcand
<code>/usr/lib/courier-imap</code>/libexec/pop3d-ssl.rc.</p>
<p>The SSL certificate is
<code>/usr/lib/courier-imap/share/pop3d.pem</code>, and the
<code>/usr/lib/courier-imap/share/mkpop3dcert</code> script can be used
to create a self-signed SSL certificate for testing purposes.</p>
<h4>System-V style startup</h4>
<p>If your system uses System-V style startup scripts, take a
look at <code>courier-imap.sysvinit</code> - this is a sample
<code>/etc/init.d</code> script.
<code>courier-imap.sysvinit</code> is created by
<code>configure</code>. In most cases it can be merely copied to
<code>/etc/init.d</code> and <code>/etc/rc?.d</code> directories
(with the execute permission bit turned on).</p>
<p>The sample startup script will check if IMAP or POP3 over SSL
is enabled. The sample startup script automatically creates dummy
SSL certificates the first time it is executed.</p>
<h4>Options to <code>configure</code>:</h4>
<ul>
<li><code>--prefix=pathname</code> - install here, instead of
<code>/usr/lib/courier-imap</code></li>
<li><code>--without-ipv6</code> - do not compile IPv6 support.
The <code>configure</code> automatically checks if IPv6 support
is available, and enables it automatically. This option
suppresses IPv6 support, even if it's available. IPv6 support
means that Courier-IMAP will create an IPv6 socket and accept
IPv6 connections. <code>--without-ipv6</code> should be used if
your system does not fully support IPv6, or if its
implementation is buggy. Most Linux distributions now ship with
IPv6 support in glibc, but without compiling the kernel for
IPv6 support. This results in <code>modprobe</code> regularly
complaining in <code>/var/log/messages</code> about the fact
that it can't load the IPv6 module. Use
<code>--without-ipv6</code> to turn off IPv6 support, if that
bothers you.</li>
<li><code>--enable-unicode</code> - include the ability to
search and sort messages in character sets other than the
default ISO-8859-1/US-ASCII. All character set tables supported
by Courier-IMAP will be included. See below for more
details.</li>
<li><code>--enable-unicode=<i>charset,charset,...</i></code> -
include ability to search and sort messages, but only for these
character sets. See below for more details.</li>
<li><code>--bindir=pathname</code> ,
<code>--mandir=pathname</code> - override default names of
subdirectories under <code>prefix</code>. See below for more
information.</li>
<li><code>--with-db=db</code> - Use the DB library instead of
the GDBM library You must have either the GDBM or the DB
library installed. If both are present, GDBM is selected unless
you use this option. The GDBM/DB library is used by Courier for
certain functions.</li>
<li><code>--with-gnutls</code> - Use the GnuTLS library even if
the OpenSSL library is also installed. Courier-IMAP
automatically uses whichever one is available. The OpenSSL
library is selected if both are present. Use this option to
override and select GnuTLS instead.</li>
<li><code>--with-piddir=dir</code> - use dir/imapd.pid to store
couriertcpd's process ID.</li>
<li><code>--with-userdb=file</code> - use <i>file</i> instead
of <code>/etc/userdb</code> (also means that userdb.dat and
userdbshadow.dat are appropriately renamed).</li>
<li><code>--enable-workarounds-for-imap-client-bugs</code> -
there are a number of various bugs in certain IMAP clients. The
current list of broken IMAP clients consists of Netscape
Messenger and Sun's StarOffice. This option enables some
workarounds for some bugs in these clients, however, note that
this may break compatibility with software that correctly
implements IMAP4rev1. Additionally, "<code>make check</code>"
will fail when this option is used. See
<code>imap/BUGS.(html|txt)</code> for more information. NOTE -
if this option is used, <code>make check</code> WILL FAIL. You
should first configure Courier-IMAP without this option, run
<code>make check</code>, then reconfigure Courier-IMAP with
this option.</li>
<li><code>--with-trashquota</code> - include deleted messages,
and the Trash folder, in the estimated quota usage for
maildirs. Quotas are optional, see the file
maildir/README.maildirquota.html for more information. The
default configuration does not count messages marked as deleted
(but not yet expunged) and the contents of the Trash folder
(which are automatically purged by the server) against the
quota usage. NOTE - if this option is used, <code>make
check</code> WILL FAIL. You should first configure Courier-IMAP
without this option, run <code>make check</code>, then
reconfigure Courier-IMAP with this option.</li>
<li><code>--with-dirsync</code> - after saving a new message to
a maildir (the <code>IMAP</code> <code>COPY</code> and
<code>APPEND</code> commands) explicitly sync the maildir's
<code>directory</code> directory. There's a school of thought
which believes that the Linux ext2 filesystem requires the
parent directory to be synced, in addition to the new message
file that's just been written to disk. There's another school
of thought that thinks that this issue is completely blown out
of proportion, and is really nothing more than a tempest in a
teapot. However -- to accomodate the former school of thought
-- this option adds a little bit of extra code to sync the
parent directory.</li>
</ul>
<h4>Foreign character set sorting/searching</h4>
<p>The Courier-IMAP server can search and sort messages using
other than the default us-ascii/iso-8859-1 character set. You can
find the list of available character sets in the file
<code>unicode/charsetlist.txt</code>.</p>
<p>The default is to include only the ISO-8859-1/US-ASCII
character set. Use the <code>--enable-unicode</code> option to
include all available character sets.</p>
<p>It is also possible to include translation tables only for
selected character sets. Example:</p>
<p><code>--enable-unicode=iso-8859-1,utf-8,iso-8859-10</code></p>
<p>Technically, IMAP servers must support the UTF-8 character
set, however few IMAP clients (I've yet to see one, actually)
care about UTF-8, so the UTF-8 character set is optional in
Courier-IMAP. The only required character set - which is always
included, explicitly or implicitly - is ISO-8859-1/US-ASCII.</p>
<p>Note that character set translation tables need substantial
memory. This should not be a problem in most cases. Most
compilers will place the read-only character set tables into a
shared text segment, that's shared by all running servers.
<code>--enable-unicode</code> should not really be much of a
burden for most modern operating systems.</p>
<p>Attentive individuals will observe that all character set
tables are compiled even without the <code>--enable-unicode
option</code>. That is normal -- only the explicitly selected
character set tables will actually make it into the final
executable.</p>
<h4>Installation directories</h4>
<p>Unless the options <code>--prefix</code>,
<code>--bindir</code>, or <code>--mandir</code> are used,
everything will be installed in the directory
<code>/usr/lib/courier-imap</code>.</p>
<p>Use the <code>--prefix</code> option to specify a different
directory. This directory will have the following
subdirectories:</p>
<ul>
<li><code>etc</code> - configuration files</li>
<li><code>bin</code> - binaries</li>
<li><code>sbin</code> - superuser binaries</li>
<li><code>libexec</code> - additional binaries</li>
<li><code>man</code> - manual pages</li>
<li><code>share</code> - scripts and data files</li>
<li><code>var</code> - temporary files used by the
<code>authdaemond</code>, daemon process (if the
<code>authdaemon</code> authentication module is
selected).</li>
</ul>
<p>Having everything installed underneath one directory allows
its contents to be easily backed up, before a newer version of
<code>courier-imap</code> is installed. Reverting to a previous
version is as simple as restoring from backup.</p>
<p>Because some binaries in <code>bin</code> and
<code>sbin</code> may be executed from the command line, it will
be necessary to change your systemwide global startup script to
add this directory to the default <code>PATH</code>.
Additionally, it will also be necessary to modify the
configuration of the <code>man(1)</code> command so that it can
find Courier-IMAP's manual pages in this directory:</p>
<pre>
PATH="/usr/lib/courier-imap/bin:$PATH"
if test -w /etc
then
PATH="/usr/lib/courier-imap/sbin:$PATH"
fi
export PATH
MANPATH="/usr/lib/courier-imap/man:$MANPATH"
export MANPATH
</pre>
<p>As an alternative, you may use the <code>--bindir</code> and
<code>--mandir</code> options in order to install binaries to
<code>/usr/local/bin</code> and the manual pages to
<code>/usr/local/man</code>, which should already be searched by
default:</p>
<pre>
./configure --bindir=/usr/local/bin --mandir=/usr/local/man
</pre>
<p>Other familiar configure options, such as
<code>--sysconfdir</code> and <code>--datadir</code> work too,
for those who know how to properly use them.</p>
<h2><a name="loginexec" id="loginexec">ACCOUNT INITIALIZATION
HOOK</a></h2>
<p>If there is a file or a symbolic link in the maildir called
"loginexec", and if it is executable, then the executable file
will be invoked after a succesful login. If the program
terminates with an exit code of 0, the "loginexec" file (or a
symbolic link) will be removed.</p>
<h2><a name="shared" id="shared">USING SHARED FOLDERS</a></h2>
<p>Courier-IMAP supports shared folders. See the file <a href=
"README.sharedfolders.html"><code>README.sharedfolders.html</code></a>
for information on how to set up shared folders.</p>
<h2><a name="crammd5" id="crammd5">CRAM-MD5
AUTHENTICATION</a></h2>
<p>CRAM-MD5 authentication allows IMAP clients to authenticate
themselves without sending the password in clear-text over the
network. Courier-IMAP now supports CRAM-MD5 by default, but is
not enabled for reasons explained below. CRAM-MD5 support is
implemented by the <code>authcram</code> module, with one
exception - <code>authldap</code>, <code>authpgsql</code>, and
<code>authmysql</code> support CRAM-MD5 authentication if the
LDAP or the MySQL/PostgreSQL server stores clear-text passwords,
and not crypt-ed passwords.</p>
<p>To use CRAM-MD5 it is necessary to use an IMAP client that
support CRAM-MD5 authentication, of course. That's the easy
part.</p>
<p>The problem is that it is not possible to use the system
password when logging in using CRAM-MD5. That's because CRAM-MD5
requires the knowledge of the actual password, in the clear, in
order to calculate authentication tokens (even though that the
password itself is not sent in the clear over the network).</p>
<p>So, implementation of CRAM-MD5 is an advanced task that should
be attempted only when you are comfortable with, and fully
understand how Courier-IMAP works in general. Here's an overview
of this procedure:</p>
<ul>
<li>Install and implement <code>/etc/userdb</code>, because
CRAM-MD5 authentication uses the <code>/etc/userdb</code> database
(but see below for LDAP-specific notes).</li>
<li>Figure out which accounts are going to use CRAM-MD5
authentication. People who do not use an IMAP client that
supports CRAM-MD5 can continue and log in with the existing
system password. But everyone who runs a client that supports
CRAM-MD5 authentication will need a new password. Also, it will
be necessary to set up CRAM-MD5 passwords for everyone at the
same time. As soon as CRAM-MD5 authentication is enabled, all
CRAM-MD5 enabled clients will attempt to use it. If no password
is available, Courier-IMAP has no choice but to reject the
authentication attempt. Once that happens, the client will
correctly interpret it as an authentication failure (and it
is), and the client will not even try to authenticate using the
system password. Use the following command to assign a CRAM-MD5
password:
<pre>
userdbpw -hmac-md5 | userdb <i>userdb</i> set hmac-md5pw
</pre>Then run the <code>makeuserdb</code> command, as always.
</li>
<li>NOTE: CRAM-MD5 authentication is also be supported by
<code>authldap</code>, <code>authpgsql</code> and
<code>authmysql</code>, as long as clear-text passwords are
used. See below for more information. Therefore, if you use
LDAP, PostgreSQL, or MySQL, and you store clear-text passwords,
you <i>should</i> all set and ready to go, and you do not need
to install <code>/etc/userdb</code>, as described in this
section.</li>
</ul>
<h3>Enabling CRAM-MD5 authentication</h3>
<p>Because of these unfortunate complexities, CRAM-MD5
authentication is disabled after installation. When you're ready
to use CRAM-MD5, edit the <code>imapd</code> configuration file
and add the "AUTH=CRAM-MD5" keyword to the IMAP_CAPABILITY
environment variable, then restart Courier-IMAP. There are
instructions in the <code>imapd</code> configuration file to that
effect.</p>
<p>If you do not intend to ever use CRAM-MD5 authentication, you
can either specify <code>--without-authcram</code> option to the
configure script, or simply edit <code>imapd</code> and remove
authcram from the AUTHMODULES setting.</p>
<h2><a name="sslcert" id="sslcert">CERTIFICATE
AUTHENTICATION</a></h2>
<p>Courier-IMAP can use SSL certificates for authentication
purposes. For certificate authentication purposes, one of the
fields in your certificates' subject must match the login ID in
the authentication database. Consider the following
certificate:</p>
<blockquote>
<pre>
...
Subject: C=US,ST=New York,L=New York,O=Acme Widgets Inc,CN=John Smith,emailAddress=johnsmith@example.com
</pre>
</blockquote>
<p>If the <code>emailAddress</code> field is configured as the
login ID, the authentication database must provide login details
for <code>johnsmith@example.com</code>. To enable certificate
authentication, edit the <code>imapd-ssl</code> and
<code>pop3d-ssl</code> configuration files, and make the
following changes:</p>
<ul>
<li>
<p>Set <code>TLS_TRUSTCERTS</code> to the filename with your
certificate authority's X.509 certificate.</p>
</li>
<li>
<p>Change the <code>TLS_VERIFYPEER</code> setting to
"<code>PEER</code>". The setting can also be changed to
"<code>REQUIREPEER</code>" to require all SSL/TLS connections
to provide a certificate. Otherwise, it is optional. If the
mail client provides an SSL certificate, it may be used to
authenticate. Without a certificate, password-based
authentication remains an option.</p>
</li>
<li>
<p>Change the <code>TLS_EXTERNAL</code> setting to the name
of the certificate subject field that gives the login ID. In
the above example, this would be
"<code>TLS_EXTERNAL=emailaddress</code>".</p>
<blockquote>
<p>NOTE: GnuTLS's <code>certtool</code> uses
"<code>email</code>" as the name of this field. If
Courier-IMAP is compiled with GnuTLS, you should still
specify this field as "<code>emailaddress</code>".</p>
</blockquote>
</li>
</ul>
<h2><a name="imapsend" id="imapsend">SENDING MAIL VIA AN IMAP
CONNECTION</a></h2>
<p>This server allows using the IMAP connection to send E-mail.
Normally, the IMAP protocol provides only access to mail in an
existing mail account, and mail clients must use SMTP in order to
send mail. The Courier-IMAP server has an optional setting to
enable mail to be send via an IMAP connection in a manner that
should work with all existing IMAP mail clients. This can be
useful when an account is logged in from a shared access pool
which normally blocks most access to the SMTP port.</p>
<p>This is implemented by enabling a setting in the
<code>imapd</code> configuration file that designates a folder as
a special "Outbox" folder. The default setting is a folder called
"Outbox" (IMAP path INBOX.Outbox), but the name can be changed to
anything. This folder, for the most part, is no different than
any other folder. If a folder by that name doesn't exist, it
needs to be created, just like any other IMAP folder. It looks
and acts like any other folder, except that each message added to
the folder, via IMAP's APPEND or COPY command, will also be
mailed out by the Courier-IMAP server to the addresses listed in
the <code>To:</code>, <code>Cc:</code>, and <code>Bcc:</code>
headers.</p>
<p>It should be possible to use this to send mail from any IMAP
client by:</p>
<ol>
<li>Composing a draft message, telling the IMAP client to save
the draft message in its drafts folder on the IMAP server.</li>
<li>Opening the drafts folder, and moving or copying the
message to the Outbox folder.</li>
<li>The act of copying the message into the Outbox folder will
send the mail. There won't be any explicit notification to the
fact that the message was sent, so it's a good idea to include
your own E-mail address on the Cc: list.</li>
</ol>
<blockquote>
<p><b>NOTE:</b> it is tempting to configure the IMAP mail
client to use Outbox as its default folder for saving drafts.
Resist the temptation. If you forget, you'll save a partially
completed draft, which will be then obediently mailed out.</p>
</blockquote>
<blockquote>
<p><b>NOTE:</b> the message, in addition to being sent, will be
saved in the folder in the normal fashion. After saving the
message, reopen the Outbox folder and delete the sent message,
or move it someplace else.</p>
</blockquote>
<blockquote>
<p><b>NOTE:</b> when enabled, the Courier-IMAP server will
advertize a private <code>XCOURIEROUTBOX</code> IMAP
capability. It is theoretically possible to code an IMAP mail
client that reads this capability and automatically configures
itself accordingly -- when this IMAP capability is present --
to send E-mail in the normal way but using the IMAP connection.
At this time, I'm not aware of any actual mail clients that
know how to do this.</p>
</blockquote>
<blockquote>
<p><b>NOTE:</b> many mail clients save some additional internal
information in headers of draft messages. The internal
information is normally removed before the mail client sends
the message. Make sure that none of this extra information is
something that should not be mailed out.</p>
</blockquote>
<h2><a name="idle" id="idle">REALTIME FOLDER STATUS
UPDATES</a></h2>
<p>If <a href="http://www.gnome.org/~veillard/gamin/" target=
"_blank">Gamin</a>
(<tt>http://www.gnome.org/~veillard/gamin/</tt>) or <a target=
"_blank" href="http://oss.sgi.com/projects/fam/">FAM</a>
(<tt>http://oss.sgi.com/projects/fam/</tt>) is installed it will
be possible to allow multiple clients to open the same folder,
and have all clients to be simultaneously notified of any changes
to the folder contents.</p>
<p>After installing the server see the <tt>imapd(8)</tt> manual
page for more information.</p>
<h2><a name="options" id="options">Account OPTIONS</a></h2>
<p>If the option '<code>disableimap</code>' or
'<code>disablepop3</code>' is set to a non-zero value, then
logins via IMAP or POP3 respectively will be disabled for that
account. You can use the DEFAULTOPTIONS setting to disable a
service globally and then re-enable it for individual accounts;
for example, setting <code>DEFAULTOPTIONS="disableimap=1"</code>
will disable IMAP access for all accounts except those which have
option <code>disableimap=0</code></p>
<p>See <code>README_authlib.html</code> in the courier-authlib
package for information on how to set per-account options.</p>
<h2><a name="smap" id="smap">SMAP</a></h2>
<p>Starting with Courier-IMAP 2.0, the server supports an
experimental mail access protocol, dubbed "Simple Mail Access
Protocol". SMAP is an experiment to provide enhanced mail
processing beyond what's currently possible with IMAP. SMAP's
purpose is to prototype and develop advanced mail access
functionality that's not possible with IMAP. SMAP is disabled by
default. Uncomment the <code>SMAP_CAPABILITY</code> setting in
the <code>imapd</code> configuration file in order to enable
SMAP. The <a target="_blank" href=
"http://www.courier-mta.org/cone/index.html">Cone</a> mail client
supports SMAP.</p>
</body>
</html>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
fa5e22015e1f2396d5d803cb1fafdafc
>
files
>
21
