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

Installation

NOTE:

This documentation describes manual installation of the Courier server. This is a somewhat involved process that may overwhelm people that do not have prior experience with installing large software packages. Many Linux-based distributions and BSD-family systems have 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 unique needs and requirements. 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. They will appreciate the feedback, and take it into consideration when preparing the next revision of the platform-specific package.

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

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

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

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

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

Table Of Contents

The following table of contents might look intimidating at first, but some sections are marked "optional". These sections are not required for a basic installation as a simple ESMTP server.

Upgrading an existing installation

Upgrading from Courier 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 Courier 0.54.2, or earlier

The logic for outbound authenticated SMTP has changed. This is when Courier 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, Courier 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 Courier, 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 Courier 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 Courier, before installing this update.

Upgrading from Courier 0.51, or earlier

Version 2.0 of maildrop, in Courier 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 Courier 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 Courier 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 Courier 0.48.2, or earlier

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

Upgrading from Courier 0.47, or earlier

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

You must download and install the Courier authentication library from http://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 Courier'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 Courier was installed in one of the known default installation directories. The documentation in courier-authlib explains what to do if the existing version of Courier is installed in a non-default location.

In any case, after upgrading to 0.48 these configuration files in Courier'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 Courier's configuration directory. They now live in Courier-authlib's configuration directory (/usr/local/etc/authlib, or whatever was specified to Courier-authlib's configure script).

Upgrading from Courier 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 Courier 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 Courier 0.42.2 or earlier

After upgrading from Courier 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 Courier 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 Courier 0.34.1 or earlier

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

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

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

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

Upgrading from Courier 0.29.1 or earlier

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

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

Back up your existing sysconfdir

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

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 Courier:

  1. The Courier Authentication Library

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

  2. A C++ compiler

    Courier is primarily developed and built with gcc. Other C++ compiler may or may not work. Solaris's C++ compiler is reported to work without any problems. There are some issues with AIX's xlC compiler, which mostly has to do with the C++ libraries and header files. IBM has released a GNU/Linux development toolkit for AIX, which may help in getting Courier to compile.

  3. PCRE

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

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

  5. Perl 5

    A recent version of Perl needs to be installed.

  6. GDBM or Berkeley DB library

    Either library must be installed.

  7. FAM, the File Alteration Monitor, or its modern Linux-specific replacement Gamin

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

  8. OpenSSL or GnuTLS

    Support for SSL/TLS requires OpenSSL/GnuTLS. If OpenSSL or GnuTLS is not installed, SSL/TLS features are disabled.

  9. OpenLDAP

    Support for LDAP directory services requires OpenLDAP client libraries to be installed. If OpenLDAP is not installed LDAP directory features are disabled. Sometimes there's some confusion when commercial LDAP servers are used, which come with their own development toolkits, which use a different API than OpenLDAP. Even if a commercial LDAP server is used to provide LDAP services, OpenLDAP is still required to enable LDAP services in Courier. Also, note that you need OpenLDAP development libraries and files. On most systems, the development files are packaged separately, in addition to the runtime OpenLDAP libraries. Make sure that you have not just the runtime OpenLDAP libraries installed, but the development libraries as well.

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

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

    This optional software is required to send E-mail messages via fax. Courier will compile and install without this software, but you will not be able to send faxes. All packages must be installed prior to installing Courier, and binaries from all packages must be installed in the default PATH before running Courier's configure script.

    mgetty+sendfax, ghostscript, and groff, are required for basic fax support, which supports faxing of plain text, Postscript, and PDF-formatted content. It's probably possible to use the original UNIX troff instead of groff, but this has not been tested. Installing NetPBM adds the ability to fax GIF, JPEG, and PNG images.

The typical sequence of commands to install Courier is as follows. Read the following section before running these commands:

   ./configure [options]
   make
   make check       # Optional -- see below
   make install
   make install-configure

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

If you're using gmake (the make on GNU/Linux, and gmake everywhere else), and you are compiling Courier on a workstation with multiple CPUs and plenty of memory, set the following environment variable:

   MAKEFLAGS="-j 4"; export MAKEFLAGS         # Bourne or Korn shell
or: 
   setenv MAKEFLAGS="-j 4"                    # The C shell

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

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

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

Preparing for installation

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

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

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

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

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

Still, if circumstances absolutely require for you to stick with mailbox files, Courier has limited compatibility support for delivering mail to mailbox files, but you have more homework to do:

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

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

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

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

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

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

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

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

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

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

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

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

OPTIONAL: Install the Socks 5 client toolkit

Courier has the ability to send outgoing SMTP mail through a Socks 5 proxy. The Socks 5 proxy option requires a separate module to be installed before installing Courier. Download the Socks 5 proxy client library from http://www.courier-mta.org/download.php#sox and follow its installation instructions. Binary RPMs can be built from the source code tarball by following the procedure outlined in http://www.courier-mta.org/FAQ.html#rpm using the "courier-sox-version" tarball, and installing the "courier-sox" and "courier-sox-devel" binary RPMs afterwards.

NOTE: Be sure to read the README, NEWS, and INSTALL files in the Courier Socks 5 library toolkit, before attempting to install it for the first time (unless using the RPM 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 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 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 Courier to relay mail via UUCP. You may need to modify your PATH environment variable to include the directory containing uux.

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

The complete reference to all configure script options is provided below. The most important options are:

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.

IPv6

IPv6 support in Courier means basically the following:

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

The configuration script will attempt to detect whether IPv6 structures and functions are available, and automatically enable IPv6 support if they are found. The --without-ipv6 option disables IPv6 support, which may be desired for the following reasons:

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

Compile and run make check

    make
    make check

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

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

Installation

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

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

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

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

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

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

Install configuration files

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

make install-configure

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

make install-configure >upgrade.log

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

PAM configuration

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

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

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

Building RPM packages

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

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

Adjust system paranoia level

There are four setuid binaries in Courier 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 Courier's group id, and restore the original userid, dropping root. The reason that it needs root setuid is to set its real group id, because setting the setgid bit on the executable is not enough. The setgid bit sets only the effective group id, and the root setuid bit is required to set both effective and real group ids. Both real and effective group IDs are needed in order to be able to implement maildrop mail filtering.

/usr/lib/courier/libexec/courier/sqwebpasswd is described in detail in the "OPTIONAL: Changing mail account passwords using the webmail server" section.

Post-installation setup

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

Post-installation checks

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

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

Verify module installation

Run the showmodules utility after all files have been installed, but before you attempt to start Courier. The showmodules utility attempts to load and initialize transport modules that have been configured, without actually starting up Courier. Running showmodules should result in something that looks like this:

   showmodules[5060]: Loading STATIC transport module libraries.
   showmodules[5060]: Installing i586-gnu-linux [0/0]
   showmodules[5060]: Installing local
   showmodules[5060]: Installed local
   showmodules[5060]: Installing esmtp
   showmodules[5060]: Installed esmtp
   showmodules[5060]: Installing dsn
   showmodules[5060]: Installed dsn
   showmodules[5060]: Initializing local
   showmodules[5060]: Initializing esmtp
   showmodules[5060]: Initializing dsn

Test child process termination

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

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

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

Start Courier as root:

/usr/lib/courier/sbin/courier start

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

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

Run the perftest1 script, which can be found in the directory containing Courier's source code:

sh perftest1 1000 "user-test-1 user-test-2 user-test-3 user-test-4 user-test-5"

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

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

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

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

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

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

User/group ID check

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

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

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

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

Send a single message to user:

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

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

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

OPTIONAL: Configure webadmin

This is a web-based administration tool. webadmin is a web CGI application. It is necessary to have a local web server installed in order to use webadmin. Apache will do, but so will any other server with a complete CGI implementation (PHP is not required). Installing webadmin is a three step process:

  1. Move /usr/lib/courier/libexec/courier/webmail/webadmin to your web server's SSL cgi-bin directory. Take care to preserve the binary's ownership and permissions.
  2. Execute "make install-webadmin-password". This prompts for a password, which is saved in the file /usr/lib/courier/etc/webadmin/password.
  3. The web server SHOULD be configured to run webadmin from the cgi-bin directory using SSL only. webadmin's authentication is rather simple: the password is saved in a cookie. Unless SSL is used, the webadmin password can be intercepted in transit. If SSL is not available, an acceptable level of security can be achieved by setting up a firewall that allows web access only from trusted IP addresses, then use a dedicated webadmin password. This is not perfect, but is generally adequate. A firewall is a good idea even if SSL is used. This is not Fort Knox, and webadmin is not going to be publicly accessible, so the only needed security is to keep everyone out except for authorized IP addresses.

    Note that webadmin, by default, will enforce this restriction: either SSL, or access from a local IP address. Create the file /usr/lib/courier/etc/webadmin/unsecureok to allow non-SSL webadmin connections from remote IP addresses.

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

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

Create system aliases

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

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

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

root: postmaster

mailer-daemon: postmaster

MAILER-DAEMON: postmaster

uucp: postmaster

You need to append the following line:

postmaster: admin

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

Run the following command as root:

/usr/lib/courier/sbin/makealiases

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

Send a test message:

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

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

Let's do it again:

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

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

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

Create smtp access list

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

/usr/lib/courier/sbin/makesmtpaccess

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

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

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

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 Courier's default backscatter configuration means that if Courier 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 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 Courier 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 Courier 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. Courier 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 Courier to bounce a received message. Several settings control how Courier filters out its own backscatter, and avoids becoming a nuisance to others.

Two settings are available. The first setting instructs Courier 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 Courier 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 Courier receives a message via SMTP for delivery to a local mailbox, and it bounces for some reason, the bounce will be discarded.

Courier 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 Courier 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 Courier fails to deliver a message to an address, this address goes on the suppression list, and Courier 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 Courier, and which are in its mail queue. The suppression list is checked when Courier is receiving a new message. Courier automatically clears an address from the suppression list after two hours. If the original message encountered a temporary delivery failure, Courier 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 Courier 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 Courier 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, Courier 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, Courier 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 Courier 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 Courier is configured, via the Courier 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 Courier 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), Courier 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:

Qmail compatibility mode.

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

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

Define local domains

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

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

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

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

Create a list of domains to accept mail for

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

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

OPTIONAL: Configure UUCP

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

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

/usr/lib/courier/etc/uucpme

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

/usr/lib/courier/etc/uucpneighbors

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

/usr/lib/courier/etc/uuucprewriteheaders

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

Configure UUCP domain aliases

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

   @example.com: uucp!bang!path!

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

OPTIONAL: Configure LDAP aliasing

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

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

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

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

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

OPTIONAL: Configure mail filtering

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

Courier provides two mail filtering interfaces:

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

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

Miscellaneous UUCP configuration

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

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

Starting and stopping Courier

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

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

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

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

Run Courier in parallel to your mail server

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

OPTIONAL: Configure ESMTP authentication and SSL

Courier supports authenticated ESMTP in order to grant ESMTP relaying privileges to remote users. The following steps set up authenticated ESMTP:

ESMTP over TLS/SSL

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

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

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

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

OPTIONAL: Configure the SECURITY ESMTP extension

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

Overview

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

The SECURITY extension builds on top of several existing, proven, technologies in order to deliver mail with the highest level of security that can possibly be implemented using the existing technology. The several steps in implementing the SECURITY extension:

  1. Install and configure the STARTTLS ESMTP extension. This extension uses TLS/SSL encryption for sending mail.
  2. Create a private, controlled, X.509 Certificate Authority.
  3. Use the private CA to sign X.509 certificates of all mail nodes in the trusted mail network. This CA's certificate is also installed in every trusted mail node.

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

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

Install and configure the STARTTLS ESMTP extension

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

Create a private X.509 Certificate Authority

Create an empty subdirectory:

    mkdir /etc/myca
    cd /etc/myca

There's a convenient OpenSSL script called CA.pl that you want to copy to the current directory:

    cp /usr/share/ssl/misc/CA.pl .

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

Replace:

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

replace with:

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

Also replace:

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

replace with:

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

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

    ./CA.pl -newca

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

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

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

    ./CA.pl -newreq

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

     example.com.  MX 10 mx1.example.com.
     example.com.  MX 20 mx2.example.com.

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

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

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

    ./CA.pl -signreq

This step creates the file newcert.pem that contains a new signed certificate. The private key from the original certificate request must be appended to this file, before the certificate can be used. Simply take the newreq.pem file from the previous step, and