
                                 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.
     * NOTE: Courier-IMAP currently does not compile under gcc 3.0
     * make -  Th e GN U ma ke is  re commended. So laris'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/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

   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-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. Read
       authlib/README.authmysql  for  information  on  how to set up this
       module.
     * authpgsql - native MySQL authentication module authpwd. This is an
       experimental  beta  module. It is set up mostly in the same way as
       the MySQL module, so you should review README.authmysql as well.
     * 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  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  (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.

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.
