Courier worksheet

Courier is a mail system which includes a number of packages. In fact it has its own MTA, but we will ignore this (it is still under heavy development). The components we are interested in are the IMAP/POP3 server, the 'deliverquota' program which Exim can use to deliver Maildir++ mailboxes more efficiently, and 'sqwebmail'. The main limitation of the Courier programs is their lack of debugging output when things aren't configured properly.

You can get the entire courier system as one package (including the MTA), or just the components.

1. Install courier-imap


Compilation requires GNU make, so install the 'gmake' package if you do not have it already.

Courier's default install directory is /usr/lib/courier-imap, but we will use /usr/courier-imap instead to be consistent with how we installed Exim.

$ tar -xvzf /path/to/file/courier-imap-1.3.8.tar.gz
$ cd courier-imap-1.3.8
$ ./configure --prefix=/usr/courier-imap
... takes a while
$ gmake
... takes a while
$ gmake check
... takes a short while, check there are no errors displayed
$ su
Password: <root password>
# gmake install
# gmake install-configure

To get access to the man pages, edit /etc/manpath.config and add the following line:

OPTIONAL_MANPATH	/usr/courier-imap/man

Test with 'man authuserdb' and see if the page is displayed.

2. Configure the daemons

Courier can get its user and password information from a variety of places, using authentication modules. Some of these, like mysql and ldap, are only compiled if those pieces of software are already installed (see INSTALL in the source directory for more information). To see which modules you have available:

# ls /usr/courier-imap/libexec/authlib
authcram        authcustom      authpam         authuserdb

You need to configure pop3d and imapd to let it know which module(s) to use

2a. Unix accounts (/etc/passwd)

Use the 'authpam' module if you are simply providing pop3/imap service to local Unix accounts. At the same time, you may wish to increase the maximum number of concurrent connections above the default (40).

# cd /usr/courier-imap/etc
# vi pop3d
# vi imapd

Edit /etc/pam.conf. You will find there is already a line for imap and pop3, but they will need to be extended as follows:

# Mail services
imap    auth    required        try_first_pass
imap    account required
imap    session required
pop3    auth    required        try_first_pass
pop3    account required
pop3    session required

2b. userdb

Courier is also table-driven; unfortunately they are not the same tables as we used for Exim.

The authuserdb module looks up account information in a database file, /etc/userdb.dat. This is generated by the command mkuserdb from a plain text file, /etc/userdb

Entries in /etc/userdb have the following format:


You can edit this file with any text editor, or use the 'userdb' command for updating it. Note that the password must be encrypted, and the 'userdbpw' command will do this for you

The required attributes are uid, gid and home. Additionally you should set mail (the location of the Maildir) because this defaults to $home/Maildir

Make the same changes to /usr/courier-imap/etc/pop3d and imapd as above, but with AUTHMODULES="authuserdb". Then create a database as follows:

Create an empty database:
# touch /etc/userdb
# chmod 600 /etc/userdb       # contains passwords!

Create a user:
# cd /usr/courier-imap/sbin
# ./userdb brian set uid=90 gid=90 home=/u/mail/brian mail=.
# ./userdbpw | ./userdb brian set systempw

Check the contents:
# cat /etc/userdb
# cat /etc/userdb
brian   uid=90|mail=/u/mail/brian|systempw=Zosu1wDBLXcS6|gid=90

Build the database file
# ./makeuserdb
# ls -l /etc/userdb*
-rw-------  1 root  wheel     62 May  5 12:52 /etc/userdb
-rw-r--r--  1 root  wheel  32768 May  5 12:55 /etc/userdb.dat
-rw-r--r--  1 root  wheel      0 May  5 12:55 /etc/userdb.lock
-rw-------  1 root  wheel  32768 May  5 12:55 /etc/userdbshadow.dat

There is a utility to convert an existing set of accounts in /etc/passwd to userdb format: you can then manually remove the unwanted (system) accounts.

# /usr/courier-imap/share/pw2userdb --shadow=/etc/master.passwd >/etc/userdb

3. Start the daemons

Make sure you have no existing pop3 server enabled in /etc/inetd.conf. You can start the pop3 and/or imap servers using one or both of the following commands, which can go in /etc/rc.local to run at startup time:

# /usr/courier-imap/libexec/pop3d.rc start
# /usr/courier-imap/libexec/imapd.rc start

To check they are running:
# ps auxwww | grep couriertcpd

Test using telnet:

# telnet localhost 110
Connected to localhost.
Escape character is '^]'.
+OK Hello there.
user <username>
+OK Password required.
pass <password>
+OK logged in.
+OK 26 49857
retr 1
+OK 1073 octets follow.
... message
+OK Bye-bye.
Connection closed by foreign host.

# telnet localhost 143
Connected to localhost.
Escape character is '^]'.
* OK Courier-IMAP ready. Copyright 1998-2001 Double Precision, Inc.  See
COPYING for distribution information.
a001 login <username> <password>
a001 OK LOGIN Ok.
a002 examine inbox
* FLAGS (\Answered \Flagged \Deleted \Seen \Recent)
* OK [PERMANENTFLAGS ()] No permanent flags permitted
* OK [UIDVALIDITY 989061119] Ok
a002 OK [READ-ONLY] Ok
a003 logout
* BYE Courier-IMAP server shutting down
a003 OK LOGOUT completed
Connection closed by foreign host.

NOTE: The daemons will fail to login if the mail directory does not exist (they will simply drop the connection to the user, although an entry does get written into /var/log/maillog). Hence you need to have delivered at least one message to the user, to create their mailbox, before they can login.

SECURITY NOTE: If your system is using a single userid (exim) for all mail, then you can tell couriertcpd to start the imapd/pop3d daemons as exim rather than root. To do this, edit /usr/courier-imap/etc/pop3d and imapd and add "-user=exim" to couriertcpd options, i.e.

TCPDOPTS="-nodnslookup -noidentlookup -user=exim"

4. pop3 and imap over SSL

If you wish, you can choose to run pop3 over SSL (port 995) and imap over SSL (port 993). The advantage is that, for clients which support it, the traffic is encrypted. The disadvantage is higher CPU load on your server for the encryption of data.

To run SSL you will need a certificate. For testing purposes you can use a 'self-signed' certificate, the following scripts will generate them for you:

# /usr/courier-imap/sbin/mkpop3dcert
# /usr/courier-imap/sbin/mkimapdcert

Then you start the servers:

# /usr/courier-imap/libexec/pop3d-ssl.rc start
# /usr/courier-imap/libexec/imapd-ssl.rc start

If you were running the service commercially you would be better to get a proper certificate signed by a recognised CA.

5. Using 'deliverquota' from Exim

Courier implements an extension to Maildir called Maildir++ which efficiently keeps track of quota status for each mailbox, even when the user has thousands of messages stored in hundreds of folders (which certainly can be the case when you are using IMAP and webmail). For this to work, all software which accesses the Maildir must adhere to this extension.

To get Exim to deliver using Maildir++, you get it to call the 'deliverquota' program, rather than delivering using its built-in Maildir capability.

Our MX configure file already has two Maildir transports built in (maildir_internal and maildir_courier), so you just need to change it to use maildir_courier instead of maildir_internal.

  directory_transport = maildir_courier

deliverquota has the useful capability of delivering a warning message when the mailbox gets nearly full (e.g. 90%). To use this, you need to create a warning message:

# cd /usr/courier-imap/etc
# cp quotawarnmsg.example quotawarnmsg
# vi quotawarnmsg

6. sqwebmail


webmail is a very useful service to offer your clients - although you may need to be careful of the extra CPU load and bandwidth it might use.

Unlike many other webmail solutions, which use POP3 or IMAP to talk to the mail store, sqwebmail reads and writes Maildir directories directly. This makes it efficient in the case where POP/IMAP and webmail run on the same box, or where there is an NFS-shared mailstore

sqwebmail is feature-rich, very customisable through HTML templates and stylesheets, supports multiple languages, and is simple to install (it runs as a single CGI). Note however that it is still under very active development and hence subject to change quite frequently.

If you don't have it, install and test Apache first:

# cd /usr/ports/www/apache13
# make install
# make clean
# /usr/local/sbin/apachectl start

Also, if you install 'ispell' and/or 'gnupg' before compiling then these will be detected and usable from the web interface.

$ tar -xvzf /path/to/file/sqwebmail-2.0.0.tar.gz
$ cd sqwebmail-2.0.0
$ ./configure --prefix=/usr/sqwebmail \
    --enable-imagedir=/usr/local/www/data/images \
... takes a while
$ gmake
... takes a while
$ gmake check
... takes a short while, check there are no errors displayed
$ su
Password: <root password>
# gmake install

On a FreeBSD system with Apache already installed, it will automatically install the CGI as /usr/local/www/cgi-bin/sqwebmail. It uses the same types of authentication modules as Courer-imap; configure which ones to use in /usr/sqwebmail/share/sqwebmail/authmodulelist

Then go to http://yourmachine/cgi-bin/sqwebmail to log in.

The INSTALL file has more information on other configuration changes you can make

SECURITY NOTE: the sqwebmail CGI is install suid-root. If you are running a system where all mail is owned by the 'exim' user, then change it to suid-exim; it will then be impossible for it to access files as a different uid.