# Courier-IMAP

For a general introduction and configuration settings for some popular IMAP clients, go and read `imap/README(.html)`.

In this document:

- Requirements
- Upgrading
- Installation
- Authentication modules - General notes
- Authentication internals
- `USERDB` Authentication module
- `VCHKPW` Authentication module
- `LDAP` Authentication module
- `DAEMON` Authentication module
- Account initialization hook
- Using shared folders
- CRAM-MD5 Authentication
- Sending mail via an IMAP connection
- Realtime folder status updates
- Account OPTIONS
- SMAP

## Requirements

Now is the good time to read the FAQ, before you start. The FAQ is located in the file `imap/FAQ(.html?)`.

- C++ compiler - A C++ compiler is required. The server is written in C, but there are some configuration scripts that use C++ code.
- make - The GNU make is recommended. Solaris's make is to be avoided. xBSD already has a gmake port, install it and use it (use gmake everywhere this document refers to make).
- GDBM/DB - either the GDBM or the Berkeley DB library is required.
- FAM, the File Alteration Monitor (`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.
- OpenLDAP/MySQL/PostgreSQL/OpenSSL - The IMAP server can optionally use a database back end for authentication. The database back end can be either an LDAP directory, a MySQL database, or a PostgreSQL database. The IMAP server can also implement IMAP over SSL (STARTTLS) as well. Generally, to enable the optional modules it is only necessary to install OpenLDAP, MySQL, PostgreSQLor OpenSSL. The configuration script checks for presence of these libraries, and compiles the appropriate files. Note: these packages MUST BE installed in directories that are searched by your C compiler by default. Some installation scripts default to installing the development libraries and include files in custom directories. In that case it will be necessary to set some environment variables, before running the configure script, to specify additional options to the compiler that add the custom directories to the compiler's search path. See the FAQ for more information. You also need to make sure that all the supporting DEVELOPMENT files are installed. Most LDAP/MySQL/PostgreSQL packages come in two parts: the runtime support, and development support. You may have just the runtime support installed, you will need to make sure that development support files are also installed.

## UPGRADING

After upgrading from Courier-IMAP 1.7.3, or earlier, any existing mail in POP3 mailboxes may show up as new mail, by some mail clients. Other mail clients may end up downloading a second copy of any message that was left in the mailbox before the upgrade. This is a one-time event. Courier-IMAP 2.0.0 uses a different mechanism for generating POP3 message identifiers. Mail clients that use POP3 identifiers will behave as if all messages, that were left in the POP3 mailbox before the upgrade, were removed, and replaced by new messages that happen to be the same content. Depending on how the POP3 mail client works, it will either flag all messages in the mailbox as unread, or download a second copy of the message.

Upgrading from Courier-IMAP 1.3.0, and later versions, is a straightforward process. Follow the instructions in the INSTALLATION section, below, to install the new version. The "`make install-configure`" command automatically preserves the existing system configuration. However, note that new versions of Courier-IMAP will often introduce additional configuration options. After `make install-configure` a cursory inspection of configuration files in `/usr/lib/courier-imap/etc` (the default location of the configuration directory) is recommended, in order to identify any new configuration settings that might need adjustment.

### Upgrading from Courier-IMAP 1.3.8.2 and earlier

The default configuration options have slightly changed. The default configuration script will now always build the `authdaemon` module, and build all real authentication modules inside `authdaemond`. This is true even with the `authvchkpw` module.

### Upgrading from Courier-IMAP 1.2.3 and earlier

Courier-IMAP 1.3.0 introduced a new configuration file format that allows configuration files to be automatically upgraded. Additionally, several existing configuration files have been renamed in order for their names to be consistent with the Courier build:

    Courier-IMAP < 1.3  Courier-IMAP 1.3.0
    --------            ---------
    imapd.config        imapd
    imapd-ssl.config    imapd-ssl
    pop3d.config        pop3d
    pop3d-ssl.config    pop3d-ssl

The NEWS file has a detailed explanation of how configuration files are now installed. Basically, `make install` now installs `configfilename.dist`, and `make install-configure` copies `configfilename.dist` to `configfilename`, becoming the actual configuration file. If there is an existing `configfilename`, the old settings in `configfilename` which are still valid will be kept in the new `configfilename`.

This only works as long as both the old and the new configuration files are in the new format, so this will actually take effect with your next upgrade Courier-IMAP. If the previous installed version of Courier-IMAP did not use the new format for configuration files (1.2.3 and earlier), the old configuration file is backed up to `configfilename.bak`.

The recommended procedure for upgrading from versions 1.2.3 and earlier is as follows:

The recommended upgrade procedure is as follows:

- Back up `/usr/lib/courier-imap/etc
  `
- Follow the installation procedures, below
- After installing, manually edit all configuration files. Restore, by hand, any custom configuration settings.

All configuration files are kept in the configuration directory. Nothing else in `/usr/lib/courier-imap` is configurable. Do not simply overwrite 1.3.0 configuration files with configuration files from the previous version. It's tempting, but don't do it. It may work, but you will lose the automatic upgrade capability for future releases.

### Upgrading from Courier-IMAP 1.1 or earlier

Note that Courier-IMAP 1.2 includes a compatible POP3 server, and the installation script will also install a POP3 server on your system. Even though it is installed, you are not required to use it, but you still need to be aware of its existence. If you install the RPM build of Courier-IMAP, you're going to get the POP3 server started at system boot. If you do not need POP3 services, edit both the `pop3d.config` and `pop3d-ssl.config` configuration files, and set `POP3DSTART` and `POP3DSSLSTART` to NO

### Upgrading from Courier-IMAP 1.0 or earlier

If the server is running, manually stop the server before installing the new version.

## INSTALLATION

To compile and install the Courier-IMAP server (this is the short version, a longer version follows):

    $ ./configure [ options, see below ]
    $ make
    $ make check       # Note - the --enable-workarounds-for-imap-client-bugs
                       # option to configure will result in make check FAILING.
    $ su root
    # make install     # Or, make install-strip, to strip the executables.
    # make install-configure   # Install configuration files.

                       # Start the authdaemond process

> NOTE

> You MUST run the `configure` script as normal user, not root. Did you extract the tarball as root? It won't work. Remove the extracted source code. 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.

As mentioned in "Requirements", above, if you are using xBSD, you must use gmake instead of make.

NOTE: The `configure` script may run as much as 5-10 minutes on slow machines. It may appear that `configure` is stuck in a loop, but that's an illusion. Courier-IMAP is built from a collection of modular components, each with its own configuration script. The configuration scripts share a lot of common code, leading to an initial impression that the same configuration script is being repeatedly run.

See below for a description of the options to the `configure` script.

WARNING: set your umask to 022 before running `make install` or `make install-strip`.

You should try `make install-strip` first. Use `make install` if `make install-strip` fails.

The configure script accepts certain options, but the defaults should be fine most of the time. `make install` puts everything in `/usr/lib/courier-imap`. If the directory `/etc/pam.d` exists, `make install` creates `/etc/pam.d/imap` and `/etc/pam.d/pop3`, overwriting any existing files. If you have some other IMAP server installed, this means that you will want to save your existing configuration in `/etc/pam.d/{imap|pop3}`.

"`make check`" performs some internal sanity checks. If `make check` fails, something is wrong, and Courier-IMAP may not work for you reliably. Certain options are documented to cause `make check` to fail, due to different IMAP protocol behavior. If you need to use those options, first compile Courier-IMAP without them, run make check, and if all goes well extract the source code again in a different directory, then build it for the second time using your options.

After installation, you will need to review the files in `/usr/lib/courier-imap/etc` and make any changes you deem necessary, including:

- If you do not want to create and use virtual mailboxes, you should remove `authuserdb` from `AUTHMODULES`. If `AUTHMODULES` contains "`authdaemon`", you will have another configuration file, `authdaemonrc`. Remove `authuserdb` from `authdaemonrc` instead.
- The configuration script automatically selects whatever authentication modules can be used on your system, but you may not necessarily want to use them. For example, if your system has OpenLDAP libraries installed, the `authldap` module gets compiled and installed, even though you might use LDAP for some other purposes, not necessarily authentication. If that's the case, remove `authldap` from the `AUTHMODULES` entry in the `imapd` configuration file, or from `authdaemonrc`, whatever the case might be.
- If you're using PAM authentication (`authpam` gets compiled and installed), you will have to tell your PAM library how to authenticate the "`imap`" service and the and "`pop3`" service (if you intend to use the bundled POP3 server too). What you need to tell your PAM library is something that you will have to figure out by yourself, because it depends on the version of your PAM library, and your operating system.

  If the directory `/etc/pam.d` exists, the installation script will automatically install `/etc/pam.d/imap` and `/etc/pam.d/pop3`, but that's just for starters. You will still have to inspect its contents and adjust the full pathname to the PAM modules, if necessary.

  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

  Your PAM library may use pam_pwdb.so instead of pam_unix.so; consult the documentation for your PAM library for more information.

`configure` should automatically detect if you use `vpopmail`, and compile and install the `authvchkpw` authentication module.

After running `make install` or `make install-strip` you will then have to modify your system's startup scripts to run Courier-IMAP when your system boots.

Use the following command to start the Courier-IMAP server:

    $ /usr/lib/courier-imap/libexec/imapd.rc start

This assumes that Courier-IMAP is installed in `/usr/lib/courier-imap`. Use the following command to stop Courier-IMAP:

    $ /usr/lib/courier-imap/libexec/imapd.rc stop

You will have to add these commands to your system startup/shutdown scripts.

#### IMAP over SSL

To add SSL support you have to install OpenSSL before installing Courier-IMAP. Download OpenSSL from `http://www.openssl.org/`. Follow the instruction in OpenSSL package to install it and configure it. SSL support in Courier-IMAP has been tested with OpenSSL 0.9.5a.

The `/usr/lib/courier-imap/lib/imapd-ssl` configuration file sets some additional options for SSL support, which you may need to adjust. Consult that configuration file for additional information. Then, you also have to run the `/usr/lib/courier-imap/libexec/imapd-ssl.rc` script from your system startup and shutdown scripts, just like the `/usr/lib/courier-imap/libexec/imapd.rc` 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-IMAP expects to find it. The default location for the X.509 certificate, in PEM format, is `/usr/lib/courier-imap/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-imap/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 bundled POP3 server

The POP3 server included with Courier-IMAP provides POP3 access to INBOX, and that's about it. Enabling the POP3 server is very similar to enabling the IMAP server, with the following differences:

The configuration files are `/usr/lib/courier-imap`/etc/pop3dand `/usr/lib/courier-imap`/etc/pop3d-ssl.

The startup/shutdown scripts are `/usr/lib/courier-imap`/libexec/pop3d.rcand `/usr/lib/courier-imap`/libexec/pop3d-ssl.rc.

The SSL certificate is `/usr/lib/courier-imap/share/pop3d.pem`, and the `/usr/lib/courier-imap/share/mkpop3dcert` script can be used to create a self-signed SSL certificate for testing purposes.

#### System-V style startup

If your system uses System-V style startup scripts, take a look at `courier-imap.sysvinit` - this is a sample `/etc/init.d` script. `courier-imap.sysvinit` is created by `configure`. In most cases it can be merely copied to `/etc/init.d` and `/etc/rc?.d` directories (with the execute permission bit turned on).

The sample startup script will check if IMAP or POP3 over SSL is enabled. The sample startup script automatically creates dummy SSL certificates the first time it is executed.

#### Options to `configure`:

- `--prefix=pathname` - install here, instead of `/usr/lib/courier-imap`
- `--without-ipv6` - do not compile IPv6 support. The `configure` automatically checks if IPv6 support is available, and enables it automatically. This option suppresses IPv6 support, even if it's available. IPv6 support means that Courier-IMAP will create an IPv6 socket and accept IPv6 connections. `--without-ipv6` should be used if your system does not fully support IPv6, or if its implementation is buggy. Most Linux distributions now ship with IPv6 support in glibc, but without compiling the kernel for IPv6 support. This results in `modprobe` regularly complaining in `/var/log/messages` about the fact that it can't load the IPv6 module. Use `--without-ipv6` to turn off IPv6 support, if that bothers you.
- `--enable-unicode` - include the ability to search and sort messages in character sets other than the default ISO-8859-1/US-ASCII. All character set tables supported by Courier-IMAP will be included. See below for more details.
- `--enable-unicode=charset,charset,...` - include ability to search and sort messages, but only for these character sets. See below for more details.
- `--without-module` - explicitly specify that the authentication module named "module" should not be installed. See below for more details. Example: `--without-authdaemon`.
- `--bindir=pathname` , `--mandir=pathname` - override default names of subdirectories under `prefix`. See below for more information.
- `--with-db=db` - Use the DB library instead of the GDBM library You must have either the GDBM or the DB library installed. If both are present, GDBM is selected unless you use this option. The GDBM/DB library is used by Courier for certain functions.
- `--with-piddir=dir` - use dir/imapd.pid to store couriertcpd's process ID.
- `--with-syslog=DEST` - select syslog destination, giving one of the facility codes from syslog.h such as "LOCAL7". Defaults to "MAIL".
- `--with-userdb=file` - use file instead of `/etc/userdb` (also means that userdb.dat and userdbshadow.dat are appropriately renamed).
- `--enable-workarounds-for-imap-client-bugs` - there are a number of various bugs in certain IMAP clients. The current list of broken IMAP clients consists of Netscape Messenger and Sun's StarOffice. This option enables some workarounds for some bugs in these clients, however, note that this may break compatibility with software that correctly implements IMAP4rev1. Additionally, "`make check`" will fail when this option is used. See `imap/BUGS.(html|txt)` for more information. NOTE - if this option is used, `make check` WILL FAIL. You should first configure Courier-IMAP without this option, run `make check`, then reconfigure Courier-IMAP with this option.
- `--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-IMAP without this option, run `make check`, then reconfigure Courier-IMAP with this option.
- `--with-dirsync` - after saving a new message to a maildir (the `IMAP` `COPY` and `APPEND` commands) explicitly sync the maildir's `directory` directory. There's a school of thought which believes that the Linux ext2 filesystem requires the parent directory to 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.

#### Foreign character set sorting/searching

The Courier-IMAP server can search and sort 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 is to include only the ISO-8859-1/US-ASCII character set. Use the `--enable-unicode` option to include all available character sets.

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.

Note that character set translation tables need substantial memory. This should not be a problem in most cases. Most compilers will place the read-only character set tables into a shared text segment, that's shared by all running servers. `--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.

#### Installation directories

Unless the options `--prefix`, `--bindir`, or `--mandir` are used, everything will be installed in the directory `/usr/lib/courier-imap`.

Use the `--prefix` option to specify a different directory. This directory will have the following subdirectories:

- `etc` - configuration files
- `bin` - binaries
- `sbin` - superuser binaries
- `libexec` - additional binaries
- `man` - manual pages
- `share` - scripts and data files
- `var` - temporary files used by the `authdaemond`, daemon process (if the `authdaemon` authentication module is selected).

Having everything installed underneath one directory allows its contents to be easily backed up, before a newer version of `courier-imap` is installed. Reverting to a previous version is as simple as restoring from backup.

Because some binaries in `bin` and `sbin` may be executed from the command line, it will be necessary to change your systemwide global startup script to add this directory to the default `PATH`. Additionally, it will also be necessary to modify the configuration of the `man(1)` command so that it can find Courier-IMAP's manual pages in this directory:

            PATH="/usr/lib/courier-imap/bin:$PATH"
            if test -w /etc
            then
                    PATH="/usr/lib/courier-imap/sbin:$PATH"
            fi
            export PATH
            MANPATH="/usr/lib/courier-imap/man:$MANPATH"
            export MANPATH

As an alternative, you may use the `--bindir` and `--mandir` options in order to install binaries to `/usr/local/bin` and the manual pages to `/usr/local/man`, which should already be searched by default:

            ./configure --bindir=/usr/local/bin --mandir=/usr/local/man

Other familiar configure options, such as `--sysconfdir` and `--datadir` work too, for those who know how to properly use them.

## AUTHENTICATION MODULES - GENERAL NOTES

Courier now has extensive authentication debugging; for a guide see authlib/README.authdebug.html

An authentication module does a few things besides checking if a userid and password are valid. It's job also includes specifying the location of the primary maildir, and its system user and group id.

There are several authentication modules available. Each authentication module implements a different way of authenticating logins, and not all authentication modules can be used by everyone. Some authentication modules can be used only on systems that have certain libraries or software installed separately.

The `configure` script checks if the required libraries and software are available for each authentication module. If the required libraries and support files are available, the `configure` script includes the corresponding authentication module. The option `--without-module` instructs `configure` not to compile an authentication module, even if it could. Multiple `--without` options are, of course, allowed (each one specifying a different authentication module).

- `authpwd` - this module looks up userids and passwords in your `/etc/passwd` file, or the equivalent NIS map (as supported by your system's `getpw` library).
- `authshadow` - this module is like `authpwd`, except that it should be used on systems that use shadow password files, `/etc/shadow`.
- `authpam` - this module should be used on systems that have the PAM library. With this module, Courier-IMAP will use whatever PAM modules you specify for authenticating the "imap" PAM service. Essentially, `authpam` allows any PAM module to be used for authenticating logins. NOTE: in addition to including this module, you will have to take additional, site-specific, steps in order to configure your PAM library for the "imap" PAM service. The specific details regarding your PAM configuration differs from system to system, and you should consult your own documentation. It might be tempting to throw in a towel and use `authshadow` or `authpwd` if you cannot figure out how to install PAM support, however that is not advisable. It is highly recommended to use `authpam` wherever the PAM library is available.

  Additionally: PAM is used only for password validation. The home directory and the user and group IDs for the account are still taken from the system password file.

- `authuserdb` - this module uses GDBM or DB database files, usually `/etc/userdb.dat` and `/etc/userdbshadow.dat` to look up userids and passwords. These files are GDBM or DB databases that are loosely equivalent in function to `/etc/passwd` and `/etc/shadow`. These databases are maintained indirectly by several Perl scripts - included with Courier-IMAP - which build these database files from a plain text file, usually called `/etc/userdb`. This file can be modified by any text editor, or it can be managed by some useful Perl scripts which are included. `/etc/userdb` may also be a subdirectory that has multiple text files in the same format, which are simply concatenated. `userdb` allows creation of virtual mail accounts that do not have a corresponding login account -- virtual mail accounts that can share the same, reserved, system userid. `/etc/userdb` can also be used to completely supersede `/etc/passwd`. With many accounts it can be quite a drain to have to continuously linearly scan `/etc/passwd` in order to look up an account. Instead, a fast database lookup can retrieve the same information from the database file. Read the included manual pages, starting with ``userdb(8)`` for more information.
- `authcram` - this module is similar to `authuserdb` (it uses the same databases), but implements CRAM-MD5 authentication. See below for more information.
- `authvchkpw` - this is another virtual mail database lookup module, except that it uses the vpopmail vpasswd files. This module is provided for a quick way to use your existing vpopmail vpasswd files. Where possible, you should convert over to `/etc/userdb`. The included script `vchkpw2userdb(8)` might be of some help in doing so.
- `authldap` - authenticates against an LDAP server. This is a new module included with Courier-IMAP. See below for more information.
- `authmysql` - native MySQL authentication module Read `authlib/README.authmysql` for information on how to set up this module.
- `authpgsql` - native PostgreSQL authentication module PostgreSQL configuration is nearly identical to MySQL information, see `authlib/README.authpostgres.html` for more information.
- `authdaemon` - background daemon authentication proxy. See below for more information.
- `authcustom` - this is a dummy authentication module that dose not authenticate anything. It is a placeholder that can be used to implement any site-specific authentication code, written in C. To implement some site-specific authentication, inspect the contents of the `authlib/preauthcustom.c` file for additional instructions.

It is possible to include more than one authentication module. For example, if you select both `authuserdb` and `authpam`, each login will first be authenticated against `/etc/userdb`. If Courier-IMAP cannot find the account in `/etc/userdb`, it will then attempt to authenticate using the PAM library.

`configure` uses the following logic to determine which authentication modules will be included by default:

- `authuserdb/authcram` - these modules are always included by default
- `authpam` - `configure` attempts to detect if the PAM library is installed, or not. `--without-authpam` can be used to avoid installing `authpam` on systems that do have a PAM library installed. Hopefully, you will have a good reason to do something this silly.
- `authldap` - `configure` checks if OpenLDAP is installed. If OpenLDAP development libraries are available, `authldap` will be compiled and installed.
- `authpwd` , `authshadow` - whether or not these modules are installed by default depends upon what happened with `authpam` and `authldap`. If PAM or LDAP support is installed, via `authpam` or `authldap`, these two modules are usually not necessary, because the PAM library, or the LDAP server, provides this functionality. If PAM support is unavailable, these modules will be installed by default.
- `authvchkpw` - this module is compiled by default only if the `vpopmail` account is defined.
- `authmysql` - this module is compiled if MySQL client libraries are available.
- `authpgsql` - this module is compiled if PostgreSQL client libraries are available.
- `authdaemon` - this module is always compiled by default. See below for more information.

## Confirming selected authentication options

You can find out what authentication modules were actually used, but you must first run `make` successfully. Running `make` compiles the `authinfo` program in the `authlib` subdirectory. This program tells you what authentication modules were compiled.

## `USERDB` AUTHENTICATION MODULE

userdb is a way to implement many virtual mailboxes - many mailboxes that do not have to have a separate system userid allocated for each one, and there is no system login associated with each mailbox. userdb uses a database for mapping virtual addresses to physical maildirs. It should be scalable to thousands of mailboxes. It can also be used to replace linear searches of `/etc/passwd` with a database lookup, see `pw2userdb(8)`.

Note - you still MUST use some valid system userid and groupid that is shared by all virtual mailboxes. Instead of allocating a single userid and groupid per each mailbox, the same userid and groupid is used for all of them.

This is a rough overview of using userdb. For additional information, read `makeuserdb(8)`, and `userdb(8)`. All the scripts will be installed in `/usr/lib/courier-imap`, so look for them there.

Courier-IMAP can use the `userdb` database simply by the virtue of installing the `authuserdb`authentication module, which happens by default. The tricky part is creating the database. Hopefully, it's only tricky once, and the second time it won't be so tricky any more. The `userdb` configuration is extremely flexible, and there are many ways of actually setting up the database.

The best way to describe how `userdb` works is to try to create one virtual mail account. As mentioned before, virtual mailboxes still need one system account to be used for uid/gid purposes. Let's call this system account "vmail".

### Simple userdb setup.

This approach should be used if you do not have many virtual mailboxes. It's very simple, but quickly becomes cumbersome if you administer many virtual mailboxes.

Create an empty `/etc/userdb`.

    # cp /dev/null /etc/userdb
    # chmod 700 /etc/userdb

`/etc/userdb` must have 700 permissions.

Now, run the script `pw2userdb`. This script converts the contents of your `/etc/passwd` to the `/etc/userdb` format (including the contents of `/etc/shadow`, this is why permissions on `/etc/userdb` must be 700). This script is usually used where you want to convert a very large `/etc/passwd` to `/etc/userdb`. userdb applications can now use a fast userdb database instead of a linear scan of `/etc/passwd` in order to look up system accounts. However, you probably don't want to do use this feature right now, so what you simply want to do is take the output of `pw2userdb`, and find the entry for the vmail account that you created earlier. Look for a line that starts with 'vmail' followed by tab, followed by familiar fields from `/etc/passwd`. Save the output of `pw2userdb` in a temporary file, edit it, and remove everything except the line containing vmail, and the very next line, which is a special entry that maps vmail's userid back to the vmail record.

Here's what you might find in the output of `pw2userdb`:

    vmail   uid=1012|gid=1012|home=/home/vmail|systempw=*
    1012=   vmail

The actual numerical values and the home directory location may vary. Save these two lines as `/etc/userdb`, and set the permissions on `/etc/userdb` to 700:

    $ chmod 700 /etc/userdb

Now, with that out of the way, let's really create a virtual account. In this example we'll create a virtual mailbox for 'john@example.com'.

    # su vmail
    $ cd $HOME
    $ maildirmake Maildir-john-example
    $ exit
    #

You may need to specify a full path to your `maildirmake` program. The end result is that you created `$HOME/Maildir-john-example` in vmail's account.

The next step is to configure your mail server to deliver mail for john@example.com directly into the maildir `~vmail/Maildir-john-example`. How that's done depends on the mail server that you use.

Now, let's connect the dots here, and create an entry in `/etc/userdb` for `john@example.com`:

    # userdb "john@example.com" set home=/home/vmail \
                                    mail=/home/vmail/Maildir-john-example \
                                    uid=UUU gid=GGG

This command runs a Perl script named `userdb` , which is installed, by default in `/usr/lib/courier-imap/sbin`. Replace UUU and GGG with the userid and groupid of the vmail account. If you now look in `/etc/userdb`, you will see that a new record for john@example.com has been appended to the end of the file.

We're not finished yet. We need to set the IMAP password for this mailbox:

    # userdbpw | userdb "john@example.com" set imappw

If you are running Red Hat Linux 6.0, or higher, you can specify the -md5 option to `userdbpw`, in order to use an MD5 password hash, instead of crypt. Specify "`systempw`" instead of "`imappw`" if you would like to use the same password for the POP3 server too. The imappw field is only checked by the IMAP server. If not defined, `systempw` is used instead. The field `pop3pw` will be checked by the POP3 server that's bundled with Courier-IMAP. If it is not defined the POP3 server will check `systempw` too

Finally, compile the database:

    # makeuserdb

This command creates the actual database, `/etc/userdb.dat` and `/etc/userdbshadow.dat` from the plain text file `/etc/userdb`. Courier-IMAP will now start accepting logins to this mailbox. Adding and removing mailboxes can be done while Courier-IMAP is running.

Courier-IMAP reads `/etc/userdb.dat` and `/etc/userdbshadow.dat` only. The plain text source, `/etc/userdb` is not read by Courier-IMAP itself. Changes take effect only when `makeuserdb` runs.

### Large virtual domain farm.

The previous approach uses a single flat file, `/etc/userdb`. This might be a bit cumbersome if you have thousands of virtual mailboxes in many domains. Here's an alternative approach that can scale to thousands of domains and mailboxes.

Instead of creating a `/etc/userdb` file, create a subdirectory:

    # mkdir /etc/userdb
    # chmod 700 /etc/userdb

Now, create `/etc/userdb/default`, containing pw2userdb's output for the vmail account, as previously described.

This time, you probably want to create all mailboxes for the same domain in a separate subdirectory:

    # su vmail
    $ cd $HOME
    $ mkdir -p domains/example-com
    $ maildirmake domains/example-com/john
    $ exit

The idea is that all the maildirs for `@example.com` will be stored in `~vmail/domains/example-com`. All maildirs for `domain.org` will be stored in `~vmail/domains/domain.org`. The actual layout and naming conventions are entirely up to you to define.

Now, configure your mail server to deliver mail for john@example.com into this maildir.

Here's how configure `/etc/userdb`.

    $ userdb "example-com/john@example.com" set home=/home/vmail \
                                    mail=/home/vmail/domains/example-com/john \
                                    uid=UUU gid=GGG

This creates the file `/etc/userdb`/example-com (the first parameter to the `userdb` command), and appends a record named "john@example.com". You will store all userdb entries for `@example.com` in the file `/etc/userdb`/example-com. All entries for `@domain.org` will be maintained in `/etc/userdb`/domain-org, and so on.

    $ userdbpw | userdb "example-com/john@example.com" set imappw

This sets the IMAP access password for this account. Finally:

    $ makeuserdb

## `VCHKPW` AUTHENTICATION MODULE

This authentication module is provided for legacy support. New installs should use the `authuserdb` module. It is possible to convert vpopmail/vchkpw single userid authentication passwd files to `/etc/userdb` using the `vchkpw2userdb` script. See `vchkpw2userdb(8)` for more information.

## `LDAP` AUTHENTICATION MODULE

This module attempts to authenticate against an LDAP server. This option installs a sample configuration file, which is `/usr/lib/courier-imap/etc/authldaprc` by default. You will need to edit this file in order to configure LDAP authentication. This configuration file defines the location of your LDAP server, as well as the names of attributes used to perform LDAP authentication. See the comments in the sample configuration file, and the `authldap(7)` manual page, for more information.

## `DAEMON` AUTHENTICATION MODULE

Selecting the `authdaemon` module (it is selected by default) will compile and install a separate process, called "`authdaemond`". The "`authdaemond`" process is started and stopped by the `imapd.rc`, `imapd-ssl.rc`, `pop3d.rc` and `pop3d-ssl.rc`. ATTENTION: all four scripts stop `authdaemond`. Typically all the scripts are called together, at system startup and shutdown. If you need to stop just ONE service, find the pid and kill it manually. Otherwise `authdaemond` stops and nobody can log in anymore.

The `authdaemon` module (and the `authdaemond` process that goes with it) is very useful when a database is used as an authentication back-end (like MySQL, PostgreSQL, or OpenLDAP). The `authdaemon` module offers an alternative to compiling all the authentication code as standalone modules. Enabling `authdaemon` in addition to any other modules will result in `authdaemon` being built as the only "official" authentication module. All other modules are compiled into a separate process, "`authdaemond`".

Certain authentication modules -- such as `authldap`, `authpgsql` and `authmysql` -- connect to an external database in order to validate an authentication request. The database connection is created and destroyed for every login request, and with a large number of connections and authentications it is better to have a single daemon process running in a background, with a semi-permanent connection to the database, handling authentication requests. That's exactly what `authdaemond` does.

The `authdaemon` authentication module takes an authentication request, and forwards it to the permanently running `authdaemond` process, waits for the answer, and returns the result to the application. Courier-IMAP, by the virtue of its modular design, "sees" only the `authdaemon` authentication module. Behind the scenes, `authdaemon` takes every authentication request and passes it along to the `authdaemond` for processing, where all the real authentication happens.

The `/usr/lib/courier-imap/etc/authdaemonrc` configuration file sets several parameters for the `authdaemond` process. See the comments in this file for more information. Currently, `authdaemonrc` sets two parameters: number of daemon processes, and which available authentication modules are used.

Although `authdaemond` might be built with several authentication modules, not all of them must be used. This allows for a single `authdaemond` binary to be made that gets installed on multiple systems with different authentication needs. The default module list specified in `authdaemonrc` is a list of all the available authentication modules.

All available authentication modules are compiled by default. Although it is possible to disable unwanted authentication modules via the `configure` script, it is better to disable them at runtime. The list of all active authentication modules is read from the `authdaemonrc` configuration file. Removing an authentication module from this configuration file disables it.

The number of `authdaemond` processes is also set in this configuration file. The more processes that are started, the more authentication requests can be handled. If `authdaemon` does not receive an answer within some amount of time, it will assume an authentication failure, and abort. Try increasing the number of processes if you start seeing random authentication failures. However, that should only be used as a stop-gap measure. If the default number of `authdaemond` processes proves to be insufficient, it is far more likely that more resources are needed for the server (more RAM, a faster disk, or a faster CPU) in the humble opinion of the author. Increasing the number of processes should only be used as a stop-gap measure, until a more thorough analysis of the system performance.

After making any changes to `authdaemonrc`, run the following command for these changes to take effect:

        /usr/lib/courier-imap/libexec/authlib/authdaemond restart

### Alternative `authdaemond` modules

`/usr/lib/courier-imap/libexec/authlib/authdaemond` is actually a script. Depending on your system configuration, there may be one or more different `authdaemond` binaries installed, and here's why.

`authdaemond.plain` will include all available authentication modules except for certain "heavy" authentication modules. The current list of "heavy" authentication modules is `authldap`, `authpgsql`, and `authmysql`.

If support for a "heavy" authentication module is selected, there will be an additional binary installed, such as `authdaemond.mysql`, `authdaemond.pgsql` or `authdaemond.ldap`. The `/usr/lib/courier-imap/libexec/authlib/authdaemond` script checks if any "heavy" authentication daemon is installed, and, if so, runs that. Otherwise, the default `authdaemond.plain` binary goes in.

This allows an easy way to create binary Courier-IMAP distributions with and without LDAP, MySQL, or PostgreSQL support. The distributor would simply build Courier-IMAP on a machine that contains both LDAP/MySQL/PostgreSQL development libraries, then take everything but `authdaemond.mysql`, `authdaemond.pgsql` and `authdaemond.ldap` and roll it into the base Courier-IMAP package. `authdaemond.mysql`, `authdaemond.pgsql`, and `authdaemond.ldap` are rolled into separate sub-packages. Loading a base package installs basic system authentication services. Adding LDAP, MySQL, or PostgreSQL support is as simple as loading the corresponding sub-package.

## ACCOUNT INITIALIZATION HOOK

If there is a file or a symbolic link in the maildir called "loginexec", and if it is executable, then the executable file will be invoked after a succesful login. If the program terminates with an exit code of 0, the "loginexec" file (or a symbolic link) will be removed.

## USING SHARED FOLDERS

Courier-IMAP supports shared folders. See the file `README.sharedfolders.html` for information on how to set up shared folders.

## CRAM-MD5 AUTHENTICATION

CRAM-MD5 authentication allows IMAP clients to authenticate themselves without sending the password in clear-text over the network. Courier-IMAP now supports CRAM-MD5 by default, but is not enabled for reasons explained below. CRAM-MD5 support is implemented by the `authcram` module, with one exception - `authldap`, `authpgsql`, and `authmysql` support CRAM-MD5 authentication if the LDAP or the MySQL/PostgreSQL server stores clear-text passwords, and not crypt-ed passwords.

To use CRAM-MD5 it is necessary to use an IMAP client that support CRAM-MD5 authentication, of course. That's the easy part.

The problem is that it is not possible to use the system password when logging in using CRAM-MD5. That's because CRAM-MD5 requires the knowledge of the actual password, in the clear, in order to calculate authentication tokens (even though that the password itself is not sent in the clear over the network).

So, implementation of CRAM-MD5 is an advanced task that should be attempted only when you are comfortable with, and fully understand how Courier-IMAP works in general. Here's an overview of this procedure:

- Install and implement `/etc/userdb`, because CRAM-MD5 authentication uses the `/etc/userdb` database (but see below for LDAP-specific notes).
- Figure out which accounts are going to use CRAM-MD5 authentication. People who do not use an IMAP client that supports CRAM-MD5 can continue and log in with the existing system password. But everyone who runs a client that supports CRAM-MD5 authentication will need a new password. Also, it will be necessary to set up CRAM-MD5 passwords for everyone at the same time. As soon as CRAM-MD5 authentication is enabled, all CRAM-MD5 enabled clients will attempt to use it. If no password is available, Courier-IMAP has no choice but to reject the authentication attempt. Once that happens, the client will correctly interpret it as an authentication failure (and it is), and the client will not even try to authenticate using the system password. Use the following command to assign a CRAM-MD5 password:

      userdbpw -hmac-md5 | userdb userdb set hmac-md5pw

  Then run the `makeuserdb` command, as always.
- NOTE: CRAM-MD5 authentication is also be supported by `authldap`, `authpgsql` and `authmysql`, as long as clear-text passwords are used. See below for more information. Therefore, if you use LDAP, PostgreSQL, or MySQL, and you store clear-text passwords, you should all set and ready to go, and you do not need to install `/etc/userdb`, as described in this section.

### Enabling CRAM-MD5 authentication

Because of these unfortunate complexities, CRAM-MD5 authentication is disabled after installation. When you're ready to use CRAM-MD5, edit the `imapd` configuration file and add the "AUTH=CRAM-MD5" keyword to the IMAP_CAPABILITY environment variable, then restart Courier-IMAP. There are instructions in the `imapd` configuration file to that effect.

If you do not intend to ever use CRAM-MD5 authentication, you can either specify `--without-authcram` option to the configure script, or simply edit `imapd` and remove authcram from the AUTHMODULES setting.

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

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

## Account OPTIONS

It is possible to adjust certain parameters on an account-by-account basis. This feature is only available with `userdb`, `LDAP`, `MySQL`, and `PostgresSQL` authentication. Individual account options are not supported with system-based authentication modules (password/shadow files, or PAM).

> NOTE

> This account option implementation is used by Courier, Courier-IMAP, and SqWebMail. Some of the following information may not be applicable. The inapplicable bits should be obvious.

Account options have a single, uniform implementation by all supported authentication methods. To summarize, account options are listed as a single text string: a comma-separated list of "`OPTION=value`" settings. At this point, the following options may be used:

`disableimap=`n

  If "n" is 1, disable IMAP access to this account, without affecting POP3 and webmail access.

`disablepop3=`n

  If "n" is 1, disable POP3 access to this account, without affecting IMAP and webmail access.

`disablewebmail=`n

  If "n" is 1, disable webmail access to this account, without affecting IMAP and POP3 access.

`sharedgroup=`name

  Append "name" to the name of the top level virtual shared folder index file. This setting restricts which virtual shard folders this account could possibly access (and that's on top of whatever else the access control lists say). See the virtual shared folder documentation for more information.

  For technical reasons, group names may not include commas or "|" characters.

Account options are specified via the authentication modules in the following manner:

userdb

  Use the `userdb` command to set a field called "`options`". Example:

  >     userdb user1@example.com set options=disableimap=1,sharedgroup=44
  >     makeuserdb

  The option text string here is "`disableimap=1,sharedgroup=44`". It specifies two options.

LDAP

  Account options are defined by the `LDAP_AUXOPTIONS` setting in the `authldaprc` configuration file. `LDAP_AUXOPTIONS` consists of a comma-separated list of "`attribute=setting`". "attribute" is the name of an LDAP attribute, and "setting" is the corresponding account setting name. The value of the attribute becomes the value of the setting. Unless you value your sanity, the names of LDAP attributes should be the same as the actual setting names (in which case "=setting" may be dropped and `LDAP_AUXOPTIONS` becomes a simple comma-separated list of supported settings), but they don't have to be.

  `LDAP_AUXOPTIONS` is nothing more than a simple mapping of LDAP attributes to account settings. A `LDAP_AUXOPTIONS` of "shared=sharedgroup,disableimap" means that the LDAP attribute called "shared" contains the "sharedgroup" setting, as described previously; and an LDAP attribute of disableimap contains the setting of the same name.

MySQL, and PostgreSQL

  Account options are defined by `MYSQL_AUXOPTIONS_FIELD` or `POSTGRESQL_AUXOPTIONS_FIELD`, in its corresponding configuration file. In the most simplest case, add a character field to the database, and put the field name into the `MYSQL_AUXOPTIONS_FIELD` or `POSTGRESQL_AUXOPTIONS_FIELD` configuration file setting. For each account, the character field should contain the literal option string. Yes, you'll just put "shared=sharedgroup,disableimap" literally, in that field.

  Fortunately, there is a cleaner way to do this, which avoid driving a database designer batty. Keep in mind that the contents of `MYSQL_AUXOPTIONS_FIELD`/`POSTGRESQL_AUXOPTIONS_FIELD` are simply inserted directly into the SQL query that fetches the account information. Both MySQL and PostgreSQL have a rich SQL that can be used to manufacture a suitable option string from plain, garden-variety, database fields. That is, you may define individual table fields like "disableimap", and "disablepop3", then provide a suitable (albeit ugly) SQL fragment that combines them together into the expected option string. An example of such an SQL string is provided in the comments portion of the configuration file.

  > NOTE

  > When using the alternative custom query option, the option string is the last field that the custom SQL query should return.

## SMAP

Starting with Courier-IMAP 2.0, the 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.