For a general introduction and configuration settings for some
popular IMAP clients, go and read
In this document:
Now is the good time to read the FAQ, before you start. The
FAQ is located in the file
FAMis installed, it is used for an enhanced IMAP
IDLEimplementation that provides real-time folder status updates to concurrent IMAP clients that have the same folder opened.
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
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.
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 http://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 (
whatever was specified to Courier-authlib's
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
install-configure a cursory inspection of configuration
/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
The default configuration options have slightly changed. The
default configuration script will now always build the
authdaemon module, and build all real authentication
authdaemond. This is true even with
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
configfilename, becoming the actual configuration
file. If there is an existing
old settings in
configfilename which are still valid
will be kept in the new
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
The recommended procedure for upgrading from versions 1.2.3 and earlier is as follows:
The recommended upgrade procedure is as follows:
All configuration files are kept in the configuration
directory. Nothing else in
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.
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-ssl.config configuration files, and set
POP3DSSLSTART to NO
If the server is running, manually stop the server before installing the new version.
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
You MUST run the
configurescript 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.
Courier-IMAP does not use
xinetdconfiguration settings for the IMAP and POP3 ports must be turned off. Courier-IMAP will not start if
xinetdis listening for IMAP or POP3 connections.
As mentioned in "Requirements", above, if you are using xBSD, you must use gmake instead of make.
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
See below for a description of the options to the
WARNING: set your umask to 022 before running
make install or
You should try
make install-strip first. Use
make install if
The configure script accepts certain options, but the defaults
should be fine most of the time.
make install puts
/usr/lib/courier-imap. If the directory
make install creates
overwriting any existing files. If you have some other IMAP
server installed, this means that you will want to save your
existing configuration in
make check" performs some internal sanity
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
After installation, you will need to review the files in
/usr/lib/courier-imap/etc and make any changes you deem
make install or
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
$ /usr/lib/courier-imap/libexec/imapd.rc stop
You will have to add these commands to your system startup/shutdown scripts.
To add SSL support you have to install OpenSSL or GnuTLS
before installing Courier-IMAP. Download OpenSSL from
or GnuTLS from
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.
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
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.
mkimapdcert script will not overwrite an
imapd.pem certificate, in order to allow
precompiled packages to simply call
after installation, without worry.
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
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
The startup/shutdown scripts are
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.
If your system uses System-V style startup scripts, take a
courier-imap.sysvinit - this is a sample
courier-imap.sysvinit is created by
configure. In most cases it can be merely copied to
(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.
--prefix=pathname- install here, instead of
--without-ipv6- do not compile IPv6 support. The
configureautomatically 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-ipv6should 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
modproberegularly complaining in
/var/log/messagesabout the fact that it can't load the IPv6 module. Use
--without-ipv6to turn off IPv6 support, if that bothers you.
--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 checkWILL 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 checkWILL 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
APPENDcommands) explicitly sync the maildir's
directorydirectory. 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.
Unless the options
--mandir are used,
everything will be installed in the directory
--prefix option to specify a different
directory. This directory will have the following
etc- configuration files
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
authdaemonauthentication 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
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
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
--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
./configure --bindir=/usr/local/bin --mandir=/usr/local/man
Other familiar configure options, such as
--datadir work too,
for those who know how to properly use them.
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.
Courier-IMAP supports shared folders. See the file
for information on how to set up shared folders.
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
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:
/etc/userdb, because CRAM-MD5 authentication uses the
/etc/userdbdatabase (but see below for LDAP-specific notes).
userdbpw -hmac-md5 | userdb userdb set hmac-md5pwThen run the
makeuserdbcommand, as always.
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.
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
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.
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,emailAddressfirstname.lastname@example.org
emailAddress field is configured as the
login ID, the authentication database must provide login details
email@example.com. To enable certificate
authentication, edit the
pop3d-ssl configuration files, and make the
TLS_TRUSTCERTS to the filename with your
certificate authority's X.509 certificate.
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.
TLS_EXTERNAL setting to the name
of the certificate subject field that gives the login ID. In
the above example, this would be
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
It should be possible to use this to send mail from any IMAP client by:
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
XCOURIEROUTBOXIMAP 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.
If Gamin (http://www.gnome.org/~veillard/gamin/) or FAM (http://oss.sgi.com/projects/fam/) 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.
After installing the server see the imapd(8) manual page for more information.
If the option '
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
will disable IMAP access for all accounts except those which have
README_authlib.html in the courier-authlib
package for information on how to set per-account options.
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
imapd configuration file in order to enable
SMAP. The Cone mail client