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

                                  Installation

Building rpm and deb packages

These are not the same packages as the ones from various distributions'
repositories. These packages carry a higher internal revision level in order to
prevent them from getting upgraded by the distribution packaging. These packages
exist in order to have a convenient way of updating after a release without
waiting for the distribution's package to get built.

NOTE: If a distribution package is already installed it should be removed
completely before switching to the upstream version (dnf remove or apt purge).
Preserve any existing configuration files, beforehand, in order to restore it
after switching packages. This applies to all Courier packages. A switch to this
courier package requires switching the courier-unicode and courier-authlib
packages too.

NOTE: These packages use their own, generic, installation layout that may
deviate slightly from the package installation conventions preferred by the
distributions:

  • The main "courier" package. This installs the main mail server that starts
    locally but does not listen on the smtp port until the appropriate esmtpd
    configuration files enable the smtp port listener(s).

  • The "courier-maildrop" package. This package installs the maildrop mail
    filter.

  • The "courier-imapd" and "courier-pop3d" packages. Installing them results in
    the IMAP and the POP3 server getting started and listening on the respective
    ports, and a self-signed SSL certificate gets automatically generated, for
    testing purposes, until it gets replaced by your real one.

  • The "courier-webmail" package. This package installs the sqwebmail webmail
    server.

  • The "courier-mlm" package. This package installs the couriermlm mailing list
    manager.

  • The "courier-mlm-web" package. This package installs couriermlm's web-based
    gateway.

  • The "courier-webadmin" package. This installs the webadmin module, for a
    basic browser-based configuration module. The "courier-ldap" module installs
    the LDAP-based alias daemon and the webadmin page for configuring it. The
    "courier-mysql" and "courier-pgsql" packages install webadmin pages for
    configuring mysql and postgres-based account authentication. The
    "courier-fax" package installs webadmin pages and scripts for integrating
    with the mgetty+sendfax gateway.

  • deb only: the "-apache2" deb packages install apache2 configuration files
    that enable each corresponding module.

The main "courier" package starts all modules, whichever modules are installed.
Depending on the distribution installing the main "courier" package may or may
not automatically start it. Installing or uninstalling an additional package
with a service may or may not result in an appropriate restart.

  rpm

Run dnf install rpm-build if it's not installed already, then:

rpmbuild -ta courier-version.tar.bz2

If this fails due to any missing dependencies, install them. This will
eventually create source and binary RPM packages. This works for all Courier
packages.

  Changing the options that the RPMs are built with

Building the RPMs directly from the source tarball uses the default options
programmed into the tarball. Sometimes you may want to use different options.
For example, you might want to enable fixes for certain bugs in some IMAP
clients. Use the following procedure to build the RPMs with different options:

  • First, build the RPM packages using the default options.
  • In addition to binary RPM packages, rpmbuild will create a source RPM
    package (filename.src.rpm)
  • Install the source RPM package: rpm -i courier-version.src.rpm.
  • The contents of the source RPM package get installed into your rpm build
    directory, which is usually $HOME/rpm/package.
  • Edit the .spec file, modifying the default configuration. You will need to
    have some understanding of how RPM spec files work, then use the modified
    spec file to build your custom package: rpmbuild -ba filename.spec

    Rocky/RHEL 8/9 notes

Courier packages require C++17 support, but the default version of gcc does not
fully support it, and a newer gcc is needed:

dnf install --enablerepo=crb -y gcc-toolset-14
scl enable gcc-toolset-14 "rpmbuild -ta courier-VERSION.tar.bz2"

Building DEB packages

Create an empty directory and copy/move the tarball into it:

$ mkdir tmp
$ mv courier-VERSION.tar.bz2 tmp
$ cd tmp

Unpack the tarball and cd into the unpacked subdirectory:

$ tar xvf courier-VERSION.tar.bz2
$ cd courier-VERSION

Run the courier-debuild script, which is a wrapper for debuild, and forwards its
parameters to it:

$ courier-debuild -us -uc

NOTE: the above steps must be followed strictly. The courier-debuild script
expects the distributed tarball in its parent directory.

NOTE: if the courier-debuild script stops with an error complaining about
missing dependencies, then use "apt install" to install them, then try again.

This eventually produces a deb subdirectory with .deb packages that can be
installed with "dpkg -i".

NOTE: All Courier packages should be built with the same version of gcc, which
is selected by the DEBGCC environment variable before running courier-debuild.
See courier-unicode's INSTALL for more information.

  Ubuntu and Debian

Courier packages require C++17 support, but the default version of gcc on Ubuntu
20 does not fully support it, and a newer gcc is needed:

$ sudo apt install -y gcc-10 g++-10
$ DEBGCC=10 ./courier-debuild -us -uc

make check requires both the ISO-8859-1 based en_US locale in addition to the
default en_US.UTF-8, on all versions of Ubuntu and Debian.

Maintainer Mode (see README in the git repository to set up)

make rpm or make deb, as appropriate, will:

 1. Increment an internal release number.

 2. Run make dist.

 3. Proceed and build a new release, creating the native packages in the rpm or
    deb subdirectory.

Manual installation

> ═══════════════════════════════════════════════════════════════════════════════

> NOTE:

> This documentation describes manual installation of the Courier mail server.
> This is a somewhat involved process that may overwhelm people that do not have
> prior experience with installing large software packages. Many distributions
> have a separately-maintained, preconfigured, ready-to-install packages that
> can be loaded with much less investment of time. Installing a pre-built
> package would probably be the best approach in this case.

> Should you choose to install a platform-specific prebuilt package, you should
> carefully read any custom documentation files that are included in the
> package. Most platform-specific packages provide custom, non-default
> configuration settings that are optimized for that platform's unique policies.
> Feedback about platform-specific precompiled packages should be copied to the
> development group that maintains the package, in additional to the
> platform-neutral courier-users mailing list.

> ═══════════════════════════════════════════════════════════════════════════════

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

Fortunately, it gets easier with each subsequent installation. The Courier mail
server 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.

The Courier mail server'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 the
Courier mail server 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.

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
  • OPTIONAL: Install the Socks 5 client toolkit
  • Run configure
  • 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
  • Backscatter suppression
  • Miscellaneous configuration
  • Define local domains
  • OPTIONAL: Configure UUCP
  • OPTIONAL: Configure LDAP aliasing
  • OPTIONAL: Enable standard mail filters
  • OPTIONAL: Configure custom mail filtering
  • Create a list of domains to accept mail for
  • Starting and stopping the Courier mail server
  • Run the Courier mail server in parallel to your mail server
  • OPTIONAL: Configure ESMTP authentication and SSL
  • OPTIONAL: Configure ESMTP smarthosting
  • OPTIONAL: Configure the SECURITY ESMTP extension
  • OPTIONAL: Configure the Sender Policy Framework
  • OPTIONAL: Configure the IMAP server
  • OPTIONAL: Configure IMAP shared folders
  • OPTIONAL: Configure IMAP over SSL
  • OPTIONAL: Certificate Authentication
  • OPTIONAL: Sending mail via an IMAP connection
  • OPTIONAL: Configure IMAP realtime folder status updates
  • OPTIONAL: Configure SMAP
  • OPTIONAL: Configure the POP3 server
  • OPTIONAL: Configure POP3 over SSL
  • OPTIONAL: Configure the IMAP/POP3 aggregator proxy
  • 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: Install automatically-appended footer text for webmail messages
  • OPTIONAL: Quota support
  • OPTIONAL: Account OPTIONS
  • OPTIONAL: Configure outbound faxing
  • OPTIONAL: Configure inbound faxing
  • OPTIONAL: Install the Courier mail server log analyzer
  • OPTIONAL: Configure Courier IP address-specific settings for servers with
    multiple IP addresses
  • OPTIONAL: Configure hostname-dependent configuration
  • Decommission your existing mail server
  • Sample init script

Upgrading an existing installation

  Upgrading from the Courier mail server 1.0.16 or earlier

The IMAP server switched to using the inotify kernel API directly instead of the
legacy FAM/Gamin daemon. When using virtual mail accounts it will be necessary
to increase the kernel's configured limit on the maximum number of inotify file
descriptors, see the IMAP server configuration notes, below.

  Upgrading from the Courier mail server 0.73.1, or earlier

The unicode library in Courier is now a separate package. Download the Courier
Unicode Library before updating to 0.74, or later.

  Upgrading from the Courier mail server 0.72, or earlier

Version 0.73 removes the TLS_DHCERTFILE parameter from esmtpd, esmtpd-ssl, imap,
and pop3d configuration files. DH parameters, and DH parameters only, get read
from the new TLS_DHPARAMS file (and the other functionaly of TLS_DHCERTFILE, for
DSA certificates, is merged into TLS_CERTFILE). After upgrading, run the
mkdhparams script to create a new TLS_DHPARAMS file.

  Upgrading from the Courier mail server 0.66.3, or earlier

In 0.67, the IMAP server resets the epoch for an internal sequence number
generator for new mailboxes. This is an internal attribute of individual IMAP
folders, that's defined by the IMAP specification. Each folder in a mailbox
carries an individual sequence number, it is defined as a 32 bit integer value,
and required to be a monotonically increasing value. and RFC 2060 recommended
that "... a good value to use for the unique identifier validity value is a
32-bit representation of the creation date/time of the mailbox."

On modern platforms, the system time is now a 64 bit value (even on the
remaining 32 bit platforms). With Y2038K on the horizon, it's time to reset the
epoch (the new epoch, for anyone who cares, runs until the year 2069). The
upgrade impact on existing systems is as follows.

There is no impact on existing folders in existing mailboxes. New folders will
have their internal sequence number in the new epoch.

One potential issue exists if a folder gets deleted by the IMAP client, and then
recreated later. The new folder will now get a lower sequence number. Although
this is technically not allowed, it's unlikely to cause problems with most IMAP
clients. If the same IMAP client deletes and recreated the mailbox, the client
should be completely up to speed. If, however, there's an IMAP client that
accesses the same folder, and some other IMAP client deletes and recreates the
same folder, this might cause confusion. Most IMAP clients are likely to recover
automatically; most IMAP clients only care that the new sequence number they see
is different from the previous one, in order to trigger a full resynchronization
with the server. In case an IMAP client fails to resynchronize, the remedy is to
remove the IMAP account configuration from the client, and add it back in.

Copying a mailbox by directly copying the files in maildirs preserves each
folder's epoch. However if a mailbox gets migrated by copying its contents over
IMAP, the folders on the destination IMAP server will not necessarily have a
monotonically higher value -- neither does IMAP guarantee that different IMAP
servers must be in agreement with each other on the subject of sequence numbers
-- and if IMAP clients are repointed to a new server they may experience
problems opening existing mailboxes. To remedy this situation it will be
necessary to completely remove and then reconfigure the IMAP account, in the
IMAP client. Again, verbatim copying of maildirs has no issues.

A marginal situation exists where if a server completely runs of disk space, or
if there's a hardware failure, and the IMAP server is unable to retrieve or save
an existing folder's sequence number, and must now start afresh and generate a
new one, the IMAP server running on a new epoch will recover with a lower
sequence than the one that existed before. The rememdy is the same: remove the
IMAP account configuration from the client, and then recreate it.

  Upgrading from the Courier mail server 0.63.0, or earlier

There's a new setting, SYSLOCALE, in the courierd configuration file, which
initializes the environment from the default system locale. The configuration
script heuristically searches for a list of known locale initialization scripts
on various platforms, if found.

If your platform's locale configuration script's name is not known to the
configuration script, manually specify your default system locale in this
configuration setting.

  Upgrading from the Courier mail server 0.55.1, or earlier

The webmlmd tool has been significantly enhanced, with a new administration
screen that consists of three new template files: style.css.tmpl,
webmlmlistadmin.tmpl.html, and webmlmlistadminpw.html.html. These three template
files must be installed in each mailing list directory. You may copy them
manually, or use the couriermlm update command. couriermlm update overwrites all
your list-specific customizations, so make backups first!

  Upgrading from the Courier mail server 0.54.2, or earlier

The logic for outbound authenticated SMTP has changed. This is when the Courier
mail server sends outbound mail through a smarthost that requires
authentication.

The specified smarthost's name is still looked up in DNS, as before. When
smtp.example.com is specified as the smarthost's name, The Courier mail server
looks up any MX or A records for smtp.example.com. A connection gets established
to a server whose name may be different than the original DNS hostname, if it
gets redirected via an MX or a CNAME record.

In earlier versions of the Courier mail server, the smarthost's userid and
password must be listed using the resulting server's physical, resolved name.
Starting with version 0.55, the smarthost's original DNS name must be listed
instead. In all cases now, the name of the server listed in esmtpauthclient will
now match the name specified in esmtproutes.

After updating to 0.55, the contents of the esmtpauthclient configuration file
may need updating.

IMPORTANT: After updating to 0.55, all existing couriermlm mailing list
directories must be updated with new configuration files. See the "update"
command in the "MANUAL COMMANDS" section of the couriermlm(1) manual page. If
you run many mailing lists, you are strongly advised to install the new version
of the Courier mail server on another machine and become re-acquainted with
couriermlm's configuration. In an emergency, make a backup copy of the
couriermlm command from your existing version of the Courier mail server, before
installing this update.

  Upgrading from the Courier mail server 0.51, or earlier

Version 2.0 of maildrop, in the Courier mail server 0.52, introduces a new
pattern matching engine that uses the PCRE library, that uses a completely
different syntax. However, very few changes should be required to upgrade
existing maildrop recipes to the new syntax.

After upgrading from the Courier mail server 0.51, or earlier, review the
maildropfilter manual page which has been revised to document the new pattern
matching syntax. The legacy pattern matching engine is still available by
setting MAILDROP_OLD_REGEXP to 1. See also the "Conversion of maildrop 1.x
pattern to 2.0" section in the manual page, for more information.

  Upgrading from the Courier mail server 0.49.0, or earlier

couriermlm's default configuration now treats both the userid and the domain
portion of E-mail addresses as case-insensitive.

Any existing mailing list that has subscribers whose E-mail addresses contain
uppercase addresses must explicitly set the new CASESENSITIVE=1 list option,
using the couriermlm command, otherwise those subscribers will have problems
unsubscribing or posting messages to the list.

  Upgrading from the Courier mail server 0.48.2, or earlier

The Courier mail server's default configuration now includes backscatter
suppression. Review Backscatter suppression, below, for any needed configuration
changes.

  Upgrading from the Courier mail server 0.47, or earlier

Beginning with 0.48, the authentication library that used to be a part of the
Courier mail server's source has been spun off into a standalone authentication
library.

You must download and install the Courier mail server authentication library
from https://www.courier-mta.org/authlib/ before upgrading. Review the
documentation in the courier-authlib package for more information.

As part of installing courier-authlib, the configuration files in the Courier
mail server's configuration directory that relate to authentication will be
copied to courier-authlib's configuration directory. The files are:
authdaemonrc, authmysqlrc, authpgsqlrc, authldaprc, and userdb (together with
the .dist versions). This works only as long as the Courier mail server was
installed in one of the known default installation directories. The
documentation in courier-authlib explains what to do if the existing version of
the Courier mail server is installed in a non-default location.

In any case, after upgrading to 0.48 these configuration files in the Courier
mail server's configuration directory will no longer be used. To avoid future
confusion the old copies of these configuration files (including the .dist
files), should be removed from the Courier mail server's configuration
directory. They now live in the Courier mail server-authlib's configuration
directory (/usr/local/etc/authlib, or whatever was specified to the Courier mail
server-authlib's configure script).

  Upgrading from the Courier mail server 0.45.4 or earlier

The command to start the webmail server daemon has changed. The system startup
script must be modified to run the new command: "/usr/lib/courier/sbin/webmaild
start". Additionally, this scripts also starts pcpd, if required. It is no
longer necessary to start pcpd by hand.

  Upgrading from the Courier mail server 0.44.0 or earlier

Version 0.44.1 introduced an updated webmail implementation. The suid cgi-bin
binary has been replaced by a combination of a stub and a daemon process. After
upgrading to 0.44.1 you will need to modify your system startup script to run
/usr/lib/courier/libexec/courier/sqwebmaild start. See below for more
information.

  Upgrading from the Courier mail server 0.42.2 or earlier

After upgrading from the Courier mail server 0.42.2, or earlier, any existing
mail in POP3 mailboxes may show up as new mail, by some mail clients. This is a
one-time event.

  Upgrading from the Courier mail server 0.42.0 or earlier

Version 0.43 introduced some functional changes to the LDAP, MySQL, and
PostgreSQL authentication modules. A new DEFAULTDELIVERY setting is added to
each module, incorporating some functionality previously done by the MAILDIR
setting. Previously, MAILDIR served two purposes: 1) define the default location
to the primary mailbox, relative to the account's home directory, 2) provide
default mail delivery instructions, overriding DEFAULTDELIVERY in the courierd
configuration file.

Starting with this version, MAILDIR only specifies the default location for the
primary mailbox, and this setting is now used only by the POP3, IMAP, and
Webmail servers. The new DEFAULTDELIVERY setting specifies the default mail
delivery instructions. Sites that previously used MAILDIR may now need to copy
its setting to DEFAULTDELIVERY.

  Upgrading from the Courier mail server 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 the Courier mail server 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 and the DEB version of the Courier mail
server.

    Back up your existing sysconfdir

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

    Back up your existing sysconfdir

Make a backup copy of your current sysconfdir. The upgrade process reinstalls
several default configuration files; specifically sysconfdir/aliases/system and
sysconfdir/smtpaccess/default. Any additions to these files will normally be
lost in the upgrade, and can be restored from the backup afterwards. Don't
forget to rerun makealiases and makesmtpaccess.

    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 the Courier
mail server:

 1. The Courier Unicode Library

    The courier-unicode package must be installed and configured prior to
    installing the Courier mail server. Download the courier-unicode package
    from https://www.courier-mta.org/unicode/.

 2. The Courier mail server Authentication Library

    The courier-authlib package must be installed and configured prior to
    installing the Courier mail server. Download the courier-authlib package
    from https://www.courier-mta.org/authlib/.

 3. A C++ compiler

    The Courier mail server 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 the Courier
    mail server to compile.

 4. PCRE

    The PCRE2 library (http:/www.pcre.org) is required.

 5. wget

    The wget command must be installed.

 6. GNU IDN library

    This library (http://www.gnu.org/software/libidn/) implements support for
    internationalized domain names.

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

 8. Perl 5

    A recent version of Perl needs to be installed.

 9. GDBM or Berkeley DB library

    Either library must be installed.

10. OpenSSL or GnuTLS

    Support for SSL/TLS requires OpenSSL/GnuTLS. All features that require
    SSL/TLS are disabled unless OpenSSL or GnuTLS is installed.

11. 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 the Courier
    mail server. 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.

    Most of the LDAP support code is already provided by the Courier mail server
    authentication library. Some LDAP features, such as LDAP-based mail aliases,
    are implemented in the Courier mail server directly. OpenLDAP client
    libraries must be installed. If OpenLDAP is not installed, LDAP directory
    features are disabled.

12. mgetty+sendfax, groff or troff (not tested), ghostscript, and NetPBM

    This optional software is required to send E-mail messages via fax. The
    Courier mail server will compile and install without this software, but you
    will not be able to send faxes. All packages must be installed prior to
    installing the Courier mail server, and binaries from all packages must be
    installed in the default PATH before running the Courier mail server'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 the Courier mail server 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 the Courier mail server 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.

════════════════════════════════════════════════════════════════════════════════

> The Courier mail server 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 the Courier mail server from
> running.

> NOTE: Linux-Mandrake includes the Openwall patch in the alternative "secure"
> kernel package. The Courier mail server 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

The Courier mail server 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. The Courier mail server can also be used as a traditional mail
server, accepting and storing messages in individual mailboxes that are
accessible via POP3, IMAP, or webmail.

The Courier mail server 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
https://www.courier-mta.org/mbox-vs-maildir/.

Additionally, The Courier mail server'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, The Courier mail server already includes a fully
integrated POP3 and IMAP server.

Still, if circumstances absolutely require for you to stick with mailbox files,
The Courier mail server 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.

The Courier mail server 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. The Courier mail server does not support dot-locks, and the
Courier mail server does not support a separate mail directory for mailbox
files. Mailbox files must be located in the home directory of each individual
account.

The Courier mail server 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. The Courier mail server will be happy
to hand off all local mail to procmail, or anything else for the actual
delivery.

The Courier mail server 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 the Courier mail
server.

  • 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, The Courier mail server will install as
user/group daemon (or some other suitable user/group id). Only two of the
Courier mail server'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 the Courier mail server'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 the Courier mail server to use a
well-defined existing user and group ID, such as daemon.

  • Define the installation directory

The Courier mail server, 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
mail server's RPM and DEB packages install 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 the Courier mail
server consists of several hundred individual files (at the last count), so if
you install the Courier mail server 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 the Courier mail server 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, The Courier mail server's source code tarball can be built 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 this 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 this 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. The Courier mail server will not
function if it's reinstalled 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 the
Courier mail server.

OPTIONAL: Install the Socks 5 client toolkit

The Courier mail server has the ability to send outgoing SMTP mail through a
Socks 5 proxy. The Socks 5 proxy option requires a separate module, the Socks 5
client/server proxy to be installed before installing the Courier mail server.
Download the Socks 5 proxy client library from
https://www.courier-mta.org/download.html#sox and follow its installation
instructions.

> NOTE: Be sure to read the README, NEWS, and INSTALL files in the Courier mail
> server Socks 5 library toolkit, before attempting to install it for the first
> time (unless using the RPM or DEB build method).

Socks proxying must be implemented in relatively low-level manner, and may not
work on all operating systems. This is why it is packaged separately, in case
that it doesn't work. The configure script, described in the following section,
enables Socks 5 support automatically if the Courier mail server Socks 5 proxy
client library is already installed. To make sure that the library is installed
correctly, specify the "--with-socks" option to the following configure script.
This option aborts the configure script if it does not detect the Courier mail
server Socks 5 proxy client library.

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
the Courier mail server 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 the Courier mail server. 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 the 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 the Courier mail server 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 the Courier mail server. Do not attempt to
    install the Courier mail server 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

    The Courier mail server 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 the Courier mail server uses internally.

  • --enable-mimecharset=charset

    Specify the default character set the Courier mail server 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 the Courier mail server 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 the Courier mail server.

  • --exec-prefix=pathname

    Specify where the Courier mail server'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 mail server 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

    Specify 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 the Courier mail server's configuration files
    are installed. This option defaults to the subdirectory "etc" in the
    directory specified by the --prefix option.

  • --localstatedir=pathname

    Specify 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

    The Courier mail server 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 the Courier mail server uses internally.

  • --enable-mimecharset=charset

    Specify the default character set the Courier mail server 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.

  • --without-explicitsync

    Normally the Courier mail server 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-dirsync

    Also explicitly sync the parent directory. There's a school of thought which
    believes that the Linux ext2 filesystem requires the parent directory to
    also be synced, in addition to the new message file that's just been written
    to disk. There's another school of thought that thinks that this issue is
    completely blown out of proportion, and is really nothing more than a
    tempest in a teapot. However -- to accomodate the former school of thought
    -- this option adds a little bit of extra code to sync the parent directory.

  • --with-shellpath=path

    Specify the contents of the PATH environment variable that is inherited by
    custom programs started by the Courier mail server 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>, The Courier mail server 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 the Courier mail server-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, The Courier
    mail server's ESMTP server will also advertise a dummy ESMTP capability
    called XCOURIEREXTENSIONS, and will not recognize any the Courier mail
    server-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 the Courier mail server 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.

  • --with-random=/dev/path, --without-random

    Sometimes the Courier mail server 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 the Courier mail
    server will generate some noise on its own. The Courier mail server will
    generate noise based on the output of a random ps command, and several
    other, hopefully unpredictable, sources.

  • --with-gnutls - Use the GnuTLS library even if the OpenSSL library is also
    installed. The Courier mail server automatically uses whichever one is
    available. The OpenSSL library is selected if both are present. Use this
    option to override and select GnuTLS instead.
  • --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 the Courier mail server use an external, previously
    installed, root CA database.

  • --with-certsdir=pathname

    Set up configuration files and scripts that reference the server's SSL
    certificates to use the pathname directory, instead of the directory
    specified by the --datadir option. Scripts that create temporary self-signed
    certificates to be used for testing (mkimapdcert, mkpop3dcert, et. al.)
    install the generated certificate in this directory, and it's referenced
    from the corresponding configuration files.

  • --with-waitfunc=wait, --with-waitfunc=wait3

    Specify 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-spellcheck

    Do not compile spell checking support in the Courier mail server's webmail
    server, which can use hunspell, ispell, or aspell spell checking utility.
    configure automatically checks which spell checking tool is available. An
    explicit --with-spellcheck=hunspell, --with-spellcheck=aspell, or
    --with-spellcheck=ispell directly selects a specific spell checking tool
    when two or more are available. See "Configure the webmail server" for more
    information on spell checking.

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

  • --with-maxargsize=bytes,--with-maxformargsize=bytes

    Sets an upper limit on the size of CGI arguments for the webmail server.
    Normally there's no reason to modify the defaults (500,000 and 10,000,000
    bytes). The latter is generally the maximum allowed size of an attachment.
    The former is generally the maximum allowed size of the typed message. These
    settings can also be adjusted at runtime. See Maximum message size, below.

  • --with-maxmsgsize=bytes

    Sets the upper limit of messages composed in the webmail server, the main
    text and all the attachments. This setting can also be adjusted at runtime.
    See Maximum message size, below.

  • --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). This setting gives the initial
    configuration, that can be individually adjusted in the Preferences screen.

  • --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. NOTE - if this option is
    used, make check WILL FAIL. You should first configure the Courier mail
    server without this option, run make check, then reconfigure the Courier
    mail server with this option.

IPv6

IPv6 support in the Courier mail server 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 the Courier mail server 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. The Courier
    mail server 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 the Courier mail server 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 the Courier mail
server. If make completes succesfully, run make check. make check runs some
simple internal tests. It is not feasible to run a complete check of the Courier
mail server'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 the Courier mail server. If you use the GNU
version of make, and you would like to see which files the Courier mail server
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 the Courier mail server 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 the Courier mail server binaries with debugging data,
which is probably a good idea to do while the Courier mail server 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 the Courier
mail server 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 and DEB packages

NOTE: If an RPM or a DEB package gets built as per this INSTALL file resulting
packages 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 creating a
distribution package, the Courier mail server package will install and the old
configuration files will get silently removed, since they were not installed
using rpm or dpkg.

The Courier mail server 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 the Courier mail server'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 or the DEB package, install it,
then restore the overwritten files. If you want to switch to the Courier mail
server, blow away your current server before running make install.

Adjust system paranoia level

There are four setuid binaries in the Courier mail server that are owned by
root: sendmail, maildrop, webmail and webadmin. There's also one setgid binary,
sqwebpasswd.

/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/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 the Courier mail server'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/sqwebpasswd is described in detail in the
"OPTIONAL: Changing mail account passwords using the webmail server" section.

Post-installation setup

A first-time the Courier mail server installation may not require the system
startup scripts to be modified to start the Courier mail server at system boot.
Until the system's functionality is verified, the system will probably continue
to use the existing mail server. Still, most the Courier mail server
configurations will require two things to be started before any part of the
system is put to use:

  • 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.
  • Run the mkdhparams script to create the DH parameter file. A monthly job
    should also be created to run the mkdhparams script, in order to
    periodically generate a new set of DH parameters. DH parameters are used to
    set up encrypted connections.

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 the Courier mail server 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 the Courier mail server 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 the Courier mail server. The showmodules utility attempts to
load and initialize transport modules that have been configured, without
actually starting up the Courier mail server. 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 the Courier mail server, 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.

Start the Courier mail server 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.

Run the perftest1 script, which can be found in the directory containing the
Courier mail server'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. The Courier mail server 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 the Courier
mail server.

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.

 2. Add the following command to your system startup script:

 /var/www/cgi-bin/webadmin daemon &

    (or the actual cgi-bin directory). Executing the cgi-bin webadmin with a
    "daemon" parameter starts the daemon process.

    It might be useful to manage webadmin with courierlogger: using
    "courierlogger -pid=/usr/lib/courier/var/webadmin.pid -start .../webadmin
    daemon" to start webadmin and "courierlogger
    -pid=/usr/lib/courier/var/webadmin.pid -stop" to stop it.

 3. Execute "make install-webadmin-password". This prompts for a password, which
    is saved in the file /usr/lib/courier/etc/webadmin/password.

 4. Edit "/usr/lib/courier/etc/webadmin/restartcmd", this file contains one
    line, a command that webadmin runs to restart courier. This defaults to
    "courier restart". If Courier gets set up to run under systemd this should
    be changed to like:

 systemctl restart courier.service &

    ... or try-restart. It is important to use & to run systemctl in the
    background. webadmin uses this as an indication for proper signal handling
    setup. webadmin blocks signals when installing an updated configuration, but
    commands executed in the background have their signal handling reset to
    default. systemd will signal processes to terminate when restarting them.
    webadmin's blocked signals permit it to finish installing any remaining
    updates. systemctl will wait for the restart to finish, but it's part of the
    service that's getting restarted, so this process needs to run in a
    background, with default signal handling so that systemctl itself gets
    terminated.

 5. Edit "/usr/lib/courier/etc/webadmin/restartauthcmd", this file contains one
    line, a command that webadmin runs to restart the Courier authentication
    library service. This defaults to "authdaemond restart". If courier-authlib
    gets set up to run under systemd this should be changed to an "systemctl
    restart", or maybe "systemctl try-restart", for example: systemctl
    try-restart courier-authlib.service.

 6. 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 an empty file
    /usr/lib/courier/etc/webadmin/unsecureok to allow non-SSL webadmin
    connections from remote IP addresses. Alternative, the unsecuredok file may
    consist of a single line with one or more IP addresses, separated by spaces.
    Non-SSL access will get accepted from these IP addresses only:

 echo 192.168.0.9 192.168.0.10 >unsecuredok

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 the Courier mail server 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. The Courier mail server
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 the Courier mail server 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.

> NOTE: Authenticated SMTP is preferred over defining explicit IP address
> ranges. When combined with SSL, authenticated SMTP enables relaying privileges
> to any sender that securely provides a valid login/password, from any IP
> address, instead of only a small range of preauthorized IP addresses. The
> "OPTIONAL: Configure ESMTP authentication and SSL" section, later in this
> installation guide, gives more information on enabling authenticated SMTP and
> SSL-based encryption.

> Furthermore, preauthorized IP address ranges are vulnerable to being a source
> of abusive backscatter E-mail. Using authenticated SMTP together with the
> optional backscatter setting, described in the following section, prevents
> transmission of abusive backscatter bounces to external recipients even from
> trusted senders that have been compromised.

Backscatter suppression

> NOTE: It is important to know that the Courier mail server's default
> backscatter configuration means that if the Courier mail server receives a
> message for delivery to a local mailbox, and encounters an error during the
> delivery, the sender may not receive a delivery failure notification. The most
> common reason is an error in a custom mail filtering script. The next most
> common reason is a configuration error (the Courier mail server authentication
> library gives the account's home directory, optional non-default mailbox
> location, the account's system userid and groupid; but they differ from the
> actual files and directories (the home directory or the account's mailbox does
> not exist, exists somewhere else, or they're owned by a different userid or
> groupid).

> When installing the Courier mail server for the first time, it is usually
> helpful to termporary turn off the default backscatter filters, by setting
> BOFHSUPPRESSBACKSCATTER to "none", as described below. Remove this setting
> after the Courier mail server is installed and its basic functions appear to
> be working.

The term "backscatter" refers to non-delivery reports sent to a forged return
address. SMTP was created a long time ago, in better times when everyone trusted
each other. Anyone could provide any return address for any E-mail message.

Times have changed. At the time this documentation is written, most surveys
report that between 75% and 80% of Internet E-mail is junk E-mail or viruses,
with a forged return address.

Backscatter becomes a problem when a mail server does not reject unwanted mail.
The mail server decides that the message is unwanted only after it is accepted.
It generates a non-delivery notice, and sends it to the original message's
return address. Because viruses and junk mail use random forged return
addresses, the unfortunate victim of address forgery must deal with large
amounts of useless non-delivery notices from the mailbox. Not to mention a bunch
of uninformed people who think he is responsible for sending the virus or the
junk mail to them.

There's now a growing consensus that backscatter bounces should be considered
E-mail abuse. The Courier mail server is already very good at minimizing the
amount of backscatter, by the virtue of refusing to receive any mail to a
nonexistent local mailbox. However it's still possible for the Courier mail
server to bounce a received message. Several settings control how the Courier
mail server filters out its own backscatter, and avoids becoming a nuisance to
others.

Two settings are available. The first setting instructs the Courier mail server
to simply discard backscatter bounces. This is the ESMTP_BLOCKBACKSCATTER
setting in the courierd configuration file. This setting lists the so-called
"message sources" which are dropped by the SMTP client. All messages from any
matching source are quietly discarded. The default setting lists one message
source: a code that means "a delivery status notification for a message received
via SMTP from a non-authenticated source". "Non-authenticated" means a message
received from an IP address that does not have relaying privileges, and did not
authenticate. It's also possible to include authenticated SMTP sources; or it's
possible to disable this setting altogether, instructing the Courier mail server
to deliver all bounces via SMTP, even if they may potentially be backscatter.

Note that messages received in other ways (such as messages sent via the
sendmail command) are not affected. Their bounces will be sent via SMTP in all
cases (although there exists an undocumented setting to block those bounces
too). Also, bounces are always delivered to local mailboxes, this setting is
ignored for local mail deliveries.

The default setting means that if the Courier mail server receives a message via
SMTP for delivery to a local mailbox, and it bounces for some reason, the bounce
will be discarded.

The Courier mail server is also often used as a smarthost for SMTP clients.
These SMTP clients either connect from trusted IP addresses (IP addresses that
belong to the organization that runs the mail server), or that succesfully
authenticate, using SMTP authenticate. If those messages bounce, the
non-delivery report gets delivered, because the default setting only drops
bounces from non-authenticated source (a connection from a trusted IP address is
always processed as if the sender succesfully authenticated).

> NOTE: Sometimes the Courier mail server serves as a backup MX for another
> organization. If mail cannot be delivered to the primary MX (it rejects the
> message, or the message times out), the bounce will be discarded, because the
> message was probably received from a non-authenticated source.

The second setting minimizes the possibility of generating a bounce, of any
kind, in the first place. The second setting controls the backscatter
suppression list, which is a list of blacklisted E-mail addresses.

When the Courier mail server fails to deliver a message to an address, this
address goes on the suppression list, and the Courier mail server will refuse to
accept any more messages to the same address. If the delivery failure was a
temporary failure, any future messages will also be turned away with a temporary
error. A permanent delivery failure results in future messages rejected with a
permanent error.

Note that the suppression list does not apply to messages already accepted by
the Courier mail server, and which are in its mail queue. The suppression list
is checked when the Courier mail server is receiving a new message. The Courier
mail server automatically clears an address from the suppression list after two
hours. If the original message encountered a temporary delivery failure, The
Courier mail server periodically tries again to re-deliver the message. If the
message continues to encounter a temporary delivery failure, the clock starts
running again, from the beginning, If a re-delivery attempts succeeds, the
address is cleared from the suppression list, and the Courier mail server will
now accept more messages to the same address, immediately.

If a message keeps encountering temporary delivery failures, the time before
re-delivery attempts gets longer. It's possible that it could take more than two
hours for another delivery attempt, on a busy mail server. The address then
falls off the list, and the Courier mail server will accept another message to
the undeliverable address. This situation is unavoidable, but is not considered
to be a major issue.

The second setting is the BOFHSUPPRESSBACKSCATTER setting, in the bofh
configuration file. See the courier(8) man page for more information. The
default BOFHSUPPRESSBACKSCATTER setting also filters only messages from
non-authenticated SMTP sources against the suppression list.

The suppression list is not updated when problematic messages are manually
removed from the mail queue (using the "courier cancel" command). Even though
the stuck messages are deleted, The Courier mail server will continue to refuse
messages to suppressed addresses, until they time out. Use the "courier clear"
command to manually clear addresses from the suppression list, if so desired.

> NOTE: A mailbox that exceeded its storage quota results in temporary delivery
> failures. Therefore, when a mailbox fills up, The Courier mail server stops
> accepting any more messages to this mailbox (there might be one or two
> messages already in the mail queue, but that shouldn't be a major issue). Mail
> deliveries will resume when the mailbox goes below the quota (although this
> may take an hour, or two, as explained previously). It's possible that an
> existing version of the Courier mail server was originally modified to
> generate a permanent delivery failure for a quota exceeded condition. This
> change should now be undone, in order for backscatter suppression to work
> properly.

The third setting is the DSNTOAUTHADDR=1 setting in the courierd configuration
file. This setting, when enabled, alters bounce handling of messages that were
received from an authenticated SMTP connection.

Bounces of authenticated messages are processed according to the previous two
settings, except that the bounce message gets sent (if it gets sent at all) to
the authenticated login address, instead of the message's return address.

> NOTE: This works only if the Courier mail server is configured, via the
> Courier mail server Authentication Library, to validate login IDs that consist
> of a full E-mail address, "user@domain", with the login ID corresponding to
> the mailbox's E-mail address.

Enabling this setting removes the possibility of the Courier mail server sending
abusive backscatter bounces to external recipients, from a compromised trusted
sender, even if the compromised trusted sender uses authenticated SMTP. Instead
of sending the bounces to the forged return address, they get redirected to the
sender's mailbox.

> NOTE: The authenticated address is used for bounces only. When the message
> gets sent to its listed recipients, the message's return address gets used, as
> usual.

> NOTE: Authenticated SMTP must be used for this option to have any effect. When
> relaying privileges are granted to explicit IP address ranges (see the
> preceding "Create smtp access list" section), The Courier mail server will not
> have the sender's authenticated login address (unless the sender voluntary
> authenticates).

Miscellaneous configuration

Review/edit contents of various configuration files in /usr/lib/courier/etc:

  • courierd

    this file controls general aspects of the Courier mail server'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 the Courier mail server 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 the Courier mail server 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 the Courier mail server'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 DNS-based blacklists or whitelists are used.

  • esmtpd-msa

    this file controls the Courier mail server'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 the Courier mail server's POP3 server.
    The Courier mail server'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 the Courier mail server's IMAP server.
    The Courier mail server'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.

    Qmail compatibility mode.

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

Run this command if you are installing the Courier mail server on a system
that's currently running the Qmail mail server. The Courier mail server will now
read .qmail files for delivery instructions, instead of .courier files. The
Courier mail server'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 the Courier mail server 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, The Courier mail server 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 the Courier mail server to accept mail for all
subdomains of this domain.

OPTIONAL: Configure UUCP

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

The Courier mail server's UUCP functionality has been tested with Taylor UUCP
1.06. It's likely that some minor tweaking will be necessary to get the Courier
mail server 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 the Courier mail server 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 the Courier mail server uses directly. The format of the uucpneighbors
configuration file is described in the makeuucpneighbors(8) manual page.

  /usr/lib/courier/etc/uuucprewriteheaders

The Courier mail server 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

The Courier mail server 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, The
Courier mail server 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 the Courier mail server accepting
mail for one address, and delivering the mail to another address. A one-to-many
substitution results in the Courier mail server accepting mail for one address,
and delivering a separate copy of the message to every address defined by the
alias.

The Courier mail server 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.

The Courier mail server 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: Enable standard mail filters

The Courier mail server includes several options for selectively filtering mail.
In general, The Courier mail server provides several plug-in interfaces for
external mail filters, that can be used to selectively accept or reject
messages.

Please note that running mail filters can have a non-trivial impact on mail
system performance and throughput.

There are three standard mail filtering modules:

  • verifyfilter - Verify all E-mail's return addresses, see the verifyfilter(8)
    manual page for more information.
  • dupfilter - Block duplicate messages, see the dupfilter(8) manual page for
    more information.
  • ratefilter - Limit the rate of messages per sender see the ratefilter(8)
    manual page for more information.

To enable a mail filter, for example:

filterctl start verifyfilter

The filterctl installs the filter, and the courierfilter starts them, see
Starting and stopping the Courier mail server.

OPTIONAL: Configure custom mail filtering

The Courier mail server comes with some sample code that demonstrates how to
write a mail filter. The Courier mail server 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 the Courier mail
    server receives must be acknowledged by every global mail filter. Note that
    if global mail filters are installed, but their daemons are not running, The
    Courier mail server will not accept any new messages.

  • Local mail filter

    this filter can be used when the message is addressed to a local recipient -
    when the Courier mail server 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

The Courier mail server 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.

The Courier mail server 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 the Courier mail server

To start the Courier mail server, run the command /usr/lib/courier/sbin/courier
start. To stop the Courier mail server, 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 the Courier mail server'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.

Run the Courier mail server in parallel to your mail server

You now have several options for migrating from your existing mail server to the
Courier mail server:

  • Your existing mail server can continue to handle incoming mail, by listening
    on the smtp port. The Courier mail server 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.
  • The Courier mail server 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

The Courier mail server 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 initialize the ESMTPAUTH configuration
    setting. The configuration file /usr/lib/courier/etc/esmtpd-msa is used for
    the ESMTP submission server on port 587. Setting this variable in esmtpd is
    sufficient, because esmtpd-msa merely supplements the settings in esmtpd.
    Explicitly initialize this setting in esmtpd-msa only if you wish to apply
    it to port 587 only.

    ESMTPAUTH is a list of SASL authentication methods to use use. Currently,
    The Courier mail server supports LOGIN, PLAIN, CRAM-SHA1 and CRAM-MD5. The
    list of authentication methods is sometimes influenced by the installed
    authentication modules in the Courier mail server Authentication Library.
    Not all authentication modules implement CRAM-MD5/SHA1. The authentication
    modules that support CRAM-MD5/SHA1 authentication are: authuserdb, authldap,
    authmysql, and authpgsql.

  • 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 the Courier mail server.

  ESMTP over TLS/SSL

The Courier mail server also supports ESMTP over TLS/SSL, by using the ESMTP
STARTTLS extension:

  • To add SSL support you have to install OpenSSL or GnuTLS before installing
    the Courier mail server. Download OpenSSL from http://www.openssl.org/, or
    GnuTLS from http://www.gnutls.org.

    Follow OpenSSL's or GnuTLS's installation instructions, then build the
    Courier mail server.

    > NOTE: Most systems already have an available OpenSSL or GnuTLS package. Do
    > not build OpenSSL or GnuTLS yourself, if a prebuilt package is already
    > available. Just install the prebuilt package.

    > NOTE: The development libraries must be installed in addition to the
    > runtime package, in order to build the Courier mail server. On most
    > systems, the development files (header files, libraries, etc...) are
    > provided in a separate "devel" package. The base OpenSSL/GnuTLS package is
    > not sufficient to build the Courier mail server, the development libraries
    > must be installed.

    The OpenSSL library is selected when both OpenSSL and GnuTLS libraries are
    found by the configure script. Use the --with-gnutls option to explicitly
    select GnuTLS library over OpenSSL.

  • 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 the Courier mail server 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 mail server userid (the userid used to install the Courier mail
    server, 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 the Courier mail server's ESMTP server after installing the X.509
    certificate.

The Courier mail server will also use TLS/SSL when sending ESMTP mail,
automatically. If the remote mail server support STARTTLS, The Courier mail
server 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,
The Courier mail server 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.

The configuration script checks for the system's list of trusted certificate
authorities, and initializes TLS_TRUSTCERTS in the courierd configuration file,
during installation. When the Courier connects to a remote server, setting
ESMTP_TLS_VERIFY_DOMAIN to 1 in the courierd configuration file (usually
/usr/lib/courier/etc/courierd or /etc/courierd) enables certificate
verifications. However, many mail servers on the Internet use self-signed
certificates, so this is generally of little use.

OPTIONAL: Configure ESMTP smarthosting

Initialize the esmtproutes configuration file if all outgoing mail need to be
forwarded to your Internet provider's mail server, or some other "smarthost".
See courier(8) for more information:

> : relay.example.com

This forwards all mail to relay.example.com

> : relay.example.com,587

This forwards all mail to relay.example.com on port 587.

> : relay.example.com,465 /SECURITY=SMTPS

This forwards all mail to relay.example.com on port 465, using encrypted SMTP.

If the smarthost requires authentication, initialize the esmtpauthclient
configuration file:

> relay.example.com,587 john@example.com snerkle

When the Courier mail server connects to relay.example.com on port 587, it will
authentication using the userid of "john@example.com" and password "snerkle".

OPTIONAL: Configure the SECURITY ESMTP extension

The Courier mail server 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 the
Courier mail server. Therefore, at present time both the sending and the
receiving mail relay must be running the Courier mail server 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 https://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.
The Courier mail server 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 the Courier mail server will send the
message. The Courier mail server 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, The Courier mail server 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 the Courier mail
server. 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. The Courier mail server 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. The Courier mail server 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. The Courier mail server 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 the
Courier mail server 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 the Courier
    mail server 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 The Courier mail server
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 Sender Policy Framework

The Courier mail server can optionally check the return address on all SMTP mail
for the sender's published Sender Policy Framework (SPF). Keep in mind SPF is an
experimental protocol that's still maturing. The Courier mail server's SPF
configuration is set up in the "bofh" configuration file, and is fully explained
in the courier(8) manual page.

OPTIONAL: Configure the IMAP server

The Courier mail server includes an integrated IMAP server. The following steps
set it up:

  • If using virtual mail accounts the system limit on the maximum number of
    inotify file descriptors, /proc/sys/fs/inotify/max_user_instances, will
    likely need to be increased, since all IMAP processes will be running under
    the same userid. Rough metric is the maximum number of concurrent IMAP
    sessions multiplied by 4. On very large servers it may also be necessary to
    increase /proc/sys/fs/inotify/max_user_watches, a rough metric would be at
    least 5 times the max_user_instances setting.
  • Edit /usr/lib/courier/etc/imapd. If you want to use IMAP SASL
    authentication, set up the IMAP_CAPABILITY variable. It performs the
    equivalent function as the ESMTPAUTH variable 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.

Configure IMAP shared folders

It is possible to share folders between different mailboxes, via IMAP. See the
file maildir/README.sharedfolders.(txt|html) for more information.

OPTIONAL: Configure IMAP over SSL

To add SSL support you have to install OpenSSL or GnuTLS before installing the
Courier mail server. Download OpenSSL from http://www.openssl.org/, or GnuTLS
from http://www.gnutls.org.

OpenSSL's support is well-tested, the GnuTLS version is a relatively new
addition, and is considered experimental. Follow OpenSSL's or GnuTLS's
installation instructions, then build the Courier mail server.

> NOTE: Most systems already have an available OpenSSL or GnuTLS package. Do not
> build OpenSSL or GnuTLS yourself, if a prebuilt package is already available.
> Just install the prebuilt package.

> NOTE: The development libraries must be installed in addition to the runtime
> package, in order to build the Courier mail server. On most systems, the
> development files (header files, libraries, etc...) are provided in a separate
> "devel" package. The base OpenSSL/GnuTLS package is not sufficient to build
> the Courier mail server, the development libraries must be installed.

The OpenSSL library is selected when both OpenSSL and GnuTLS libraries are found
by the configure script. Use the --with-gnutls option to explicitly select
GnuTLS library over OpenSSL.

The /usr/lib/courier/etc/imapd-ssl configuration file sets some additional
options for SSL support, which you may need to adjust. Consult that
configuration file for additional information. Then, you also have to run the
/usr/lib/courier/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
the Courier mail server 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 IMAP realtime folder status updates

It's possible to allow multiple clients to open the same folder, and have all
clients to be simultaneously notified of any changes to the folder contents.

After installing the server see the imapd(8) manual page for more information.

OPTIONAL: Configure SMAP

Starting with the Courier mail server 0.43, the IMAP server supports an
experimental mail access protocol, dubbed "Simple Mail Access Protocol". SMAP is
an experiment to provide enhanced mail processing beyond what's currently
possible with IMAP. SMAP's purpose is to prototype and develop advanced mail
access functionality that's not possible with IMAP. SMAP is disabled by default.
Uncomment the SMAP_CAPABILITY setting in the imapd configuration file in order
to enable SMAP. The Cone mail client supports SMAP.

OPTIONAL: Configure the POP3 server

The Courier mail server 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
    POP3AUTH variable. It performs the equivalent function as the corresponding
    variable 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 IMAP/POP3 aggregator proxy

It is possible to distribute IMAP and POP3 mailboxes between multiple server.

See imap/README.proxy for more information.

CERTIFICATE AUTHENTICATION

The Courier mail server can use SSL certificates for authentication purposes.
That is, instead of using a login ID and a password, for accessing the mailbox,
The Courier mail server uses a client-side SSL certificate. For certificate
authentication purposes, one of the fields in your certificates' subject must
match the login ID in the authentication database. Consider the following
certificate:

> ...
> Subject: C=US,ST=New York,L=New York,O=Acme Widgets Inc,CN=John Smith,emailAddress=johnsmith@example.com

If the emailAddress field is configured as the login ID, the authentication
database must provide login details for johnsmith@example.com. To enable
certificate authentication, edit the following configuration files in
sysconfdir: imapd-ssl, pop3d-ssl, esmtpd and esmtpd-ssl (the esmtpd files enable
SSL certificate authentication for incoming SMTP connections, if a good SSL
certificate is provided, the client receives mail relaying privileges). All of
these configuration files require the same set of changes:

  • Set TLS_TRUSTCERTS to the filename with your certificate authority's X.509
    certificate.

  • Change the TLS_VERIFYPEER setting to "PEER". The setting can also be changed
    to "REQUIREPEER" to require all SSL/TLS connections to provide a
    certificate. Otherwise, it is optional. If the mail client provides an SSL
    certificate, it may be used to authenticate. Without a certificate,
    password-based authentication remains an option.

  • Change the TLS_EXTERNAL setting to the name of the certificate subject field
    that gives the login ID. In the above example, this would be
    "TLS_EXTERNAL=emailaddress".

    > NOTE: GnuTLS's certtool uses "email" as the name of this field. If the
    > Courier mail server is compiled with GnuTLS, you should still specify this
    > field as "emailaddress".

OPTIONAL: Configure the webmail server

The integrated webmail server is made up of two parts. The first part, by
default, is installed as /usr/lib/courier/libexec/courier/webmail. You can
simply copy this binary executable to your web server's cgi-bin directory, or
create a link from the cgi-bin directory to this program. This is a small stub
program that connects, via a local socket, to the sqwebmaild daemon process,
which implements the webmail service. It is necessary to start the webmail
server by adding the following command to the system startup screen (so that the
webmail server gets automatically started at boot):

/usr/lib/courier/sbin/webmaild start

(It is also possible to run "webmaild stop" from the system shutdown script in
order to shut down webmail service gracefully).

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

  SELinux

The following extension may be necessary to make webmail work when SELinux
kernel extensions are turned on:

allow httpd_sys_script_t var_t:sock_file write;
allow httpd_sys_script_t unconfined_t:unix_stream_socket connectto;

  Spell checking

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

NOTE: Courier mail server assumes that the spell checking dictionary is called
"english", for ispell or aspell, and "en_US" for hunspell. 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.

The OpenLDAP development toolkit must be installed before building SqWebMail, in
order for LDAP search code to compile.

The file ldapaddressbook configuration file should contain a default systemwide
list of accessible address book. See courier(8) for more information. A default
file will be installed, listing some common Internet address books. Each line in
this file contains the following information:

name<tab>host<tab>port<tab>suffix<tab>binddn<tab>bindpw

<tab> is a single ASCII TAB character. name is the unique name for this LDAP
server. host and port specify the connection parameters. suffix specifies the
root LDAP entry whose subtree gets searched. The binddn and bindpw fields are
not presently used (they were used in earlier version of the webmail server,
before the LDAP search interface was rewritten and simplified).

  Webmail session timeouts

A login session is automatically logged out after certain period of inactivity.
The timeout period defaults to 20 minutes, and is set by the
--enable-softtimeout option to the configure script. It is also possible to
adjust this value by setting the SQWEBMAIL_TIMEOUTSOFT environment variable. For
example, with Apache, by adding the following to httpd.conf:

SetEnv SQWEBMAIL_TIMEOUTSOFT 3600

There is also a hard timeout, which logs out a session no matter what. The
default of two hours is changed with the --enable-hardtimeout option to the
configure script, and the SQWEBMAIL_TIMEOUTHARD environment variable.

WARNING:

The hard timeout interval is used to calculate the maintenance of the login
cache (if that option is selected). This factor is used in the cleancache.pl
cleanup script, and changes to this value must be coordinated appropriately. It
is not possible to use different hard timeout values with the same login cache
(in different virtual domains, as described in the next session). Leisurely
tinkering with this environment variable is STRONGLY DISCOURAGED, it's very easy
to screw up the whole system. You've been warned.

If you adjust the hard timeout, you must simultaneously delete your current
login cache directory, and adjust $timeouthard in the installed cleancache.pl
script.

  Maximum message sizes

Messages composed in the webmail server are limited in size. The additional
limitation are on top of the limit set in the sizelimit configuration file, see
the courier(8) manual page.

The --with-maxargsize, --with-maxformargsize, and --with-maxmsgsize options to
the configure script set the parameters that control the maximum size of
messages and attachments. These parameters can also be set through the following
environment variables.

> NOTE: The configure script parameters define the minimum settngs. The
> following environment variables may be used to set larger limits only.

> NOTE: These settings limit only the maximum size of messages sent from the
> webmail server. The limit on the incoming message size is set by other Courier
> mail server settings (usually the sizelimit setting also).

SQWEBMAIL_MAXARGSIZE
        Approximate maximum size, in bytes, of the message, excluding any
        attachments (overrides the --with-maxargsize parameter to the configure
        script). This is the maximum message that can be typed into the webmail
        server.

        NOTE: The webmail server has an inactivity timeout. While composing a
        new message use the "Preview" button frequently to save the unfinished
        message and keep the session from timing out.

SQWEBMAIL_MAXATTSIZE
        Approximate maximum size, of each allowed attachment. (overrides the
        --with-maxargsize parameter to the configure script).

        NOTE: Attaching binary files to E-mail messages incurs an overhead of
        approximately 33%. E-mail is really not the optimum medium for
        exchanging files. Setting SQWEBMAIL_MAXATTSIZE to 4000000 will
        effectively allow attaching files of up to 3000000 bytes in length,
        approximately.

SQWEBMAIL_MAXMSGSIZE
        Approximate maximum size, of a message, including the text portion and
        all attachments (overrides the --with-maxmsgsize parameter to the
        configure script). There can be any number of attachments, each one up
        to SQWEBMAIL_MAXATTSIZE bytes long, but the sum total of the entire
        message cannot exceed SQWEBMAIL_MAXMSGSIZE.

These variables must be set in the environment that runs the webmail CGI
program. With Apache, these variables can be set in the httpd.conf file by the
SetEnv command. httpd.conf example:

> SetEnv SQWEBMAIL_MAXATTSIZE 1000000
> SetEnv SQWEBMAIL_MAXMSGSIZE 4000000

> NOTE: These settings are global, and apply to all mailboxes. However, advanced
> Apache configuration can be used to use different environment variable
> settings with different virtual hosts.

> NOTE: On 32-bit platforms, the maximum limits may not exceed 2 gigabytes. A
> 64-bit platform is required to have SqWebMail capable of handling attachments
> and messages larger than 2 gigabytes.

  Custom site banner generator

>       SetEnv SQWEBMAIL_BANNERPROG=/usr/local/bin/bannerprog
>

The SQWEBMAIL_BANNERPROG environment variable, if set, defines a full path to a
program that generates a banner. sqwebmail replaces the character sequence [#B#]
in HTML template files with the output generated by this program. The first
argument to the program will be the name of the HTML file. The banner program
can use that to customize banner output.

It is also possible for a site to stick multiple @B tags in the same HTML page.
To distinguish each instance follow the @B tag with up to 30 letters or digits,
surrounded by braces. For example: [#B#]{TOP} and [#B#]{BOTTOM}. "TOP", or
"BOTTOM" (or anything else) will be the second argument to the banner program.

  Random seed

A random seed is required for preventing certain kinds of external attacks
against the SqWebMail server. The random seed must be a constant value, only
varying between different instances of SqWebMail. By default the random seed is
derived from the inode number of one of the supporting script files. The script
file ordinarily remains constant, thus the random seed does not change, but
different SqWebMail installs will end up with a different seed.

When a pool of SqWebMail servers is combined for load-balancing, all servers
must use the same random seed. This is done by defining the SQWEBMAIL_RANDSEED
environment variable. This can be set in the httpd.conf as well:

> SetEnv SQWEBMAIL_RANDSEED 82738AZ

SQWEBMAIL_RANDSEED should contain up to ten letters or numbers.

  Domain-based templates

The default set of templates for the dynamically generated HTML is installed in
/usr/local/share/sqwebmail/html. When the same server is used to provide webmail
access for multiple domains it is possible to specify a different set of HTML
templates for each domain.

This functionality is not directly implemented in SqWebMail, simply because
there is no standard way to specify this. Instead, this is something that will
need some minor work set up.

Domain-based templates are implemented by making the web server set the
environment variables SQWEBMAIL_TEMPLATEDIR prior to running the sqwebmail
binary. The contents of this environment variable override the default location
of /usr/local/share/sqwebmail/html. By having the web server initialize this
variable based on the domain name it is possible to present different templates,
based on the domain name used.

To do this, make copies of the HTML template directory,
/usr/local/share/sqwebmail/html. Then, configure the web server to initialize
SQWEBMAIL_TEMPLATEDIR appropriately. For example, with Apache:

  <VirtualHost a.b.c.d>
    ServerName webmail.example.com
    [...]
    SetEnv SQWEBMAIL_TEMPLATEDIR /usr/local/share/webmail/webmail.example.com
    [...]
  </VirtualHost>

The possibilities are endless.

  Name-based templates

It is now possible to display two or more templates from the same CGI binary
WITHOUT setting up multiple domain names.

For example, with Name-based templates an sqwebmail administrator can set up
sqwebmail to display a template in the /usr/local/share/sqwebmail/html directory
when sqwebmail is called from the URL: http://www.foo.com/cgi-bin/sqwebmail

And display a different template in the
/usr/local/share/sqwebmail/alternate-html directory when sqwebmail is called
from the URL: http://www.foo.com/cgi-bin/sqwebmail-alt-template

This is made possible by a little web server magic (explained below in the
section entitled "Apache Name-based template configuration example") and the
setting of TWO sqwebmail environment variables:

SQWEBMAIL_TEMPLATEDIR
SQWEBMAIL_IMAGEURL

You should recognize the SQWEBMAIL_TEMPLATEDIR environment variable from the
section above on Domain-based templates. If you haven't read that section yet,
please do so now.

The SQWEBMAIL_IMAGEURL environment variable is new in versions of sqwebmail
greater than sqwebmail-3.5.3.20030629. It allows us to set, at run time, the
image URL, or the root URL, in which to look for our template's images. This
image URL is then automatically inserted into the current template anytime a
conditional image tag or an IMAGEURL tag is encountered.

This is an example of a conditional image tag:

[#@image.gif, ... @text@#]

The conditional image tag is replaced at template processing time with an HTML
<img src="..."> tag if (hence the word "conditional") sqwebmail is set up to
display images.

This is an example of an IMAGEURL tag:

[#IMAGEURL#]

The IMAGEURL tag is replaced at template processing time with the contents of
the SQWEBMAIL_IMAGEURL environment variable, if set, and otherwise with the
value of the --with-imageurl configure option, which defaults to "/webmail".

  Apache Name-based template configuration example

Let's take a look at a simple Apache Name-based sqwebmail template configuration
example:


  # Sqwebmail Alternate Template URL
  ScriptAlias /cgi-bin/sqwebmail-alt-template "/usr/local/apache/cgi-bin/sqwebmail"

  <Location /cgi-bin/sqwebmail-alt-template>
      Setenv SQWEBMAIL_TEMPLATEDIR "/usr/local/share/sqwebmail/alternate-template"
      Setenv SQWEBMAIL_IMAGEURL "/alternate-webmail"
      [...]
  </Location>


The above should allow your users to run sqwebmail with the template in
/usr/local/share/sqwebmail/alternate-template and an image URL of
/alternate-webmail, simply by calling sqwebmail from the following URL:

http://www.yourdomain.com/cgi-bin/sqwebmail-alt-template

The original sqwebmail templates would then still be available from this URL:

http://www.yourdomain.com/cgi-bin/sqwebmail

Using Apache's <Location> directive we can utilize a virtually unlimited number
of templates without setting up a single virtual domain.

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 library. The login
ID and password are validated by the authentication library, 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 the Courier mail server'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.

  Webmail runtime configuration

There are some options which can be used to change the webmail server's behavior
for individual accounts, or globally, using the "Account Options" feature in the
Courier mail server Authentication library. The individual account's setting
takes precedence over the DEFAULTOPTIONS settings in the authdaemonrc
configuration, so for example if you want to disable webmail access for most
accounts but enable it for a select few, you can set
DEFAULTOPTIONS="disablewebmail=1" in the authdaemonrc configuration file, and
add the option disablewebmail=0 to individual accounts. See the section "Account
options" in README_authlib.html in the courier-authlib package for more
information on setting the following account options:

disablewebmail - if set to a non-zero value, this account will not be permitted
to login to webmail (e.g. because the user is only allowed to use POP3 or IMAP)

wbnochangingfrom - if set to a non-zero value, the webmail server will not allow
the From: header to be changed, it will always have its default value.

wbnochangepass - if set to a non-zero value, the webmail server will not allow
passwords to be changed. See "Changing mail account passwords using the webmail
server", below, for more information.

wbusexsender - if set to a non-zero value, the webmail server will attach an
X-Sender: header to all outgoing messages. This can be used in the event you
would like to be able to modify the From: header, yet also be able to track sent
mail to the original account.

wbnoimages - if set to a non-zero value then no images or icons will be used.
The generated interface will be a text-only interface.

wbnodsn - set to a non-zero value then the option to request delivery
confirmation receipts will not be shown.

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.

If you do not want to use the password change function you can also remove the
sqwebpasswd program. This is a helper program, installed with the set-groupid
bit set, that relays the password change request to the authentication daemon,
through the filesystem socket that is not globally accessible. The password
change request consists of the account name, the old password, and the new
password. The password change request is validated by the authentication daemon,
and the old password must match the existing password on the account, before the
password change goes through. This set-groupid helper program is safe to use.

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: Install automatically-appended footer text for webmail messages

/usr/lib/courier/share/sqwebmail/html/LANG/footer - if this file exists, its
contents will be appended to the end of every sent message from the webmail
server. The actual directory where sqwebmail's html language files are installed
may be different with prebuilt Courier packages. LANG is the language code here,
there can be a separate footer per installed language. The footer file carries
the following requirements:

  • The footer file must be coded in UTF-8.

  • The footer file must follow the format=flowed; delsp=yes format, as
    specified by RFC 3676. Capsule summary:

       • Paragraphs are delimited by blank lines.

       • Paragraphs that consist of more than one line must have a trailing
         space ending each line except the last line in the paragraph.

       • That trailing space is in addition to a space that delimits individual
         words in most Western languages. Therefore, a line that ends on a word
         without punctuation and continues with the next word at the beginning
         of the next line must end with two spaces: the usual space that
         separates individual words, and a second space that indicates that the
         paragraph continues on the next line.

       • Restated: a line that ends with a space is logically joined with the
         next line, after the trailing space is logically removed.

       • Lines that begin with a space character or the ">" character must have
         an additional space character prepended to them. This leading space
         character is logically removed from the contents of the line.

    A convenient way to format text in flowed format is to use the leaf editor
    that's part of the Cone package.

  • Signature content gets formatted as part of the message together with the
    rest of the content. Sender-selected option to format the message as either
    a plain text message, or using wiki-style HTML markup applies to the footer
    file too. The footer file's contents should be constructed taking into
    account the possibility that wiki-style HTML markup may get optionally
    applied to the footer content.

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

The Courier mail server 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.

Account OPTIONS

It is possible to adjust certain parameters on an account-by-account basis. This
feature is actually implemented in the Courier mail server Authentication
Library. See ACCOUNT OPTIONSin the auth_generic manual page.

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 the Courier mail server, must also be installed. The Courier mail
server does not handle the actual job of faxing. The Courier mail server only
reformats E-mail messages as fax images, and runs mgetty+sendfax to send the
fax. The Courier mail server 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 the Courier mail server. 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. The Courier mail server does
not use the spooling scripts found in the mgetty+sendfax package. The Courier
mail server 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. The Courier mail server 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.

On the cover page, the sender's name, the recipient's name, and the fax subject
gets taken from the E-mail message's headers. The ability to use non-Latin
characters depends on the support from the underlying tools, ghostscript and
groff, for the default system locale.

Install the NetPBM library 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. The Courier mail server 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 the Courier mail server 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.

The Courier mail server 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.

OPTIONAL: Install the Courier mail server log analyzer

The Courier mail server log analyzer (the courier-analog package) is a Perl
script that generates log summaries for the Courier mail server. The Courier
mail server log analyzer generates log summaries for incoming and outgoing SMTP
connections, and IMAP and POP3 activity. courier-analog can generate output in
text or HTML format.

The Courier log analyzer is not included in the main the Courier mail server
tarball, it must be downloaded separately from
https://www.courier-mta.org/download.html#analog. After downloading and
installing this package, see the courier-analog manual page for more
information.

OPTIONAL: Configure Courier IP address-specific settings for servers with
multiple IP addresses

When running Courier on a server that has more than one IP address, it's
possible to configure Courier to have a "vanity" configuration for each IP
address, such as the IP address for outgoing connections for relaying messages
received by a client that connects to each address, or its server name that it
uses in the "Received:" headers that Courier adds to each message.

See the "Servers with multiple IP addresses" section in the courier(8) manual
page for more information.

OPTIONAL: configure hostname-dependent configuration

Several Courier configuration files specify settings that reference the server's
fully-qualified domain name. It is possible to have a fixed set of configuration
files with the key configuration files using a wildcard placeholder for the
system hostname, and replicate these configuration files to multiple servers
with externally- assigned hostname (and likely IP addresses), such as
DHCP-provided ones; with the server's hostname referenced by the relevant
placeholders.

Example: replicate the same set of configuration files to servers assigned
hostnames of "mx1" and "mx2", via DHCP, with Courier recognizing its
fully-qualified domain name as "mx1.example.com" and "mx2.example.com",
respectively.

See the "Hostname-dependent configuration" section of the courier(8) manual page
for more information.

Decommission your existing mail server

This step 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 the Courier mail server 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 the Courier RPM or DEB 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 the Courier mail server:"

        # Use default DH parameter file, if it does not exist.

        if test ! -f ${datadir}/dhparams.pem
        then
            ln ${datadir}/dhparams.pem.dist ${datadir}/dhparams.pem
        fi

        # 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 ${ACCESSFILE}.dat || ${sbindir}/makesmtpaccess

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

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

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

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

        if test -f ${libexecdir}/courier/sqwebmaild
        then
                ${sbindir}/webmaild start
                echo -n " webmail"
        fi

        ${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-certificate..."

                                        ${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-certificate..."

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

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

        if test -x ${bindir}/webmlmd
        then
                . ${sysconfdir}/webmlmrc
                if test "$LISTS" != ""
                then
                        ${bindir}/webmlmd start ${sysconfdir}/webmlmrc && \
                                echo -n " webmlmd"
                fi
        fi

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

        if test -x ${bindir}/webmlmd
        then
                ${bindir}/webmlmd stop ${sysconfdir}/webmlmrc
                echo -n " webmlmd"
        fi

        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 -f ${libexecdir}/courier/sqwebmaild
        then
                ${sbindir}/webmaild stop
                echo -n " webmail"
        fi

        if test -x ${sbindir}/courierldapaliasd
        then
                ${sbindir}/courierldapaliasd stop
                echo -n " courierldapaliasd"
        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.
