                                  Courier-IMAP

  • Installation
  • Requirements
  • Upgrading
  • Manual compilation and installation
  • IMAP configuration file
  • Account initialization hook
  • Using shared folders
  • CRAM-MD5 Authentication
  • Certificate Authentication
  • Sending mail via an IMAP connection
  • Account OPTIONS
  • SMAP

INSTALLATION

  rpm and deb packages

These are not the same packages as the ones from various distributions'
repositories. These packages carry a higher internal revision level in order to
prevent them from getting upgraded by the distribution packaging, and their
installation layout may differ from the distributions' preferred package
installation layout. This packaging exists in order to have a convenient way of
updating after a release without waiting for the distribution's package to get
built, and to have a better correspondence with the documentation.

NOTE: If a distribution package is already installed it should be removed
completely before switching to the upstream version (dnf remove or apt purge).
Preserve any existing configuration files, beforehand, in order to restore it
after switching packages. This applies to all Courier packages. A switch to this
courier-imap package requires switching the courier-unicode and courier-authlib
packages too.

NOTE: these packages use their own, generic, installation layout that may
deviate slightly from the package installation layout that's preferred by the
distributions.

  rpm

Run dnf install rpm-build if it's not installed already, then:

rpmbuild -ta courier-imap-VERSION.tar.bz2

If this fails due to any missing dependencies, install them.

After installing the package, "systemctl enable courier-imap and systemctl start
courier-imap starts the IMAP and the POP3 servers. Self-signed SSL certificates
get generated and installed for the corresponding SSL ports too.

    Rocky/RHEL 8/9 notes

Courier packages require C++17 support, but the default version of gcc does not
fully support it, and a newer gcc is needed:

dnf install --enablerepo=crb -y gcc-toolset-14
scl enable gcc-toolset-14 "rpmbuild -ta courier-authlib-VERSION.tar.bz2"

  deb

Run "apt install devscripts debhelper", if they're not installed already. Create
an empty directory and copy/move the tarball into it:

$ mkdir tmp
$ mv courier-imap-VERSION.tar.bz2 tmp
$ cd tmp

Unpack the tarball and cd into the unpacked subdirectory:

$ tar xvf courier-imap-VERSION.tar.bz2
$ cd courier-imap-VERSION

Run the courier-debuild script, this is a wrapper for debuild, and it forwards
its parameters to it:

$ ./courier-debuild -us -uc

NOTE: the above steps must be followed strictly. The courier-debuild script
expects the distributed tarball in its parent directory.

NOTE: if the courier-debuild script stops with an error complaining about
missing dependencies, then use "apt install" to install them, then try again.

$ DEBGCC=10 ./courier-debuild -us -uc

Setting the DEBGCC environment variable selects a non-default gcc version.

NOTE: all Courier packages should be built using the same version of gcc.

After installing the package, the IMAP and the POP3 servers get automatically
started; and self-signed SSL certificates get generated and installed for the
corresponding SSL ports too.

    Ubuntu and Debian

Courier packages require C++17 support, but the default version of gcc on Ubuntu
20 does not fully support it, and a newer gcc is needed:

$ sudo apt install -y gcc-10 g++-10
$ DEBGCC=10 ./courier-debuild -us -uc

make check requires both the ISO-8859-1 based en_US locale in addition to the
default en_US.UTF-8, on all versions of Ubuntu and Debian.

  Maintainer Mode (see README in the git repository to set up)

make rpm or make deb, as appropriate, will:

 1. Increment an internal release number.

 2. Run make dist.

 3. Proceed and build a new release, creating the native packages in the rpm or
    deb subdirectory.

  Manual installation

To compile and install the Courier-IMAP server (this is the short version, a
longer version follows):


$ ./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

> NOTE

> You MUST run the configure 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
> configure. You will do everything as a normal user, except for the final step
> of installing the compiled software.

Requirements

  • C++ compiler - A C++ compiler is required. The server is written in C, but
    there are some configuration scripts that use C++ code.
  • 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).
  • GDBM/DB - either the GDBM or the Berkeley DB library is required.
  • The GNU IDN library (https://www.gnu.org/software/libidn/).
  • The Courier authentication library. Before installing Courier-IMAP, download
    and install https://www.courier-mta.org/authlib/.
  • The GNU IDN) library is required.
  • The Courier unicode library. Before installing Courier-IMAP, download and
    install https://www.courier-mta.org/unicode/.

UPGRADING

  Upgrading from Courier-IMAP 5.0.13, and earlier

Courier-IMAP switched to using the inotify kernel API directly instead of the
legacy FAM/Gamin daemon. When using virtual mail accounts it will be necessary
to increase the kernel's configured limit on the maximum number of inotify file
descriptors, see the installation notes, below.

  Upgrading from Courier-IMAP 4.18.2, and earlier

Courier-IMAP 5.0 added IMAP UTF8 support, and converted maildir folders' names
to Unicode. Updating an existing system to Courier-IMAP 5.0, and later, requires
a manual one-time conversion of all existing maildirs using the maildirmake
command. See the maildirmake(1) manual page for more information.

NOTE: If Cone is installed, Cone also must be updated to 0.97, or later.

  Upgrading from Courier-IMAP 4.14, and earlier

Version 4.15 removes the TLS_DHCERTFILE parameter from imap, and pop3d
configuration files. DH parameters, and DH parameters only, get read from the
new TLS_DHPARAMS file (and the other functionaly of TLS_DHCERTFILE, for DSA
certificates, is merged into TLS_CERTFILE). After upgrading, run the mkdhparams
script to create a new TLS_DHPARAMS file.

  Upgrading from Courier-IMAP 4.9.3, and earlier

In 4.10.0, the IMAP server resets the epoch for an internal sequence number
generator for new mailboxes. This is an internal attribute of individual IMAP
folders, that's defined by the IMAP specification. Each folder in a mailbox
carries an individual sequence number, it is defined as a 32 bit integer value,
and required to be a monotonically increasing value. and RFC 2060 recommended
that "... a good value to use for the unique identifier validity value is a
32-bit representation of the creation date/time of the mailbox."

On modern platforms, the system time is now a 64 bit value (even on the
remaining 32 bit platforms). With Y2038K on the horizon, it's time to reset the
epoch (the new epoch, for anyone who cares, runs until the year 2069). The
upgrade impact on existing systems is as follows.

There is no impact on existing folders in existing mailboxes. New folders will
have their internal sequence number in the new epoch.

One potential issue exists if a folder gets deleted by the IMAP client, and then
recreated later. The new folder will now get a lower sequence number. Although
this is technically not allowed, it's unlikely to cause problems with most IMAP
clients. If the same IMAP client deletes and recreated the mailbox, the client
should be completely up to speed. If, however, there's an IMAP client that
accesses the same folder, and some other IMAP client deletes and recreates the
same folder, this might cause confusion. Most IMAP clients are likely to recover
automatically; most IMAP clients only care that the new sequence number they see
is different from the previous one, in order to trigger a full resynchronization
with the server. In case an IMAP client fails to resynchronize, the remedy is to
remove the IMAP account configuration from the client, and add it back in.

Copying a mailbox by directly copying the files in maildirs preserves each
folder's epoch. However if a mailbox gets migrated by copying its contents over
IMAP, the folders on the destination IMAP server will not necessarily have a
monotonically higher value -- neither does IMAP guarantee that different IMAP
servers must be in agreement with each other on the subject of sequence numbers
-- and if IMAP clients are repointed to a new server they may experience
problems opening existing mailboxes. To remedy this situation it will be
necessary to completely remove and then reconfigure the IMAP account, in the
IMAP client. Again, verbatim copying of maildirs has no issues.

A marginal situation exists where if a server completely runs of disk space, or
if there's a hardware failure, and the IMAP server is unable to retrieve or save
an existing folder's sequence number, and must now start afresh and generate a
new one, the IMAP server running on a new epoch will recover with a lower
sequence than the one that existed before. The rememdy is the same: remove the
IMAP account configuration from the client, and then recreate it.

  Upgrading from Courier-IMAP 3, and earlier.

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.

You must download and install the Courier Authentication Library from
https://www.courier-mta.org/authlib/ before upgrading. Review the documentation
in the courier-authlib package for more information.

After upgrading to 4.0, or later, to avoid future confusion the old copies of
these configuration files (including the .dist files), should be removed from
Courier-IMAP's configuration directory. They now live in Courier-authlib's
configuration directory (/usr/local/etc/authlib, or whatever was specified to
Courier-authlib's configure script).

  Upgrading from Courier-IMAP 1.7.3, and earlier.

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.

Upgrading from Courier-IMAP 1.3.0, and later versions, is a straightforward
process. Follow the instructions in the INSTALLATION section, below, to install
the new version. The "make install-configure" command automatically preserves
the existing system configuration. However, note that new versions of
Courier-IMAP will often introduce additional configuration options. After make
install-configure a cursory inspection of configuration files in
/usr/lib/courier-imap/etc (the default location of the configuration directory)
is recommended, in order to identify any new configuration settings that might
need adjustment.

  Upgrading from Courier-IMAP 1.3.8.2 and earlier

The default configuration options have slightly changed. The default
configuration script will now always build the authdaemon module, and build all
real authentication modules inside authdaemond. This is true even with the
authvchkpw module.

  Upgrading from Courier-IMAP 1.2.3 and earlier

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:

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

The NEWS file has a detailed explanation of how configuration files are now
installed. Basically, make install now installs configfilename.dist, and make
install-configure copies configfilename.dist to configfilename, becoming the
actual configuration file. If there is an existing configfilename, the old
settings in configfilename which are still valid will be kept in the new
configfilename.

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 configfilename.bak.

The recommended procedure for upgrading from versions 1.2.3 and earlier is as
follows:

The recommended upgrade procedure is as follows:

  • Back up /usr/lib/courier-imap/etc
  • Follow the installation procedures, below
  • After installing, manually edit all configuration files. Restore, by hand,
    any custom configuration settings.

All configuration files are kept in the configuration directory. Nothing else in
/usr/lib/courier-imap 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.

  Upgrading from Courier-IMAP 1.1 or earlier

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 pop3d.config and pop3d-ssl.config configuration files, and set
POP3DSTART and POP3DSSLSTART to NO

  Upgrading from Courier-IMAP 1.0 or earlier

If the server is running, manually stop the server before installing the new
version.

Manual compilation and installation

As mentioned above an installable package should be prepared and installed using
the system's package manager. If the included script that create installable rpm
or deb packages won't work, for some reason, the following instructions provide
additional information for manual installation.

  Configuration and installation

As mentioned in "Requirements", above, if you are using xBSD, you must use gmake
instead of make.

════════════════════════════════════════════════════════════════════════════════

NOTE: The configure script may run as much as 5-10 minutes on slow machines. It
may appear that configure 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.

See below for a description of the options to the configure script.

WARNING: set your umask to 022 before running make install or make
install-strip.

You should try make install-strip first. Use make install if make install-strip
fails.

The configure script accepts certain options, but the defaults should be fine
most of the time. make install puts everything in /usr/lib/courier-imap. If the
directory /etc/pam.d exists, make install creates /etc/pam.d/imap and
/etc/pam.d/pop3, overwriting any existing files. If you have some other IMAP
server installed, this means that you will want to save your existing
configuration in /etc/pam.d/{imap|pop3}.

"make check" performs some internal sanity checks. If make check fails,
something is wrong, and Courier-IMAP may not work for you reliably. Certain
options are documented to cause make check 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.

After installation, you will need to review the files in
/usr/lib/courier-imap/etc and make any changes you deem necessary.

After running make install or make install-strip you will then have to modify
your system's startup scripts to run Courier-IMAP when your system boots.

Use the following command to start the Courier-IMAP server:


$ /usr/lib/courier-imap/libexec/imapd.rc start

This assumes that Courier-IMAP is installed in /usr/lib/courier-imap. Use the
following command to stop Courier-IMAP:


$ /usr/lib/courier-imap/libexec/imapd.rc stop

You will have to add these commands to your system startup/shutdown scripts.

    IMAP over SSL

To add SSL support you have to install OpenSSL or GnuTLS before installing
Courier-IMAP. Download OpenSSL from http://www.openssl.org/, or GnuTLS from
http://www.gnutls.org.

Follow OpenSSL's or GnuTLS's installation instructions, then build Courier-IMAP.

> NOTE: 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.

> NOTE: 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.

The OpenSSL library is selected when both OpenSSL and GnuTLS libraries are found
by the configure script. Use the --with-gnutls option to explicitly select the
GnuTLS library over OpenSSL.

The /usr/lib/courier-imap/etc/imapd-ssl 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
/usr/lib/courier-imap/libexec/imapd-ssl.rc script from your system startup and
shutdown scripts, just like the /usr/lib/courier-imap/libexec/imapd.rc script.
You may accept both SSL and non-SSL connections by running both scripts.

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 /usr/lib/courier-imap/share/imapd.pem. 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
/usr/lib/courier-imap/share/mkimapdcert 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.

The mkimapdcert script will not overwrite an existing imapd.pem certificate, in
order to allow precompiled packages to simply call mkimapdcert after
installation, without worry.

    Initial parameters, and a monthly cron job to generate DH parameters

Run the mkdhparams script to create a DH parameter file. A monthly cron job
should be created to run the mkdhparams script, in order to periodically
generate a new set of DH parameters. mkdhparams checks if the DH parameter
file's timestamp is older than 25 days, and creates a new file if it is. DH
parameters are used to set up encrypted connections.

    The bundled POP3 server

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:

The configuration files are /usr/lib/courier-imap/etc/pop3dand
/usr/lib/courier-imap/etc/pop3d-ssl.

The startup/shutdown scripts are /usr/lib/courier-imap/libexec/pop3d.rcand
/usr/lib/courier-imap/libexec/pop3d-ssl.rc.

The SSL certificate is /usr/lib/courier-imap/share/pop3d.pem, and the
/usr/lib/courier-imap/share/mkpop3dcert script can be used to create a
self-signed SSL certificate for testing purposes.

    System-V style startup

If your system uses System-V style startup scripts, take a look at
courier-imap.sysvinit - this is a sample /etc/init.d script.
courier-imap.sysvinit is created by configure. In most cases it can be merely
copied to /etc/init.d and /etc/rc?.d directories (with the execute permission
bit turned on).

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.

    Options to configure:

  • --prefix=pathname - install here, instead of /usr/lib/courier-imap
  • --without-ipv6 - do not compile IPv6 support. The configure 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.
    --without-ipv6 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 modprobe regularly complaining in /var/log/messages about the
    fact that it can't load the IPv6 module. Use --without-ipv6 to turn off IPv6
    support, if that bothers you.
  • --bindir=pathname , --mandir=pathname - override default names of
    subdirectories under prefix. See below for more information.
  • --with-db=db - 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.
  • --with-gnutls - 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.
  • --with-piddir=dir - use dir/imapd.pid to store couriertcpd's process ID.
  • --with-userdb=file - use file instead of /etc/userdb (also means that
    userdb.dat and userdbshadow.dat are appropriately renamed).
  • --enable-workarounds-for-imap-client-bugs - 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, "make check" will fail when this option is used. See
    imap/BUGS.(html|txt) for more information. NOTE - if this option is used,
    make check WILL FAIL. You should first configure Courier-IMAP without this
    option, run make check, then reconfigure Courier-IMAP with this option.
  • --with-trashquota - 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, make check WILL FAIL. You should first configure Courier-IMAP without
    this option, run make check, then reconfigure Courier-IMAP with this option.
  • --with-dirsync - after saving a new message to a maildir (the IMAP COPY and
    APPEND commands) explicitly sync the maildir's directory 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.

    Installation directories

Unless the options --prefix, --bindir, or --mandir are used, everything will be
installed in the directory /usr/lib/courier-imap.

Use the --prefix option to specify a different directory. This directory will
have the following subdirectories:

  • etc - configuration files
  • bin - binaries
  • sbin - superuser binaries
  • libexec - additional binaries
  • man - manual pages
  • share - scripts and data files
  • var - temporary files used by the authdaemond, daemon process (if the
    authdaemon authentication module is selected).

Having everything installed underneath one directory allows its contents to be
easily backed up, before a newer version of courier-imap is installed. Reverting
to a previous version is as simple as restoring from backup.

Because some binaries in bin and sbin 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 PATH. Additionally, it will also be necessary to modify
the configuration of the man(1) command so that it can find Courier-IMAP's
manual pages in this directory:

        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

As an alternative, you may use the --bindir and --mandir options in order to
install binaries to /usr/local/bin and the manual pages to /usr/local/man, which
should already be searched by default:

        ./configure --bindir=/usr/local/bin --mandir=/usr/local/man

Other familiar configure options, such as --sysconfdir and --datadir work too,
for those who know how to properly use them.

Configure the maximum number of inotify file descriptors

If courier-authlib gets set up to use virtual mail accounts that share the
system userid, it will be necessary to adjust the Linux kernel's limit on the
maximum number of file descriptors per userid,
/proc/sys/fs/inotify/max_user_instances. A good rough metric would be the
maximum number of concurrent IMAP logins multiplied by 4. On very large servers
it may also be necessary to increase /proc/sys/fs/inotify/max_user_watches, a
rough metric would be at least 5 times the max_user_instances setting.

Configuration file

The /usr/lib/courier-imap/etc/imapd configuration file sets some configurable
options. Each setting has a brief description. Review each setting, and make any
necessary adjustments.

The /usr/lib/courier-imap/etc/imapd-ssl configuration file sets additional
configuration setting for the server running IMAP over TLS or SSL on port 993.
Note that, by default, the regular IMAP server on port 143 also supports
encrypted connections, and the default startup script for the port 143 server
reads both configuration files.

The /usr/lib/courier-imap/etc/pop3d and the /usr/lib/courier-imap/etc/pop3d-ssl
configuration files set options of the POP3 server.

NOTE: the actual location of the configuration file directory is itself
configured at compilation time.

ACCOUNT INITIALIZATION HOOK

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.

USING SHARED FOLDERS

Courier-IMAP supports shared folders. See the file README.sharedfolders.html for
information on how to set up shared folders.

CRAM-MD5 AUTHENTICATION

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 authcram module, with one exception - authldap,
authpgsql, and authmysql support CRAM-MD5 authentication if the LDAP or the
MySQL/PostgreSQL server stores clear-text passwords, and not crypt-ed passwords.

To use CRAM-MD5 it is necessary to use an IMAP client that support CRAM-MD5
authentication, of course. That's the easy part.

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).

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:

  • Install and implement /etc/userdb, because CRAM-MD5 authentication uses the
    /etc/userdb database (but see below for LDAP-specific notes).
  • 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:

 userdbpw -hmac-md5 | userdb userdb set hmac-md5pw


    Then run the makeuserdb command, as always.
  • NOTE: CRAM-MD5 authentication is also be supported by authldap, authpgsql
    and authmysql, 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 should all set and ready to go, and you do not
    need to install /etc/userdb, as described in this section.

  Enabling CRAM-MD5 authentication

Because of these unfortunate complexities, CRAM-MD5 authentication is disabled
after installation. When you're ready to use CRAM-MD5, edit the imapd
configuration file and add the "AUTH=CRAM-MD5" keyword to the IMAP_CAPABILITY
environment variable, then restart Courier-IMAP. There are instructions in the
imapd configuration file to that effect.

If you do not intend to ever use CRAM-MD5 authentication, you can either specify
--without-authcram option to the configure script, or simply edit imapd and
remove authcram from the AUTHMODULES setting.

CERTIFICATE AUTHENTICATION

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:

> ...
> Subject: C=US,ST=New York,L=New York,O=Acme Widgets Inc,CN=John Smith,emailAddress=johnsmith@example.com

If the emailAddress field is configured as the login ID, the authentication
database must provide login details for johnsmith@example.com. To enable
certificate authentication, edit the imapd-ssl and pop3d-ssl configuration
files, and make the following changes:

  • Set TLS_TRUSTCERTS to the filename with your certificate authority's X.509
    certificate.

  • Change the TLS_VERIFYPEER setting to "PEER". The setting can also be changed
    to "REQUIREPEER" 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.

  • Change the TLS_EXTERNAL setting to the name of the certificate subject field
    that gives the login ID. In the above example, this would be
    "TLS_EXTERNAL=emailaddress".

    > NOTE: GnuTLS's certtool uses "email" as the name of this field. If
    > Courier-IMAP is compiled with GnuTLS, you should still specify this field
    > as "emailaddress".

SENDING MAIL VIA AN IMAP CONNECTION

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.

This is implemented by enabling a setting in the imapd 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 To:, Cc:,
and Bcc: headers.

It should be possible to use this to send mail from any IMAP client by:

 1. Composing a draft message, telling the IMAP client to save the draft message
    in its drafts folder on the IMAP server.
 2. Opening the drafts folder, and moving or copying the message to the Outbox
    folder.
 3. 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.

> NOTE: 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.

> NOTE: 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.

> NOTE: when enabled, the Courier-IMAP server will advertize a private
> XCOURIEROUTBOX 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.

> NOTE: 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.

Account OPTIONS

If the option 'disableimap' or 'disablepop3' 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 DEFAULTOPTIONS="disableimap=1"
will disable IMAP access for all accounts except those which have option
disableimap=0

See README_authlib.html in the courier-authlib package for information on how to
set per-account options.

SMAP

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
SMAP_CAPABILITY setting in the imapd configuration file in order to enable SMAP.
The Cone mail client supports SMAP.
