Courier FAQ

This is a beginning of a modest FAQ. Contributors:

Table of contents:

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:

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:

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.

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:

Q: Can't log in

A: Check the following

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:

Q: Can't log in

A: Check the following

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