# Courier FAQ

This is a beginning of a modest FAQ. Contributors:

- `[PP]` - Patrick Price `<sysadmin``@moment.net>`
- `[RS]` - Roland Schneider `<list-courier``@serv.ch>`

Table of contents:

- Configuration issues
  - The `configure` script is stuck in an infinite loop
  - What's the deal with authentication modules? Why can't I get OpenLDAP/MySQL/Vpopmail/PAM/whatever working?
  - Configuration script reports the following error, and stops: "Cannot find either the gdbm or the db library", or it fails in the `gdbmobj` or `bdbobj` subdirectory.
  - Compilation fails on Solaris in the waitlib subdirectory
  - Compiling Courier-IMAP on OS/X
  - `make install-strip` or `make check` fails
  - `gmake check` fails on Compaq Tru64 UNIX
  - I don't know how to build the RPM packages as non-root
  - Problems compiling/linking with vpopmail
- ESMTP
  - Why are my e-mails taking so long to send?
  - Courier delivers ESMTP mail with a strange error message
  - Server is not accepting any mail, returns a `450 Service unavailable` error every time.
  - How do I enable relaying for an IP address range?
  - How do I implement virtual domain hosting?
  - Courier keeps restarting every minute, and there are weird syslog messages about "unsafe" hard links
  - How to configure Courier to be a backup MX for a domain
  - Messages with more than 20 recipients are rejected
- IMAP
  - My IMAP client doesn't work
  - Can't create IMAP folders, only subfolders of INBOX
  - Can't login via IMAP
  - Repeated messages in syslog: "Failed to create cache file: maildirwatch (user) Error: Input/output error Check for proper operation and configuration of the File Access Monitor daemon (famd)." How can I solve it?
  - Q: I heard that Courier does not implement IMAP properly
- POP3
  - The POP3 server doesn't run at bootup
  - Can't login via POP3
- Webmail
  - How do I create new system accounts via the webmail server?
- Miscellaneous
  - Asking for help on the courier-users mailing list
  - Using virtual domains
  - Using `fetchmail`

## Configuration and installation

### Q: The `configure` script is stuck in an infinite loop

A: It's not. Courier is made up of over thirty modular pieces, and each one has its own `configure` script. All `configure` scripts are recursively executed. `configure` scripts are generated off a template, and share a lot of common code, so when `configure` runs, it seems like the same script is being executed over and over again.

### Q: What's the deal with authentication modules? Why can't I get OpenLDAP/MySQL/Vpopmail/PAM/whatever working?

A: The authentication library used by Courier (and Courier-IMAP, and SqWebMail) is probably the most thorniest part of the package. Some people just breeze through authentication module configuration, others just have one problem after another. There is no single point at which people get stuck. Any one of a set of problems can materialize and brings things to a halt. This FAQ entries explains the authentication modules in greater detail. The information given here should be sufficient to get everything in working order.

The authentication modules serve three purposes:

1. Determine if a given E-mail or a login name is valid, or not.
2. Determine if the password that is used to access the mail account is valid.
3. Determine where the mailbox for this mail account lives on the system.

The authentication modules are generally used in one of two ways:

> A. When delivering an E-mail message, Courier uses functions #1 and #3 to figure out where the mail needs to go.

> B. When the owner of the mail account logs in to read the mail, functions #1, #2, and #3 are used to open the mail account (this is all provided that maildirs are used, since Courier's IMAP, POP3, and webmail servers talk to maildirs only).

The authentication library therefore provides an authentication layer that cleanly separates the vague notion of an "E-mail address" and the actual files and directories where mail for this account goes. Courier provides several authentication modules. Not every authentication module will be compiled and installed on every system. Some authentication modules require external libraries to be present. The `configure` script inventories the system configuration, and tries to figure out which authentication modules are needed.

Usually, this is an automatic process. Occasionally, some manual intervention will be necessary.

#### `authpwd`, `authshadow`, and `authpam`

These three authentication modules are used in the most simple environment - authentication based on the system password file. They use the traditional `pwd.h` and `group.h` library functions. Mail to `<user@domain>` is delivered to the system account `user`, in the default mailbox location specified in the `courierd` configuration file. The IMAP, POP3, and webmail servers assume that default mailbox is `$HOME/Maildir`. The only difference between these three authentication modules is that `authpwd` reads the account password from the `/etc/passwd` file, `authshadow` reads the `/etc/shadow` file, and `authpam` uses the PAM library to authenticate passwords. This actually allows account passwords to be read from sources other than the `passwd` or `shadow` files. For example, if the `pam_smb` PAM module is used, it may be possible to authenticate passwords against an NT domain controller, but this is really outside the scope of this document.

If the `configure` finds that the system uses `PAM` for authentication, `authpam` will be automatically installed, and `authpwd` and `authshadow` will NOT be installed. This is because reading the `passwd` and `shadow` files is not recommended when PAM is used for authentication, since the `passwd` and `shadow` files may be (as an example) simply a text dump of the real account database, which is stored elsewhere.

NOTE: PAM is only used for authenticating password. The `authpam` module still uses the `pwd.h` and `group.h` library to find the account's home directory and mailbox.

#### `authuserdb/authcram`

This is a poor man's virtual mail account implementation. The `authuserdb` module is accompanied by a set of Perl scripts that are used to map arbitrary E-mail addresses to arbitrary make-believe "home directories" and mailboxes. The `authuserdb` module is a convenient way to implement a comparatively small number of mail accounts without bothering to create real system accounts, or using a more complicated LDAP or MySQL-based account database.

The E-mail addresses, the location of the corresponding mailboxes, and other miscellaneous information is kept in a set of plain text files. A couple of Perl scripts are provided to conveniently enter and edit the contents of the `userdb` text files, and compile them into a binary database format that's used directly to deliver to/read the mailbox for the corresponding E-mail address.

`userdb` is loosely based on the traditional passwd/shadow files. There are two binary database files, one world readable, the other not (that one contains just the passwords). Each "mail account" has the usual properties defined in the `userdb` database: name, "home directory", uid, gid, and password. This is basically an equivalent to the traditional `passwd` file, except that an efficient binary database format is used to search it.

All the traditional account properties - the uid and the gid - are present, that doesn't mean that every `userdb` account has to have unique properties. The most typical environment allocates a single uid/gid for all mail accounts, and creates all mail accounts with the same uid/gid, but different pseudo-homedirs and mailboxes.

The `userdb` database contains a couple of other fields that are not found in the traditional `passwd` file. The `mail` field specifies a non-default location of the mailbox for the account, and overrides the assumed default of $HOME/Maildir. The `quota` field is used for "Maildir quotas", a loosely-implemented cap on the maximum size of the given maildir. The usage of maildir quotas is described in the INSTALL file.

`userdb` records may include other arbitrary fields too. Courier will simply ignore them. They can be used to conveniently store system-specific custom information.

The `authuserdb` module is designed to handle up to a couple of thousand mail accounts. Beyond that, more "heavyweight" modules should be used, such as `authldap` and `authmysql`. Although the binary `userdb` database is rather quick, creating the binary database from the original plain text files is a comparatively slow process, and it must be done every time any changes are made to the `userdb` files. The conversion from text to binary is done by a couple of Perl scripts. Perl is an interpreted language, and is comparatively slow. `userdb` is not meant to handle huge lists of accounts, so no attempt has been made to optimize the whole process.

#### `authldap`, and `authmysql`

These two modules are used to store all account information in an LDAP directory or a MySQL server. Except for the actual back-end, these two modules have similar functionality. Both of them have a corresponding configuration file which defines where the server is, and the name of the fields where the requisite information can be found. The `configure` script will automatically add these modules if it finds the requisite development libraries: OpenLDAP development libraries or MySQL development libraries.

Note that it is not sufficient to have just the runtime support libraries available, in order to compile `authldap` or `authmysql`. Some operating system distributions provide separate "runtime" and "development" packages for OpenLDAP and MySQL. The "development" package will contain the necessary files to compile `authldap` and `authmysql`. Once compiled, the modules can be installed on any server that contains only the runtime support files.

Normally, if the `configure` scripts detects that the development libraries is installed, the appropriate module will be automatically compiled and installed. However, for an external library to be detected, it must be installed wherever the C or the C++ compiler looks for libraries.

Courier relies on the C or the C++ compiler to detect the availability of a particular library. Example: if OpenSSL is installed in the directory `/usr/local/ssl` chances are that the C or the C++ compiler does not usually search this directory for libraries or include files. Most C and C++ compilers search only the directories `/lib`, `/usr/lib`, and `/usr/include` (for include files).

All C and C++ compilers allow you to specify any additional directories to search, beside the default ones. The configuration script uses the environment variables `CPPFLAGS`, `CFLAGS`, and `LDFLAGS` to pass extra options to the compiler's preprocessor, the compiler itself, and the linker.

For example, if OpenSSL's include files are installed in the directory `/usr/local/ssl/include`, and OpenSSL libraries are installed in `/usr/local/ssl/lib`, the `gcc` compiler needs to have the `-I/usr/local/ssl/include` option for the preprocessor, and the `-L/usr/local/ssl/lib` option for the linker. So, to have the configuration script detect OpenSSL, use the following commands:

    CPPFLAGS="-I/usr/local/ssl/include"
    LDFLAGS="-L/usr/local/ssl/lib"
    export CPPFLAGS
    export LDFLAGS
    ./configure [ options ]

The same applies for OpenLDAP, MySQL, and any other library. The configuration script does not maintain a list of all the non-standard locations where various libraries get installed by default, because that's subject to change at any time. The configuration script expects that the compiler can find the development files by itself.

#### `authvchkpw`

`authvchkpw` uses the `vpopmail` library to handle the authentication tasks. `Vpopmail` is a virtual domain management library that is popular on Qmail systems.

The `Vpopmail` library often uses MySQL by itself, but `Courier!` doesn't have a way of knowing that. When that happens, `authvchkpw` will fail to compile because it is necessary to link `authvchkpw` with MySQL libraries. When that happens, the Makefile must be manually edited to link `authvchkpw` with MySQL.

#### `authcustom`

This is a dummy authentication modules, it doesn't do anything. It is a placeholder to insert custom authentication code.

#### `authdaemon`

`authdaemon` is a "metamodule". It is not a real authentication modules, but acts like one. When `authdaemon` is selected, the `authlib` authentication library compiles all the other authentication modules into a separate program, `authdaemond`, that runs as the background process. The `authdaemon` module receives all authentication requets, and forwards them to the `authdaemond`.

This approach is used to optimize database-driven modules such as `authldap` or `authmysql`. When invoked separately, `authldap` must log in to the server, process the authentication requests, then disconnect. Lather, rinse, repeat.

As part of the permanent `authdaemond` background process, these modules log in to the database server, and maintain a persistent long-running process, which is used to process a stream of authentication requests. The configuration file for the `authdaemond` process specifies the number of `authdaemond` processes that will be started. This allows Courier to handle heavy volumes of authentication requests.

#### Authentication module configuration

It is possible to have more than one authentication module configured. For example, using `authpam` to authenticate system accounts, and `authuserdb` to authenticate virtual mail accounts. The `configure` script inventories the system configuration and will often pick several authentication modules that can be used with the existing system configuration.

There are two ways to disable unwanted authentication modules. The `configure` option `--without-name` disables module name. Another way is to simply disable the authentication module at runtime. The configuration file for the main Courier mail server, the IMAP, POP3, and webmail servers specifies which authentication modules the servers use. When `authdaemon` is installed, the `authdaemond` configuration file lists the active authentication modules. Removing the name of the authentication module from the list will effectively disable it.

### Q: Configuration script reports the following error, and stops: "Cannot find either the gdbm or the db library"

A: Courier requires either the GDBM library or the Berkeley DB library to be installed. If you have the library installed, it is possible that it is installed in a non-standard location. See "Q: I have OpenLDAP, or OpenSSL, or MySQL installed" for how to resolve this situation.

### Q: Configuration script fails in the `gdbmobj` or `bdbobj` subdirectory.

A: There are two possible causes of this error:

- A C++ compiler is not installed.
- The corresponding library is installed in a non-standard location.

Another possible reason for this error is that the GDBM or the Berkeley DB library is not installed in a directory that is searched by the C and C++ compilers, by default. See "Q: I have OpenLDAP, or OpenSSL, or MySQL installed" for how to resolve this situation.

### Q: Cannot find the GDBM library during compilation

A: If you have `libgdbm.so` installed in `/usr/local/lib` and `gdbm.h` installed in `/usr/local/include`, it's possible that your compiler doesn't search those directories. Reconfigure your compiler to search those directories by default. Try setting `CPPFLAGS` and `LDFLAGS` when running configure:

    CPPFLAGS="-I /usr/local/include" \
       LDFLAGS="-L /usr/local/lib" ./configure [options]

It is also possible that `libgdbm.so` is not found at runtime because your dynamic linker doesn't search `/usr/local/lib` either. You will have to reconfigure your dynamic linker.

An alternative solution is to install soft links in `/usr/lib` and `/usr/include` to point to the GDBM library.

### Q: Compilation fails on Solaris in the waitlib subdirectory

A: Use `--with-waitfunc=wait3` option to configure. A better solution is to pester Sun to fix their kernel. Using this option is just a bandaid solution, and you might still experience runtime problems with zombie processes not being reaped, etc... One person reported that installing the fix for bug `"4220394 wait3 library function fails after 248 days"` fixes this problem, someone else claimed that this continues to happen even after installing this patch.

## Compiling Courier-IMAP on OS/X

Set the RANLIB environment variable before running the `configure` script, as follows:

>     RANLIB="ranlib -c"
>     export RANLIB
>     ./configure [ options ]

### Q: `make install-strip` fails

Use `make install` instead.

### Q: `make check` fails

Use the GNU make.

make check will fail if `--enable-workarounds-for-imap-client-bugs` option is selected. It's not a bug, it's a feature.

### Q: `gmake check` fails on Compaq Tru64 UNIX

A: A patchkit for Tru64 5.x that fixes this problem is scheduled to be released by Compaq in early spring 2002. Tru64 4.x is not affected by this problem.

### Q: I don't know how to build the RPM packages as non-root

A: You should really go out and get a copy of "Maximum RPM". It's very out of date, but if you learn the basics, you'll be able to figure the rest out by yourself. The following instructions are applicable to RPM 3.0.4, or higher. First, you need to create a mirror image of the main RPM directory in your account:

        mkdir $HOME/rpm
        mkdir $HOME/rpm/SOURCES
        mkdir $HOME/rpm/SPECS
        mkdir $HOME/rpm/BUILD
        mkdir $HOME/rpm/SRPMS
        mkdir $HOME/rpm/RPMS
        mkdir $HOME/rpm/RPMS/i386

Use `sparc`, or `alpha`, or whatever's appropriate. Finally:

        echo "%_topdir    $HOME/rpm" >> $HOME/.rpmmacros

That's it, now you can build your RPMs:

        rpm -ta courier-0.40.tar.bz2

or,

        rpmbuild -ta courier-0.40.tar.bz2   # For RPM 4.1, and higher (Red Hat 8.0)

### Q: I want to change the options that the RPMs are built with

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

- Move the tarball to your `SOURCES` directory.
- Extract a single file from the tarball, `courier.spec`. This file is found at the top level of the source tree.
- Move `courier.spec` to your `SPECS` directory. Edit it and make whatever changes you need to make.
- Use that spec file to build your RPMs.
- You will have to repeat the procedure when you want to build packages from the next release. The spec file is subject to change, and there is no guarantee that a spec file from one release will still work for the next release.

### Q: Problems compiling/linking with vpopmail

A: Courier does provide hooks for using the vpopmail virtual domain management library, however it will usually be necessary to tweak a couple of things in order to get it to work. The problem stems from the fact that vpopmail itself has a plethora of configuration options and different database back-ends. It is not possible to automatically figure out the right voodoo combination of link libraries to pull in all the necessary code. Use the following procedure to get Courier and vpopmail working together:

1. Use the most current version of Courier and the vpopmail library. Vpopmail's developers always quickly provide patches anytime there are changes to the vpopmail API.
2. The most common problem is linking with libraries required by vpopmail. Put the required libraries and linker flags in the DYNMYSQLLIBS environment variable prior to running `configure`. For example:

       DYNMYSQLLIBS="-L/opt/mysql/lib -lmysqlclient"
       export DYNMYSQLLIBS
       ./configure [options]

## ESMTP

### Why are my e-mails taking so long to send?

Several things happen when Courier receives a connection on the SMTP port 25. Sometimes those things take an excessively long time to complete, and it seems that Courier answers port 25 connections after a long delay.

This usually happens for all connections to port 25, but it's usually noticed when trying to send mail using a mail client that's set up to use a Courier server as a mail relay. Connections from other mail servers may experience similar delays, but they are less likely to be noticed. It's hard to ignore a mail client that does nothing, when it's commanded to send a message.

When a new connection is received on port 25, with the default configuration Courier performs the following checks:

1. The connecting IP address is looked up in DNS.
2. If the connecting IP address is resolved to a hostname, the hostname is looked up in DNS again, to see if it resolves to the connecting IP address.
3. The connecting IP address is queried using the IDENT protocol.

The results obtained from these queries will be recorded in the `Received:` header of any message received from the connecting IP address.

A non-responding DNS server may result in lengthy connection delays, as the DNS query times out (which may take several minutes). A non-responding server for the connecting IP address's netblock will probably not be a major problem, since the intermediate DNS resolvers should quickly failover to any functioning backup authoritative servers for the connecting IP address, or its hostname. A bigger problem is when the local DNS resolver, listed in /etc/resolv.conf goes down. This will result in a certain percentage of all incoming connections experiencing major delays.

A local, or an intermediate firewall may also drop IDENT packets. IDENT is a fairly old protocol whose original purpose is to identify individual users of a shared network server. Some proxies may also use IDENT to identify the original source of a proxied connection. However, since IDENT is an old, and not a very well known protocol, some poorly-written firewalls may not recognize the protocol, and bit-bucket IDENT connection requests. An IDENT request times out after 30 seconds.

When investigating connection delays:

1. Check each server listed in `/etc/resolv.conf`. NOTE: Courier does not read the `hosts` file. It needs a DNS server (although it is possible to have a working Courier configuration in a completely DNS-free environment, this excersize requires changing many configuration files, and perhaps will be its own FAQ entry some day).
2. Try to resolve the connecting IP address in DNS, backwards and forwards.
3. Conduct a search for any misbehaving firewall between the server, and the connecting IP address.

As a last resort, both of these lookups can be turned off. Add the `-nodnslookup` and `-noidentlookup` options to TCPDOPTS, in the esmtpd configuration file (usually `/usr/lib/courier/etc/esmtpd`). Example:

> `TCPDOPTS="-nodnslookup -noidentlookup"`

There'll probably be an existing TCPDOPTS setting in there. Add the whitespace-delimited options to anything that's already in there.

> NOTE: This should only be done as a last resort, if there are no options left. The information gathered by the queries may prove to be essential in investigating high-level mail delivery-related issues. If a realization hits that the DNS or IDENT information is needed to track down a particular piece of mail, it'll be already too late. It should've been there right from the start.

### Q: Courier rejects mail with the following error:

> `MX records for $domain violate section 3.3.9 of RFC 1035`

> or

> `This domain's DNS violates RFC 1035.`

`[PP]` Cause: Invalid DNS MX Records for that domain

Solution: Contact sysadmin for that domain and advise to fix their DNS.

A common problem appears to be that an MX record will point to an IP address rather than a domain name (FQDN) as follows:

INCORRECT MX RECORD:

    domain.com    preference = 20, mail exchanger = 192.68.0.10

CORRECT MX RECORD:

    domain.com    preference = 20, mail exchanger = mail.domain.com

Temporary Solution: Put the offending domain into the `esmtproutes` file and point it to that domain's mail exchanger host. Doing so bypasses checking the domains MX or A records and mail is sent directly to the relay specified in esmtproutes. Reference: man courier(8).

### Q: Courier rejects mail with the following error:

> `517 Syntax error - your mail software violates RFC 821.`

`[PP]` Cause: Most often generated by WinCE gizmos. Several reasons, most common missing required <> surrounding the MAIL FROM: or RCPT TO: verbs

`[SV]` This problem is apparently present in the Microsoft Outlook client too. See item #7 in `http://support.microsoft.com/support/kb/articles/Q180/4/84.ASP`. Note: contrary to the information in that article, this address specification format is REQUIRED by RFC 821, and Microsoft is simply ignoring another Internet standard, here.

`[PP]` Solution: The usual solution for a 517 is to tell people to explicitly put <> around all E-mail addresses. That is, program their WinCE gizmo to believe that their return address is "<user@domain.com>" instead of "user@domain.com", and have them enter each recipient's address in a similar way.

### Q: Courier delivers ESMTP mail with a strange error message:

Mail received by the received is replaced by the following text, with the original message attached.

> `I received the following message for delivery to your address. Unfortunately, the sender's mail software did not properly format the following message properly, in accordance with Internet mail formatting protocols, and I can only deliver mail which has been properly formatted according to Internet standards. Instead of returning the following message as undeliverable, it is saved, in its original form, in the following attachment, which you can open with any editor or word processor.`

`[PP] [Sam]` Cause: Various bugs in poorly written software that generates invalid MIME-formatted messages. Previous versions of Courier used to automatically return mis-formatted mail as undeliverable. Starting with version 0.36.1, mis-formatted mail is replaced by this canned message text, and the original message is attached as plain text.

Solution: for now, manually edit `SubmitFile::MessageEnd()` in `courier/submit2.C`, and remove the code that reports both 8-bit related errors, `RFC2045_ERR8BITHEADER` and `RFC2045_ERR8BITCONTENT` (the first and the third error message).

This will suppress the error and accept the garbage mail, but expect random mail access problems. Certain versions of Outlook have known bugs handling misformatted mail, so you're on your own.

NOTE: Do not remove the code that reports RFC2045_ERR2COMPLEX, this error indicates a denial-of-service attack.

NOTE: Removing the check for RFC2045_ERRBADBOUNDARY suppresses the second error message, however think long and hard before you do this. You are virtually guaranteed to end up with corrupted MIME mail if this check is removed!

### Q: Server is not accepting any mail, returns a `450 Service unavailable` error every time.

- You are using a database-based back-end, such as LDAP or MySQL, and the back-end server is down.
- You are using `authdaemon`, and the `authdaemond` process is not running.

### Q: How do I enable relaying for an IP address range?

Put the IP address range in any file in the `smtpaccess` configuration subdirectory, then run `makesmtpaccess`. See makesmtpaccess(8) and couriertcpd(8). For example, to enable relaying for IP address 10.192.64.0 - 10.192.64.255, put the following into `smtpaccess`:

    10.192.64<TAB>allow,RELAYCLIENT

"`<TAB>`" is a single TAB character.

### Q: How do I implement virtual domain hosting?

There are literally a dozen different ways to do it. If you are comfortable with how virtual domains are implemented by Qmail, you can do something similar with Courier. If you are used to implementing virtual domains with sendmail, you'll be able to do something similar too. Additionally, you can use LDAP directories or MySQL databases to store your mail account configuration. Or, you can simply enter virtual account information in text files, and run a script to convert the text file database to a binary GDBM or DB database that Courier can use to map arbitrary mail addresses to home directories and mailboxes. In all cases, the same configuration is automatically shared by ESMTP, IMAP, POP3, and webmail components. They all use the same authentication back-end.

NOTE: in all cases you are still responsible for creating the home directories and/or mailboxes for each account, with the appropriate ownership and permissions. You will still need to do that in all cases.

#### Using USERDB

The `authuserdb` authentication module is included by default. To use it, create a file or a subdirectory named `userdb` in the configuration directory (the default location is `/usr/lib/courier/etc`, but that may vary on your platform). If `userdb` is a subdirectory, the contents of files in that subdirectory are simply concatenated. Use the following commands to create a virtual account:

    userdb john@example.com set home=/home/virtual/example.com/john \
                 uid=999 gid=999

    userdbpw | userdb john@example.com set systempw

If `userdb` is a subdirectory instead of a file, replace "john@example.com" with "filename/john@example.com".

On systems that use MD5 password hashes, instead of crypt-ed passwords, specify the `-md5` option to `userdbpw`.

The home directory of this virtual account must now be created, as well as its default system mailbox (usually `$HOME/Maildir`).

When a virtual account does not really have a home directory, just the system mailbox, set both the `home` and `mail` fields to the same pathname:

    userdb john@example.com set home=/home/virtual/example.com/john \
                 mail=/home/virtual/example.com/john \
                 uid=999 gid=999

In this case `/home/virtual/example.com/john` is the system mailbox.

Run the `makeuserdb` command to rebuild the `userdb` database.

Finally, `example.com` must be configured as a virtual domain. Edit the `hosteddomains` configuration file, add `example.com` to the file, then run `makehosteddomains`. See courier(8) for more information.

`userdb` can completely replace the functionality of the traditional `/etc/passwd` file. With a large passwd file, converting the flat text file to a fast database file can greatly improve performance. The `pw2userdb` script convert `/etc/passwd` to `userdb` format.

#### Qmail-style virtual domains

Append the following to the `aliases` configuration file:

    @example.com: john

If `aliases` is a subdirectory, append this to any file in the subdirectory (or create a new one). In all cases, run `makealiases` for the change to take effect.

Mail to `anything@example.com` gets delivered to local address `john-anything`. The local `john` account may install dot-courier(5) delivery instructions for any particular `anything` address.

#### Sendmail-style virtual domains

Append the following to the `aliases` configuration file:

    john@example.com: john1

If `aliases` is a subdirectory, append this to any file in the subdirectory (or create a new one). In all cases, run `makealiases` for the change to take effect.

Mail to `john@example.com` will be delivered to the local account `john1`.

#### Using `LDAP` or `MySQL` back-ends

Virtual domains can also be supported by storing the account information in an LDAP directory or a MySQL database. This is implemented by installing the `authldap` and `authmysql` authentication module.

It will be necessary to initialize `hosteddomains`, and run `makehosteddomains` in order to configure Courier to pass virtual domains to the local mail module. Additionally, `authldap` and `authmysql` come with their corresponding configuration files, `authldaprc` and `authmysqlrc`, that specify the gory details such as the location of the back-end server, and the name of the tables or records involved. Consult that configuration file for more information.

### Q: Courier keeps restarting every minute, and there are weird syslog messages about "unsafe" hard links

You are running an operating system kernel that's been altered with one of several nonstandard modifications that aim to improve system security by rejecting certain kinds of operating system calls. You will need to disable these non-standard patches. They completely modify the traditional file permission semantics, in the name of security. This breaks Courier, whose security model is based on traditional filesystem permissions.

### How to configure Courier to be a backup MX for a domain

To configure a Courier server as a backup MX, meaning that Courier receives mail for `@domain.com`, and forwards it to the primary MX server for domain.com when it becomes available (presumably the primary MX server is not available at this moment):

1. Put `domain.com` into the `esmtpacceptmailfor` configuration file (or the `esmtpacceptmailfor.dir` directory, then run `makeacceptmailfor`).
2. Insert a DNS MX record. The MX record must have a higher priority than `domain.com`'s primary MX. Furthermore, the hostname in the MX record must be one of the hostnames in the `locals` configuration file. For example:

       domain.com      MX 10  primary.domain.com
       domain.com      MX 20  backupmx.domain.com
       primary.domain.com  A 192.168.0.4
       backupmx.domain.com A 192.168.0.5        # IP address of the backup MX server

       locals:
       backupmx.domain.com

       esmtpacceptmailfor:
       domain.com

3. It is also possible to have backupmx.domain.com listed at the same MX priority as the primary MX. If so, it will also be necessary to explicitly initialize the esmtproutes configuration file:

       domain.com: [192.168.0.4]

### Q: Messages with more than 20 recipients are rejected

A: You can set the maximum number of recipients for a single email by adding the line:

`maxrcpts number`

to etc/bofh.

## IMAP

### Q: StarOffice's IMAP client doesn't work, Messenger's IMAP client reports command errors when new messages arrive

A: Both IMAP clients do not correctly implement certain parts of IMAP4rev1. Rerun configure, and use `--enable-workarounds-for-imap-client-bugs` option. Note that make check will fail when this option is used.

### Q: Can't create folders, only subfolders of INBOX

This is a configuration issue with your mail client. IMAP servers are free to use any folder namespace arrangement that's technically convenient for them. Courier uses "INBOX." as the namespace for private folders, and "shared." as the namespace for public, shared, folders. The IMAP NAMESPACE extension (see `http://www.rfc-editor.org/rfc/rfc2342.txt`) allows IMAP clients to automatically discover where the server creates folders, and your IMAP client should implement it.

This should be completely transparent to you, if your IMAP client properly uses the `NAMESPACE` extension. If your IMAP client were to automatically take advantage of self-configuration features offered by RFC 2060 and RFC 2342, it would automatically discover, without any additional configuration from the user, that:

1. The folder namespace hierarchy separator is the . character
2. Private folders are stored underneath the "`INBOX.`" hierarchy
3. Public folders are stored underneath the "`shared.`" hierarchy

If you have to explicitly create folders that are subfolders of INBOX, or if you explicitly have to name that "`INBOX.foldername`", this is due to your IMAP client not being able to configure itself accordingly.

A: Correct. IMAP servers are free to define any root of the folder namespace tree that's convenient for them. Courier's IMAP server uses INBOX as the folder namespace root, rather than the root hierarchy itself. Courier supports the `NAMESPACE` IMAP extension which allows compliant IMAP clients to automatically configure themselves so that the folder namespace root is transparent. Submit an enhancement request to have your IMAP client gracefully handle the folder namespace root.

### Q: The IMAP server doesn't run at bootup

A: Check the following:

- The entry for the IMAP port is not in `/etc/inetd.conf`.
- If you're using the example system V init script, IMAPDSTART is set to YES in the `imapd` configuration file (usually `/usr/lib/courier/etc/imapd`).

### Q: Can't log in

A: Check the following

- `AUTHMODULES` in the `imapd` configuration file is correct.
- If the `authdaemon` authentication proxy is used, check the `authdaemonrc` configuration file. Check that `authdaemond` is running.
- Your authentication modules are properly configured. Some authentication modules have additional configuration files (`authldap` and `authmysql`). If you're using `authpam`, you need to configure your PAM library to authenticate the "imap" service. This is a separate task, and is specific to your PAM library and operating system.
- You are using a database-based back-end, such as LDAP or MySQL, and the back-end server is down.
- You're using maildirs. Courier's IMAP server only supports maildirs (`$HOME/Maildir`), it doesn't support mailbox files.

### Q: Repeated messages in syslog: "Failed to create cache file: maildirwatch (user) Error: Input/output error Check for proper operation and configuration of the File Access Monitor daemon (famd)." How can I solve it?

This means that Courier was compiled with File Alteration Monitor (FAM), but FAM is not running, or is not configured. If you have FAM installed you can add it to a runlevel and start it. Some FAM configuration use portmapper, so you will need to have portmap running also. You can also see "man 8 imapd" for more information.

### Q: I heard that Courier does not implement IMAP properly

A: This topic deserves its own web page. See http://www.courier-mta.org/fud/ for more information.

## POP3

### Q: The POP3 server doesn't run at bootup

A: Check the following:

- The entry for the pop3 port is not in `/etc/inetd.conf`.
- If you're using the example system V init script, POP3DSTART is set to YES in the `pop3d` configuration file (usually `/usr/lib/courier/etc/pop3d`).

### Q: Can't log in

A: Check the following

- `AUTHMODULES` in the `pop3d` configuration file is correct.
- If the `authdaemon` authentication proxy is used, check the `authdaemonrc` configuration file. Check that `authdaemond` is running.
- Your authentication modules are properly configured. Some authentication
- Your authentication modules are properly configured. Some authentication modules have additional configuration files (`authldap` and `authmysql`). If you're using `authpam`, you need to configure your PAM library to authenticate the "pop3" service. This is a separate task, and is specific to your PAM library and operating system.
- You are using a database-based back-end, such as LDAP or MySQL, and the back-end server is down.
- You're using maildirs. Courier's POP3 server only supports maildirs (`$HOME/Maildir`), it doesn't support mailbox files.

## Webmail

### Q: How do I create new system accounts via the webmail server?

A: Write your own CGI script for this. Not everyone wants this ability, plus with all the different authentication module there are literally dozens of different ways accounts can be set up, and there's no way to provide a uniform interface for this purpose.

### Q: I changed the system password for an account, but the webmail password hasn't changed?

A: Mainly for the same reason, there's no uniform way to change system passwords, so the webmail server maintains its own passwords, which are initialized from the system password. You can reconfigure Courier with the `--enable-webpass=no` flag (see INSTALL), and lose the ability to change passwords in the webmail interface, so all password changes must now be done on the system level.

## Miscellaneous

### Q: Asking for help on the courier-users and courier-imap mailing lists

A: The courier-users or the courier-imap mailing list should be the first place to look for assistance with resolving any issues. You only need to observe a few simple rules in order to increase your chances of getting a quick and helpful response:

1. Subscribe/subscribe to the mailing list before you ask any questions. If you are not subscribed, you will not receive any replies that are mailed to the list only.
2. Very important: Read http://www.catb.org/~esr/faqs/smart-questions.html#intro before sending your first question.
3. Do not send HTML E-mail messages, unless you want many people to automatically delete them, unread. If you are using MS-Outlook, turn off HTML formatting before sending mail to the list.
4. Before sending a question, check it to make sure that your message does not contain the words "doesn't work." Saying only that something doesn't work is not very useful in trying to analyze the problem. If something isn't working correctly, merely stating it will not make much progress. Be sure to always include in your messages:
   - The contents of any related configuration files.
   - What happens, exactly, that makes you think that something isn't working right.
   - The contents of your system log file (syslog, or `/var/log/messages`).
   - Be sure to describe any non-standard modifications to the operating system you're using, such as a kernel hacked with one of several varieties of the OpenWall patch, or filesystema mounted with a no-suid option. Many problems turn out to be unintentional conflicts with various unexpected side-effects of these custom modifications (but not after wasting a great deal of time chasing ghosts).
5. Do not send large attachments (over 10K bytes is a rule of thumb), to the list. Put it somewhere - on the web or on a FTP server - and include a link in your message instead.
6. Always mention what you've already tried to do in order to fix the problem. People are more likely to help you if they know that you've made some effort to figure it out by yourself, and you are only asking for help after running into a dead end.
7. If you do not get an answer in one hour, don't resend your message. If people open their mailbox and see five copies of the same message, they'll be ignored. Have patience. Either wait some more, or accept it as a fact of life. Try again to figure out the answer on your own. You can certainly ask again after you've tried to figure it out once more, and still didn't get anywhere. Don't just write again, and simply say that it still doesn't work. Provide some additional information, showing what else you've tried to do, to no avail.

### Q: Using virtual domains

There are several ways to implement virtual mailboxes, to address different situations and environments. The simplest case involved simply redirecting certain mail addresses to a local mailbox:

    user@domain.com: localuser

This entry in the `aliases` configuration file (run the `makealiases` script after editing `aliases`) causes mail for <user@domain.com> to be delivered to `localuser`, which must be an existing system account. If IMAP/POP3/Webmail access has been configured, it is necessary to log in as `localuser` to pick up this mail.

A slightly different syntax in `aliases` results in mail for an entire mail domain to be controlled by a local system account:

    @domain.com: localuser

Here, any mail address <foo@domain.com> will be redirected to the local address <localuser-foo>. Note, the address is <localuser-foo>, not <localuser>. This means that the account owner <localuser> gets to control the mailboxes in this domain. In this case, the file `$HOME/.courier-foo` will control disposition of mail addressed to `foo@domain.com`. See the dot-courier(5) man page for more information. In this case, there is no default way to access mail to various mailboxes via IMAP/POP3/Webmail. If `$HOME/.courier-default` is used to deliver all mail for this domain to the default mailbox for the `localuser` account, mail can be read via IMAP/POP3/Webmail by loggin in as `localuser`.

The other way to implement virtual domains is by using a custom authentication back-end, such as LDAP, MySQL, and PostgreSQL, to explicitly administer virtual domains. The first step is to add `domain.com` to the `hosteddomains` configuration file, and run the `makehosteddomains` script. This tells Courier to deliver mail for this domain locally. The next step is to appropriately configure the authentication library, and define the valid mailboxes in this domain. See the authlib(8) man page for information on setting up the various authentication back-ends. The authentication back-ends that can support virtual domains are LDAP, MySQL, PostgreSQL, and userdb (also vchkpw, but that requires some external configuration).

Note that Courier does not automatically create the maildirs for virtual mail accounts. After setting up a virtual mail account it is still necessary to create and initialize the virtual home directory, and the virtual maildir directory, with the correct permission and ownership.

Most authentication modules require their own specific configuration files to be initialized. Most authentication modules also require that they be compiled into the `authdaemon` authentication proxy. This means that it will be necessary to arrange to have `authdaemond` started at system startup. See the authlib(8) man page for more information.

### Q: Using `fetchmail`

Since Courier provides both IMAP and POP3 services, nothing unusual is required to download mail from a Courier-hosted mailbox, using either protocol. Here is a suggested `fetchmail.rc` configuration file to download mail from an external mail account into a local mailbox. For readability, some long lines below have been split across multiple lines, and they should be manually combined. Insert your account information in the appropriate place, and run `fetchmail` from the account's crontab:

>     ### [RS]

>     ### global options
>     # set logfile /relay/home/var/log/fetchmail
>     set syslog
>     # set idfile /root/.fetchids
>     set postmaster postmaster@hostname.dom
>     set no bouncemail
>     set no spambounce
>     set no showdots
>     # set invisible

>     defaults
>             ### server options (qmail-style headers)
>             via pop.provider.dom protocol POP3 auth cram-md5 timeout 15
>             no dns no checkalias no uidl
>             envelope Delivered-To qvirtual mydomain.dom.ch-
>             localdomains mydomain.dom
>             # tracepolls
>             ### user options (courierpop3d)
>             fetchlimit 32 batchlimit 16 limit 6000000 warnings 3600 antispam -1
>             no rewrite no idle pass8bits fetchall
>             # mda "/relay/bin/sendmail -N delay,fail -R full -f %F %T"
>             # postconnect "exec /bin/sleep 5"
>             smtphost 127.0.0.1 smtpaddress hostname.dom
>             is * here
>             # keep

>     poll username interval 4 user "username@mydomain.dom" pass "whatever"
>     mda "/relay/bin/env USER=relay HOME=/relay/home/username \
>        DEFAULT=./ SENDER=%F RECIPIENT=%T \
>        /usr/lib/courier/bin/maildrop -V 1 -f '%F' /home/username/.mailfilter"

This example is for a basic system that uses traditional system accounts, and with an existing `$HOME/.mailfilter` (which can be generated via the webmail server). This can be used with virtual accounts, provided that additional steps are added to run maildrop under the correct system uid/gid, and the explicit pathname to the virtual account's `.mailfilter` is provided, and that the virtual account's `MAILDIR/mailfilterfilterconfig` is manually initialized to contain absolute pathnames (so that the generated `.mailfilter` file itself uses absolute paths).

This is a simple example that downloads one external mailbox to a local mailbox. Some external mail providers offer a service to deliver all mail for an entire domain into a single mailbox. This example will also work for downloading all such mail into a single local mailbox. This approach cannot be reliable modified to distribute domain mail to multiple local mailboxes, no matter what anyone else tells you, even though `fetchmail` contains facilities for doing so. If that's what you want to do, have your mail delivered by ESMTP or UUCP. Delivering mail to a mailbox automatically discards all the required recipient information, and by redistributing mail locally you're going to attempt to reconstruct this information from mail headers. This is never going to be a 100% reliable process, and unless you fully understand all these issues, you're likely to end up with occasional mail loops and bounces, which will annoy many people. You've been warned.