
   NOTE:  a  more  readable  HTML version of this INSTALL document can be
   found in courier/doc/install.html.

                                 Installation

   Read  this  document in its entirety before entering a single command.
   Installing  Courier for the first time will take a while. If possible,
   consider  looking  around  for anyone who has already packaged Courier
   for your operating system, and save yourself the hassle.

   Fortunately, it gets easier with each subsequent installation. Courier
   is a complicated piece of software. Most problems people will have are
   likely  to  be  with  the  configuring  and  installing  it correctly.
   Designing  complex  software  that  compiles  and  installs  on a wide
   variety of POSIX systems is not a trivial task.

   Courier's  configuration and installation scripts are very flexible in
   setting  up  installation  directories for each logical set of files -
   configuration  files,  binaries, scripts, the mail queue, and more. If
   you  begin by installing someone else's package, instead of installing
   everything  yourself,  you  should take careful notes where things are
   installed.  If  you  later  decide  to roll your own package, you will
   either  need to use a COMPLETELY IDENTICAL configuration, or take care
   to  back  up  your  old  configuration,  and then restore it after the
   upgrade. The following documentation refers to the default location of
   various  configuration  files (and other files as well). If you choose
   to  install  some files in a non-default location (either by yourself,
   or  by  using someone else's package), you will need to take this into
   account while reading the following documentation.

   This  cannot be emphasized enough: the configuration defaults are very
   generic;  the  goal is to have the default configuration settings work
   for  almost  everyone.  In  every  case  using  at  least  a couple of
   non-default  parameters  will make Courier work better on your system.
   You  should anticipate going through several trial-and-error installs,
   tweaking  the  options  to  see what works better for you. Even my own
   pre-configured RPM package uses a number of non-default parameters.

   NOTE: older versions of the linuxconf configuration tool are hardwired
   for  sendmail.  They  like  to  change  the permission of the sendmail
   wrapper  to  match the permissions they think the real sendmail should
   have.  Older  versions of linuxconf also have a tendency to create the
   /var/spool/mqueue directory, even if sendmail is not installed.

Table Of Contents

   The  following table of contents might look intimidating at first, but
   some  sections  are marked "optional". These sections are not required
   for a basic installation as a simple ESMTP server.
     * Upgrading an existing installation
     * Overview
     * Preparing for installation
     * Run configure
     * Authentication modules
     * Confirming selected authentication options
     * IPv6
     * Compile and run make check
     * Installation
     * Install configuration files
     * Adjust system paranoia level
     * Post-installation setup
     * Post-installation checks
     * OPTIONAL: Configure webadmin
     * Create system aliases
     * Create smtp access list
     * Miscellaneous configuration
     * Define local domains
     * OPTIONAL: Configure UUCP
     * OPTIONAL: Configure LDAP aliasing
     * OPTIONAL: Configure filtering
     * Create a list of domains to accept mail for
     * Starting and stopping Courier
     * Run Courier in parallel to your mail server
     * OPTIONAL: Configure ESMTP authentication and SSL
     * OPTIONAL: Configure the SECURITY ESMTP extension
     * OPTIONAL: Configure the IMAP server
     * OPTIONAL: Configure IMAP over SSL
     * OPTIONAL: Sending mail via an IMAP connection
     * OPTIONAL: Configure the POP3 server
     * OPTIONAL: Configure POP3 over SSL
     * OPTIONAL: Configure the webmail server
     * OPTIONAL: Configure webmail calendaring
     * OPTIONAL: Configure mail filtering for the webmail server
     * OPTIONAL: Changing mail account passwords using the webmail server
     * OPTIONAL: Configure autoreplies for the webmail server
     * OPTIONAL: Configure encryption for the webmail server
     * OPTIONAL: Quota support
     * OPTIONAL: Configure outbound faxing
     * OPTIONAL: Configure inbound faxing
     * Decommission your existing mail server
     * Sample init script

Upgrading an existing installation

  Upgrading from Courier 0.34.1 or earlier.

   Version  0.35  introduced  the ability to update system passwords from
   the  webmail  server.  If  you are using the authuserdb authentication
   module, rerun the makeuserdb script after upgrading to 0.35 or later.

   Prior  to  0.35,  the  default  configuration  of  the  webmail server
   maintained  a  separate  webmail password file. The webmail server did
   not  have the logic to update system login passwords, the approach was
   to  copy system login passwords into a webmail password file. Changing
   the  webmail  password  involved  simply updating the webmail password
   file, and life was good.

   In  0.35, logic was added to update the real system password file, and
   the  eliminate  the webmail password file. After upgrading in 0.35, it
   will  probably  be  necessary  to  reset all mail account passwords on
   existing  accounts,  since the webmail password file is not being used
   any  more,  and  most  people  have  probably  changed  their  webmail
   passwords.

   As the result of the password change, the default configuration script
   will  now  always  build  the  authdaemond  authentication  module  by
   default.  Previously, authdaemond was built by default only if LDAP or
   MySQL support was necessary.

  Upgrading from Courier 0.29.1 or earlier.

   Version  0.30  changed the format of most configuration files. The new
   configuration   file   format   allows   configuration   files  to  be
   automatically  upgraded.  The  automatic upgrade feature requires that
   both  the old and the new installation have preformatted configuration
   files.  Therefore,  when upgrading from version 0.29.1 or earlier, use
   the following procedure to upgrade the existing configuration files.

   All   configuration   files  are  installed  in  the  same  directory,
   "sysconfdir".  sysconfdir  is  a  configurable parameter, it's usually
   /usr/lib/courier/etc. sysconfdir is /etc/courier in the RPM version of
   Courier.

    Back up your existing sysconfdir

   Make  a  backup  copy  of your current sysconfdir, then delete the old
   version  of Courier. "rm -rf /usr/lib/courier" will do nicely. All the
   possible  configurable settings are in sysconfdir, everything else can
   simply go.

    Install the new version

   Follow  the  installation procedure in the next section (including the
   make  install-configure).  The  following  configuration files are now
   preformatted for automatic installation:
   ldapaddressbook
   esmtpd
   esmtpd-msa
   courierd
   pop3d
   pop3d-ssl
   imapd
   imapd-ssl
   ldapaliasrc
   authldaprc
   authmysqlrc
   authpgsqlrc
   authdaemonrc

   NOTE:  depending  upon  your  configuration, you may not actually have
   every  one  of  these files installed, so just disregard the ones that
   are  not  present.  Manually  edit  filename,  and  retype  any custom
   modifications  from the backup copy of the configuration file. This is
   a  hassle,  but it only needs to be done once. Future upgrades will be
   99% automatic.

   Any  custom  configuration  changes  are  generally  confined to these
   configuration  files  only.  Very rarely are any configuration changes
   made  to  the  remaining  configuration  files. If necessary, they can
   simply  be  restored  from  the backup copy made in the previous step.
   Something  to  keep in mind is that future versions may add additional
   complexity  to  other  configuration  files,  resulting  in additional
   configuration files being reformatted for automatic upgrading.

Overview

   You  will  need the following software in order to compile and install
   Courier:
    1. A C++ compiler
       Courier  is  primarily  developed  and  built  with gcc. Other C++
       compiler  may  or may not work. Solaris's C++ compiler is reported
       to work without any problems. There are some issues with AIX's xlC
       compiler, which mostly has to do with the C++ libraries and header
       files.  IBM  has released a GNU/Linux development toolkit for AIX,
       which may help in getting Courier to compile.
    2. NOTE: At this time, Courier cannot be compiled by gcc 3.0
    3. GNU make
       On the BSD platform family GNU make is usually installed as gmake.
       Simply  replace 'make' with 'gmake' in the following instructions.
       GNU make is REQUIRED. Use anything else at your own risk.
    4. Perl 5
       A recent version of Perl needs to be installed.
    5. expect
       The  expect  utility  is used by the webmail server to control the
       passwd  command in order to change mail login passwords. expect is
       a  part  of most operating systems. If you do not have it, you can
       download  it  from  http://expect.nist.gov/. You do not need it if
       you  will  not  be  using  the  webmail  server, or if you will be
       creating virtual (non-system) mail accounts.
    6. GDBM or Berkeley DB library
       Either library must be installed.
    7. OpenSSL
       Support for SSL/TLS requires OpenSSL. If OpenSSL is not installed,
       SSL/TLS features are disabled.
    8. OpenLDAP
       Support  for  LDAP  directory  services  requires  OpenLDAP client
       libraries  to  be  installed.  If  OpenLDAP  is not installed LDAP
       directory  features are disabled. Sometimes there's some confusion
       when  commercial  LDAP servers are used, which come with their own
       development  toolkits,  which  use  a different API than OpenLDAP.
       Even if a commercial LDAP server is used to provide LDAP services,
       OpenLDAP  is  still  required  to enable LDAP services in Courier.
       Also, note that you need OpenLDAP development libraries and files.
       On most systems, the development files are packaged separately, in
       addition  to  the  runtime  OpenLDAP libraries. Make sure that you
       have  not  just  the runtime OpenLDAP libraries installed, but the
       development libraries as well.
    9. MySQL/PostgreSQL
       Support  for  MySQL  and PostgreSQL-based authentication requires,
       obviously,   MySQL/PostgreSQL   development   libraries.   Note  -
       MySQL/PostgreSQL  runtime support files is not sufficient to build
       Courier - you must also install MySQL/PostgreSQL development files
       and libraries (which may not be installed by default).
   10. mgetty+sendfax,  groff  or  troff  (not  tested), ghostscript, and
       NetPBM
       This  optional  software  is  required to send E-mail messages via
       fax.  Courier  will compile and install without this software, but
       you will not be able to send faxes. All packages must be installed
       prior  to  installing Courier, and binaries from all packages must
       be   installed  in  the  default  PATH  before  running  Courier's
       configure script.
       mgetty+sendfax, ghostscript, and groff, are required for basic fax
       support,  which  supports  faxing  of  plain text, Postscript, and
       PDF-formatted  content. It's probably possible to use the original
       UNIX  troff  instead  of  groff,  but  this  has  not been tested.
       Installing  NetPBM  adds  the  ability  to  fax GIF, JPEG, and PNG
       images.

   The  typical  sequence  of  commands to install Courier is as follows.
   Read the following section before running these commands:
   ./configure [options]
   make
   make check       # Optional -- see below
   make install
   make install-configure

   These  commands  are  described  in  greater  detail  in the following
   sections.
     _________________________________________________________________

     If  you're using gmake (the make on GNU/Linux, and gmake everywhere
     else), and you are compiling Courier on a workstation with multiple
     CPUs and plenty of memory, set the following environment variable:
   MAKEFLAGS="-j 4"; export MAKEFLAGS         # Bourne or Korn shell

     or:
   setenv MAKEFLAGS="-j 4"                    # The C shell

     This  must  be done before running the configure script. This works
     only with gmake.
     _________________________________________________________________

     Courier  will  not  work on a Linux kernel that's been patched with
     the  Openwall  security  patch  in  its  default configuration. The
     current version of the Openwall patch has a non-default option that
     turns  off the portion of the Openwall patch which prevents Courier
     from running.

     NOTE: Linux-Mandrake includes the Openwall patch in the alternative
     "secure"  kernel  package.  Courier  will not run on Linux-Mandrake
     under the alternative "secure" kernel. This package must be removed
     and the standard kernel package must be installed.
     _________________________________________________________________

Preparing for installation

   The  first  step  consists  of  gathering  some information about your
   existing mail system. Before proceeding, you will need to identify and
   resolve the following issues:
     * Maildirs or mailbox files

   Courier can be used as a simple mail relay -- which does not store any
   mail  locally  but  is  merely a gateway between internal and external
   mail  systems.  Courier can also be used as a traditional mail server,
   accepting  and  storing  messages  in  individual  mailboxes  that are
   accessible via POP3, IMAP, or webmail.

   Courier  defaults  to  storing  mail in maildirs, not traditional flat
   file  mailbox files. Maildirs require less I/O and CPU resources; they
   do  not  use  locking;  and  multiple  clients can read and write from
   maildirs  simultaneously.  Maildirs  scale  very  well to servers with
   multiple  CPUs.  Some benchmark numbers on maildirs are available from
   http://www.courier-mta.org/mbox-vs-maildir/.

   Additionally,   Courier's  integrated  POP3,  IMAP,  and  HTTP/webmail
   servers  support  maildir  mailboxes only. They do not support mailbox
   files.

   If  you have an existing mail server in service, chances are that your
   current  mail  server  delivers  mail  to  mailbox  files.  You should
   consider  migrating  and converting to maildirs, but this will require
   that you also upgrade your POP3 server, your IMAP server, and all your
   other  mail  clients  to software that supports maildirs. Fortunately,
   Courier already includes a fully integrated POP3 and IMAP server.

   Still,  if  circumstances  absolutely  require  for  you to stick with
   mailbox   files,   Courier   has  limited  compatibility  support  for
   delivering mail to mailbox files, but you have more homework to do:
     * What locking mechanism is used on mailbox files

   If you decide to stick with mailbox files, you must know - of course -
   where  your mailboxes are located, and what locking mechanism is being
   used  by  your  mail  software.  Mailbox  files  require  some form of
   locking,  because  only one application can access the mailbox file at
   the   same   time.  Unfortunately,  different  operating  systems  use
   different   locking   methods.  There  are  several  possible  locking
   strategies  that  can  be used: so-called "dot-locks", or one of three
   possible  kinds  of  file  locking calls. You will need to consult the
   documentation  for  your  existing  mail  software  to  determine what
   locking mechanisms you should use.

   In  most  cases,  mailbox  files  are located in a separate partition,
   usually  the  directory  /var/spool/mail.  In  some instances, mailbox
   files  may  be  kept in the home directory of each individual account,
   and  the  mail  is  delivered to either $HOME/Mailbox, or $HOME/INBOX.
   Again, you will have to figure this out by yourself.

   Courier  can deliver mail to mailbox files only if the default mailbox
   file  is  in the home directory of each individual account, and if you
   use file locking. Courier does not support dot-locks, and Courier does
   not support a separate mail directory for mailbox files. Mailbox files
   must be located in the home directory of each individual account.

   Courier  can  use  a  recipient  database  (userdb) that can specify a
   non-default  location  for  a  recipient's  mailbox.  In theory, it is
   possible   to   point  each  account  to  its  individual  mailbox  in
   /var/spool/mail,  or  somewhere  else.  However, that's a tedious task
   that  must  be  done  manually for each account, and is likely to be a
   major maintenance issue.

   A better solution is to use a separate local mail delivery agent. Your
   existing  mail  system is very likely to include a separate local mail
   delivery  agent.  If  you  already  use  a mail delivery agent such as
   procmail,  you probably already have it set to use the correct locking
   mechanism  for  mailbox  files, and it already knows where the mailbox
   files  are.  Courier  will  be  happy  to  hand  off all local mail to
   procmail, or anything else for the actual delivery.

   Courier  source distribution includes the maildrop mail delivery agent
   which  has  some  additional file locking options, however you'll have
   less  problems if you stick with procmail in the beginning, and switch
   to  maildrop  after  you've  gained  some  experience  configuring and
   installing Courier.
     * Create the courier user and group IDs

   You  should  create  a  new userid and groupid named "courier". That's
   optional,  but  highly  recommended. If this is not done, Courier will
   install  as  user/group daemon (or some other suitable user/group id).
   Only  two of Courier's daemon processes run as a superuser (and one of
   them  is  perpetually  waiting  for  a non-superuser daemon process to
   terminate,  in  order  to  restart  it).  Everything  else  runs  as a
   non-superuser process. Ideally, you should reserve a separate user and
   group  ID  for Courier's use only, so a compromised mail system cannot
   be  used to compromise the rest of the system. If push comes to shove,
   you  can  set up Courier to use a well-defined existing user and group
   ID, such as daemon.
     * Define the installation directory

   Courier,  by default, installs in /usr/lib/courier. Everything goes in
   there:  binaries,  scripts, configuration files, and manual pages. You
   will  have  to  configure your man command to look for manual pages in
   /usr/lib/courier/man   by   adding   this  directory  to  the  MANPATH
   environment  variable.  You will also need to add /usr/lib/courier/bin
   and  /usr/lib/courier/sbin  (for  the  root  user only) to the default
   PATH.  The  Courier  RPM  package installs a script that automatically
   implements that.

   Note  that  this  installation  layout  is  nothing  more than a basic
   default,  chosen  because  this simple arrangement works for everyone.
   The  installation  layout can be easily changed. For example, binaries
   can  go  to /usr/local/bin, and configuration files to /usr/local/etc.
   But  keep  in mind that Courier consists of several hundred individual
   files (at the last count), so if you install Courier somewhere else it
   might  be  very cumbersome to keep track of where everything went, and
   it will lead to almost guaranteed problems later, when you upgrade.

   You should try to use some kind of a packaging system in order to keep
   track  of  your  Courier  installation.  Once  you  choose a packaging
   system, you should stick to it. If you switch to a different packaging
   system  you  should take extreme care to remove your previous package,
   and  install your new package. Extreme configuration flexibility means
   that  different  packages  will  install in different places, and even
   have different file ownerships!

   For example, Courier's source code tarball can be built by RPM version
   3.0.3  or  higher,  into  a binary RPM package. The binary RPM package
   installs  configuration  files  in  /etc/courier,  the  mail  queue in
   /var/spool/courier,  and  everything  else in /usr/lib/courier. If you
   install my package, and later decide to either create your own package
   or  use  someone  else's,  you  will have to make sure to use the same
   settings,  or remove my package completely, before installing your new
   package.  I  mean  it  when I say "remove my package completely". That
   includes  the  mail queue containing any unsent messages. Courier will
   not  function  if you reinstall it using a different user/group ID, or
   if you use a different value for any other option.
     * Conclusion

   Once  these  issues  are  squared away, you are ready to configure and
   install Courier.

Run configure

   After  you  are squared away with the preliminaries, run the configure
   script:

   ./configure [ options ]

     NOTE

     You MUST run the configure script as normal user, not root. Did you
     extract  the  tarball as root? It won't work. Delete everything you
     have  just extracted, as root. 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. When you're ready to do a make
     install, later, su yourself to root, and run make install.

   The  configure script can take a while to complete. There will be more
   then  thirty  separate  configuration scripts that will be executed by
   this  command.  To  an  untrained  eye  it  may  seem  that  the  same
   configuration  script  is  stuck  in  a loop; that's because all these
   configuration  scripts  share  a  lot  of code. It may take as much as
   15-20 minutes for configure to finish on a slow machine - even more.

   You  must  have  the  uux  command  in your default search path if you
   intend  to  use Courier to relay mail via UUCP. You may need to modify
   your  PATH  environment  variable  to include the directory containing
   uux.

   gcc/egcs  is  officially  blessed  for building Courier. In most cases
   there's  no  need  to  tweak any compiler-specific settings. Note that
   there  currently may be some unresolved issues with gcc 2.96. gcc 2.91
   has  been  tested  and known to work. Occasionally some of your system
   libraries  may be stuck in some oddball directory that is not searched
   by default. Non-standard options for the compiler or linker can be set
   by  putting  them into environment variables. This must be done before
   running the configurescript:
     * CFLAGS - additional flags for the C compiler.
     * CXXFLAGS - additional flags for the C++ compiler.
     * LDFLAGS - additional flags for linker.
     * LDADD  - additional libraries to link with. NOTE - everything will
       be linked with these libraries.

   The  complete  reference  to  all configure script options is provided
   below. The most important options are:
     * --prefix=pathname  -  install  Courier in pathname, instead of the
       default  location  of /usr/lib/courier. Note - the examples in the
       rest  of this text assumes this is where you will install Courier.
       Do  not  attempt  to  install  Courier  in  a directory whose name
       contains  spaces or punctuation marks. Periods or dashes are fine,
       but refrain the temptation to use other, exotic, punctuation.
     * --with-db=db  or --with-db=gdbm - Courier requires either the GDBM
       or the DB database library. GDBM is used if both are present. This
       option forces the selection of the database library.
     * --with-locking-method=function  -  Select a file locking function.
       Available  functions  are:  fcntl,  lockf,  and  flock.  Not every
       function  is  available  on  every platform. If this option is not
       present,  configure  tries  each one, and takes the first one that
       works.  You  can  select a specific locking function by using this
       option.  This affects both the locking used for delivering mail to
       mailbox  files,  and  for other kinds of locking that Courier uses
       internally.
     * --enable-mimecharset=charset - specifies the default character set
       Courier  uses  when  adding  MIME  headers  to  a  message. If not
       specified, us-ascii is used.
     * --without-tcpddns  -  use  this  option if you are running a small
       network  without  access  to  a DNS server. This option will cause
       couriertcpd  to  use  the  system  resolver's  gethostby functions
       instead  of  issuing  DNS  queries.  Also: you must initialize the
       esmtproutes  control  file  with  the  IP  addresses  of  all your
       servers.

  configure reference

   Here's  a comprehensive list of options for the configure script. They
   are  presented  in  no  particular  order.  In  almost  all cases, the
   configure script will automatically figure out the correct values, but
   sometimes it is necessary to specify them explicitly. If you ever have
   a  need to manually specify any configuration option, try to determine
   whether  you need it because of a particular unique case that involves
   your  server  only,  or  whether  it  affects  any server running your
   hardware,  or  system.  In  the later case, try to investigate if it's
   possible  for  configure  to  be  a  bit  smarter  and  make the right
   decision.
     * --prefix=pathname  -  install  Courier in pathname, instead of the
       default  location  of /usr/lib/courier. Note - the examples in the
       rest of this text assumes this is where you will install Courier.
     * --exec-prefix=pathname      -      specify     where     Courier's
       machine-executable  binaries should be installed. This defaults to
       the  same directory as given by the --prefix option. There will be
       three   subdirectories   created  underneath  exec-prefix:  bin  -
       user-executable  binaries; sbin - superuser-only binaries; libexec
       -  other  binaries  that are not directly invoked from the command
       line, but are started by other Courier commands.
     * --bindir=pathname  ,  --sbindir=pathname,  --libexecdir=pathname -
       these  options  override  the  default value for the corresponding
       subdirectory  underneath  --exec-prefix  (see  above).  The bindir
       directory  contains  programs  that  can  be  executed  by anyone.
       sbindir  contains  programs  that  can  only  be  executed  by the
       superuser.  libexecdir contains programs and libraries that cannot
       be  directly executed from the command line. The default locations
       are  the  bin,  sbin,  and  libexec  subdirectories underneath the
       directory specified by exec_prefix.
     * --datadir=pathname  -  specifies the directory where miscellaneous
       shell  scripts,  Perl  scripts,  and data files will be installed.
       This  option defaults to the subdirectory "share" in the directory
       specified by the --prefix option.
     * --sysconfdir=pathname  -  specifies  the directory where Courier's
       configuration  files  are  installed.  This option defaults to the
       subdirectory  "etc"  in  the  directory  specified by the --prefix
       option.
     * --localstatedir=pathname  - specifies the directory that will hold
       the  mail queue, and other temporary data. This option defaults to
       the  subdirectory "var" in the directory specified by the --prefix
       option.
     * --without-ipv6  -  do  not  compile IPv6 support. IPv6 support, if
       available  is  normally  automatically  detected  and enabled. Use
       --without-ipv6  to  disable  it.  IPv6  implementations on various
       platforms  is  still in flux, and IPv6 support will not be enabled
       if the detection logic fails. Use --with-ipv6 in order to fail the
       configuration  stage  if IPv6 is not detected, instead of silently
       continuing  with  IPv4  support  only.  See  "IPv6" below for more
       information.
     * --with-db=db  or --with-db=gdbm - Courier requires either the GDBM
       or the DB database library. GDBM is used if both are present. This
       option forces the selection of the database library.
     * --with-locking-method=function  -  Select a file locking function.
       Available  functions  are:  fcntl,  lockf,  and  flock.  Not every
       function  is  available  on  every platform. If this option is not
       present,  configure  will choose the first locking function that's
       available.  You  can  select  a specific locking function by using
       this  option.  This  affects  both the locking used for delivering
       mail to mailbox files, and for other kinds of locking that Courier
       uses internally.
     * --enable-mimecharset=charset - specifies the default character set
       Courier  uses  when  adding  MIME  headers  to  a  message. If not
       specified, us-ascii will be used.
     * --without-tcpddns  -  use  this  option if you are running a small
       network  without  access  to  a DNS server. This option will cause
       couriertcpd  to  use  the  system  resolver's  gethostby functions
       instead  of issuing DNS queries. Also: you will have to initialize
       the  smtproutes  control  file  with  the IP addresses of all your
       servers.
     * --with-mailuser=user  -  all  except  two Courier daemons run as a
       non-privileged user. This option specifies the userid that Courier
       will install and run as.
     * --with-mailgroup=group  -  like --with-mailuser, but specifies the
       group ID.
     * --with-mailuid=userid,   --with-mailgid=groupid  -  these  options
       specify the numerical user and group IDs. Do not use these options
       unless configure fails and tells you to use them.
     * --without-explicitsync - normally Courier will automatically sync,
       or  flush  out  all file buffers to disk, at certain key points in
       order  to  try  to  minimize  the  extent  the  mail queue can get
       corrupted if the system crashes. If the mail queue is installed on
       a  reliable  disk  array or a network file server, this may not be
       necessary, and will only serve to slow down the mail delivery. Use
       this option to turn off syncing.
     * --with-shellpath=path   -  specifies  the  contents  of  the  PATH
       environment  variable that is inherited by custom programs started
       by Courier to deliver messages. If not specified, PATH will be set
       to /bin:/usr/bin:/usr/local/bin.
     * --disable-local-extensions  -  normally,  in addition to accepting
       mail  that's  addressed  to  <user@domain.com>, Courier can accept
       mail  that's  addressed  to  <user-xxx@domain.com>,  for arbitrary
       values  of xxx. In order for that to happen the user has to create
       a  special file with delivery instructions. See the dot-courier(5)
       manual  page  for  more  information.  This  option  disables this
       feature.
     * --with-paranoid-smtpext    -    be   paranoid   when   negotiating
       Courier-specific ESMTP extensions with remote servers. The Courier
       mail  server  defines  and  implements  certain experimental ESMTP
       extensions:  XVERP  and  XEXDATA. Problems may result in the event
       that  someone  else  uses  the  same  name to implement some other
       extension.  If  this  option  is specified, Courier's ESMTP server
       will    also   advertise   a   dummy   ESMTP   capability   called
       XCOURIEREXTENSIONS,  and  will  not recognize any Courier-specific
       extensions  unless  the  remote  mail  server also advertises this
       dummy ESMTP capability.
     * --enable-workarounds-for-imap-client-bugs   -  there  are  several
       confirmed bugs in some IMAP clients that do not properly implement
       the  IMAP4rev1  protocol. This option enables some workarounds for
       those  buggy  IMAP  clients.  NOTE:  make  check will fail if this
       option  is  used.  You should first configure without this option,
       and  if all post-configuration tests succeed, rerun configure with
       this option and recompile.
     * --with-qdircount=n  -  set  n  to  be  the  number  of  mail queue
       subdirectories.  In  order  to  improve the speed of access to the
       mail  queue,  messages are stored in subdirectories, hashed by the
       message  queue number. n specifies how many subdirectories will be
       created.  If this option is not specified, 100 subdirectories will
       be  used.  WARNING:  once  you've  installed  Courier once, if you
       decide  to  reconfigure  and  reinstall,  you  MUST  use  the same
       subdirectory  count  (by default, or explicitly), otherwise you'll
       end  up  with a big mess on your hands if you have ANY messages in
       the  mail  queue.  If you need to change this option, wait for all
       messages  in  the  queue  to be flushed out, and reinstall with an
       empty mail queue.
     * --disable-changepass   -  disable  the  ability  to  change  login
       passwords  in  the  webmail  server. Use this if you don't want to
       install  the  authdaemon.passwd  utility  (which is installed suid
       root) that is used to change login passwords.
     * --without-authpam,      --without-authldap,     --without-authpwd,
       --without-authmysql,   --without-authpgsql,  --without-authshadow,
       --without-authuserdb,   --without-authvchkpw,  --without-authcram,
       --without-authdaemon  -  manually  disable authentication modules.
       Authentication  modules  are  used  to  verify  passwords for POP3
       access,  webmail  access,  authenticated  ESMTP relaying, and IMAP
       access (where available). They're also used to locate accounts and
       mailboxes  that  correspond  to  a  given  local mail address. The
       configure  script  automatically checks the system and selects the
       appropriate  authentication  modules,  based  upon  the  available
       libraries.  Rarely  is there a need to manually use these options.
       It  is always possible to install an authentication module, but to
       disable it in actual use. See below for more information.
     * --with-random=/dev/path,  --without-random  -  for authenticating,
       Courier  sometimes  needs  a  good  source  of  random  noise.  If
       configure  finds  /dev/urandom,  it  will use that. If your random
       device  is  named  otherwise, specify it using this option. If you
       don't  want  to use a random device, specify --without-random, and
       Courier will generate some noise on its own. Courier will generate
       noise  based  on  the  output  of a random ps command, and several
       other, hopefully unpredictable, sources.
     * --without-certdb  -  do not install a default set of trusted X.509
       root  CA  certs  (in  order  to validate the remote server's X.509
       certificate).  See  "Configure  ESMTP  authentication and SSL" for
       more information.
     * --with-certdb=pathname  -  do not install the default set, but put
       pathname as the default location of the root CA database, into the
       configuration  file.  This  is a convenient option to have Courier
       use an external, previously installed, root CA database.
     * --with-waitfunc=wait, --with-waitfunc=wait3 - specifies the system
       call  to  use  to  asynchronously  reap child processes. This is a
       sticky  one,  because  the  behavior  of the wait and wait3 system
       calls  varies  greatly  depending  on the level of each individual
       system's  POSIX  compliance.  The configure script will attempt to
       compile  and  run some test programs in order to attempt to figure
       out  which  system  call  actually  works. If the configure script
       fails,  or  if  it selects a wrong function (which will be evident
       when mail delivery stops, and you have a bunch of zombies that are
       not  being  reaped),  you  might have to manually specify it using
       either  option. In that case, however, you should also examine the
       test  programs,  investigate  what  went wrong, and patch the test
       programs to give a correct result for your system.
     * --without-ispell, --with-ispell=program - Courier's webmail server
       can use spell checking, if the ispell program is available (aspell
       can  be  used  too).  If configure finds ispell, spell checking is
       enabled.   Use   --without-ispell   to  forcefully  disable  spell
       checking.  If  ispell  is  not  in  the  current  search path, use
       --with-ispell=program  to  explicitly  set the location of ispell.
       See  "Configure the webmail server" for more information on ispell
       or aspell.
     * --disable-utf7-folder-encoding  -  use this option if you will not
       have  IMAP  access  to  mail  accounts,  and  provide only webmail
       access.  IMAP mail clients use modified UTF-7 to encode high 8-bit
       characters  in  folder  names. If there will not be IMAP access to
       mail accounts, modified UTF-7 support in the webmail served can be
       removed, saving a little bit of overhead.
     * --enable-unicode  -  include  the  ability  in  the IMAP server to
       search  and  sort  messages  in character sets besides the default
       ISO-8859-1/US-ASCII.   All   character  set  tables  supported  by
       Courier's  IMAP  server  will be included. See "Configure the IMAP
       server"  and  "Configure the webmail server" for more information.
       Additionally,  all  unicode  tables  will  also be included in the
       webmail  server.  Keep this in mind because the full unicode table
       set is quite large.
       The  webmail server also uses unicode tables to implement modified
       UTF-7 folder name encoding (see the
       --disable-utf7-folder-encoding),  additionally  the webmail server
       will be able to translate message text to the local character set,
       if the two are different and the unicode tables for both character
       sets are available.
     * --enable-unicode=charset,charset,...  -  include ability to search
       and  sort  messages,  but  only  for  these  character sets. Also,
       include  only  these  character  sets  in  the webmail server. See
       "Configure the IMAP server" and "Configure the webmail server" for
       more information.
     * --enable-imageurl=/url - use /url/ as the URL to the static images
       displayed  by  the  webmail  server.  HTML  pages  are dynamically
       generated  by  the  webmail server CGI, but they also include some
       static  icons.  The  webmail  CGI  will use /url as the URL to the
       directory  containing  the  static  images.  The  default  URL  is
       "/webmail",  which  means that the static images must be installed
       in  the <DocumentRoot>/webmail directory. This is a manual process
       that  is  described  in  more detail in the "Configure the webmail
       server" section, below.
     * --enable-https, --enable-https=login, --enable-https=auto - if you
       have  an  SSL-enabled web server, use the --enable-https option in
       order    to    configure    webmail    access    for    SSL.   Use
       --enable-https=login  in order to use SSL only when logging in, to
       send  the  password.  Use --enable-https=auto to generate relative
       URLs,  so  that  users  can  connect with either http or https and
       their session will remain that way.
       --enable-https=login  and  --enable-https=auto  require  that your
       http  and  https  URLs  that refer to the webmail CGI be identical
       (which is the usual default).
       --enable-https=auto  is  the  default.  Use --disable-https if you
       need to completely disable https, for some reason.
     * --enable-hardtimeout=7200  -  set  the  hard  timeout  for webmail
       sessions  (in  seconds).  The default is 2 hours. webmail sessions
       are unequivocally logged out after the indicated time interval.
     * --enable-softtimeout=1200 - set the inactivity timeout for webmail
       sessions (in seconds). The default is 20 minutes. webmail sessions
       are  logged  out  if  there's  no  activity for the indicated time
       interval.
     * --with-defaultlang=lang - reserved for future use.
     * --enable-mimetypes=file:file:file - this is a colon-separated list
       of  all  of  your  mime.types  files. The mime.types configuration
       files  are  used to map file extension to their corresponding MIME
       content  types.  The  configuration  script  will  look in several
       directories  where  mime.types  usually  exists.  You can use this
       option  to  explicitly  specify  a  list of mime.types files to be
       used, instead of the default.
     * --enable-bannerprog=pathname  - advanced option that sets a banner
       program  that the webmail server will execute. This program should
       print HTML, on standard output, to generate a typical banner.
     * --with-maxargsize=bytes,--with-maxformargsize=bytes   -   sets  an
       upper  limit  on  the  size  of CGI arguments. Normally there's no
       reason  to  modify the defaults (500,000 and 2,000,000 bytes). The
       latter is generally the maximum allowed size of an attachment. The
       former is generally the maximum allowed size of a message.
     * --with-cachedir=dir, --with-cacheowner=userid - the webmail server
       uses  a  cache  of  currently  active  logins.  The webmail server
       binary,  is  executed  for  each  and  every HTTP request, and the
       user's  maildir  needs  to  be  quickly located each time. Because
       hitting   the   authentication  module  can  be  expensive  (think
       MySQL/PostgreSQL/LDAP  query  for every HTTP request!) the webmail
       server  will  cache this information in order to avoid having your
       authentication  server  brought down to its knees. By default, the
       directory  /usr/lib/courier/var/webmail-logincache  will  be used,
       owned  by  the  bin  user.  These options can be used to specify a
       different location for the webmail login cache directory.
       If you'll be using the webmail server, you MUST add an hourly cron
       job   to  run  the  /usr/lib/courier/share/sqwebmail/cleancache.pl
       script   which  deletes  expired  cache  records  from  the  cache
       directory.  Add  the following command to be executed from cron at
       least once an hour:
su -c "/usr/lib/courier/share/sqwebmail/cleancache.pl" bin
       (This assumes that your cache directory is owned by the bin user).
       There's  no  need to set up this cron job if the webmail server is
       not  used.  NOTE:  your  su  command  may use different options or
       syntax, check the su manual page to confirm the correct syntax.
     * --without-gzip  -  if  the  configuration  script  finds  the gzip
       utility,   the   webmail   server   will  automatically  use  gzip
       compression  for  some  large  web  pages  (if  the client browser
       supports  gzip  compression).  Use  this  option  to turn off gzip
       compression.
     * --disable-autorenamesent  -  do  not  rename the Sent folder every
       month.    This    option   can   also   be   controlled   by   the
       SQWEBMAIL_AUTORENAMESENT environment variable (which can be set in
       Apache's httpd.conf, for example).
     * --with-calendarpurge=N  - if calendaring is enabled, purge expired
       calendar events after N days (default: 30).
     * --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.

Authentication modules

   Authentication  modules  serve  two purposes: identify the location of
   the  mailbox  for a local mail account; validate the password provided
   by IMAP, POP3, or Webmail to access the mailbox.

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

   The configure script checks the system configuration and automatically
   prepares  a  default set of authentication modules which will be used.
   The option --without-module, where "module" represents the name of the
   module,  can  be  used  to  selectively  disable  the module. However,
   there's  usually  no reason to do that. Modules can be easily disabled
   at  runtime,  by  removing  them from the authmodulelist configuration
   file,  or from the authdaemonrc file if the authdaemon module is going
   to be installed.

   Here's a brief list of the available authentication modules:
     * authpwd - authenticate against the system passwd file.
     * authshadow - use instead of authpwd on systems that use the shadow
       password file.
     * authpam  - use the PAM library for authentication. authpam MUST be
       used  instead  of  authpwd  or  authshadow on systems that use PAM
       authentication.
     * authuserdb  -  authenticate from a GDBM/DB database, maintained by
       some simple Perl script that are included with Courier.
     * authcram  -  also  authenticate  from  a GDBM/DB database, but use
       CRAM-MD5 or CRAM-SHA1 authentication.
     * authmysql  -  authenticate  from an account file stored in a MySQL
       database.
     * authpgsql  -  authenticate  from  an  account  file  stored  in  a
       PostgreSQL database.
     * authldap  -  authenticate  from  an account file stored in an LDAP
       directory.
     * authvchkpw - use the vpopmail library for authenticating.
     * authdaemon - use the authdaemond authentication proxy process (see
       below).

   Most   of   these   authentication   modules   have   a  corresponding
   configuration  file  that  define various parameters (server location,
   field  names,  etc).  After  installation  you will need to open their
   configuration  files, and follow the instructions in the configuration
   file.

   The  list  of  authentication  modules, and their respective order, is
   read   from   the  authmodulelist  configuration  file,  and  unwanted
   authentication  modules  can  be disabled simply by removing them from
   this  file.  When authdaemon is installed the list of modules is found
   in  the  authdaemonrc  file  instead.  When  authdaemon  is installed,
   Courier  does not issue authentication requests directly, instead they
   are  forwarded  to the authdaemond process. This is a small persistent
   process  that  runs  in  the  background and opens persistent database
   connections. This is much faster than opening and closing a connection
   to the database for each individual authentication request.

   Starting  with  Courier  0.35,  the  authdaemon  module will always be
   installed,  unless  explicitly  disabled by the configure script. This
   greatly  simplifies  these  installation  instructions.  Additionally,
   authdaemon  is required in order to be able to change passwords in the
   webmail  server.  If  authdaemon  is not installed, webmail may not be
   able  to  change  the account password, because that procedure usually
   requires  elevated privileges (and webmail drops root privileges right
   away, while authdaemon retains them, in the background).

  authpam

   This  module should be used on systems that have the PAM library. With
   this  module,  Courier  will  use whatever PAM modules are defined for
   authenticating  the  "webmail", "imap", "pop3", or "esmtp" PAM service
   services.  Essentially,  authpam  allows any PAM module to be used for
   authenticating  mail  account  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 "webmail" 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.

   Although  the  exact procedure to configure PAM authentication differs
   from  system  to  system,  if  you  have  the directory /etc/pam.d try
   creating the file /etc/pam.d/webmail, containing the following text:
#%PAM-1.0
auth    required  /lib/security/pam_pwdb.so shadow nullok
account required  /lib/security/pam_pwdb.so

   Repeat  the  same for imap, pop3, and esmtp files. Your system may use
   the pam_unix.so module instead of pam_pwdb.so, and your modules may be
   located in a different directory.

   If  instead  of /etc/pam.d you have a global file named /etc/pam.conf,
   try appending the following lines to the end of this file:
webmail auth    required pam_pwdb.so shadow nullok
webmail account required pam_pwdb.so shadow nullok

   Repeat  the same lines with "imap", "pop3", and "esmtp" entries to set
   up  authentication  for those services as well. Again, you may have to
   use pam_unix.so or specify the full pathname to the PAM module.

   HINT:  try to look at how other PAM services are set up, and duplicate
   their  configuration for the webmail service. A good example to follow
   would be the ppp service, if it exists.

     NOTE: If optional webmail calendaring is enabled in groupware mode,
     PAM  must  be  configured to authenticate the "calendar" service in
     addition  to  "webmail".  In  most cases, creating a soft link from
     /etc/pam.d/calendar to /etc/pam.d/webmail does the trick.

  authuserdb/authcram

   These  modules  use 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 database files that are loosely equivalent in
   function  to  /etc/passwd  and  /etc/shadow.  authuserdb  handles  the
   traditional   userid/password   logins,   and  authcram  handles  CRAM
   authentication.  The  database  files  are  maintained  indirectly  by
   several  Perl  scripts  (which are included with Courier), which build
   these   database   files  from  a  plain  text  file,  usually  called
   /etc/userdb that can be modified using any text editor, or via command
   line  with  the  aid  of these Perl scripts. /etc/userdb may also be a
   subdirectory  with  multiple  text files of the same format, which are
   concatenated.  This  allows creating 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  supercede  /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.

  authmysql

   Edit  the authmysqlrc configuration file to configure this module. For
   more information, see the file authlib/README.authmysql.html.

  authpgsql

   Edit  the  authpgsqlrc  configuration  file  to configure this module.
   PostgreSQL configuration is nearly identical to MySQL information, see
   authlib/README.authpostgres.html for more information.

  authdaemon

   After running make install, edit your system's startup script and have
   it run authdaemond start at system boot.

   The  authdaemond  start 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  authdaemond start 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 distributions with
   and  without LDAP or MySQL support. The distributor would simply build
   Courier  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  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.

Confirming selected authentication options

   You  can  find out what authentication modules were actually used, but
   after  running  the  configure script you must also at least run make,
   and  have it succesfully complete. Running make, compiles the authinfo
   program in the authlib subdirectory. Run this program to tell you what
   authentication modules were compiled in.

   To change the list of enabled authentication modules, simply rerun the
   configurescript.

IPv6

   IPv6 support in Courier means basically the following:
     * ESMTP,  IMAP,  and  POP3  servers  will  create an IPv6 socket and
       accept IPv6 connections.
     * The  ESMTP client will attempt to resolve AAAA records in addition
       to A records.
     * Headers  in incoming mail will log IPv6 addresses, instead of IPv4
       addresses.  Delivery  Status Notifications and log files will also
       reflect IPv6 addresses.

   IPv6  implementations  are required to accept IPv4 connections on IPv6
   sockets,  so IPv6 sockets should be able to receive both IPv4 and IPv6
   connections. In the event that your IPv6 implementation is not stable,
   or  is  partially  incomplete,  IPv6  support  in  Courier  should  be
   disabled.

   The   configuration   script  will  attempt  to  detect  whether  IPv6
   structures  and functions are available, and automatically enable IPv6
   support  if  they  are  found. The --without-ipv6 option disables IPv6
   support, which may be desired for the following reasons:
     * The IPv6 implementation on your platform is incomplete.
     * The   IPv6   implementation  on  your  platform  is  actually  not
       available,  despite the presence of IPv6 structures and functions.
       Most  GNU/Linux distributions ship without IPv6 support enabled in
       the  default  kernel  build.  Courier  automatically falls back to
       creating  an  IPv4  socket,  if it can't create an IPv6 socket, so
       things  should  continue  to work in that case. However, each such
       attempt  is  likely  to  result  in  an  error  message  logged to
       /var/log/messages  --  modprobe  is  whining that it can't find an
       IPv6  module  to  load.  On  systems that handle a large amount of
       traffic the log files can fill up rather quickly.
     * Implementing  IPv6 can increase the amount of DNS traffic, even if
       there is no IPv6 support in the kernel. Even if Courier falls back
       to  IPv4  sockets,  it  will  continue  to resolve IPv6 addresses,
       resulting in some extra DNS queries. There won't be a lot of extra
       DNS  queries,  but  there will be some. Also, there are still some
       DNS  servers  that  cannot  correctly  handle  IPv6  queries,  and
       attempts  to  deliver  mail to these domains will fail despite the
       presence of valid IPv4 records.

   IPv6   support   is  still  a  bit  spotty  in  some  places.  If  the
   configuration checks fail, IPv6 support will be quietly suppressed. If
   you  expect  IPv6  support  to be present, the --with-ipv6 flag can be
   used to abort configuration if IPv6 support was not detected.

Compile and run make check

    make
    make check

   If the configure script ran without errors, run make to build Courier.
   If  make  completes  succesfully, run make check. make check runs some
   simple  internal  tests. It is not feasible to run a complete check of
   Courier's  behavior,  but make check does automatically run some tests
   on several modules.

   If  make  check fails, you need to do some detective work. Investigate
   the  source  of  the  failure.  It  is  possible that the issue can be
   resolved  by  specifying different options to the configure script, in
   which case you have to go back and rerun the configure script again.

Installation

   su  yourself  to root, if you want to do a live install, then run make
   install  or  make install-strip to install Courier. If you use the GNU
   version  of  make,  and  you  would  like  to  see which files Courier
   installs  and  where,  don't  su  yourself  to  root, but set the make
   variable named DESTDIR. For example:

   make install DESTDIR=/var/tmp/courier-inst

   The  contents  of  DESTDIR  are  prepended  to  the name of every file
   installed,  so if --prefix was set to /usr/lib/courier, the files will
   be installed in /var/tmp/courier-inst/usr/lib/courier. This only works
   if you use GNU make.

   NOTE:  you  must  make sure that your umask is 022 before you run make
   install.

   If  executed  by  root,  make  install  automatically sets the correct
   ownership  on  the  installed files. Non-root make installs do not set
   the  ownership,  but  still  set  correct permissions. This feature is
   mainly  for  use  by  people  who  are rolling Courier into a prebuilt
   package, since this allows them to build the package as a normal user,
   not  root.  In  this  situation the command make install-perms will be
   very  useful. This command creates a file called permissions.dat. This
   file contains a complete listing of everything that will be installed,
   and what the correct permissions are on every file.

   make  install  installs Courier binaries with debugging data, which is
   probably  a  good  idea  to  do  while  Courier is in development. Use
   makeinstall-strip  to  install  binaries  without debugging data. Some
   systems have a broken install utility, so make install-strip may fail.

Install configuration files

   The following command creates and updates configuration files. It must
   be executed after running make install:

   make install-configure

   This   command  copies  each  configuration  file  "filename.dist"  to
   "filename".  The  existing  filename  is backed up as filename.bak. If
   upgrading  from  Courier  0.30  or  later,  the previous configuration
   settings  in  filename.bak  will  be automatically copied to filename,
   provided  that they are still valid. If a configuration setting may no
   longer  be valid, it will be reset to its default value. The output of
   make  install-configure will indicate the status of each configuration
   setting,  therefore it is advistable to save the output to a file, and
   examine it:

   make install-configure >upgrade.log

   Versions  prior  to  0.30  cannot  have  their  configuration settings
   automatically   preserved,   and   must   be  restored  manually  from
   filename.bak.  Do  not simply copy filename.bak to filename, this will
   lose all the formatting codes that allow automatic upgrades.

  PAM configuration

   If  you use PAM library for authentication, you may need to set up PAM
   for  authenticating  POP3  logins, IMAP logins, webmail logins, and/or
   ESMTP  authentication.  In  most  cases, all you have to do is install
   /usr/lib/courier/etc/pop3d.authpam         as         /etc/pam.d/pop3,
   /usr/lib/courier/etc/imapd.authpam         as         /etc/pam.d/imap,
   /usr/lib/courier/etc/webmail.authpam    as   /etc/pam.d/webmail,   and
   /usr/lib/courier/etc/esmtp.authpam  as  /etc/pam.d/esmtp.  However you
   will  have to consult your PAM documentation, and the manual pages for
   authpam, in order to make sure.

   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
esmtp auth    required        pam_unix.so      try_first_pass
esmtp account required        pam_unix.so
esmtp session required        pam_permit.so

  Building RPM packages

   NOTE:  If  you  build an RPM package directly from the source tarball,
   the  resulting RPMs may not install if you have an existing IMAP or an
   existing  POP3  server  installed. The RPM packages will contain these
   PAM   configuration  files,  and  they  will  conflict  with  any  PAM
   configuration  files  installed by another IMAP or POP3 server. If you
   manually  installed an IMAP or a POP3 server without packaging them up
   into  an  RPM,  the  Courier  RPM  package  will  install  and the old
   configuration  files  will  be  silently  removed, since they were not
   installed using RPM.

   Courier  includes  integrated POP3, IMAP, and webmail servers, however
   they  only  work  with maildirs. Decide if you want to keep using your
   current  server,  or switch to Courier's IMAP/POP3/webmail servers. If
   you  want  to keep your existing servers, back up the contents of your
   /etc/pam.d  directory  before  installing  the  RPM,  install it, then
   restore  the overwritten files. If you want to switch to Courier, blow
   away your current server before running make install.

Adjust system paranoia level

   There  are  six  setuid  binaries  in  Courier that are owned by root:
   sendmail,   maildrop,   webmail,   webadmin,   authdaemon.passwd   and
   authstart.

   /usr/lib/courier/bin/maildrop  is  the mail filter. If you do not need
   mail  filtering,  you can remove it. The setuid root privilege is only
   needed  to implement mail filtering "on the wire", when receiving mail
   from   an   external  mail  relay  (see  localmailfilter(7)  for  more
   information).  Removing  the  setuid root bit still allows traditional
   mail filtering to be used, after the message is received and delivered
   to the mailbox.

   /usr/lib/courier/libexec/courier/webmail/webmail  is  the webmail CGI.
   It   is   executed  by  the  web  server,  and  needs  to  change  its
   userid/groupid,  in  order  to  enter  the maildir. If you do not need
   webmail  access,  you  can  remove  it. An alternative is to implement
   virtual  mailboxes,  owned  by a non-privileged userid, and change the
   ownership of the webmail CGI to the non-privileged user (you will also
   need to use the --with-cacheowner option to the configure script since
   the  webmail process must have write access to the webmail login cache
   directory).

   /usr/lib/courier/libexec/authlib/changepwd/authdaemon.passwd  is  used
   by  the  webmail server to update mail account passwords. The password
   authentication  module,  authdaemon is a persistent background process
   that  receives  authentication  requests  from a privileged filesystem
   socket.  authdaemon.passwd  receives  a  request  to  change  the mail
   account  password:  the  old  userid,  the  old  password, and the new
   password,  then  opens  the privileged socket and sends the request to
   the  authentication  module. This binary can be deleted if the webmail
   server is not going to be used.

   /usr/lib/courier/libexec/courier/webmail/webadmin  is  the wrapper for
   the web-based administration tool. See below for more information.

   /usr/lib/courier/bin/sendmail  is  the  command  line mail sender. Its
   first  order of business is to set its group id to Courier's group id,
   and  restore  the  original  userid, dropping root. The reason that it
   needs  root  setuid  is  to set its real group id, because setting the
   setgid  bit  on the executable is not enough. The setgid bit sets only
   the  effective  group  id,  and the root setuid bit is required to set
   both  effective  and real group ids. Both real and effective group IDs
   are needed in order to be able to implement maildrop mail filtering.

   /usr/lib/courier/libexec/courier/modules/esmtp/authstart  is  used  by
   the  ESMTP  server  to implement authenticated ESMTP. The ESMTP server
   runs  as  a  non-privileged user. Authenticating a userid and password
   requires  root privileges, since only root can typically access system
   passwords.  authstart  is  installed without any world read or execute
   permissions,  and can be executed only by the courier system group id.
   If  you  do  not  need to implement authenticated ESMTP you can remove
   authstart.  Permissions  on  authstart will be tightened up a bit in a
   future release.

Post-installation setup

   A  first-time  Courier installation may not require the system startup
   scripts  to  be  modified  to  start Courier at system boot. Until the
   system's  functionality is verified, the system will probably continue
   to  use  the  existing mail server. Still, most Courier configurations
   will require two things to be started before any part of the system is
   put to use:
    1. The   authdaemond   process   must   be   started   in  order  for
       authentication   to   work.   The  default  configuration  uses  a
       background  process  to  authenticate  local  mail  accounts.  Run
       "/usr/lib/courier/libexec/authlib/authdaemond  start" to start the
       background   process.  Before  starting  authdaemond,  review  the
       contents  of  the  /usr/lib/courier/etc/authdaemonrc configuration
       file,  to  select  the  authentication  modules  to  be used. Some
       authentication modules will require additional configuration files
       to  be initialized (such as authmysqlrc, authpgsql and authldaprc)
       before authdaemond is started.
    2. An  hourly  cron  job needs to be created to run the cleancache.pl
       script,  which purges expired webmail login cache records. Logging
       in  to  the mail account via the web creates a file in a temporary
       directory  that  caches  the login session identity. The output of
       make  install  includes  the  command that needs to be set up as a
       cron  job  by  root.  The cron job runs su to change to the userid
       that  owns  the login cache directory, then runs the purge script.
       The  su  command  on  some system uses a slightly different syntax
       than  what's shown by make install. It may be necessary to consult
       the su man page before setting up the cron job. Run the su command
       as  root,  to make sure that its syntax is correct, before setting
       up  the  cron  job.  The cron job can be omitted if webmail is not
       going to be used.

Post-installation checks

   The  following  tests  should  be run to verify that your installation
   works  properly.  These tests are not really comprehensive tests, they
   only  make  sure  that  the  basic  functionality  is  there, and they
   definitely  must  be  done  the  first  time  you install a version of
   Courier on your system. If you later reinstall the same version on the
   same  platform,  using  the  same configuration, you don't need to run
   these   installation   checks   (but  you  better  be  sure  that  the
   reinstallation  is  COMPLETELY identical to the original install). You
   might  also  wish  to  rerun these installation checks after upgrading
   your base operating system.

   The  following  documentation  assumes  that  Courier  is installed in
   /usr/lib/courier.

  Verify module installation

   Run  the  showmodules utility after all files have been installed, but
   before  you attempt to start Courier. The showmodules utility attempts
   to  load  and  initialize transport modules that have been configured,
   without  actually  starting  up  Courier.  Running  showmodules should
   result in something that looks like this:
   showmodules[5060]: Loading STATIC transport module libraries.
   showmodules[5060]: Installing i586-gnu-linux [0/0]
   showmodules[5060]: Installing local
   showmodules[5060]: Installed local
   showmodules[5060]: Installing esmtp
   showmodules[5060]: Installed esmtp
   showmodules[5060]: Installing dsn
   showmodules[5060]: Installed dsn
   showmodules[5060]: Initializing local
   showmodules[5060]: Initializing esmtp
   showmodules[5060]: Initializing dsn

  Test child process termination

   In  this  test,  you  will start Courier, then attempt to rapidly pump
   through  as  many  messages  as  fast  as  possible,  to  verify  that
   asynchronous  child  process termination handling works. For this test
   (and the following tests) you need to use a test account.

   Log on to the test account and run maildirmake to create two maildirs:
   maildirmake $HOME/test, and maildirmake $HOME/bounces.

   Create   $HOME/.courier-test-default,  containing  one  line:  ./test.
   Create   $HOME/.courier,   containing  one  line:  ./bounces.  If  you
   previously  selected  .qmail  compatibility,  you  will  need  to  use
   .qmail-test-default  and  .qmail,  of course. Keep that in mind as you
   work through the remaining tests.

   Configure  Courier  for local account authentication. If you intend to
   use  LDAP  or MySQL authentication, there are some configuration files
   that  must  be  edited to configure authentication. See the authlib(8)
   manual page for more information.

   Start Courier as root:

   /usr/lib/courier/sbin/courier start

   Check  your  system  log  files  for  any  error  messages. Run the ps
   command, and check that you only have the following processes running:
   courierd  (two  processes), courierdsn, courieruucp, courieresmtp, and
   courierlocal.  You  will  also  have  a  couple  of "logger" processes
   hanging around, that's ok too.

   One  of  the  two  courierd  processes  will  be  running as root. The
   courierlocal process will also be running as root. All other processes
   will  be running as the courier (or daemon, or mail) user. courieruucp
   may be running as uucp.

   If  your  configuration  includes the authdaemon authentication module
   (see  "configure  reference"  above) you need to start the authdaemond
   process too:

   /usr/lib/courier/libexec/authlib/authdaemond start

   Run  the  perftest1  script,  which  can  be  found  in  the directory
   containing Courier's source code:
sh perftest1 1000 "user-test-1 user-test-2 user-test-3 user-test-4 user-test-5"

   Run  this  script  while logged on to the test account. Replace "user"
   with  the name of your test account. This will send 1000 messages with
   five  recipients  per  message.  You  should  end up with exactly 5000
   messages in $HOME/test/new. Count them.

   Monitor  the  system logs. There will be a lot of activity. On my test
   system,  the  system  logger  usually  backs up. Courier generates log
   messages faster than the logger can record them. When all the activity
   stops,  count  how  many  files  you have in $HOME/test/new. For extra
   credit,  total up the Delivered-To: headers in all the messages, there
   should be 1000 headers for each one of the five addresses.

   If  you  did  not  get  5000 messages, and mailq comes up empty, check
   $HOME/bounces/new.  If  you're lucky, the rest bounced. That's still a
   problem, but the bounces will help you to investigate things further.

   If  you  did  not  get  5000  messages,  and mailq shows some messages
   remaining  in  the queue, and ps shows some dead zombie processes that
   are not being reaped, this means that asynchronous process termination
   is  not  working.  You  will need to examine your configuration to see
   whether  configure selected the wait or the wait3 function. Unpack the
   source   code   again   and   rerun   configure.  This  time  use  the
   --with-waitfunc  option  to  choose the other wait function, manually.
   Recompile, reinstall, and rerun this test.

   If  you  did  get  all  the  messages,  go  through  your  syslog  for
   extra-extra  credit.  grep  it  for  the  word  "defer"  to see if any
   messages  required  multiple  delivery attempts. This shouldn't happen
   either.

   If  your  hardware has enough juice to pump through 5000 messages in a
   short  period  of  time,  rerun  this  test  with  a  larger number of
   messages.  Before  doing  that,  wipe  the Maildirs clean, in order to
   confirm  the  message count, later. The test must run for at least 3-4
   minutes in order to get meaningful results.

  User/group ID check

   For  this  test  you  will  need  to use or create a regular user test
   account,  which will be referred to as user. You can use the same test
   account  you used in the last test, but erase all .courier (or .qmail)
   files.

   In user's home directory, create .courier which contains the following
   text:

   | /usr/bin/id >ID
   | /usr/bin/env >ENV

   Make  sure  that your id and env commands are in /usr/bin. If not, use
   the correct path.

   Send a single message to user:

   echo "To: user" | /usr/lib/courier/bin/sendmail

   Thie  message will disappear into the never-never land, so don't waste
   time  looking  for it. Just examine, very closely, the contents of the
   ID  and the ENV files in user's home directory. Double check what user
   and  the group ids recorded in ID match user's. Pay close attention to
   any auxiliary group IDs, make sure that they haven't "leaked" from the
   root user who started Courier.

   Also,  examine  the  environment,  in  ENV.  Check the manual page for
   dot-courier,  ENV  should  contain  only  the  documented  environment
   variables,  and  any  environment  variables  that  are defined in the
   /usr/lib/courier/etc/courierd file.

OPTIONAL: Configure webadmin

   This  is  a  web-based  administration  tool.  webadmin  is  a web CGI
   application.  It  is necessary to have a local web server installed in
   order  to  use  webadmin. Apache will do, but so will any other server
   with  a  complete CGI implementation (PHP is not required). Installing
   webadmin is a three step process:
    1. Move /usr/lib/courier/libexec/courier/webmail/webadmin to your web
       server's SSL cgi-bin directory. Take care to preserve the binary's
       ownership and permissions.
    2. Execute  "make  install-webadmin-password".  This  prompts  for  a
       password, which is saved in the file
       /usr/lib/courier/etc/webadmin/password.
    3. The  web  server  SHOULD  be  configured  to run webadmin from the
       cgi-bin  directory  using  SSL  only. webadmin's authentication is
       rather  simple:  the  password is saved in a cookie. Unless SSL is
       used,  the webadmin password can be intercepted in transit. If SSL
       is  not available, an acceptable level of security can be achieved
       by  setting up a firewall that allows web access only from trusted
       IP  addresses, then use a dedicated webadmin password. This is not
       perfect, but is generally adequate. A firewall is a good idea even
       if  SSL  is used. This is not Fort Knox, and webadmin is not going
       to  be publicly accessible, so the only needed security is to keep
       everyone out except for authorized IP addresses.
       Note  that  webadmin,  by  default, will enforce this restriction:
       either  SSL,  or  access  from a local IP address. Create the file
       /usr/lib/courier/etc/webadmin/unsecureok to allow non-SSL webadmin
       connections from remote IP addresses.

   webadmin is designed to be self-explanatory. Configuration options are
   divided  into  logical sections. Changes made to configuration options
   do not take effect immediately. To apply configuration changes, select
   "Install  new configuration" from the main menu. To cancel all changes
   made,  select  "Cancel  new  configuration".  Selecting  "Install  new
   configuration"  will apply all the changes to the configuration files,
   and  restart  any  Courier modules that must be restarted in order for
   the changes to take effect.

   If  you  decide  to  use webadmin, most of the remaining steps in this
   INSTALL document can be done using webadmin's equivalent screens.

Create system aliases

   You  must now specify which account gets postmaster mail. Courier does
   NOT  deliver  any  mail  to  root.  You  must use a non-privileged for
   postmaster  mail.  You will also need to specify where your postmaster
   account  is.  In  the  following  example the same account is used for
   both, but you can easily use separate mailboxes.

   Let's  say  that  you want postmaster mail to be delivered to the user
   "admin".

   Create  /usr/lib/courier/etc/aliases/system  using any text editor. An
   example  aliases/system  file  is created by make install, and you can
   simply edit what you have there. The default contents of this file are
   as follows:

   root: postmaster

   mailer-daemon: postmaster

   MAILER-DAEMON: postmaster

   uucp: postmaster

   You need to append the following line:

   postmaster: admin

   These  aliases  cause  all  mail  addressed  to  root,  postmaster, or
   mailer-daemon,  to be delivered to admin's account. If you want root's
   mail  delivered  somewhere  else,  you can replace "root: postmaster",
   with something else.

   Run the following command as root:

   /usr/lib/courier/sbin/makealiases

   This command creates /usr/lib/courier/etc/aliases.dat, a database that
   contains your new aliases.

   Send a test message:

   echo "To: postmaster" | /usr/lib/courier/bin/sendmail

   Check admin's mailbox, the message should be there.

   Let's do it again:

   echo "To: postmaster" | /usr/lib/courier/bin/sendmail -Nsuccess

   This  time,  in  addition  to  the  blank message, the sending account
   should receive a return receipt.

   Additional  aliases can be either added to this file, or placed in any
   other text file in the /usr/lib/courier/etc/aliases directory.

Create smtp access list

   You  need  to define which IP addresses are allowed to relay SMTP mail
   through     the    server.    The    installation    script    creates
   /usr/lib/courier/etc/smtpaccess/default  containing  an example of how
   to  enable  relaying  for  IP  address 127.0.0.1, and several reserved
   netblocks.  You  can either append additional entries to this file, or
   put   your   additional   entries   in   any   other   file   in   the
   /usr/lib/courier/etc/smtpaccess   subdirectory.   Afterwars,  run  the
   following as root:

   /usr/lib/courier/sbin/makesmtpaccess

   This  command creates the /usr/lib/courier/etc/smtpaccess.dat database
   that couriertcpd uses to initialize the environment for courieresmtpd.

   You   will   need   to   rerun  makesmtpaccess  in  order  to  rebuild
   smtpaccess.dat after any changes in the smtpaccess subdirectory.

   The  default  Courier configuration applies smtpaccess.dat to both the
   regular  ESMTP  server  (port  25),  and the message submission server
   (port  587).  It is possible to set up different access files for both
   ports.   To   do   that,   edit  /usr/lib/courier/etc/esmtpd-msa,  and
   explicitly  set  ACCESSFILE to a different file, create that file, and
   use  the  makesmtpaccess-msa command to compile the dedicated port 587
   access database.

Miscellaneous configuration

   Review/edit    contents    of    various    configuration   files   in
   /usr/lib/courier/etc:
     * courierd - this file controls general aspects of Courier's message
       processing.  A  default file is installed with comments describing
       what the various options are. Review the default options, and make
       whatever  changes  you deem appropriate. You will probably need to
       make  changes  to  this  configuration file in order to select the
       correct  way to deliver local mail (whether to have Courier handle
       the  delivery  directly,  or whether to run procmail or maildrop).
       There  are  comments  in  this file that tell you what needs to be
       done  to  have  Courier  use a separate local mail delivery agent,
       such   as  procmail,  for  mail  delivery.  Read  and  follow  the
       instructions there.
     * esmtpd  -  this is an important file that controls Courier's ESMTP
       server.  Options in this file include setting the maximum limit on
       simultaneous   server  connections,  whether  to  disable  certain
       optional  SMTP  features,  whether  or  not you have a mail filter
       module  installed,  and  whether  or  not  blacklists are used. By
       default,  this file configures Courier to filter all incoming mail
       against the MAPS RBL (see http://mail-abuse.org/). There's also an
       entry  in there for MAPS RSS, however RSS-listed mail does not get
       rejected  by  default, the indicator is only made available for an
       external  mail  filter  to  use.  Instructions  for having Courier
       itself  block  RSS-listed  relays,  in addition to RBL-blacklisted
       ones, are included.
     * esmtpd-msa - this file controls Courier's ESMTP message submission
       server  (RFC  2476).  The  settings  in  this  file supplement the
       settings in esmtpd. The default startup script first reads esmtpd,
       then   esmtpd-msa   in  order  to  initialize  the  ESMTP  message
       submission server on port 587.
     * smtpaccess  -  this  configuration  file/directory  is used to ban
       explicit  IP addresses from connecting to the ESMTP server at all,
       or  to  specify  which IP address ranges are allowed to relay mail
       through  the ESMTP server. The default file turns on relaying in a
       couple   of  reserved  IP  address  ranges,  as  an  example.  The
       makesmtpaccess  command  must  be  executed  for  any  changes  to
       smtpaccess to take effect.
     * pop3d  - this file sets various options for Courier's POP3 server.
       Courier's  POP3  server  can  be  used  only  if mail is stored in
       Maildirs.  You  will need to use another POP3 server if you choose
       to   deliver   your  mail  to  legacy  mailbox  files.  A  default
       configuration file is installed, describing the available options.
     * imapd  - this file sets various options for Courier's IMAP server.
       Courier's  IMAP  server  can  be  used  only  if mail is stored in
       Maildirs.  You  will need to use another IMAP server if you choose
       to   deliver   your  mail  to  legacy  mailbox  files.  A  default
       configuration file is installed, describing the available options.
     * authmodulelist  - authentication modules for the core mail server.
       The  pop3d,  imapd, and esmtpd, and esmtpd-msa configuration files
       specify  standalone  authentication  modules  that are used by the
       corresponding  servers.  Courier's  core mail server also needs to
       use   those  authentication  modules  in  order  to  locate  local
       mailboxes.  However,  for  speed, those authentication modules are
       statically  linked  with  Courier's  mail  core  daemon.  In  some
       situations  you  do  not want Courier's mail core daemon to use an
       authentication   module.  The  authmodulelist  configuration  file
       contains  a  list of authentication modules used by Courier's main
       mail core daemon. If you want to disable an authentication module,
       simply  remove  it from this file. The default installed file will
       be  initialized to contain all the authentication modules that are
       installed at configuration file.
       For  example,  if  OpenLDAP  client  libraries  are installed, the
       configure  script will install the authldap authentication module.
       If you do not want to use your LDAP server in order to look up the
       location  of  mailboxes  for local accounts (if the LDAP server is
       used  by some other application), simply remove authldap from this
       configuration  file  (and  from  other  configuration  files too -
       esmtpd, esmtpd-msa, imapd, and pop3d).
       Of  course,  you  can always use the --without-authldap option for
       the  configure script, however if you want to install the authldap
       module, but not use it right away, this is how you would do it.
       This  configuration  file  is  also used by Courier's HTTP webmail
       server,  which  also  statically  links  with  the  authentication
       modules, for speed.
       If  the  authdaemon  authentication  module was selected, then the
       authmodulelist  configuration  file  must  always specify only the
       authdaemon  module,  and  the authdaemonrc configuration file will
       specify the real authentication modules that are available.

    Qmail compatibility mode.

echo "qmail" >/usr/lib/courier/etc/dotextension

   Run  this  command  if  you  are installing Courier on a system that's
   currently  running the Qmail mail server. Courier will now read .qmail
   files  for delivery instructions, instead of .courier files. Courier's
   .courier  files  are  mostly compatible with Qmail's .qmail files, but
   there  are  some  minor  differences. Still, most of your .qmail files
   should work without too many problems.

Define local domains

   The  configuration  file  /usr/lib/courier/etc/locals is a list of all
   the  domains  that  are  considered  local. Mail to any address in any
   local  domain  is  handled  as a local delivery. If this file does not
   exist  Courier  will use the contents of the me configuration file, or
   it will obtain its machine name from the operating system.

   This  file contains a list of domains, one per line. In most cases you
   need  to initialize this file to contain every hostname that has a DNS
   A,  or  AAAA,  record  pointing  to  any  IP  address assigned to this
   machine,  including  "localhost".  You  will  also need to include any
   domain that lists this machine as its primary MX relay.

   You  may  also  include  domain  wildcards  in locals by prefixing the
   domain  with  a  period.  For  example:  ".example.com" will treat any
   domain underneath example.com - like a.example.com, b.example.com - as
   a local domain. Note that this does not include example.com itself, so
   you may need to list it explicitly as well!

   NOTE: The makealiases command must be entered after making any changes
   to this file.

Create a list of domains to accept mail for

   If  you  would like your server to function as a backup mail relay for
   other domains, create /usr/lib/courier/etc/esmtpacceptmailfor. This is
   a  plain  text  file, containing a list of domains, one per line. This
   file  lists all domains your server will accept mail for. NOTE: if you
   create this file, you MUST include all your local domains. Usually you
   can  simply  append  what  you have in /usr/lib/courier/etc/locals. If
   /usr/lib/courier/etc/esmtpacceptmailfor  does  not exist, Courier will
   accept    mail    only    for    the    machine    name    listed   in
   /usr/lib/courier/etc/me, (or the system machine name).

   Like /usr/lib/courier/etc/locals, prepending a period to a domain name
   in  esmtpacceptmailfor  will  cause  Courier  to  accept  mail for all
   subdomains of this domain.

OPTIONAL: Configure UUCP

   Courier  is  capable  of  sending and receiving mail via UUCP. Courier
   does  not implement UUCP directly, but instead uses your existing UUCP
   software to send and receive mail.

   Courier's  UUCP  functionality  has been tested with Taylor UUCP 1.06.
   It's  likely that some minor tweaking will be necessary to get Courier
   working  with  other  UUCP builds. Give it a shot, and keep an eye out
   for problems.

  /usr/lib/courier/etc/uucpme

   This configuration file must be initialized to list the UUCP node name
   that  this  machine  is  known  as. Currently Courier does not support
   multiple UUCP node aliases for the same machine.

  /usr/lib/courier/etc/uucpneighbors

   This  configuration  file  contains  a list of all the nodes that your
   machine  talks  to  via  UUCP.  Obviously  this  information will be a
   duplicate   of   the   corresponding   data   in  your  existing  UUCP
   configuration  files,  and  some maintenance will be necessary to keep
   both   lists   in  sync.  That  is,  unfortunately,  unavoidable.  The
   makeuucpneighbors commands turns this plain text file into a database,
   which  is  what Courier uses directly. The format of the uucpneighbors
   configuration  file  is  described  in the makeuucpneighbors(8) manual
   page.

  /usr/lib/courier/etc/uuucprewriteheaders

   Courier  automatically  rewrites message envelope addresses from ESMTP
   to  UUCP  format. If this file exists, the addresses in the headers of
   messages sent to/from UUCP addresses will also be rewritten.

Configure UUCP domain aliases

   Courier  can  accept  mail  addressed  to <user@example.com>, and then
   forward  it to uucp!bang!path!user, via UUCP. This is done by adding a
   UUCP  virtual  domain  alias  to your aliases file, see "Create system
   aliases".  Append  the  following entry to your /etc/aliases, then run
   the makealiases command:
   @example.com: uucp!bang!path!

   See the makealiases(8) manual page for more information.

OPTIONAL: Configure LDAP aliasing

   In  addition  to  using  LDAP  for  authentication  and  for  managing
   accounts, Courier can use an LDAP directory for routing, or "aliasing"
   mail.

   The  term  "aliasing" refers to substituting one or more addresses for
   another   address.   A  one-to-one  substitution  results  in  Courier
   accepting  mail  for  one  address, and delivering the mail to another
   address.  A one-to-many substitution results in Courier accepting mail
   for  one  address,  and  delivering  a separate copy of the message to
   every address defined by the alias.

   Courier  supports  a  basic  form of aliasing using a GDBM or DB-based
   database.   The   makealiases(8)  command  reads  a  plain  text  file
   containing  the  aliasing  rules, the creates a GDBM or a DB database.
   Each  recipient  address is looked up in the database, and if an alias
   is  defined  for  the  recipient  address,  it is used in place of the
   original  address.  Aliasing can be used against individual addresses,
   one  by  one.  An extended form of aliasing maps an entire domain to a
   single local address, using dot-courier(5) delivery instruction files.

   Courier  can use an LDAP directory instead of a GDBM or a DB database,
   to  perform essentially the same function. If OpenLDAP is available at
   time   of   installation,   the   installation   script  installs  the
   courierldapaliasd(8)  program and a ldapaliasrc configuration file. It
   will  be  necessary to enter appropriate information into ldapaliasrc,
   and  arrange  to run "courierldapaliasd start" at system boot time (it
   is  a  background  daemon process that opens persistent connections to
   the LDAP server).

   Additional  instructions  for setting up LDAP-based aliasing are found
   in the courierldapaliasd(8) manual page.

OPTIONAL: Configure mail filtering

   Courier  includes  several  options for selectively filtering mail. In
   general,  Courier  provides  only  the  plug-in  interfaces  by  which
   arbitrary  external  mail filters can be used to selectively accept or
   reject  messages.  Courier  comes  only  with  some  sample  code that
   demonstrates how to write a mail filter. An actual mail filter must be
   written  and  installed  separately.  Please  note  that  running mail
   filters  can  have a non-trivial impact on mail system performance and
   throughput.

   Courier provides two mail filtering interfaces:
     * Global mail filters - these filters are installed and will be used
       to   filter  every  incoming  message.  Global  mail  filters  are
       permanently running daemons that create and listen on a filesystem
       domain  socket.  Each  new  message  that Courier receives must be
       acknowledged by every global mail filter. Note that if global mail
       filters  are installed, but their daemons are not running, Courier
       will not accept any new messages.
     * Local  mail  filter  - this filter can be used when the message is
       addressed  to a local recipient - when Courier itself will deliver
       the  message  to  a  physical  mailbox.  Local  mail  filtering is
       designed  to  be  primarily used by the maildrop mail filter. With
       the  local  mail  filtering  installed,  individual recipients can
       create  files  containing  mail  filtering  instructions  that can
       selectively accept or reject individual messages.

   See courierfilter(8) for more information on global mail filters.

   See maildropfilter(7) for more information on local mail filters.

  Miscellaneous UUCP configuration

   Courier  sends  UUCP  mail by running rmail via uux. The configuration
   script  searches  for  the  uux command in the default search path. If
   your  uux command is not in a directory that's in your search path you
   will have to modify PATH before running configure.

   Courier  receives UUCP mail by expecting your UUCP software to run the
   rmail  command,  which  is  installed  in  /usr/lib/courier/bin. (It's
   actually a soft link to sendmail, but we'll talk about it later). Your
   UUCP  software  probably  does not run commands from this directory by
   default,  so  you will have to make the necessary adjustments. You can
   always  create  another soft link in a directory that UUCP searches by
   default.

Starting and stopping Courier

   To start Courier, run the command /usr/lib/courier/sbin/courier start.
   To  stop  Courier, run the command /usr/lib/courier/sbin/courier stop.
   See the courier(8) manual page for more information.

   You  should  add  these  commands  to your system startup and shutdown
   scripts.

   Note that this command starts and stops Courier's core processes only.
   It  does  not start any additional daemon processes that you may need,
   such  as  the mail filtering daemon, the ESMTP server daemon, the POP3
   server daemon, or the IMAP server daemon.

   The  commands  courierfilter  start, courierfilter stop, esmtpd start,
   esmtpd  stop,  esmtpd-msa  start,  esmtpd-msa stop, pop3d start, pop3d
   stop,  imapd  start, and imapd stop (all commands are installed in the
   sbin  directory)  are  used to start or stop their respective daemons,
   and  they should be added to your system startup and shutdown scripts,
   where   required.   As   described   in  the  relevant  manual  pages,
   courierfilter  should  be  the  first daemon process to start, and the
   last  one  to  terminate.  The remaining daemons may be started in any
   order.

   When  the  authdaemon  authentication  module is used, the authdaemond
   start  and authdaemond stop commands must also be added to your system
   scripts. No mail will be processed without authdaemond running.

Run Courier in parallel to your mail server

   You  now  have  several  options for migrating from your existing mail
   server to Courier:
     * Your existing mail server can continue to handle incoming mail, by
       listening  on  the  smtp  port.  Courier  will be used to send all
       outgoing  mail.  This  is  accomplished  by  configuring your mail
       software   to  run  /usr/lib/courier/bin/sendmail  to  send  mail,
       instead of your current sendmail program.
     * Courier  can  handle  incoming mail by listening on the smtp port,
       and  your existing mail server can continue to handle all outgoing
       mail.  You  will  need  to  stop  your  existing  mail server from
       listening on the smtp port, and run the following command:
/usr/lib/courier/sbin/esmtpd start
       from   your   system   start   up  script.  You  should  also  add
       /usr/lib/courier/sbin/esmtpd  stop to your system shutdown script.
       Note  that  there's  a  separate  script  that  starts  the  ESMTP
       submission  server on port 587 - /usr/lib/courier/sbin/esmtpd-msa,
       that is used in an analogous fashion.

OPTIONAL: Configure ESMTP authentication and SSL

   Courier  supports authenticated ESMTP in order to grant ESMTP relaying
   privileges  to  remote users. The following steps set up authenticated
   ESMTP:
     * Edit /usr/lib/courier/etc/esmtpd and uncomment the AUTHMODULES and
       ESMTPAUTH       variables.       The       configuration      file
       /usr/lib/courier/etc/esmtpd-msa  is  used for the ESMTP submission
       server   on  port  587.  Setting  these  variables  in  esmtpd  is
       sufficient,  because esmtpd-msa merely supplements the settings in
       esmtpd. Explicitly initialize these settings in esmtpd-msa only if
       you wish to apply them to port 587 only.
       AUTHMODULES  is  a list of Courier authentication modules that you
       want  to  use.  See  configure  reference  for more information on
       authentication modules. ESMTPAUTH is a list of SASL authentication
       methods  you  will  use.  Currently,  Courier  supports  LOGIN and
       CRAM-MD5.  CRAM-SHA1  is  also  implemented on experimental basis.
       CRAM-MD5/SHA1  is  not implemented in every authentication module.
       The    authentication    modules    that   support   CRAM-MD5/SHA1
       authentication are: authcram (this is the CRAM-MD5/SHA1 version of
       authuserdb,  use authcram for CRAM-MD5/SHA1 and use authuserdb for
       LOGIN), authldap, and authmysql.
     * Your  authentication modules may require additional configuration,
       you will have to take care of that too. For example, authpam - the
       PAM  authentication module - requires that you also configure your
       PAM  library. In this case, you need to configure your PAM library
       to  support  the  "esmtp"  service.  The PAM library configuration
       details depend on your particular operating system, and are beyond
       the scope of this document. Consult the documentation for your PAM
       library for more information.
     * Restart Courier.

  ESMTP over TLS/SSL

   Courier  also supports ESMTP over TLS/SSL, by using the ESMTP STARTTLS
   extension:
     * To  implement  STARTTLS  you  will  need to install OpenSSL before
       installing Courier. Download OpenSSL from http://www.openssl.org/.
       Follow  the  instructions  provided  with  OpenSSL  to install it.
       STARTTLS has been tested with OpenSSL 0.9.5a.
     * STARTTLS  is  enabled simply by installing an X.509 certificate as
       /usr/lib/courier/share/esmtpd.pem.   If   this  file  exists,  the
       STARTTLS  ESMTP  extension  will be automatically advertised. This
       file must be owned by the userid Courier is installed as, and MUST
       NOT be world readable!
     * Note  that  SSL  requires  a  signed  X.509  certificate.  You can
       generate  your own self-signed certificates with OpenSSL, but mail
       clients will display a warning message the first time they connect
       to  the  server.  To prevent the warning message, you will need to
       pay  money  to  have  your  certificate  signed  by  a certificate
       authority.  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 certificate must be installed as
       /usr/lib/courier/share/esmtpd.pem.  This  file  MUST  NOT HAVE any
       group or world permissions! It must be owned by the Courier userid
       (the userid used to install Courier, usually courier or daemon).
     * In     times     of     extreme     desperation     the     script
       /usr/lib/courier/sbin/mkesmtpdcert   can   be   used  to  generate
       /usr/lib/courier/share/esmtpd.pem.   This   script  will  silently
       terminate  if  OpenSSL  is  not  installed,  or  if the esmtpd.pem
       certificate  file  already exists (so it will not be overwritten).
       This  makes  it  easier to have this script invoked from a package
       install script.
     * Restart   Courier's   ESMTP  server  after  installing  the  X.509
       certificate.

   Courier  will also use TLS/SSL when sending ESMTP mail, automatically.
   If  the  remote  mail  server  support  STARTTLS,  Courier will use it
   automatically.

   SSL/TLS  settings  for  the  ESMTP  client  can  be  adjusted  in  the
   /usr/lib/courier/etc/courierd  configuration  file.  When sending mail
   using  SSL,  Courier  can  optionally verify the remote server's X.509
   certificate.  This is done by setting ESMTP_TLS_VERIFY_DOMAIN to 1, in
   /usr/lib/courier/etc/courierd.  Also, TLS_PEERCERTDIR must be set to a
   directory  that  contains  PEM  files of X.509 certificates of trusted
   root  certificate  authorities.  The  PEM  files  must  be  hashed  by
   OpenSSL's  c_rehash  script.  When  this  is done, the remote server's
   X.509  certificate  must  signed by trusted root CA, else Courier will
   bounce the recipient.

   Starting  with version 0.34, Courier installs a default set of trusted
   public  certificate  authorities,  and  the default configuration will
   require  the  remote  server  to  present  an X.509 certificate that's
   signed  by  any  trusted certificate authority. To disable certificate
   validation,      set      ESMTP_TLS_VERIFY_DOMAIN      to     0     in
   /usr/lib/courier/etc/courierd.  Alternatively, custom certificates may
   be     installed    instead.    The    TLS_TRUSTCERTS    setting    in
   /usr/lib/courier/etc/courierd   specifies   the  location  of  trusted
   certificate authorities.

OPTIONAL: Configure the SECURITY ESMTP extension

   Courier  includes  an experimental extension to ESMTP that can be used
   to  set  up secure E-mail delivery between trusted mail relays over an
   untrusted  network.  This  is  implemented  by  an  experimental ESMTP
   extension  in Courier. Therefore, at present time both the sending and
   the  receiving mail relay must be running Courier that's configured to
   support  this extension. The specification for this ESMTP extension is
   publicly  available.  This  is a very small extension of the existing,
   draft-standard STARTTLS ESMTP extension. The SECURITY extension should
   only  require  minor changes to existing mail servers and clients that
   already implement STARTTLS.

  Overview

   The  first  necessary  step  is  to  read the formal definition of the
   SECURITY  extension, which can be found on http://www.courier-mta.org.
   Although  the  following  instructions  do  not  use  any  information
   directly  from  this document, it is important to understandi how this
   mechanism  works. This will be very useful in troubleshooting. This is
   not called an "experimental" extension just for the hell of it.

   The  SECURITY  extension  builds  on  top of several existing, proven,
   technologies  in  order  to  deliver  mail  with  the highest level of
   security   that   can  possibly  be  implemented  using  the  existing
   technology. The several steps in implementing the SECURITY extension:
    1. Install and configure the STARTTLS ESMTP extension. This extension
       uses TLS/SSL encryption for sending mail.
    2. Create a private, controlled, X.509 Certificate Authority.
    3. Use the private CA to sign X.509 certificates of all mail nodes in
       the  trusted mail network. This CA's certificate is also installed
       in every trusted mail node.

   The SECURITY extension is an optional tag that's attached to an E-mail
   message.   Courier   requires   STARTTLS  to  forward  SECURITY-tagged
   messages,   and  the  receiving  mail  nodes  must  present  an  X.509
   certificate,  signed  by  the  private  Certificate  Authority, before
   Courier will send the message. Courier will refuse to send the message
   to  a  mail  node that does not support STARTTLS, or doesn't present a
   suitable X.509 certificate.

   Therefore,  in  an  ideal world, mail clients will simply tag messages
   with  the  SECURITY extension. Obviously, this means that mail clients
   must be updated to implement this feature. Until this happens, Courier
   will  provide  a  workaround  that automatically tags all messages for
   selected  domains  with  the SECURITY extension. This is not a perfect
   solution,  and  it has some minor limitations, which will be mentioned
   later.

  Install and configure the STARTTLS ESMTP extension

   The  first  step  is to implement ESMTP STARTTLS. Use the instructions
   elsewhere  in  this  document  to activate ESMTP STARTTLS support. The
   following  instructions use the scripts from OpenSSL 0.9.6, but should
   also work with OpenSSL 0.9.5a.

  Create a private X.509 Certificate Authority

   Create an empty subdirectory:
    mkdir /etc/myca
    cd /etc/myca

   There's a convenient OpenSSL script called CA.pl that you want to copy
   to the current directory:
    cp /usr/share/ssl/misc/CA.pl .

   Your OpenSSL package may have CA.pl installed someplace else. Find it,
   and  copy  it  to  /etc/myca.  The CA.pl needs to be slightly modified
   before  it  can  be  used.  Find  the following commands in CA.pl, and
   change them as follows:

   Replace:
      system ("$REQ -new -keyout newreq.pem -out newreq.pem $DAYS");

   replace with:
      system ("$REQ -new -nodes -keyout newreq.pem -out newreq.pem $DAYS");

   Also replace:
      system ("$REQ -new -x509 -keyout " .
          "${CATOP}/private/$CAKEY -out ${CATOP}/$CACERT $DAYS");

   replace with:
      system ("$REQ -new -nodes -x509 -keyout " .
          "${CATOP}/private/$CAKEY -out ${CATOP}/$CACERT $DAYS");

   The  CA.pl  script  creates  password-protected  certificate  keys  by
   default.  Password  protected  certificates currently do not work with
   Courier.  Adding  the  -nodes parameter turns off password protection.
   This  means that it is vital to make sure that the trusted mail relays
   are  properly  secured. All the encryption in the world will not be of
   much  use  if  the  mail relays are running a rootable FTP server (for
   example). Anyway, run CA.pl to create a new certificate authority:
    ./CA.pl -newca

   CA.pl  prompts for a basic description of the new CA, then creates the
   certificate  and  the  certificate  key.  The CA's root certificate is
   saved in /etc/myca/demoCA/cacert.pem.

  Use the private CA to sign X.509 certificates of all trusted mail nodes

   This step must be performed to create the X.509 certificates for every
   mail  node in the trusted secure network. First, a certificate request
   is created:
    ./CA.pl -newreq

   CA.pl  prompts for a basic description of the new certificate. Special
   care  must  be  paid to the "commonName" setting. "commonName" MUST be
   set to the hostname of the trusted mail node, NOT its mail domain. For
   example, given the following DNS setup for example.com:
     example.com.  MX 10 mx1.example.com.
     example.com.  MX 20 mx2.example.com.

     mx1.example.com. A 192.68.0.1
     mx2.example.com. A 192.68.1.1

   This  domain  will need two certificates, one with "commonName" set to
   "mx1.example.com", and one with "commonName" set to mx2.example.com.

   Running ./CA.pl produces a certificate request in the file newreq.pem.
   Run the following command to sign it:
    ./CA.pl -signreq

   This  step  creates  the  file  newcert.pem that contains a new signed
   certificate.  The  private  key  from the original certificate request
   must  be  appended  to  this file, before the certificate can be used.
   Simply take the newreq.pem file from the previous step, and append the
   private  key  in  that  file to newcert.pem. The resulting certificate
   file should look something like this:
   [ description of the certificate ]

-----BEGIN CERTIFICATE-----

   [ binary goo ]

-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----

   [ binary goo ]

-----END RSA PRIVATE KEY-----

   The  OpenSSL documentation contains instructions on how to perform the
   equivalent procedure with Diffie-Hellman instead of RSA.

  Configure trusted mail nodes

   Two files must be installed on every trusted mail node.
     * The  mail  node's  certificate,  the  newcert.pem  file  from  the
       previous  step. The following documentation assumes that this file
       is  installed  as  /etc/mycert.pem.  This  mail node will use this
       certificate to authenticate itself to other trusted mail nodes.
     * The   certificate   authority   file,  cacert.pem.  The  following
       documentation  assumes that it's installed as /etc/cacert.pem. The
       CA's certificate is used to authenticate other trusted mail nodes.

   Edit   the   /usr/lib/courier/etc/esmtpd   configuration   file.   Set
   TLS_CERTFILE  to  /etc/mycert.pem.  Courier  will  use TLS_CERTFILE to
   authenticate itself to other trusted mail nodes.

   Edit   the   /usr/lib/courier/etc/courierd   configuration  file.  Set
   TLS_TRUSTSECURITYCERTS to /etc/cacert.pem. Courier will not send ESMTP
   mail  tagged  with  the SECURITY extension to other mail relays unless
   they produce a certificate that's signed by TLS_TRUSTSECURITYCERTS.

  Testing

   The  following  simple  steps  can  be  carried  out  to  verify  that
   everything  is  working  correctly.  These examples use two mail nodes
   called send.example.com and receive.example.com. The test messages are
   sent  from send.example.com, and are addressed to receive.example.com.
   Courier   must   be   restarted   on  both  send  and  receive,  after
   reconfiguring the machines for each test. It is not strictly necessary
   to  do this every time, actually, but it's simply easier to do make it
   a  part  of  the  routine.  It  is  necessary to restart both the main
   Courier  daemon processes as well as the separate ESMTP daemon process
   (on receive):
    courier stop
    courier start
    esmtpd stop
    esmtpd start
    1. Temporary  get  rid  of /usr/lib/courier/bin/couriertls wrapper on
       receive.example.com.  Rename  it  to  couriertls.save. STARTTLS is
       automatically disabled if couriertls is missing,
    2. Run the following command on send.example.com:
    echo "To: postmaster" | /usr/lib/courier/bin/sendmail \
              -S STARTTLS postmaster@receive.example.com
       This  message  should  bounce  back  since  receive  has  STARTTLS
       disabled.
    3. Restore  couriertls  on receive.example.com, but then rename it on
       send.example.com.  The  situation  is  now  reversed, and the test
       message should still bounce.
    4. Restore    couriertls    on   send.example.com.   Edit   receive's
       /usr/lib/courier/etc/esmtpd   file.   Comment   out   the  current
       TLS_CERTFILE setting (which points to the private CA certificate).
       Reset  TLS_CERTFILE to /usr/lib/courier/share/esmtpd.pem, which is
       the  self-signed  test  certificate  created  by  the mkesmtpdcert
       script, when STARTTLS support in Courier was first set up.
       Send a test message WITHOUT the "-S STARTTLS" option. This message
       should   go  through,  assuming  all  the  other  setting  in  all
       configuration  files  are  the initial defaults. The regular ESMTP
       STARTTLS  extension,  without  authentication,  will  be  used the
       deliver  this  message. Verify this by checking the headers in the
       received message on receive.example.com.
       Send  a  test  message  WITH  the  "-S STARTTLS" option. It should
       bounce,  even though receive.example.com supports STARTTLS. That's
       because  it is using an X.509 certificate that's not signed by the
       private CA authority.
    5. Restore  TLS_CERTFILE on receive, and send a test message with the
       -S STARTTLS option, which should now go through.

  Force SECURITY for selected domains

   As demonstrated by the test messages, messages must be tagged with the
   SECURITY  extension in order for them to be securely transmitted. This
   must  be  done  by the sending mail client. Until mail clients support
   SECURITY  Courier  can  automatically  add  the  SECURITY tag to every
   message  addressed to a domain. This is done by entering the domain in
   the esmtproutes configuration file using the following syntax:
receive.example.com:  /SECURITY=STARTTLS

   Repeat the tests in the previous section, but this time add and delete
   this entry in /usr/lib/courier/etc/esmtproutes instead of using the -S
   STARTTLS  option. The test messages must still bounce or not bounce in
   the same way.

   Consult  the  courier(8)  manual  page  for  more  information  on the
   esmtproutes configuration file.

  Limitations

   This  setup  makes  it  virtually impossible to intercept mail traffic
   between  trusted  mail  nodes.  Even  if  the DNS cache is poisoned to
   intercept  mail to a hostile mail node, mail will not go through since
   the  attacker  will not have a signed X.509 cert. However, all is lost
   if  the mail nodes themselves are compromised directly. After securing
   the  compromised  node,  everything  must be rebuilt. A new CA must be
   created,  and  all  mail nodes must now receive new certificates. Once
   support  for  certificate revocation lists is improved, this situation
   will get somewhat better.

   Another  possible  way  to  mitigate  that  possibility  is  to  use a
   different   certificate   authority   for  every  trusted  mail  node.
   TLS_TRUSTSECURITYCERTS  can  point  to a directory, instead of a file.
   This directory can contain multiple certificate authorities (hashed by
   OpenSSL's  c_rehash  script).  Then,  only the compromised mail node's
   authority  certificate  needs  to  be  tossed  out,  regenerated,  and
   redistributed.

   TODO:  it may be possible to avoid generating individual certificates,
   and  distribute  self-signed  certificate authority certs only, with a
   properly-initialized commonName field. This needs to be researched.

   There  are  some  minor  differences  between using -S STARTTLS versus
   putting  the domain into esmtproutes. If the sending mail node forward
   mail  to  this  domain  via  UUCP,  -S  STARTTLS  will  bounce.  Since
   esmtproutes does not apply to UUCP, putting this domain in esmtproutes
   will have no effect whatsoever.

OPTIONAL: Configure the IMAP server

   Courier includes an integrated IMAP server. The following steps set it
   up:
     * Edit  /usr/lib/courier/etc/imapd.  If  you  want  to use IMAP SASL
       authentication,  uncomment  the  AUTHMODULES  and  IMAP_CAPABILITY
       variables.   They   perform   the   equivalent   function  as  the
       corresponding  variables  in the esmtpd configuration file, except
       that  IMAP_CAPABILITY  also  sets  several other IMAP capabilities
       that are advertised to IMAP clients. Also, for IMAP, CRAM-MD5/SHA1
       authentication  has  been  tested,  and is known to work, so it is
       listed as a default. Also, note than if the authpam authentication
       module is used, you will need to configure the "imap" PAM service.
       Other authentication modules have their own requirements too.
     * Uninstall any existing IMAP server that you have, remove the entry
       for  the  IMAP  port  in  /etc/inetd.conf,  and  restart the inetd
       daemon.
     * Add the following command to your system startup script
/usr/lib/courier/sbin/imapd start
       Of  course,  add /usr/lib/courier/sbin/imapd stop to your shutdown
       script too.

   NOTE:  if you have previously installed the stand-alone version of the
   Courier-IMAP  server,  you  will  need to remove it prior to using the
   directly  integrated  version. They use the same base source code, but
   have a slightly different configuration.

   NOTE:  this  IMAP  server  supports maildirs only. It does not support
   mbox file mailboxes.

  Foreign character set sorting/searching

   The  IMAP  server  can  sort  and search 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  configuration  includes  only  the  ISO-8859-1/US-ASCII
   character   set.  Use  the  --enable-unicode  option  to  include  all
   character sets.

   If  the  configure  scripts  finds  that GnuPG 1.0.5 is installed, the
   configure  script will also add the utf-8 character set to the default
   setting.

   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.

   The  utf-8  character set MUST be included if GnuPG 1.0.5 is installed
   (see   "Configure   encryption   for  the  webmail  server"  for  more
   information).

   Note  that character set translation tables take up additional memory.
   This  should  not be a problem in most cases. Most compilers place the
   read-only  character  set  tables into a shared text segment, which is
   shared  by all running server instances. Using --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.

OPTIONAL: Configure IMAP over SSL

   To  implement  IMAP  over  SSL  you will need to separately obtain and
   install OpenSSL. Download OpenSSL from http://www.openssl.org/. Follow
   the  instructions  in  the OpenSSL package to install it and configure
   it. IMAP over SSL has been tested with OpenSSL 0.9.5a.

   The   /usr/lib/courier/etc/imapd-ssl   configuration  file  sets  some
   additional  options for OpenSSL, which you may need to adjust. Consult
   that  configuration  file  for  additional information. Then, you also
   have  to  run  the  /usr/lib/courier/sbin/imapd-ssl  script  from your
   system    startup    and    shutdown    scripts,    just    like   the
   /usr/lib/courier/sbin/imapd  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 expects to find it. The default location for
   the X.509 certificate, in PEM format, is
   /usr/lib/courier/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/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  IMAP  server  also  supports  the  IMAP  STARTTLS extension as an
   alternative    or    a    complement    to    IMAP   over   SSL.   The
   /usr/lib/courier/etc/imapd-ssl  configuration  file  is  also  used to
   enable  or  disable IMAP STARTTLS, which has all the same requirements
   and prerequisites as IMAP over SSL.

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

OPTIONAL: Configure the POP3 server

   Courier  includes  an integrated POP3 server. The following steps will
   set it up:
     * Edit  /usr/lib/courier/etc/pop3d.  Very  few  POP3 clients support
       POP3  SASL  authentication,  but  if  you want to use it, for some
       reason,  uncomment  the  AUTHMODULES  and POP3AUTH variables. They
       perform  the equivalent function as the corresponding variables in
       the  esmtpd  and  imapd  configuration files. For POP3, SASL LOGIN
       authentication  has  been  tested,  and  is  known  to  work,  and
       CRAM-MD5/SHA1  has  not been tested. Also, note than if authpam is
       used,  you  will  need  to configure the "pop3" PAM service. Other
       authentication modules have their own requirements.
     * Uninstall any existing POP3 server that you have, remove the entry
       for  the  POP3  port  in  /etc/inetd.conf,  and  restart the inetd
       daemon.
     * Add the following command to your system startup script:
/usr/lib/courier/sbin/pop3d start
       Of  course,  add /usr/lib/courier/sbin/pop3d stop to your shutdown
       script too.

   NOTE:  this  POP3  server  supports maildirs only. It does not support
   mbox file mailboxes.

OPTIONAL: Configure POP3 over SSL

   Implementing  POP3  over SSL is very similar to implementing IMAP over
   SSL.  The  only  differences  are that the startup/shutdown command is
   "/usr/lib/courier/sbin/pop3d  start"  and "/usr/lib/courier/sbin/pop3d
   stop",  the configuration file is /usr/lib/courier/etc/pop3d, the name
   of  the  required SSL certificate is /usr/lib/courier/share/pop3d.pem,
   and the command to generate a test SSL certificate is mkpop3dcert.

OPTIONAL: Configure the webmail server

   The   integrated   webmail   server   is  installed,  by  default,  in
   /usr/lib/courier/libexec/courier/webmail.  It's  a single, executable,
   CGI   binary   that   uses   the   authentication  modules  listed  in
   /usr/lib/courier/etc/authmodulelist (or
   /usr/lib/courier/etc/authdaemonrc  if  the  authentication  daemon  is
   used). You can simply copy the webmail executable to your web server's
   cgi-bin directory, or create a link from the cgi-bin directory to this
   executable.

   Note  that  the  webmail  server  is  used  to access mail in existing
   accounts  only.  There  is no provision to create accounts through the
   webmail interface (nor there should be).

   Your  web  server  also  needs  to  be configured to use HTTP/1.0 when
   talking  to any MSIE browser. The MSIE browser has a number of bugs in
   its HTTP/1.1 implementation, at least as of MSIE 4.x and 5.x. You must
   configure  your  web  server  to use HTTP/1.0 when talking to any MSIE
   browser  (at  least until MSIE gets fixed). The problem has to do with
   downloading attachments. Apparently, MSIE forgets how MIME works, when
   it  uses  HTTP/1.1.  For  the  Apache  server,  insert  the  following
   directive in httpd.conf:
BrowserMatch "MSIE" nokeepalive downgrade-1.0 force-response-1.0

   Recent  versions  of  Apache  already  have  a similar directive for a
   specific  version  of  MSIE,  MSIE  4.0b2.  Just  replace  it  with  a
   browsermatch for any MSIE version.

  Modified UTF-7 encoding and unicode support

   Most IMAP clients use a Unicode-based encoding method called "modified
   UTF7"  in  order  to  represent  names  of  folders that contain 8-bit
   characters.  If there will not be any IMAP access to the mail accounts
   in  question,  there's no need to include all this baggage. The option
   --disable-utf7-folder-encoding  to the configure script will turn this
   off.

   There  are  a few IMAP clients that do not use modified UTF7 to encode
   folder names. The option --disable-utf7-folder-encoding can be used if
   that  is  the  case. It is currently not possible to support both UTF7
   and non-UTF7 clients at the same time.

   By  default,  the  configure  script  works  like  this.  It takes the
   character  set  used  for  the  HTML  templates, and loads the Unicode
   mappings  just  for  that character set. By default, Courier's webmail
   server  is  distributed  with a default set of HTML templates that use
   the  iso-8859-1  character  set.  If  you  are  installing  a modified
   derivative  that  includes  additional templates, the configure script
   will pick up any additional character sets used by those templates.

   Sometimes  it is useful to include additional unicode tables. The list
   of  available  unicode tables can be found in unicode/charsetlist.txt.
   This  is useful when there are alternative encodings for the same base
   character    set,    like    KOI8-R    and    IBM866.    The    option
   "--enable-unicode=koi8-r,ibm866",   when   used   with   koi8-r   HTML
   templates,  will  allow  the  webmail server to display ibm866-encoded
   E-mail using the koi8-r character set (and vice versa). Note, for this
   to  work you will need to install a set of KOI8-R HTML templates. In a
   pinch, you can simply edit webmail/html/en/CHARSET.

  Spell checking

   The webmail server can use either the ispell or the aspell package for
   spell checking. Install ispell or aspell before installing Courier.

   NOTE:  Courier  assumes  that  the spell checking dictionary is called
   "english".  Some  systems  use  a different name for the default spell
   checking  dictionary.  To  change  the  name  of  the  spell  checking
   dictionary  used by the webmail server, put the name of the dictionary
   into the file /usr/lib/courier/share/sqwebmail/html/en-us/ISPELLDICT.

  Images

   It  is  also  necessary  to install the static icon images used by the
   webmail  server.  The  installation script copies the static images to
   the /usr/lib/courier/share/sqwebmail/images directory. By default, the
   webmail server uses the URL "/webmail/" to specify the location of the
   static  images, for example: /webmail/folders.gif. This means that you
   must  create  a  subdirectory  called  "webmail"  in your web server's
   document  root  -  typically  /usr/local/etc/apache/htdocs/webmail, or
   /usr/local/www/htdocs/webmail,  or something similar. You will need to
   determine the actual location of your web root directory, which varies
   from  system  to  system. Then, create a subdirectory named "webmail",
   and copy all the icons to that directory.

   Another possibility is to install a soft link, instead of creating the
   webmail    sub    directory,    and    point    the   soft   link   to
   /usr/lib/courier/share/sqwebmail/images  (you also must make sure that
   the web server is configured to follow symlinks).

   There  is  a configuration option, --enable-imageurl, that can be used
   to use something other than /webmail/ as the URL prefix for images.

  Alternative timezones

   The    file   /usr/lib/courier/share/sqwebmail/html/en-us/TIMEZONELIST
   contains  a  list  of  alternative timezones. By default all dates and
   times  are  shown  in  the server's default timezone, and the dropdown
   list  on  the  login  screen  can  be  used  to  select an alternative
   timezone.  The  default  alternative  timezone  list that lists only a
   small  number  of  timezones. Additional timezones can be entered into
   this file to be shown on the login web page.

  LDAP address book import

   The  webmail  server  can  import  E-mail  addresses  from public LDAP
   address  books  into  an individual address book. A default systemwide
   list  of  accessible  LDAP  address books is defined for everyone, and
   individuals   can   configure   additional   LDAP  address  books  for
   themselves.

   OpenLDAP  runtime  libraries and tools are required to be installed in
   order  to  search  LDAP  address  books.  It  is not necessary to have
   OpenLDAP  development  libraries  installed. The webmail server simply
   runs  the  ldapsearch tool to query LDAP address books, and parses the
   results.

   The default list of systemwide-accessible LDAP address book is defined
   in  the  ldapaddressbook  configuration  file. See courier(8) for more
   information.

   The webmail server runs /usr/lib/courier/share/sqwebmail/ldapsearch to
   search  an  external LDAP address book. This is a wrapper shell script
   that  calls  OpenLDAP's  ldapsearch  tool.  The  configuration  script
   attempts  to  find the location of where OpenLDAP tools are installed.
   The  path  to  ldapsearch  in this shell script should be verified and
   fixed,  if  necessary.  The  default shell script adds some additional
   options  to  ldapsearch to limit the search time to sixty seconds, and
   to return a maximum of twenty entries from the address book.

OPTIONAL: Configure webmail calendaring

   Optional  calendaring  services  can be enabled in the webmail server.
   Right  now,  the  current  implementation  provides  basic calendaring
   services.   For   more   information  on  calendaring,  see  the  file
   pcp/README.html.

OPTIONAL: Configure mail filtering for the webmail server

   This  is  an  optional  feature  where  the  webmail server is used to
   automatically  set  up  mail  filtering  rules  to  forward or deliver
   incoming mail to folders. This feature requires maildrop to be used as
   the local mail delivery agent.

   Edit  the  courierd configuration file, and follow the instructions in
   that  file to install maildrop as the local mail delivery agent. Then,
   follow the instruction below to create the maildirfilter configuration
   file,  which  may be installed either in the global configuration file
   directory  (/usr/lib/courier/etc  by  default),  or in each individual
   Maildir (which overrides the global default).

   Implementing  mail  filtering  requires a couple of dominos to fall in
   the  right  order.  This  is not difficult to do, but is a bit tricky.
   Here's how it works, in general. Specifics follow.

   Some people would probably have a difficult time setting it up. That's
   to be expected. The implementation allows only selected accounts to be
   set  up  for mail filtering, so the suggested way is to attempt to set
   up mail filtering for one account only, test it to make sure it works,
   then roll it out globally.

  The big picture

   The  maildrop  mail  filter  is  used to do the actual mail filtering.
   maildrop must be installed as your local mail delivery agent. The next
   thing  to  do  is  to actually learn how maildrop works, and learn its
   filtering  language.  Although  the  mail  filter will be automaticaly
   generated  here,  you still need to become familiar with the filtering
   language  in order to troubleshoot any installation problems. maildrop
   comes with manual pages documenting the filtering language, as well as
   some examples. Read them.

  The little picture

   Here's  what's  going to happen. The webmail server will automatically
   generate  a  maildrop filtering recipe. maildrop reads the recipe, and
   does its thing. Sounds simple enough, right?

   Well,  it's  not.  There  are  a  few  little  details that need to be
   resolved.

   For    starters,    the   default   maildrop   filtering   recipe   is
   $HOME/.mailfilter.  That's  how  things  usually  work physical system
   accounts  are  used.  When virtual mailboxes are installed, things are
   less  murky.  There  are  several  ways  to  set up virtual mailboxes,
   described elsewhere in this INSTALL file, so the actual implementation
   varies from system to system. Somehow, the virtual mailboxes share the
   same physical account, and have the same $HOME. In that case the usual
   approach  is  for  each virtual mailbox to have the corresponding mail
   filtering  recipe  manually  specified to maildrop as an extra command
   line argument. Review the maildrop documentation for more information.

   Now,  on  the  other  hand,  the  webmail  server  doesn't really know
   anything  about  physical  and virtual accounts. The mapping between a
   login  ID  and  the  maildir  is  completely encapsulated in the black
   box-type authentication layer. The login ID and password are validated
   by  the  authentication layer, which obtains the maildir corresponding
   to  the  login ID, and the webmail server is started for that maildir.
   Whether  or  not a login ID corresponds to an actual system account or
   to virtual account, that's something the webmail server doesn't really
   know,  or  care.  All it cares about is the maildir where all the mail
   is,  and  that's the end of the story. (The IMAP and POP3 servers work
   the same way).

   So,   the  issue  is  that  the  webmail  server  needs  to  find  the
   corresponding  maildrop  filtering  recipe, so it knows where to write
   the mail delivery instructions. That's the deal

   In  order  for  mail  filtering  to  be  enabled,  it  is necessary to
   initialize  the  file named maildirfilterconfig in the maildir itself.
   This  is  where the webmail server runs, so it simply reads this file.
   The contents of this file should be as follows:
MAILDIRFILTER=pathtomailfilter
MAILDIR=pathtomaildir

   pathtomailfilter  specifies  the  location  of  the maildrop filtering
   recipe  for  this  maildir,  relative  to  the maildir itself. Set the
   current  directory to the maildir directory. Now ask yourself, where's
   my maildrop filtering recipe?

   In  most  cases,  where  virtual  mailboxes  are  not used, everyone's
   maildir  is  $HOME/Maildir,  and  maildrop  uses  $HOME/.mailfilter by
   default. In this case, pathtomailfilter must be set to ../.mailfilter.

   When  virtual mail accounts are used, this will obviously be something
   else.  The  only requirement is that the maildrop filtering recipe and
   the maildir must be on the same filesystem or partition.

   pathtomaildir  is  the  other  half of the story. When maildrop gets a
   message  to  deliver,  maildrop  needs to know where the mailboxes and
   folders  are.  Maildrop  begins running in what it considers to be the
   recipient's home directory, reading either .mailfilter, by default, or
   the file specified on the command line.

   The  webmail  server  needs  to  generate  filtering  instruction that
   deliver   messages  to  its  maildir.  By  default,  the  maildir  for
   non-virtual  accounts  is  $HOME/Maildir, so pathtomaildir needs to be
   set to ./Maildir.

  Summary for virtual accounts

   Basically,  99%  of  the time MAILDIRFILTER will be ../.mailfilter and
   MAILDIR  will  be  ./Maildir.  When  virtual  mail  accounts are used,
   maildrop  still  must  be  used as a mail delivery agent. Somehow, the
   correct  maildir that corresponds to the recipient's mail account must
   be  specified as the argument to maildrop. Usually all or most virtual
   accounts  are set up inside a single physical account. In that case it
   is  necessary to set up a different maildrop filtering recipe file for
   each  virtual mail account (since everyone's $HOME/.mailfilter will be
   the  same  file), and in each maildir specify the relative path to its
   corresponding  filtering  recipe, and the relative path to the maildir
   from  the default home directory. Then, for each virtual mail account,
   the  mail  server  must  run  maildrop to do the actual mail delivery,
   explicitly specifying the filtering recipe to be used.

  The global maildirfilterconfig file

   In  most  cases  where  virtual  mail  accounts  are  not  used, every
   maildir's maildirfilterconfig should be the same. As an alternative to
   installing  the  same  maildirfilterconfig  in  each  maildir,  it  is
   possible to install a single maildirfilterconfig systemwide.

   Install  the  global  maildirfilterconfig  in  Courier's configuration
   directory (/usr/lib/courier/etc by default).

   The global maildirfilterconfig will be used unless maildirfilterconfig
   exists    in    the   maildir   directory.   Therefore,   the   global
   maildirfilterconfig  can be used to provide a default for the majority
   of  the  mail  accounts,  and any exceptions are handled by installing
   maildirfilterconfig  in  the  maildir  directory,  whose contents will
   override the global file.

  Happy filtering.

   If everything is set up correctly, the webmail menu will present a new
   link to a screen where mail filtering rules are defined and installed.
   A  mail  filter consists of a condition, and an action. A condition is
   usually  based  on  the  contents of some header, or the message body.
   Regular  expressions  are  allowed.  Which  means that certain special
   characters  must  be  quoted.  For  example,  to search for the string
   "[announce]"  verbatim  in  the  subject header, it must be entered as
   "\[announce\]".  Pattern  matching,  for now, is case-insensitive. The
   regular  expression  syntax  uses pretty much the same syntax as Perl.
   See the maildropfilter manual page for more information.

   Multiple  mail  filtering rules can be installed. Their relative order
   can be rearranged by selecting a filtering rule, then selecting either
   the  "Up"  or  the  "Down" button. It is necessary to select "Save all
   changes"  for  any  changes  to  the  filtering  rules to take effect.
   Leaving that page in any other way will throw away all changes made.

OPTIONAL: Changing mail account passwords using the webmail server

   After  installing  the  webmail  server be sure to test that the login
   password  can  be  changed  through the webmail server (ignore this if
   --disable-changepass  was specified). Be sure to change the password a
   couple of times, logging out and back in each time.

   For  the  virtual  domain  modules  (authldap, authmysql, and friends)
   changing  the  login is a no-brainer. The tricky situation is when the
   webmail   server  uses  system  passwords  to  log  in  (the  authpwd,
   authshadow,  or  authpam authentication module). Different systems use
   different   ways  to  keep  login  passwords.  Many  systems  use  the
   traditional  /etc/passwd  and  /etc/shadow  files. Other systems use a
   binary  database;  other  systems  use  NIS.  And  on some systems the
   password  file  lookup  library  is  a  wrapper  that  goes against an
   external LDAP directory, or a database. For maximum compatibility, the
   webmail  server changes login passwords by running the passwd command.
   This  is  the  traditinal  *nix  command that changes login passwords.
   passwd  is  an interactive command. It's normally run from a terminal.
   the  webmail server uses an expect script - as mentioned in Overview -
   to  answer  interactive prompts from passwd. The expect script expects
   to  get  a plain, garden-variety, passwd command, which acts something
   like this:
     # passwd
     Changing password for luser
     (current) UNIX password:         (old password typed here)
     New UNIX password:               (new password typed here)
     Retype new UNIX password:        (new password retyped here)
     passwd: all authentication tokens updated successfully
     #

   Systems that use a passwd command with very different prompts may find
   that  the  default  expect  script will fail. In which case it will be
   necessary  to  tweak  the  expect script to match the prompts from the
   system's passwd command.

   Modern  systems  use  a  passwd command that rejects "bad" passwords -
   passwords  that  are  based on dictionary words, are too short, or are
   obvious  for  other reasons. When testing the webmail server's ability
   to change system passwords be sure to use randomly-generated gibberish
   for  the  test  passwords.  Otherwise,  the default expect script will
   actually be working, but you won't be the wiser. For security reasons,
   the actual messages passwd will not be shown by the webmail server.

OPTIONAL: Configure autoreplies for the webmail server

   Enabling mail filtering, according to the instructions in the previous
   section,  automatically enables MIME autoreply capability. The webmail
   interface  can  be used to configure simple autoresponders. By default
   there  is  no  limit on the number of the size of created autoreplies,
   therefore it is recommended that a quota be set up on the autoreplies.

   An   global   autoreply   quota   is   set   up  by  initializing  the
   /usr/lib/courier/etc/autoresponsesquota  configuration file. This file
   sets  the  autoreply quota globally. An autoresponsesquota file in the
   Maildir  will override the global quota setting for that maildir only.
   See   the   courier(8)   manual   page  for  the  description  of  the
   autoresponsesquota file.

   Autoreplies  can  include  any  valid MIME content (MIME content other
   than  plain  text  can  be  uploaded). The following special procedure
   needs  to be used to prepare multipart autoreply content, such as text
   and html alternatives of the same message:

   Assign  a  filename  extension to the message/rfc822 MIME content. For
   example,  edit your mime.types file, find the message/rfc822 MIME type
   (append  one  if it's not in mime.types), and make sure that it has at
   least one filename extension, such as "msg".

   Prepare  the  multipart  MIME autoreply. The most convenient way is to
   prepare  a  normal  E-mail message using a conventional E-mail client.
   Save  the  RFC822-formatted message in a file with a ".msg" extension,
   and upload it on the autoreply screen.

   Webmail  handles  uploaded  message/rfc822  content  by  removing  all
   headers except the MIME headers, leaving the MIME content type header,
   and the actual MIME content.
   Normally  there  is  no  limit  on  the  number  or  the total size of
   autoreplies  configured  via  the  webmail  server.  A  quota  can  be
   installed  by  initializing the autoresponsesquota configuration file.
   See courier(8) for more information.

OPTIONAL: Configure encryption for the webmail server

   This  is  an optional feature in the webmail server that uses GnuPG to
   send  and receive encrypted/signed E-mail. There is no encryption code
   in  the webmail server, it uses GnuPG to do encryption and decryption.
   For more information on setting up and using encryption, read the file
   gpglib/README.html in the source distribution.

OPTIONAL: Quota support

   There are two ways to implement a quota on the size of a mail account:
   filesystem quotas and maildir quotas:

  Filesystem quotas

   The  maximum  disk  space  quota  is  implemented within the operating
   system's  filesystem support code. Here, the operating system enforces
   the  maximum  disk space that can be used by each account. This is the
   only  reliable  quota implementation if individual accounts have login
   access to the mail account. Maildir quotas (see below) are implemented
   entirely   within   the  maildir  support  code,  and  can  easily  be
   superceeded   by  anyone  with  login  access  to  the  mail  account.
   Additionally,  mail  accounts  must  all  be  system accounts. Virtual
   accounts  --  that  share  the  same  physical system userid -- cannot
   usually  be  support  by  filesystem-based  quotas,  because  all mail
   accounts have the same userid and groupid.

   The  webmail server cannot be used with filesystem quotas. The webmail
   server  creates  and  maintains,  all  by itself, a number of database
   files  that  are  used  to  quickly  index  and access messages. If an
   account exceeds its disk quota, the webmail server will not be able to
   create  and  update  those  database  file,  which results in a rather
   spectacular crash. If login access is available, it is possible to log
   in and manually delete some files to reclaim some disk space. If login
   access  is  not available, the administrator will have to manually fix
   the  account  --  the  webmail server will not even be able to open an
   existing  folder  and  delete messages in order to free up disk space.
   There  is  some  good  news,  though: the IMAP and the POP3 server can
   still be used to access and delete messages from the mail account. Due
   to  the way that out-of-quota condition is handled by the IMAP server,
   some  IMAP  clients  may  mark any existing messages in the account as
   unread, but that is a minor glitch that does no harm.

  Maildir quotas

   Courier  can  manually  enforce  a  quota  for  mail accounts that use
   maildirs.  This quota enforcement is implemented entirely in software,
   and   is   available   only   when   maildirs  are  used.  This  quota
   implementation  will  also  work  with virtual accounts. Maildir quota
   support  is  available  only  with  userdb, LDAP, MySQL and PostgreSQL
   authentication  back-ends. Maildir quotas are supported by IMAP, POP3,
   and  the  webmail  server. To add a maildir quota with userdb, run the
   following commands, for example:
userdb account set quota=quota
makeuserdb

   Here,  account  identifies the account to which the quota applies, and
   quota  is the quota specification, as described in the maildirquota(7)
   manual page.

   To  implement  a  quota with an LDAP, MySQL, or a PostgreSQL back end,
   simply   follow   the   instructions   given   in   the  corresponding
   configuration file.

OPTIONAL: Configure outbound faxing

   Fax  sending  is  disabled  by default and must be explicitly enabled,
   according to the following instructions. After fax sending is enabled,
   addressing  an  E-mail message to <5552000@fax> will have this message
   faxed.

   Of  course, the necessary hardware and software must be available. The
   requisite  hardware  is  a class 2 faxmodem attached to a serial port.
   Additional  software,  separate  from Courier, must also be installed.
   Courier  does  not  handle  the  actual  job  of  faxing. Courier only
   reformats  E-mail  messages  as fax images, and runs mgetty+sendfax to
   send the fax. Courier also needs additional software to convert E-mail
   messages   to  faxes.  All  additional  software  must  be  separately
   installed,  configured,  and tested before enabling faxing in Courier.
   Most  systems  already  include  the following software as part of the
   base  operating  system,  so in most cases adding fax support will not
   actually  require  any additional software to be installed, only minor
   reconfiguration of existing software:

  mgetty+sendfax

   mgetty+sendfax works with most Class 2 faxmodems. Courier does not use
   the spooling scripts found in the mgetty+sendfax package. Courier uses
   its  own  mail spool. A fax message is handled no differently than any
   other  E-mail  message. The only difference is that the E-mail message
   is addressed to <phonenumber@fax>.

   mgetty+sendfax  should be configured with its default settings, EXCEPT
   as follows:

     * In  /etc/mgetty+sendfax,  the "max-tries-continue" setting must be
       set to "n".

  groff or troff, ghostscript, NetPBM

   Conversion of E-mail messages to faxes uses ghostscript, and groff. It
   should  be  possible  to use the original UNIX troff instead of groff,
   but  this  has  not  been tested. Courier generates the fax cover page
   from  the  contents  of the E-mail message's headers. The initial text
   portion  of the E-mail message will appear as fax cover page comments.
   Note  that  the  initial text portion of the E-mail message must be in
   plain  text,  not  HTML.  E-mail  attachments  will  be  converted and
   attached as additional fax pages. E-mail attachments may contain plain
   text,  Postscript  or  PDF documents. Other attachments will result in
   the E-mail message being returned as undeliverable.

   Install  the  NetPBM  library  is installed, to add the ability to fax
   GIF,  JPEG,  and  PNG images. Each image will be converted to a single
   fax page. Images in excess of 1500x1500 pixels (approximately) will be
   truncated, and color images will be dithered to black-and-white.

  Enabling faxing

   The  configuration  file  /usr/lib/courier/etc/faxrc must be edited in
   order  to enable faxing. This file sets up the dialing parameters, and
   the  default  file disables faxing by rejecting all phone numbers. The
   configuration  file  has  extensive  comments that explain how dialing
   parameters are set.

   Using  webadmin  to set up fax sending is highly recommended. A proper
   faxrc  will  automatically  hide  all  the  local  daling conventions.
   Webadmin knows how to generate the dialing configuration for the North
   American  dialing plan, with a configurable area code. Faxes should be
   addressed  to  a  fixed  ten  digit  area  code+phone  number address,
   <nnnxxxxxxx@fax>,  which  will be converted for dialing from the local
   area code appropriately. Webadmin can also optionally enable faxing to
   international 011 phone numbers. Webadmin can also fall back to a bare
   configuration  where all phone numbers are dialed as-is, for locations
   outside of North America.

  Sending faxes

   E-mail   messages   may  contain  attachments.  Courier  combines  all
   attachments  in the message into a single fax transmission. Attachment
   types  may  be  freely  mixed.  A single message may contain one plain
   text,  and  one  PDF attachment, for example. It is possible to select
   certain options, as follows:
     * <phonenumber@fax-lowres> - sends a low-resolution fax.
     * <phonenumber@fax-ignore> - Ignore attachments that Courier doesn't
       know  how  to  convert  to  a  FAX  image  format. Normally, if an
       attachment  cannot  be  converted the whole message is returned as
       undeliverable.
     * <phonenumber@fax-cover>  -  sends only the cover page. This can be
       useful  for  .courier files. See the courierfax(8) manual page for
       an example.

   These options can be combined: <phonenumber>@fax-lowres-ignore>.

  Cover pages

   /usr/lib/courier/etc/faxcoverpage.tr  is  the troff source for the FAX
   cover  page, which includes the first plain text section of the E-mail
   message.  Do  not attempt to play with faxcoverpage.tr without a clear
   understanding  of  troff.  It is safe to make trivial changes (such as
   replacing the "FACSIMILE COVER PAGE" text).

  Dialing

   The /usr/lib/courier/etc/faxrc configuration file provides rudimentary
   phone  number  rewriting logic (stuff like dialing "9," to get outside
   line  from  a  PBX).  The default faxrc configuration file specifies a
   typical  dialing  configuration for the North American numbering plan,
   with  seven  digit  local phone numbers, and 1+ten digit long distance
   phone  numbers.  The area code in the default faxrc configuration file
   is  set  to "999", you will need to change it to your area code (there
   are two places in faxrc where the area code needs to be set).

   In  general,  messages should be addressed to the full ten-digit phone
   numbers.  The  local area code will be stripped automatically, and "1"
   will  be  dialed  before  all  other  area  codes.  If this is done in
   practice,  local  area  code  changes  will  only require an update to
   faxrc, without any need to update the address book.

   Comments  in  the  faxrc  configuration file explain the format of the
   phone  number  rewriting  rules,  in the event that local phone system
   customization  is  required  (for example, dialing 9 to get an outside
   line).  Several  places in North America now use ten digit local phone
   number  overlays,  with  1+ten  digit long distance dialing. TODO: Use
   webadmin if you are not sure how to set this up.

  Security

   The  default  faxrc  configuration  file allows only locally-generated
   faxes. faxrc must be modified in order to accept faxes via ESMTP.

   Additionally,  faxes are accepted via ESMTP only if the FAXRELAYCLIENT
   variable  is  set.  See  the makesmtpaccess(8) man page for additional
   information.

OPTIONAL: Configure inbound faxing

   mgetty  has  an  option  that  runs a script called "new_fax" after it
   receives  a  fax.  The  default  location  for  this  script is either
   /usr/local/lib/etc/mgetty+sendfax/new_fax or
   /etc/mgetty+sendfax/new_fax.  Consult  your  mgetty  documentation  to
   determine  if  the  new_fax  option  is  enabled, and the exact script
   location.

   Courier  provides  a script - /usr/lib/courier/share/faxmail/new_fax -
   that  can  be  used  as  mgetty's new_fax script. This script converts
   incoming  faxes  to  PNG  images,  and delivers it to a local mailbox.
   Simply  copy  this script to mgetty's etc directory (or install a soft
   link   there),  to  automatically  drop  incoming  faxes  to  a  local
   mailboxes.

   The  /usr/lib/courier/etc/faxnotifyrc configuration file specifies the
   mailbox  that  receives  incoming  faxes,  and  several  other related
   options.

Decommission your existing mail server

   This  steps  consists of flushing the mail queue of your existing mail
   server and removing it from the system.

   If you're using sendmail, edit your startup script, and start sendmail
   with  the  option  '-q30m'  only.  Remove  the -bd option. This causes
   sendmail  to  stop  listening on port 25, and stay as a daemon process
   only for the purpose of running the queue every 30 minutes.

   If  you're  using  Qmail,  remove  tcpserver  from your system startup
   script.

   Wait  for  all  existing  mail  to  flush itself out, then permanently
   remove your existing server.

   Depending  on  your  system,  you  may  need to create a bunch of soft
   links,  such  as /usr/bin/sendmail, /usr/sbin/sendmail, /lib/sendmail,
   or  /etc/sendmail  that point to /usr/lib/courier/bin/sendmail. If you
   want  to  receive  mail  via UUCP you will also need to make sure that
   UUCP knows to find rmail in /usr/lib/courier/bin as well.

Sample init script

   You're  now  ready to configure your system to start Courier at system
   boot  time  (and shut it down at system shutdown). If your system uses
   system-V  init scripts, here's a sample script that you can install in
   your /etc/rc?.ddirectories. This is a slightly modified version of the
   init  script  that's  used in my RPM package (courier.sysvinit file in
   the source code tarball).

   NOTE:  the  following  script may take a long time to finish, the very
   first  time  it  runs. That's because the script automatically creates
   test  SSL  certificates  the first time the script runs (provided that
   SSL  support  is available). This can take as much as 5-6 minutes on a
   slow machine. Subsequent starts should take only a few seconds.
#! /bin/sh
#
# chkconfig: 2345 35 65
# description: Courier - SMTP server
#
# NOTE: The 'restart' here does a "hard" stop, and a start.  Be gentle, use
# "courierd restart" for a kindler, gentler, restart.
#
#

prefix="/usr/lib/courier"
exec_prefix="/usr/lib/courier"
sysconfdir="/usr/lib/courier/etc"
sbindir="${exec_prefix}/sbin"
libexecdir="/usr/lib/courier/libexec"
datadir="/usr/lib/courier/share"

case "$1" in
start)
        cd /
        # Start daemons.
        touch /var/lock/subsys/courier

        echo -n "Starting Courier mail server:"

        # First time after install create aliases.dat and makesmtpaccess.dat

        test -f ${sysconfdir}/aliases.dat || ${sbindir}/makealiases

        esmtpdcert=0

        . ${sysconfdir}/esmtpd
        case x$ESMTPDSTART in
        x[yY]*)
                esmtpdcert=1
                ;;
        esac

        test -f ${sysconfdir}/${ACCESSFILE}.dat || ${sbindir}/makesmtpaccess

        . ${sysconfdir}/esmtpd-msa
        case x$ESMTPDSTART in
        x[yY]*)
                esmtpdcert=1
                ;;
        esac

        test -f ${sysconfdir}/${ACCESSFILE}.dat || ${sbindir}/makesmtpaccess-ms
a

        ${sbindir}/courierfilter start
        echo -n " courierfilter"

        if test -x ${libexecdir}/authlib/authdaemond
        then
                ${libexecdir}/authlib/authdaemond start
                echo -n " authdaemond"
        fi

        if test -x ${sbindir}/courierldapaliasd
        then
                ${sbindir}/courierldapaliasd start
                echo -n " courierldapaliasd"
        fi


        case "`cat ${sysconfdir}/calendarmode 2>/dev/null`" in
        net)
                if test -x ${libexecdir}/courier/pcpd
                then
                        ${libexecdir}/courier/pcpd start
                fi
                echo -n " pcpd"
                ;;
        *)
                ;;
        esac

        ${sbindir}/courier start
        echo -n " courierd"

        if test "$esmtpdcert" = 1
        then
# If we do not have a certificate, make one up.

                if test ! -f ${datadir}/esmtpd.pem
                then
                        if test -x $COURIERTLS
                        then
                                echo -n " generating-ESMTP-SSL-certificate..."
                                ${sbindir}/mkesmtpdcert >/dev/null 2>&1
                        fi
                fi
        fi

        . ${sysconfdir}/esmtpd
        case x$ESMTPDSTART in
        x[yY]*)

                ${sbindir}/esmtpd start
                echo -n " esmtpd"
                ;;
        esac

        . ${sysconfdir}/esmtpd-msa
        case x$ESMTPDSTART in
        x[yY]*)

                ${sbindir}/esmtpd-msa start
                echo -n " esmtpd-msa"
                ;;
        esac

        if test -x ${sbindir}/pop3d
        then
                POP3DSTART=""
                POP3DSSLSTART=""

                if test -f ${sysconfdir}/pop3d
                then
                        . ${sysconfdir}/pop3d
                fi
                case x$POP3DSTART in
                x[yY]*)
                        ${sbindir}/pop3d start
                        echo -n " pop3d"
                        ;;
                esac
                if test -f ${sysconfdir}/pop3d-ssl
                then
                        . ${sysconfdir}/pop3d-ssl
                fi
                case x$POP3DSSLSTART in
                x[yY]*)
                        if test -x $COURIERTLS
                        then
# If we do not have a certificate, make one up.

                                if test ! -f ${datadir}/pop3d.pem
                                then
                                        echo -n " generating-POP3-SSL-certifica
te..."

                                        ${sbindir}/mkpop3dcert >/dev/null 2>&1
                                fi

                                ${sbindir}/pop3d-ssl start && \
                                        echo -n " pop3d-ssl"
                        fi
                        ;;
                esac
        fi

        if test -x ${sbindir}/imapd
        then
                . ${sysconfdir}/imapd
                case x$IMAPDSTART in
                x[yY]*)
                        ${sbindir}/imapd start
                        echo -n " imapd"
                        ;;
                esac
                . ${sysconfdir}/imapd-ssl
                case x$IMAPDSSLSTART in
                x[yY]*)
                        if test -x $COURIERTLS
                        then
# If we do not have a certificate, make one up.

                                if test ! -f ${datadir}/imapd.pem
                                then
                                        echo -n " generating-IMAP-SSL-certifica
te..."

                                        ${sbindir}/mkimapdcert >/dev/null 2>&1
                                fi

                                ${sbindir}/imapd-ssl start && \
                                        echo -n " imapd-ssl"
                        fi
                        ;;
                esac
        fi

        echo ""
        ;;
stop)
        echo -n "Stopping Courier mail server:"

        if test -x ${sbindir}/imapd
        then
                ${sbindir}/imapd stop
                echo -n " imapd"
        fi

        if test -x ${sbindir}/imapd-ssl
        then
                ${sbindir}/imapd-ssl stop
                echo -n " imapd-ssl"
        fi

        ${sbindir}/esmtpd-msa stop
        echo -n " esmtpd-msa"

        ${sbindir}/esmtpd stop
        echo -n " esmtpd"

        if test -x ${sbindir}/pop3d
        then
                ${sbindir}/pop3d stop
                echo -n " pop3d"
        fi

        if test -x ${sbindir}/pop3d-ssl
        then
                ${sbindir}/pop3d-ssl stop
                echo -n " pop3d-ssl"
        fi

        ${sbindir}/courier stop
        echo -n " courierd"

        if test -x ${sbindir}/courierldapaliasd
        then
                ${sbindir}/courierldapaliasd stop
                echo -n " courierldapaliasd"
        fi

        if test -x ${libexecdir}/courier/pcpd stop
        then
                ${libexecdir}/courier/pcpd stop
                echo -n " pcpd"
        fi

        if test -x ${libexecdir}/authlib/authdaemond
        then
                ${libexecdir}/authlib/authdaemond stop
                echo -n " authdaemond"
        fi
        ${sbindir}/courierfilter stop
        echo " courierfilter"
        ;;
restart)
        $0 stop
        $0 start
        ;;
esac
exit 0

   The  reason  I  test  for  the  existence  of the POP3 and IMAP server
   binaries  is  because  I  build  the POP3 and IMAP servers as separate
   sub-packages,  that do not have to be installed. These tests avoid the
   need for each sub-package to install its own startup script.
     _________________________________________________________________

   PREV: Status/Download NEXT: FAQ
