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
- 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: Configure filtering
- Create a list of domains to accept mail for
- Starting and stopping Courier
- Run Courier in parallel to your mail server
- OPTIONAL: Configure ESMTP authentication and SSL
- OPTIONAL: Configure the SECURITY ESMTP extension
- OPTIONAL: Configure the Sender Policy Framework
- OPTIONAL: Configure the IMAP server
- OPTIONAL: Configure IMAP shared folders
- OPTIONAL: Configure IMAP over SSL
- 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: Quota support
- OPTIONAL: Account OPTIONS
- OPTIONAL: Configure outbound faxing
- OPTIONAL: Configure inbound faxing
- OPTIONAL: Install the Courier log analyzer
- Decommission your existing mail server
- Sample init script

## Upgrading an existing installation

### 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-IMAP'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

   FAM (`http://oss.sgi.com/projects/fam/`) is optional. If FAM 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

   Support for SSL/TLS requires OpenSSL. If OpenSSL 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:

- Maildirs or mailbox files

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

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

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

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

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

- What locking mechanism is used on mailbox files

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

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

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

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

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

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

- Create the `courier` user and group IDs

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

- Define the installation directory

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

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

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

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

- Conclusion

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

## 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:`

- `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 Courier in pathname, instead of the default location of `/usr/lib/courier`. Note - the examples in the rest of this text assumes this is where you will install Courier. Do not attempt to install Courier in a directory whose name contains spaces or punctuation marks. Periods or dashes are fine, but refrain the temptation to use other, exotic, punctuation.

- `--with-db=db` or `--with-db=gdbm`

  Courier requires either the GDBM or the DB database library. GDBM is used if both are present. This option forces the selection of the database library.

- `--with-locking-method=function`

  Select a file locking function. Available functions are: `fcntl`, `lockf`, and `flock`. Not every function is available on every platform. If this option is not present, `configure` tries each one, and takes the first one that works. You can select a specific locking function by using this option. This affects both the locking used for delivering mail to mailbox files, and for other kinds of locking that Courier uses internally.

- `--enable-mimecharset=charset`

  Specify the default character set Courier uses when adding MIME headers to a message. If not specified, `us-ascii` is used.

- `--without-tcpddns`

  Use this option if you are running a small network without access to a DNS server. This option will cause `couriertcpd` to use the system resolver's gethostby functions instead of issuing DNS queries. Also: you must initialize the `esmtproutes` control file with the IP addresses of all your servers.

### `configure` reference

Here's a comprehensive list of options for the `configure` script. They are presented in no particular order. In almost all cases, the `configure` script will automatically figure out the correct values, but sometimes it is necessary to specify them explicitly. If you ever have a need to manually specify any configuration option, try to determine whether you need it because of a particular unique case that involves your server only, or whether it affects any server running your hardware, or system. In the later case, try to investigate if it's possible for `configure` to be a bit smarter and make the right decision.

- `--prefix=pathname`

  Install Courier in pathname, instead of the default location of `/usr/lib/courier`. Note - the examples in the rest of this text assumes this is where you will install Courier.

- `--exec-prefix=pathname`

  Specify where Courier's machine-executable binaries should be installed. This defaults to the same directory as given by the `--prefix` option. There will be three subdirectories created underneath `exec-prefix`: `bin` - user-executable binaries; `sbin` - superuser-only binaries; `libexec` - other binaries that are not directly invoked from the command line, but are started by other Courier commands.

- `--bindir=pathname`, `--sbindir=pathname`, `--libexecdir=pathname`

  These options override the default value for the corresponding subdirectory underneath `--exec-prefix` (see above). The `bindir` directory contains programs that can be executed by anyone. `sbindir` contains programs that can only be executed by the superuser. `libexecdir` contains programs and libraries that cannot be directly executed from the command line. The default locations are the `bin`, `sbin`, and `libexec` subdirectories underneath the directory specified by `exec_prefix`.

- `--datadir=pathname`

  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 Courier'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`

  Courier requires either the GDBM or the DB database library. GDBM is used if both are present. This option forces the selection of the database library.

- `--with-locking-method=``function`

  Select a file locking function. Available functions are: `fcntl`, `lockf`, and `flock`. Not every function is available on every platform. If this option is not present, configure will choose the first locking function that's available. You can select a specific locking function by using this option. This affects both the locking used for delivering mail to mailbox files, and for other kinds of locking that Courier uses internally.

- `--enable-mimecharset=charset`

  Specify the default character set Courier uses when adding MIME headers to a message. If not specified, `us-ascii` will be used.

- `--without-tcpddns`

  \Use this option if you are running a small network without access to a DNS server. This option will cause `couriertcpd` to use the system resolver's gethostby functions instead of issuing DNS queries. Also: you will have to initialize the smtproutes control file with the IP addresses of all your servers.

- `--without-explicitsync`

  Normally Courier will automatically sync, or flush out all file buffers to disk, at certain key points in order to try to minimize the extent the mail queue can get corrupted if the system crashes. If the mail queue is installed on a reliable disk array or a network file server, this may not be necessary, and will only serve to slow down the mail delivery. Use this option to turn off syncing.

- `--with-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 Courier to deliver messages. If not specified, `PATH` will be set to `/bin:/usr/bin:/usr/local/bin`.

- `--disable-local-extensions`

  Normally, in addition to accepting mail that's addressed to `<user@domain.com>`, Courier can accept mail that's addressed to `<user-xxx@domain.com>`, for arbitrary values of xxx. In order for that to happen the `user` has to create a special file with delivery instructions. See the `dot-courier(5)` manual page for more information. This option disables this feature.

- `--with-paranoid-smtpext`

  Be paranoid when negotiating Courier-specific ESMTP extensions with remote servers. The Courier mail server defines and implements certain experimental ESMTP extensions: `XVERP` and `XEXDATA`. Problems may result in the event that someone else uses the same name to implement some other extension. If this option is specified, Courier's `ESMTP` server will also advertise a dummy ESMTP capability called `XCOURIEREXTENSIONS`, and will not recognize any Courier-specific extensions unless the remote mail server also advertises this dummy ESMTP capability.

- `--enable-workarounds-for-imap-client-bugs`

  There are several confirmed bugs in some IMAP clients that do not properly implement the IMAP4rev1 protocol. This option enables some workarounds for those buggy IMAP clients. NOTE: `make check` will fail if this option is used. You should first configure without this option, and if all post-configuration tests succeed, rerun configure with this option and recompile.

- `--with-qdircount=n`

  Set n to be the number of mail queue subdirectories. In order to improve the speed of access to the mail queue, messages are stored in subdirectories, hashed by the message queue number. n specifies how many subdirectories will be created. If this option is not specified, 100 subdirectories will be used. WARNING: once you've installed Courier once, if you decide to reconfigure and reinstall, you MUST use the same subdirectory count (by default, or explicitly), otherwise you'll end up with a big mess on your hands if you have ANY messages in the mail queue. If you need to change this option, wait for all messages in the queue to be flushed out, and reinstall with an empty mail queue.

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

  Sometimes Courier sometimes needs a good source of random noise. If `configure` finds `/dev/urandom`, it will use that. If your random device is named otherwise, specify it using this option. If you don't want to use a random device, specify `--without-random`, and Courier will generate some noise on its own. Courier will generate noise based on the output of a random ps command, and several other, hopefully unpredictable, sources.

- `--without-certdb`

  Do not install a default set of trusted X.509 root CA certs (in order to validate the remote server's X.509 certificate). See "Configure ESMTP authentication and SSL" for more information.

- `--with-certdb=pathname`

  Do not install the default set, but put pathname as the default location of the root CA database, into the configuration file. This is a convenient option to have Courier use an external, previously installed, root CA database.

- `--with-waitfunc=wait, --with-waitfunc=wait3`

  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-ispell, --with-ispell=program`

  Courier's webmail server can use spell checking, if the ispell program is available (aspell can be used too). If configure finds ispell, spell checking is enabled. Use `--without-ispell` to forcefully disable spell checking. If ispell is not in the current search path, use `--with-ispell=program` to explicitly set the location of ispell. See "Configure the webmail server" for more information on ispell or aspell.

- `--disable-utf7-folder-encoding`

  Use this option if you will not have IMAP access to mail accounts, and provide only webmail access. IMAP mail clients use modified UTF-7 to encode high 8-bit characters in folder names. If there will not be IMAP access to mail accounts, modified UTF-7 support in the webmail served can be removed, saving a little bit of overhead.

- `--enable-unicode`

  Include the ability in the IMAP server to search and sort messages in character sets besides the default ISO-8859-1/US-ASCII. All character set tables supported by Courier's IMAP server will be included. See "Configure the IMAP server" and "Configure the webmail server" for more information. Additionally, all unicode tables will also be included in the webmail server. Keep this in mind because the full unicode table set is quite large.

  The webmail server also uses unicode tables to implement modified UTF-7 folder name encoding (see the `--disable-utf7-folder-encoding`), additionally the webmail server will be able to translate message text to the local character set, if the two are different and the unicode tables for both character sets are available.

- `--enable-unicode=charset,charset,...`

  Include ability to search and sort messages, but only for these character sets. Also, include only these character sets in the webmail server. See "Configure the IMAP server" and "Configure the webmail server" for more information.

- `--enable-imageurl=/url`

  Use /url/ as the URL to the static images displayed by the webmail server. HTML pages are dynamically generated by the webmail server CGI, but they also include some static icons. The webmail CGI will use /url as the URL to the directory containing the static images. The default URL is "/webmail", which means that the static images must be installed in the `<DocumentRoot>/webmail` directory. This is a manual process that is described in more detail in the "Configure the webmail server" section, below.

- `--enable-https, --enable-https=login, --enable-https=auto`

  If you have an SSL-enabled web server, use the `--enable-https` option in order to configure webmail access for SSL. Use `--enable-https=login` in order to use SSL only when logging in, to send the password. Use `--enable-https=auto` to generate relative URLs, so that users can connect with either http or https and their session will remain that way.

  `--enable-https=login` and `--enable-https=auto` require that your http and https URLs that refer to the webmail CGI be identical (which is the usual default).

  `--enable-https=auto` is the default. Use `--disable-https` if you need to completely disable https, for some reason.

- `--enable-hardtimeout=7200`

  set the hard timeout for webmail sessions (in seconds). The default is 2 hours. webmail sessions are unequivocally logged out after the indicated time interval.

- `--enable-softtimeout=1200`

  set the inactivity timeout for webmail sessions (in seconds). The default is 20 minutes. webmail sessions are logged out if there's no activity for the indicated time interval.

- `--with-defaultlang=lang`

  reserved for future use.

- `--enable-mimetypes=file:file:file`

  this is a colon-separated list of all of your `mime.types` files. The `mime.types` configuration files are used to map file extension to their corresponding MIME content types. The configuration script will look in several directories where `mime.types` usually exists. You can use this option to explicitly specify a list of `mime.types` files to be used, instead of the default.

- `--enable-bannerprog=pathname`

  advanced option that sets a banner program that the webmail server will execute. This program should print HTML, on standard output, to generate a typical banner.

- `--with-maxargsize=bytes,--with-maxformargsize=bytes`

  Sets an upper limit on the size of CGI arguments for the webmail server. Normally there's no reason to modify the defaults (500,000 and 2,000,000 bytes). The latter is generally the maximum allowed size of an attachment. The former is generally the maximum allowed size of 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).

- `--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 Courier without this option, run `make check`, then reconfigure Courier with this option.

## IPv6

IPv6 support in Courier means basically the following:

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

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

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

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

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

## Compile and run `make check`

        make
        make check

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

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

## Installation

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

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

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

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

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

`make install` installs Courier binaries with debugging data, which is probably a good idea to do while Courier is in development. Use `make` `install-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:

- An hourly `cron` job needs to be created to run the `cleancache.pl` script, which purges expired webmail login cache records. Logging in to the mail account via the web creates a file in a temporary directory that caches the login session identity. The output of `make install` includes the command that needs to be set up as a `cron` job by root. The `cron` job runs `su` to change to the userid that owns the login cache directory, then runs the purge script. The `su` command on some system uses a slightly different syntax than what's shown by `make install`. It may be necessary to consult the `su` man page before setting up the cron job. Run the `su` command as root, to make sure that its syntax is correct, before setting up the `cron` job. The `cron` job can be omitted if webmail is not going to be used.

## Post-installation checks

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

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

### Verify module installation

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

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

### Test child process termination

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

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

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

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

- `courierd`

  this file controls general aspects of Courier's message processing. A default file is installed with comments describing what the various options are. Review the default options, and make whatever changes you deem appropriate. You will probably need to make changes to this configuration file in order to select the correct way to deliver local mail (whether to have Courier handle the delivery directly, or whether to run procmail or maildrop). There are comments in this file that tell you what needs to be done to have Courier use a separate local mail delivery agent, such as `procmail`, for mail delivery. Read and follow the instructions there.

- `esmtpd`

  this is an important file that controls Courier's ESMTP server. Options in this file include setting the maximum limit on simultaneous server connections, whether to disable certain optional SMTP features, whether or not you have a mail filter module installed, and whether or not blacklists are used.

- `esmtpd-msa`

  this file controls Courier's ESMTP message submission server (RFC 2476). The settings in this file supplement the settings in `esmtpd`. The default startup script first reads `esmtpd`, then `esmtpd-msa` in order to initialize the ESMTP message submission server on port 587.

- `smtpaccess`

  this configuration file/directory is used to ban explicit IP addresses from connecting to the ESMTP server at all, or to specify which IP address ranges are allowed to relay mail through the ESMTP server. The default file turns on relaying in a couple of reserved IP address ranges, as an example. The `makesmtpaccess` command must be executed for any changes to `smtpaccess` to take effect.

- `pop3d`

  this file sets various options for Courier's POP3 server. Courier's POP3 server can be used only if mail is stored in Maildirs. You will need to use another POP3 server if you choose to deliver your mail to legacy mailbox files. A default configuration file is installed, describing the available options.

- `imapd`

  this file sets various options for Courier's IMAP server. Courier's IMAP server can be used only if mail is stored in Maildirs. You will need to use another IMAP server if you choose to deliver your mail to legacy mailbox files. A default configuration file is installed, describing the available options.

#### Qmail compatibility mode.

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

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

## Define local domains

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

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

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

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

## Create a list of domains to accept mail for

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

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

## OPTIONAL: Configure UUCP

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

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

### `/usr/lib/courier/etc/uucpme`

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

### `/usr/lib/courier/etc/uucpneighbors`

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

### `/usr/lib/courier/etc/uuucprewriteheaders`

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

## Configure UUCP domain aliases

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

       @example.com: uucp!bang!path!

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

## OPTIONAL: Configure LDAP aliasing

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

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

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

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

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

## OPTIONAL: Configure mail filtering

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

Courier provides two mail filtering interfaces:

- Global mail filters

  these filters are installed and will be used to filter every incoming message. Global mail filters are permanently running daemons that create and listen on a filesystem domain socket. Each new message that Courier receives must be acknowledged by every global mail filter. Note that if global mail filters are installed, but their daemons are not running, Courier will not accept any new messages.

- Local mail filter

  this filter can be used when the message is addressed to a local recipient - when Courier itself will deliver the message to a physical mailbox. Local mail filtering is designed to be primarily used by the `maildrop` mail filter. With the local mail filtering installed, individual recipients can create files containing mail filtering instructions that can selectively accept or reject individual messages.

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

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

### Miscellaneous UUCP configuration

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

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

## Starting and stopping Courier

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

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

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

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

## Run Courier in parallel to your mail server

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

- Your existing mail server can continue to handle incoming mail, by listening on the smtp port. Courier will be used to send all outgoing mail. This is accomplished by configuring your mail software to run `/usr/lib/courier/bin/sendmail` to send mail, instead of your current sendmail program.
- Courier can handle incoming mail by listening on the smtp port, and your existing mail server can continue to handle all outgoing mail. You will need to stop your existing mail server from listening on the smtp port, and run the following command:

      /usr/lib/courier/sbin/esmtpd start

  from your system start up script. You should also add `/usr/lib/courier/sbin/esmtpd stop` to your system shutdown script. Note that there's a separate script that starts the ESMTP submission server on port 587 - `/usr/lib/courier/sbin/esmtpd-msa`, that is used in an analogous fashion.

## OPTIONAL: Configure ESMTP authentication and SSL

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

- Edit `/usr/lib/courier/etc/esmtpd` and 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, Courier supports `LOGIN`, `PLAIN`, `CRAM-SHA1` and `CRAM-MD5`. The list of authentication methods is sometimes influenced by the installed authentication modules in the Courier 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 Courier.

### ESMTP over TLS/SSL

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

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

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

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

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

## OPTIONAL: Configure the SECURITY ESMTP extension

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

### Overview

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

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

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

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

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

### Install and configure the STARTTLS ESMTP extension

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

### Create a private X.509 Certificate Authority

Create an empty subdirectory:

        mkdir /etc/myca
        cd /etc/myca

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

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

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

Replace:

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

replace with:

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

Also replace:

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

replace with:

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

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

        ./CA.pl -newca

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

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

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

        ./CA.pl -newreq

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

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

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

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

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

        ./CA.pl -signreq

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

       [ description of the certificate ]

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

       [ binary goo ]

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

       [ binary goo ]

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

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

### Configure trusted mail nodes

Two files must be installed on every trusted mail node.

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

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

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

### Testing

The following simple steps can be carried out to verify that everything is working correctly. These examples use two mail nodes called `send.example.com` and `receive.example.com`. The test messages are sent from `send.example.com`, and are addressed to `receive.example.com`. Courier must be restarted on both `send` and `receive`, after reconfiguring the machines for each test. It is not strictly necessary to do this every time, actually, but it's simply easier to do make it a part of the routine. It is necessary to restart both the main Courier daemon processes as well as the separate ESMTP daemon process (on `receive`):

        courier stop
        courier start
        esmtpd stop
        esmtpd start

1. Temporary get rid of `/usr/lib/courier/bin/couriertls` wrapper on `receive.example.com`. Rename it to `couriertls.save`. `STARTTLS` is automatically disabled if `couriertls` is missing,
2. Run the following command on `send.example.com`:

           echo "To: postmaster" | /usr/lib/courier/bin/sendmail \
                     -S STARTTLS postmaster@receive.example.com

   This message should bounce back since `receive` has STARTTLS disabled.

3. Restore `couriertls` on `receive.example.com`, but then rename it on `send.example.com`. The situation is now reversed, and the test message should still bounce.
4. Restore `couriertls` on `send.example.com`. Edit `receive`'s `/usr/lib/courier/etc/esmtpd` file. Comment out the current `TLS_CERTFILE` setting (which points to the private CA certificate). Reset `TLS_CERTFILE` to `/usr/lib/courier/share/esmtpd.pem`, which is the self-signed test certificate created by the `mkesmtpdcert` script, when STARTTLS support in Courier was first set up.

   Send a test message WITHOUT the "-S STARTTLS" option. This message should go through, assuming all the other setting in all configuration files are the initial defaults. The regular ESMTP STARTTLS extension, without authentication, will be used the deliver this message. Verify this by checking the headers in the received message on `receive.example.com`.

   Send a test message WITH the "-S STARTTLS" option. It should bounce, even though `receive.example.com` supports STARTTLS. That's because it is using an X.509 certificate that's not signed by the private CA authority.

5. Restore `TLS_CERTFILE` on `receive`, and send a test message with the `-S STARTTLS` option, which should now go through.

### Force SECURITY for selected domains

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

    receive.example.com:  /SECURITY=STARTTLS

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

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

### Limitations

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

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

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

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

## OPTIONAL: Configure the Sender Policy Framework

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

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

- Edit `/usr/lib/courier/etc/imapd`. If you want to use IMAP SASL authentication, 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.

### Foreign character set sorting/searching

The IMAP server can sort and search messages using other than the default us-ascii/iso-8859-1 character set. You can find the list of available character sets in the file `unicode/charsetlist.txt`.

The default configuration includes only the ISO-8859-1/US-ASCII character set. Use the `--enable-unicode` option to include all character sets.

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

It is also possible to include translation tables only for selected character sets. Example:

`--enable-unicode=iso-8859-1,utf-8,iso-8859-10`

Technically, IMAP servers must support the UTF-8 character set, however few IMAP clients (I've yet to see one, actually) care about UTF-8, so the UTF-8 character set is optional in Courier-IMAP. The only required character set - which is always included, explicitly or implicitly - is ISO-8859-1/US-ASCII.

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

Note that character set translation tables take up additional memory. This should not be a problem in most cases. Most compilers place the read-only character set tables into a shared text segment, which is shared by all running server instances. Using `--enable-unicode` should not really be much of a burden for most modern operating systems.

Attentive individuals will observe that all character set tables are compiled even without the `--enable-unicode option`. That is normal -- only the explicitly selected character set tables will actually make it into the final executable.

## 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 implement IMAP over SSL you will need to separately obtain and install OpenSSL. Download OpenSSL from `http://www.openssl.org/`. Follow the instructions in the OpenSSL package to install it and configure it. IMAP over SSL has been tested with OpenSSL 0.9.5a.

The `/usr/lib/courier/etc/imapd-ssl` configuration file sets some additional options for OpenSSL, which you may need to adjust. Consult that configuration file for additional information. Then, you also have to run the `/usr/lib/courier/sbin/imapd-ssl` script from your system startup and shutdown scripts, just like the `/usr/lib/courier/sbin/imapd` script. You may accept both SSL and non-SSL connections by running both scripts.

Note that SSL requires a valid, signed, X.509 certificate to be installed where Courier expects to find it. The default location for the X.509 certificate, in PEM format, is `/usr/lib/courier/share/imapd.pem`. The X.509 certificate must be signed by a certificate authority that is known to the IMAP client. You can generate your own self-signed certificate by running the script `/usr/lib/courier/share/mkimapdcert` which will work too, except that IMAP clients using SSL will display a warning message the first time they connect to the server. To get rid of the warning message you'll have to pay for a signed X.509 certificate. The gory details of setting up SSL is beyond the scope of this document, and you should consult the OpenSSL documentation for more information.

The `mkimapdcert` script will not overwrite an existing `imapd.pem` certificate, in order to allow precompiled packages to simply call `mkimapdcert` after installation, without worry.

The IMAP server also supports the IMAP STARTTLS extension as an alternative or a complement to IMAP over SSL. The `/usr/lib/courier/etc/imapd-ssl` configuration file is also used to enable or disable IMAP STARTTLS, which has all the same requirements and prerequisites as IMAP over SSL.

## OPTIONAL: Sending mail via an imap connection

This server allows using the IMAP connection to send E-mail. Normally, the IMAP protocol provides only access to mail in an existing mail account, and mail clients must use SMTP in order to send mail. The Courier-IMAP server has an optional setting to enable mail to be send via an IMAP connection in a manner that should work with all existing IMAP mail clients. This can be useful when an account is logged in from a shared access pool which normally blocks most access to the SMTP port.

This is implemented by enabling a setting in the `imapd` configuration file that designates a folder as a special "Outbox" folder. The default setting is a folder called "Outbox" (IMAP path INBOX.Outbox), but the name can be changed to anything. This folder, for the most part, is no different than any other folder. If a folder by that name doesn't exist, it needs to be created, just like any other IMAP folder. It looks and acts like any other folder, except that each message added to the folder, via IMAP's APPEND or COPY command, will also be mailed out by the Courier-IMAP server to the addresses listed in the `To:`, `Cc:`, and `Bcc:` headers.

It should be possible to use this to send mail from any IMAP client by:

1. Composing a draft message, telling the IMAP client to save the draft message in its drafts folder on the IMAP server.
2. Opening the drafts folder, and moving or copying the message to the Outbox folder.
3. The act of copying the message into the Outbox folder will send the mail. There won't be any explicit notification to the fact that the message was sent, so it's a good idea to include your own E-mail address on the Cc: list.

> NOTE: it is tempting to configure the IMAP mail client to use Outbox as its default folder for saving drafts. Resist the temptation. If you forget, you'll save a partially completed draft, which will be then obediently mailed out.

> NOTE: the message, in addition to being sent, will be saved in the folder in the normal fashion. After saving the message, reopen the Outbox folder and delete the sent message, or move it someplace else.

> NOTE: when enabled, the Courier-IMAP server will advertize a private `XCOURIEROUTBOX` IMAP capability. It is theoretically possible to code an IMAP mail client that reads this capability and automatically configures itself accordingly -- when this IMAP capability is present -- to send E-mail in the normal way but using the IMAP connection. At this time, I'm not aware of any actual mail clients that know how to do this.

> NOTE: many mail clients save some additional internal information in headers of draft messages. The internal information is normally removed before the mail client sends the message. Make sure that none of this extra information is something that should not be mailed out.

## OPTIONAL: Configure IMAP realtime folder status updates

If the FAM, the File Alteration Monitor (`http://oss.sgi.com/projects/fam/`) is installed it will be 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 Courier 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

Courier includes an integrated POP3 server. The following steps will set it up:

- Edit `/usr/lib/courier/etc/pop3d`. Very few POP3 clients support POP3 SASL authentication, but if you want to use it, for some reason, uncomment the `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.

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

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

    BrowserMatch "MSIE" nokeepalive downgrade-1.0 force-response-1.0

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

### 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;

### Modified UTF-7 encoding and unicode support

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

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

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

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

### Spell checking

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

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

### Images

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

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

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

### Alternative timezones

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

### LDAP address book import

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

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

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

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

### 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 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 Courier's configuration directory (`/usr/lib/courier/etc` by default).

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

### Happy filtering.

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

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

### 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 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: Quota support

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

### Filesystem quotas

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

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

### Maildir quotas

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

    userdb account set quota=quota
    makeuserdb

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

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

## Account OPTIONS

It is possible to adjust certain parameters on an account-by-account basis. This feature is actually implemented in the Courier 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 Courier, must also be installed. Courier does not handle the actual job of faxing. Courier only reformats E-mail messages as fax images, and runs mgetty+sendfax to send the fax. Courier also needs additional software to convert E-mail messages to faxes. All additional software must be separately installed, configured, and tested before enabling faxing in Courier. Most systems already include the following software as part of the base operating system, so in most cases adding fax support will not actually require any additional software to be installed, only minor reconfiguration of existing software:

### mgetty+sendfax

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

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

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

### groff or troff, ghostscript, NetPBM

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

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

### Enabling faxing

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

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

### Sending faxes

E-mail messages may contain attachments. Courier combines all attachments in the message into a single fax transmission. Attachment types may be freely mixed. A single message may contain one plain text, and one PDF attachment, for example. It is possible to select certain options, as follows:

- `<phonenumber@fax-lowres>`

  sends a low-resolution fax.

- `<phonenumber@fax-ignore>`

  Ignore attachments that Courier doesn't know how to convert to a FAX image format. Normally, if an attachment cannot be converted the whole message is returned as undeliverable.

- `<phonenumber@fax-cover>`

  sends only the cover page. This can be useful for .courier files. See the courierfax(8) manual page for an example.

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

### Cover pages

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

### Dialing

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

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

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

### Security

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

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

## OPTIONAL: Configure inbound faxing

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

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

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

## OPTIONAL: Install the Courier log analyzer

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

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

## Decommission your existing mail server

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

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

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

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

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

## Sample init script

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

NOTE: the following script may take a long time to finish, the very first time it runs. That's because the script automatically creates test SSL certificates the first time the script runs (provided that SSL support is available). This can take as much as 5-6 minutes on a slow machine. Subsequent starts should take only a few seconds.

    #! /bin/sh
    #
    # chkconfig: 2345 35 65
    # description: Courier - SMTP server
    #
    # NOTE: The 'restart' here does a "hard" stop, and a start.  Be gentle, use
    # "courierd restart" for a kindler, gentler, restart.
    #
    #

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

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

            echo -n "Starting Courier mail server:"

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

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

            esmtpdcert=0

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

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

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

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

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

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

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

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

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

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

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

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

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