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, and does not have the flexibility needed for an ISP environment). 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.

$ ftp
login as 'ftp' or 'anonymous'
ftp> cd pub
ftp> cd FreeBSD
ftp> cd releases/i386/4.8-RELEASE
ftp> cd packages
ftp> cd All
ftp> dir gmake*
ftp> get gmake-3.80.tgz
150 Opening BINARY mode data connection for 'gmake-3.80.tgz' (303909 bytes).
100% |**************************************************|   296 KB    00:00 ETA
226 Transfer complete
ftp> quit
221 Goodbye.
$ su
Enter root password
# pkg_add gmake-3.80.tgz
# pkg_info | more
... check that the package is in the list of installed packages
# rm gmake-3.80.tgz
# exit

If you don't have them already, fetch courier-imap-1.7.3.tar.bz2 and sqwebmail-3.5.3.tar.bz2 from the pub/t1 directory on

Normally when Courier builds it installs itself under /usr/lib/courier-imap, but we will tell the configure script to use /usr/courier-imap instead to be consistent with how we installed Exim.

$ cd
$ tar -xvyf /path/to/file/courier-imap-1.7.3.tar.bz2
$ cd courier-imap-1.7.3
$ ./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).

With current versions of Courier-IMAP, all these authentication methods are built into a single authentication daemon, "authdaemond"

The only configuration you may need to do for the pop3 and imap daemons is to increase the maximum number of concurrent connections from the default of 40, if you have a fairly powerful mailserver:

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

If you wish, you can configure the authdaemond process not to use any authentication mechanisms which you know you don't need. For example, if all your authentication is only via PAM for Unix system passwords, then you can remove all the others:

# cd /usr/courier-imap/etc
# vi authdaemonrc

The "authpam" modules lets you authenticate against your Unix password file (PAM = Pluggable Authentication Modules). You need two lines in /etc/pam.conf for this to work, but in FreeBSD-4.8 they are already there:

# Mail services
imap    auth    required        try_first_pass
pop3    auth    required        try_first_pass

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: (they have long command lines!)
# 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, although current versions do now provide an error message. Hence you need to have delivered at least one message to the user, to create their mailbox, before they can login.

SECURITY NOTE: If you had built your system so that users are not in the password file, and all mailboxes are owned by a single userid (exim), then you could tell couriertcpd to start the imapd/pop3d daemons as exim rather than root. To do this, you would edit /usr/courier-imap/etc/pop3d and imapd and add "-user=exim" to couriertcpd options, i.e.

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

However, do not do this in the exercise.

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

You can't use a regular telnet to test it, because all your communication needs to be encrypted, but openssl has an SSL client you can use to make an encrypted connection for testing:

# openssl s_client -connect localhost:995

If you were running the service commercially you would be better to get a proper certificate signed by a recognised CA, rather than using a self-signed certificate.

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.

Modify the 'localuser' router:

  driver = accept
  transport = local_delivery_courier

Add a new entry in the 'transports' section:

  driver = pipe
  command = /usr/courier-imap/bin/deliverquota -c -w 90 \
        $home/Maildir 10000000S


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: you can do this from the FreeBSD ports collection.

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

(Note: using the FreeBSD port will mean you must use some different paths than the examples below, e.g. /usr/local/www/data instead of /usr/local/apache/htdocs)

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

$ tar -xvyf /path/to/file/sqwebmail-3.5.3.tar.bz2
$ cd sqwebmail-3.5.3
$ ./configure --prefix=/usr/sqwebmail
... takes a while
$ gmake configure-check
(check that it has chosen the right locations for cgi-bin and webmail images)
SqWebMail CGI will be installed in /usr/local/apache/cgi-bin
Images will be installed in /usr/local/apache/htdocs/webmail
URL to the image directory is /webmail
$ gmake
... takes a while
$ gmake check
... takes a short while, check there are no errors displayed
$ su
Password: <root password>
# gmake install-strip
# gmake install-configure

It will automatically install the CGI as /usr/local/apache/cgi-bin/sqwebmail. It uses the same types of authentication modules as Courier-imap (see /usr/sqwebmail/authdaemonrc)

Next start the authdaemond processes for sqwebmail:

# /usr/sqwebmail/libexec/authlib/authdaemond start

You need to put this in /etc/rc.local so that it starts automatically when the machine is next rebooted.

One other change is required: add the following line to /etc/crontab to periodically clean out old sessions:

0	*	*	*	*	bin	/usr/sqwebmail/

Then, using a web browser, go to http://yourmachine/cgi-bin/sqwebmail to log in, or https:// if you have SSL running. You should be able to read and send mail.

The INSTALL file in the source tarball 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.