
                                 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
     * Using shared folders
     * CRAM-MD5 Authentication
       
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.
     * OpenLDAP/MySQL/OpenSSL - The IMAP server can optionally use a
       database back end for authentication. The database back end can be
       either an LDAP directory or a MySQL 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, or 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.

UPGRADING

   If you are upgrading from a previous install of Courier-IMAP you
   should back up the contents of your configuration directory before
   starting the upgrade. The default configuration directory is
   /usr/lib/courier-imap/etc. The installation procedure installs a fresh
   set of default configuration files, overwriting the existing ones.

   New releases usually introduce additional options and features that
   must be configured. Keeping old configuration files in place means
   that it's very likely that things will not work after an upgrade,
   because some required option has not been set. The safest approach is
   to always install a fresh set of default configuration files, each
   time. Then use your backed up configuration directory to reset your
   required configuration.

   The recommended upgrade procedure is as follows:
     * Back up /usr/lib/courier-imap/etc
     * Follow the installation procedures, below
     * Reset your local configuration, based on the contents of backed up
       configuration files

   All configuration files are kept in the configuration directory.
   Nothing else in /usr/lib/courier-imap is configurable.

  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

     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.

   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.

   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
   /usr/lib/courier-imap/etc/*.config 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 imapd.config, 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.config 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/pop3d.configand
   /usr/lib/courier-imap/etc/pop3d-ssl.config.

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

    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

   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 authpwd. Beta -
       read authlib/README.authmysql for information on how to set up
       this module.
     * 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 (OpenLDAP 2.0
       is not yet supported, OpenLDAP 1.2.11 is required). 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.

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 authuserdb authentication 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(8)
   manual page, for more information.

DAEMON AUTHENTICATION MODULE

   Selecting the authdaemon module 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 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 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.

   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 and authmysql.

   If support for a "heavy" authentication module is selected, there will
   be an additional binary installed, such as authdaemond.mysql 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 or MySQL support. The distributor would simply
   build Courier-IMAP on a machine that contains both LDAP and MySQL
   development libraries, then take everything but authdaemond.mysql and
   authdaemond.ldap and roll it into the base Courier-IMAP package.
   authdaemond.mysql and authdaemond.ldap are rolled into separate
   sub-packages. Loading a base package installs basic system
   authentication services. Adding LDAP or MySQL support is as simple as
   loading the corresponding sub-package.

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 and authmysql support
   CRAM-MD5 authentication if the LDAP or the MySQL 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 and
       authmysql, as long as clear-text passwords are used. See below for
       more information. Therefore, if you use LDAP 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
   imapd.config and add the "AUTH=CRAM-MD5" keyword to the
   IMAP_CAPABILITY environment variable, then restart Courier-IMAP. There
   are instructions in imapd.config 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.config and remove authcram from the AUTHMODULES
   setting.
