                                  Courier-IMAP

   For a general introduction and configuration settings for some popular
   IMAP clients, go and read imap/README(.html).

   In this document:

     * Requirements

     * Upgrading

     * Installation

     * Authentication modules - General notes

     * Authentication internals

     * USERDB Authentication module

     * VCHKPW Authentication module

     * LDAP Authentication module

     * DAEMON Authentication module

     * Account initialization hook

     * Using shared folders

     * CRAM-MD5 Authentication

     * Sending mail via an IMAP connection

     * Realtime folder status updates

     * Account OPTIONS

     * SMAP

Requirements

   Now is the good time to read the FAQ, before you start. The FAQ is located
   in the file imap/FAQ(.html?).

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

     * FAM, the File Alteration Monitor (http://oss.sgi.com/projects/fam/) is
       optional. If FAM is installed, it is used for an enhanced IMAP IDLE
       implementation that provides real-time folder status updates to
       concurrent IMAP clients that have the same folder opened.

     * OpenLDAP/MySQL/PostgreSQL/OpenSSL - The IMAP server can optionally use
       a database back end for authentication. The database back end can be
       either an LDAP directory, a MySQL database, or a PostgreSQL database.
       The IMAP server can also implement IMAP over SSL (STARTTLS) as well.
       Generally, to enable the optional modules it is only necessary to
       install OpenLDAP, MySQL, PostgreSQLor OpenSSL. The configuration
       script checks for presence of these libraries, and compiles the
       appropriate files. Note: these packages MUST BE installed in
       directories that are searched by your C compiler by default. Some
       installation scripts default to installing the development libraries
       and include files in custom directories. In that case it will be
       necessary to set some environment variables, before running the
       configure script, to specify additional options to the compiler that
       add the custom directories to the compiler's search path. See the FAQ
       for more information. You also need to make sure that all the
       supporting DEVELOPMENT files are installed. Most LDAP/MySQL/PostgreSQL
       packages come in two parts: the runtime support, and development
       support. You may have just the runtime support installed, you will
       need to make sure that development support files are also installed.

UPGRADING

   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.

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.

     ----------------------------------------------------------------------

   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,
   including:

     * If you do not want to create and use virtual mailboxes, you should
       remove authuserdb from AUTHMODULES. If AUTHMODULES contains
       "authdaemon", you will have another configuration file, authdaemonrc.
       Remove authuserdb from authdaemonrc instead.

     * The configuration script automatically selects whatever authentication
       modules can be used on your system, but you may not necessarily want
       to use them. For example, if your system has OpenLDAP libraries
       installed, the authldap module gets compiled and installed, even
       though you might use LDAP for some other purposes, not necessarily
       authentication. If that's the case, remove authldap from the
       AUTHMODULES entry in the imapd configuration file, or from
       authdaemonrc, whatever the case might be.

     * If you're using PAM authentication (authpam gets compiled and
       installed), you will have to tell your PAM library how to authenticate
       the "imap" service and the and "pop3" service (if you intend to use
       the bundled POP3 server too). What you need to tell your PAM library
       is something that you will have to figure out by yourself, because it
       depends on the version of your PAM library, and your operating system.

       If the directory /etc/pam.d exists, the installation script will
       automatically install /etc/pam.d/imap and /etc/pam.d/pop3, but that's
       just for starters. You will still have to inspect its contents and
       adjust the full pathname to the PAM modules, if necessary.

       Some versions of the PAM library, do not use the /etc/pam.d directory.
       Instead they use a single configuration file /etc/pam.conf. Here's an
       example of what needs to be added to /etc/pam.conf on FreeBSD 4.0.
       NOTE: other platforms may need something similar:

 imap  auth    required        pam_unix.so      try_first_pass
 imap  account required        pam_unix.so
 imap  session required        pam_permit.so
 pop3  auth    required        pam_unix.so      try_first_pass
 pop3  account required        pam_unix.so
 pop3  session required        pam_permit.so

       Your PAM library may use pam_pwdb.so instead of pam_unix.so; consult
       the documentation for your PAM library for more information.

   configure should automatically detect if you use vpopmail, and compile and
   install the authvchkpw authentication module.

   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 before installing
   Courier-IMAP. Download OpenSSL from http://www.openssl.org/. Follow the
   instruction in OpenSSL package to install it and configure it. SSL support
   in Courier-IMAP has been tested with OpenSSL 0.9.5a.

   The /usr/lib/courier-imap/lib/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.

    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.

     * --enable-unicode - 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.

     * --enable-unicode=charset,charset,... - include ability to search and
       sort messages, but only for these character sets. See below for more
       details.

     * --without-module - explicitly specify that the authentication module
       named "module" should not be installed. See below for more details.
       Example: --without-authdaemon.

     * --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-piddir=dir - use dir/imapd.pid to store couriertcpd's process
       ID.

     * --with-syslog=DEST - select syslog destination, giving one of the
       facility codes from syslog.h such as "LOCAL7". Defaults to "MAIL".

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

    Foreign character set sorting/searching

   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 unicode/charsetlist.txt.

   The default is to include only the ISO-8859-1/US-ASCII character set. Use
   the --enable-unicode option to include all available character sets.

   It is also possible to include translation tables only for selected
   character sets. Example:

   --enable-unicode=iso-8859-1,utf-8,iso-8859-10

   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.

   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. --enable-unicode should not really be much of a
   burden for most modern operating systems.

   Attentive individuals will observe that all character set tables are
   compiled even without the --enable-unicode option. That is normal -- only
   the explicitly selected character set tables will actually make it into
   the final executable.

    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.

AUTHENTICATION MODULES - GENERAL NOTES

   Courier now has extensive authentication debugging; for a guide see
   authlib/README.authdebug.html

   An authentication module does a few things besides checking if a userid
   and password are valid. It's job also includes specifying the location of
   the primary maildir, and its system user and group id.

   There are several authentication modules available. Each authentication
   module implements a different way of authenticating logins, and not all
   authentication modules can be used by everyone. Some authentication
   modules can be used only on systems that have certain libraries or
   software installed separately.

   The configure script checks if the required libraries and software are
   available for each authentication module. If the required libraries and
   support files are available, the configure script includes the
   corresponding authentication module. The option --without-module instructs
   configure not to compile an authentication module, even if it could.
   Multiple --without options are, of course, allowed (each one specifying a
   different authentication module).

     * authpwd - this module looks up userids and passwords in your
       /etc/passwd file, or the equivalent NIS map (as supported by your
       system's getpw library).

     * authshadow - this module is like authpwd, except that it should be
       used on systems that use shadow password files, /etc/shadow.

     * authpam - this module should be used on systems that have the PAM
       library. With this module, Courier-IMAP will use whatever PAM modules
       you specify for authenticating the "imap" PAM service. Essentially,
       authpam allows any PAM module to be used for authenticating logins.
       NOTE: in addition to including this module, you will have to take
       additional, site-specific, steps in order to configure your PAM
       library for the "imap" PAM service. The specific details regarding
       your PAM configuration differs from system to system, and you should
       consult your own documentation. It might be tempting to throw in a
       towel and use authshadow or authpwd if you cannot figure out how to
       install PAM support, however that is not advisable. It is highly
       recommended to use authpam wherever the PAM library is available.

       Additionally: PAM is used only for password validation. The home
       directory and the user and group IDs for the account are still taken
       from the system password file.

     * authuserdb - this module uses GDBM or DB database files, usually
       /etc/userdb.dat and /etc/userdbshadow.dat to look up userids and
       passwords. These files are GDBM or DB databases that are loosely
       equivalent in function to /etc/passwd and /etc/shadow. These databases
       are maintained indirectly by several Perl scripts - included with
       Courier-IMAP - which build these database files from a plain text
       file, usually called /etc/userdb. This file can be modified by any
       text editor, or it can be managed by some useful Perl scripts which
       are included. /etc/userdb may also be a subdirectory that has multiple
       text files in the same format, which are simply concatenated. userdb
       allows creation of virtual mail accounts that do not have a
       corresponding login account -- virtual mail accounts that can share
       the same, reserved, system userid. /etc/userdb can also be used to
       completely supersede /etc/passwd. With many accounts it can be quite a
       drain to have to continuously linearly scan /etc/passwd in order to
       look up an account. Instead, a fast database lookup can retrieve the
       same information from the database file. Read the included manual
       pages, starting with userdb(8) for more information.

     * authcram - this module is similar to authuserdb (it uses the same
       databases), but implements CRAM-MD5 authentication. See below for more
       information.

     * authvchkpw - this is another virtual mail database lookup module,
       except that it uses the vpopmail vpasswd files. This module is
       provided for a quick way to use your existing vpopmail vpasswd files.
       Where possible, you should convert over to /etc/userdb. The included
       script vchkpw2userdb(8) might be of some help in doing so.

     * authldap - authenticates against an LDAP server. This is a new module
       included with Courier-IMAP. See below for more information.

     * authmysql - native MySQL authentication module Read
       authlib/README.authmysql for information on how to set up this module.

     * authpgsql - native PostgreSQL authentication module PostgreSQL
       configuration is nearly identical to MySQL information, see
       authlib/README.authpostgres.html for more information.

     * authdaemon - background daemon authentication proxy. See below for
       more information.

     * authcustom - this is a dummy authentication module that dose not
       authenticate anything. It is a placeholder that can be used to
       implement any site-specific authentication code, written in C. To
       implement some site-specific authentication, inspect the contents of
       the authlib/preauthcustom.c file for additional instructions.

   It is possible to include more than one authentication module. For
   example, if you select both authuserdb and authpam, each login will first
   be authenticated against /etc/userdb. If Courier-IMAP cannot find the
   account in /etc/userdb, it will then attempt to authenticate using the PAM
   library.

   configure uses the following logic to determine which authentication
   modules will be included by default:

     * authuserdb/authcram - these modules are always included by default

     * authpam - configure attempts to detect if the PAM library is
       installed, or not. --without-authpam can be used to avoid installing
       authpam on systems that do have a PAM library installed. Hopefully,
       you will have a good reason to do something this silly.

     * authldap - configure checks if OpenLDAP is installed. If OpenLDAP
       development libraries are available, authldap will be compiled and
       installed.

     * authpwd , authshadow - whether or not these modules are installed by
       default depends upon what happened with authpam and authldap. If PAM
       or LDAP support is installed, via authpam or authldap, these two
       modules are usually not necessary, because the PAM library, or the
       LDAP server, provides this functionality. If PAM support is
       unavailable, these modules will be installed by default.

     * authvchkpw - this module is compiled by default only if the vpopmail
       account is defined.

     * authmysql - this module is compiled if MySQL client libraries are
       available.

     * authpgsql - this module is compiled if PostgreSQL client libraries are
       available.

     * authdaemon - this module is always compiled by default. See below for
       more information.

Confirming selected authentication options

   You can find out what authentication modules were actually used, but you
   must first run make successfully. Running make compiles the authinfo
   program in the authlib subdirectory. This program tells you what
   authentication modules were compiled.

USERDB AUTHENTICATION MODULE

   userdb is a way to implement many virtual mailboxes - many mailboxes that
   do not have to have a separate system userid allocated for each one, and
   there is no system login associated with each mailbox. userdb uses a
   database for mapping virtual addresses to physical maildirs. It should be
   scalable to thousands of mailboxes. It can also be used to replace linear
   searches of /etc/passwd with a database lookup, see pw2userdb(8).

   Note - you still MUST use some valid system userid and groupid that is
   shared by all virtual mailboxes. Instead of allocating a single userid and
   groupid per each mailbox, the same userid and groupid is used for all of
   them.

   This is a rough overview of using userdb. For additional information, read
   makeuserdb(8), and userdb(8). All the scripts will be installed in
   /usr/lib/courier-imap, so look for them there.

   Courier-IMAP can use the userdb database simply by the virtue of
   installing the authuserdbauthentication module, which happens by default.
   The tricky part is creating the database. Hopefully, it's only tricky
   once, and the second time it won't be so tricky any more. The userdb
   configuration is extremely flexible, and there are many ways of actually
   setting up the database.

   The best way to describe how userdb works is to try to create one virtual
   mail account. As mentioned before, virtual mailboxes still need one system
   account to be used for uid/gid purposes. Let's call this system account
   "vmail".

  Simple userdb setup.

   This approach should be used if you do not have many virtual mailboxes.
   It's very simple, but quickly becomes cumbersome if you administer many
   virtual mailboxes.

   Create an empty /etc/userdb.

  
 # cp /dev/null /etc/userdb
 # chmod 700 /etc/userdb

   /etc/userdb must have 700 permissions.

   Now, run the script pw2userdb. This script converts the contents of your
   /etc/passwd to the /etc/userdb format (including the contents of
   /etc/shadow, this is why permissions on /etc/userdb must be 700). This
   script is usually used where you want to convert a very large /etc/passwd
   to /etc/userdb. userdb applications can now use a fast userdb database
   instead of a linear scan of /etc/passwd in order to look up system
   accounts. However, you probably don't want to do use this feature right
   now, so what you simply want to do is take the output of pw2userdb, and
   find the entry for the vmail account that you created earlier. Look for a
   line that starts with 'vmail' followed by tab, followed by familiar fields
   from /etc/passwd. Save the output of pw2userdb in a temporary file, edit
   it, and remove everything except the line containing vmail, and the very
   next line, which is a special entry that maps vmail's userid back to the
   vmail record.

   Here's what you might find in the output of pw2userdb:

  
 vmail   uid=1012|gid=1012|home=/home/vmail|systempw=*
 1012=   vmail

   The actual numerical values and the home directory location may vary. Save
   these two lines as /etc/userdb, and set the permissions on /etc/userdb to
   700:

  
 $ chmod 700 /etc/userdb

   Now, with that out of the way, let's really create a virtual account. In
   this example we'll create a virtual mailbox for 'john@example.com'.

  
 # su vmail
 $ cd $HOME
 $ maildirmake Maildir-john-example
 $ exit
 #

   You may need to specify a full path to your maildirmake program. The end
   result is that you created $HOME/Maildir-john-example in vmail's account.

   The next step is to configure your mail server to deliver mail for
   john@example.com directly into the maildir ~vmail/Maildir-john-example.
   How that's done depends on the mail server that you use.

   Now, let's connect the dots here, and create an entry in /etc/userdb for
   john@example.com:

  
 # userdb "john@example.com" set home=/home/vmail \
                                 mail=/home/vmail/Maildir-john-example \
                                 uid=UUU gid=GGG

   This command runs a Perl script named userdb , which is installed, by
   default in /usr/lib/courier-imap/sbin. Replace UUU and GGG with the userid
   and groupid of the vmail account. If you now look in /etc/userdb, you will
   see that a new record for john@example.com has been appended to the end of
   the file.

   We're not finished yet. We need to set the IMAP password for this mailbox:

  
 # userdbpw | userdb "john@example.com" set imappw

   If you are running Red Hat Linux 6.0, or higher, you can specify the -md5
   option to userdbpw, in order to use an MD5 password hash, instead of
   crypt. Specify "systempw" instead of "imappw" if you would like to use the
   same password for the POP3 server too. The imappw field is only checked by
   the IMAP server. If not defined, systempw is used instead. The field
   pop3pw will be checked by the POP3 server that's bundled with
   Courier-IMAP. If it is not defined the POP3 server will check systempw too

   Finally, compile the database:

  
 # makeuserdb

   This command creates the actual database, /etc/userdb.dat and
   /etc/userdbshadow.dat from the plain text file /etc/userdb. Courier-IMAP
   will now start accepting logins to this mailbox. Adding and removing
   mailboxes can be done while Courier-IMAP is running.

   Courier-IMAP reads /etc/userdb.dat and /etc/userdbshadow.dat only. The
   plain text source, /etc/userdb is not read by Courier-IMAP itself. Changes
   take effect only when makeuserdb runs.

  Large virtual domain farm.

   The previous approach uses a single flat file, /etc/userdb. This might be
   a bit cumbersome if you have thousands of virtual mailboxes in many
   domains. Here's an alternative approach that can scale to thousands of
   domains and mailboxes.

   Instead of creating a /etc/userdb file, create a subdirectory:

  
 # mkdir /etc/userdb
 # chmod 700 /etc/userdb

   Now, create /etc/userdb/default, containing pw2userdb's output for the
   vmail account, as previously described.

   This time, you probably want to create all mailboxes for the same domain
   in a separate subdirectory:

  
 # su vmail
 $ cd $HOME
 $ mkdir -p domains/example-com
 $ maildirmake domains/example-com/john
 $ exit

   The idea is that all the maildirs for @example.com will be stored in
   ~vmail/domains/example-com. All maildirs for domain.org will be stored in
   ~vmail/domains/domain.org. The actual layout and naming conventions are
   entirely up to you to define.

   Now, configure your mail server to deliver mail for john@example.com into
   this maildir.

   Here's how configure /etc/userdb.

  
 $ userdb "example-com/john@example.com" set home=/home/vmail \
                                 mail=/home/vmail/domains/example-com/john \
                                 uid=UUU gid=GGG

   This creates the file /etc/userdb/example-com (the first parameter to the
   userdb command), and appends a record named "john@example.com". You will
   store all userdb entries for @example.com in the file
   /etc/userdb/example-com. All entries for @domain.org will be maintained in
   /etc/userdb/domain-org, and so on.

  
 $ userdbpw | userdb "example-com/john@example.com" set imappw

   This sets the IMAP access password for this account. Finally:

  
 $ makeuserdb

VCHKPW AUTHENTICATION MODULE

   This authentication module is provided for legacy support. New installs
   should use the authuserdb module. It is possible to convert
   vpopmail/vchkpw single userid authentication passwd files to /etc/userdb
   using the vchkpw2userdb script. See vchkpw2userdb(8) for more information.

LDAP AUTHENTICATION MODULE

   This module attempts to authenticate against an LDAP server. This option
   installs a sample configuration file, which is
   /usr/lib/courier-imap/etc/authldaprc by default. You will need to edit
   this file in order to configure LDAP authentication. This configuration
   file defines the location of your LDAP server, as well as the names of
   attributes used to perform LDAP authentication. See the comments in the
   sample configuration file, and the authldap(7) manual page, for more
   information.

DAEMON AUTHENTICATION MODULE

   Selecting the authdaemon module (it is selected by default) will compile
   and install a separate process, called "authdaemond". The "authdaemond"
   process is started and stopped by the imapd.rc, imapd-ssl.rc, pop3d.rc and
   pop3d-ssl.rc. ATTENTION: all four scripts stop authdaemond. Typically all
   the scripts are called together, at system startup and shutdown. If you
   need to stop just ONE service, find the pid and kill it manually.
   Otherwise authdaemond stops and nobody can log in anymore.

   The authdaemon module (and the authdaemond process that goes with it) is
   very useful when a database is used as an authentication back-end (like
   MySQL, PostgreSQL, or OpenLDAP). The authdaemon module offers an
   alternative to compiling all the authentication code as standalone
   modules. Enabling authdaemon in addition to any other modules will result
   in authdaemon being built as the only "official" authentication module.
   All other modules are compiled into a separate process, "authdaemond".

   Certain authentication modules -- such as authldap, authpgsql and
   authmysql -- connect to an external database in order to validate an
   authentication request. The database connection is created and destroyed
   for every login request, and with a large number of connections and
   authentications it is better to have a single daemon process running in a
   background, with a semi-permanent connection to the database, handling
   authentication requests. That's exactly what authdaemond does.

   The authdaemon authentication module takes an authentication request, and
   forwards it to the permanently running authdaemond process, waits for the
   answer, and returns the result to the application. Courier-IMAP, by the
   virtue of its modular design, "sees" only the authdaemon authentication
   module. Behind the scenes, authdaemon takes every authentication request
   and passes it along to the authdaemond for processing, where all the real
   authentication happens.

   The /usr/lib/courier-imap/etc/authdaemonrc configuration file sets several
   parameters for the authdaemond process. See the comments in this file for
   more information. Currently, authdaemonrc sets two parameters: number of
   daemon processes, and which available authentication modules are used.

   Although authdaemond might be built with several authentication modules,
   not all of them must be used. This allows for a single authdaemond binary
   to be made that gets installed on multiple systems with different
   authentication needs. The default module list specified in authdaemonrc is
   a list of all the available authentication modules.

   All available authentication modules are compiled by default. Although it
   is possible to disable unwanted authentication modules via the configure
   script, it is better to disable them at runtime. The list of all active
   authentication modules is read from the authdaemonrc configuration file.
   Removing an authentication module from this configuration file disables
   it.

   The number of authdaemond processes is also set in this configuration
   file. The more processes that are started, the more authentication
   requests can be handled. If authdaemon does not receive an answer within
   some amount of time, it will assume an authentication failure, and abort.
   Try increasing the number of processes if you start seeing random
   authentication failures. However, that should only be used as a stop-gap
   measure. If the default number of authdaemond processes proves to be
   insufficient, it is far more likely that more resources are needed for the
   server (more RAM, a faster disk, or a faster CPU) in the humble opinion of
   the author. Increasing the number of processes should only be used as a
   stop-gap measure, until a more thorough analysis of the system
   performance.

   After making any changes to authdaemonrc, run the following command for
   these changes to take effect:

     /usr/lib/courier-imap/libexec/authlib/authdaemond restart

  Alternative authdaemond modules

   /usr/lib/courier-imap/libexec/authlib/authdaemond is actually a script.
   Depending on your system configuration, there may be one or more different
   authdaemond binaries installed, and here's why.

   authdaemond.plain will include all available authentication modules except
   for certain "heavy" authentication modules. The current list of "heavy"
   authentication modules is authldap, authpgsql, and authmysql.

   If support for a "heavy" authentication module is selected, there will be
   an additional binary installed, such as authdaemond.mysql,
   authdaemond.pgsql or authdaemond.ldap. The
   /usr/lib/courier-imap/libexec/authlib/authdaemond script checks if any
   "heavy" authentication daemon is installed, and, if so, runs that.
   Otherwise, the default authdaemond.plain binary goes in.

   This allows an easy way to create binary Courier-IMAP distributions with
   and without LDAP, MySQL, or PostgreSQL support. The distributor would
   simply build Courier-IMAP on a machine that contains both
   LDAP/MySQL/PostgreSQL development libraries, then take everything but
   authdaemond.mysql, authdaemond.pgsql and authdaemond.ldap and roll it into
   the base Courier-IMAP package. authdaemond.mysql, authdaemond.pgsql, and
   authdaemond.ldap are rolled into separate sub-packages. Loading a base
   package installs basic system authentication services. Adding LDAP, MySQL,
   or PostgreSQL support is as simple as loading the corresponding
   sub-package.

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.

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.

REALTIME FOLDER STATUS UPDATES

   If the FAM, the File Alteration Monitor (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.

Account OPTIONS

   It is possible to adjust certain parameters on an account-by-account
   basis. This feature is only available with userdb, LDAP, MySQL, and
   PostgresSQL authentication. Individual account options are not supported
   with system-based authentication modules (password/shadow files, or PAM).

     NOTE

     This account option implementation is used by Courier, Courier-IMAP, and
     SqWebMail. Some of the following information may not be applicable. The
     inapplicable bits should be obvious.

   Account options have a single, uniform implementation by all supported
   authentication methods. To summarize, account options are listed as a
   single text string: a comma-separated list of "OPTION=value" settings. At
   this point, the following options may be used:

   disableimap=n

           If "n" is 1, disable IMAP access to this account, without
           affecting POP3 and webmail access.

   disablepop3=n

           If "n" is 1, disable POP3 access to this account, without
           affecting IMAP and webmail access.

   disablewebmail=n

           If "n" is 1, disable webmail access to this account, without
           affecting IMAP and POP3 access.

   sharedgroup=name

           Append "name" to the name of the top level virtual shared folder
           index file. This setting restricts which virtual shard folders
           this account could possibly access (and that's on top of whatever
           else the access control lists say). See the virtual shared folder
           documentation for more information.

           For technical reasons, group names may not include commas or "|"
           characters.

   Account options are specified via the authentication modules in the
   following manner:

   userdb

           Use the userdb command to set a field called "options". Example:

 userdb user1@example.com set options=disableimap=1,sharedgroup=44
 makeuserdb

           The option text string here is "disableimap=1,sharedgroup=44". It
           specifies two options.

   LDAP

           Account options are defined by the LDAP_AUXOPTIONS setting in the
           authldaprc configuration file. LDAP_AUXOPTIONS consists of a
           comma-separated list of "attribute=setting". "attribute" is the
           name of an LDAP attribute, and "setting" is the corresponding
           account setting name. The value of the attribute becomes the value
           of the setting. Unless you value your sanity, the names of LDAP
           attributes should be the same as the actual setting names (in
           which case "=setting" may be dropped and LDAP_AUXOPTIONS becomes a
           simple comma-separated list of supported settings), but they don't
           have to be.

           LDAP_AUXOPTIONS is nothing more than a simple mapping of LDAP
           attributes to account settings. A LDAP_AUXOPTIONS of
           "shared=sharedgroup,disableimap" means that the LDAP attribute
           called "shared" contains the "sharedgroup" setting, as described
           previously; and an LDAP attribute of disableimap contains the
           setting of the same name.

   MySQL, and PostgreSQL

           Account options are defined by MYSQL_AUXOPTIONS_FIELD or
           POSTGRESQL_AUXOPTIONS_FIELD, in its corresponding configuration
           file. In the most simplest case, add a character field to the
           database, and put the field name into the MYSQL_AUXOPTIONS_FIELD
           or POSTGRESQL_AUXOPTIONS_FIELD configuration file setting. For
           each account, the character field should contain the literal
           option string. Yes, you'll just put
           "shared=sharedgroup,disableimap" literally, in that field.

           Fortunately, there is a cleaner way to do this, which avoid
           driving a database designer batty. Keep in mind that the contents
           of MYSQL_AUXOPTIONS_FIELD/POSTGRESQL_AUXOPTIONS_FIELD are simply
           inserted directly into the SQL query that fetches the account
           information. Both MySQL and PostgreSQL have a rich SQL that can be
           used to manufacture a suitable option string from plain,
           garden-variety, database fields. That is, you may define
           individual table fields like "disableimap", and "disablepop3",
           then provide a suitable (albeit ugly) SQL fragment that combines
           them together into the expected option string. An example of such
           an SQL string is provided in the comments portion of the
           configuration file.

             NOTE

             When using the alternative custom query option, the option
             string is the last field that the custom SQL query should
             return.

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.
