Gentoo Wiki


This article is part of the HOWTO series.
Installation Kernel & Hardware Networks Portage Software System X Server Gaming Non-x86 Emulators Misc



Setting up Courier to use MySQL as it backend, making SSL certificates if needed, it really only takes a few minutes apart from compiling.

This HOWTO is based on a thread on gentoo forums(which moved to, with permission from the owner. In this HOWTO, we will be using the domain as our primary domain, and as the address of our smtp, imap and pop servers. The postmaster email will be


What this HOWTO will do

  1. Install courier
  2. Configure courier to use MySQL.

Required packages


This HOWTO does not focus on how to set up MySQL. Please see Installing MySQL for instructions on how to do that.

Use flags

You need two useflags to be set for this guide:

Install Packages

This is probably the easiest step. It is good practice to always do an ask/verbose before installing any package. This way you know what is going to be installed (focusing on dependencies, if any). Kick back for a while as it takes about 30 minutes to install the packages, depending on hardware/optimizations. It will take longer if any dependencies need to be installed.

Code: Install Courier
# emerge --sync
# emerge -av courier-authlib courier

Configuring Courier

The first step is to create the certificates, there are two ways of doing this, using selfsigned certificates, or using certificates signed by a known CA. The choice is yours.


Using Selfsigned Certificates

Edit these three files in /etc/courier to fit your needs:

Code: Files to edit
* esmtpd.cnf 
* imapd.cnf 
* pop3d.cnf

Now, run these commands to regenarate new certificates:

Code: Run Command
# mkesmtpdcert
# mkimapdcert
# mkpop3dcert

NB: If it complains about existing certificates then simply remove the old ones first.

Using Certificates Signed By A CA

This is a little bit more complicated, but still quite easy to do. For this HOWTO we will be using as our CA. You can use any other, such as Verisign etc. if you like. We also use the same certificate for smtp, imap and pop.

First, create a directory and enter it, this way we have all the files needed in one place, and no other files causing troubles.

Then, you need to generate a key:

Code: Generate a key
openssl genrsa -out 1024

Now, we need to generate the certificate request (CSR) (the commonName field should be in this case):

Code: Generate the certificate request (CSR)
openssl req -new -key -out

Now you should send the csr file to your CA, the method for doing this is different from CA to CA, so go read on their website on how to do that.

When you get the certificate from them, save it as

The only thing left to do is to create the .pem file: Now we have a signed certificate we need to 'mangle' it slightly to make it work ok with courier. The first step is to remove the human readable version of the certificate which the signing process might have inserted at the top of the new .crt file. Open it in an editor and remove everything down to the line which begins:

File: Remove everything above

After you have removed that you need to put both the .key and .crt files into a .pem file for use with courier:

Code: Run Command
~ # cat >

The last step in preparing this certificate for use with courier is to add the Diffie-Hellman code to the .pem file:

Code: Run Command
~ # openssl gendh >>

Now copy to the other names:

Code: copy to these filenames
* esmtpd.pem 
* imapd.pem 
* pop3d.pem

Then copy all three to /usr/share/courier.

Enable the desired services

You will now need to edit these files in /etc/courier:

There is a line at the bottom that tells if this service should start or not, so change setting to the desired one.

Creating the MySQL database

First, make sure MySQL is running:

Code: Run Command
~ # /etc/init.d/mysql start
* Starting mysqld...               [ ok ]

Now we need to login into MySQL, create the database, and create the courier user:

Code: Run Commands
~ # mysql -p 
mysql> CREATE DATABASE courier;
mysql> use courier; 
      id                    char(128) NOT NULL, 
      crypt                 char(128) NOT NULL, 
      clear                 char(128) NOT NULL, 
      name                  char(128) NOT NULL, 
      uid                   int(10) unsigned DEFAULT '8' NOT NULL, 
      gid                   int(10) unsigned DEFAULT '12' NOT NULL, 
      home                  char(255) NOT NULL, 
      maildir               char(255) NOT NULL, 
      defaultdelivery       char(255) NOT NULL, 
      quota                 char(255) NOT NULL, 
      options               char(255) NOT NULL, 
      KEY id (id(128))
mysql> grant select on courier.passwd to courier@localhost identified by "enter_password_here";

Now, edit /etc/courier/authlib/authmysqlrc and make sure these fields are correct:

File: Edit these fields in /etc/courier/authlib/authmysqlrc
 The MYSQL_SOCKET will have to be changed to what the mysql server uses.
 On gentoo systems it is: /var/run/mysqld/mysqld.sock

Configuring Courier to use MySQL

All we need to do is edit /etc/courier/authlib/authdaemonrc, and change the following options:

File: Edit these fields in /etc/courier/authlib/authdaemonrc

Setting up postmaster and hosted domains

We need to edit a few files now.

File: Edit these fields in /etc/courier/aliases/system

Now, run these commands:

Code: Run Commands

Setting up maildirs and adding users

Next we need to make the directories for the maildirs:

Code: Run Commands
mkdir /var/mail/
mkdir /var/mail/
cd /var/mail/
maildirmake .maildir 
chown mail:mail -R /var/mail/

Now we need to add the user to the database, I would recommend using phpMyAdmin, since it can encrypt the password for you. First, we need to know the UID and GID for the mail user and group:

Code: Run Commands
~ # cat /etc/passwd |grep ^mail |cut -d ':' -f 3
~ # cat /etc/group |grep ^mail |cut -d ':' -f 3

On most systems these are UID: 8 and GID: 12

The fields that should be used are:

File: Fields to use
  • id : the full email address, example: .
  • crypt : users password, select Encrypt in phpMyAdmin when adding the encrypted password.
  • clear : leave empty, since we are using encrypted passwords.
  • uid : the UID of the mail user.
  • gid : the GID of the mail group.
  • home : the directory where the users .maildir is placed, example: /var/mail/
  • maildir : leave empty, not needed here.
  • defaultdelivery : the path to the default dir for delivery of mail (incoming), only change if you want to override the default, settings, which is in users homedir/.maildir .
  • quota : Defined quota types are 'S' - total size of all messages, and 'C' - the maximum count of messages in the maildir. example 10000000S,1000C specifies a quota of 10,000,000 bytes or 1,000 messages, whichever comes first.
  • option : various options, you do not have to fill in some. comma seperated, example: disableimap=1,disablepop3=1,disablewebmail=1

Disabling the built-in webmail

Since we are not going to use the webmail in courier (if you need webmail, you can install another webmail package)

File: /etc/init.d/courier

Comment out the lines in the start and stop methods that mention webmail.

Quota warning notice

If you want, Courier will be send a warning notice to the user, wich ./.maildir size is greater than XX% of the quota (in this example - 90%). First, copy file in /etc/courier/quotawarnmsg.example to /etc/courier/quotawarnmsg and edit it. Then, you must configure option DEFAULTDELIVERY in /etc/courier/courierd file:

File: /etc/courier/courierd
# default value is DEFAULTDELIVERY=./.maildir
DEFAULTDELIVERY=“| /usr/bin/maildrop -w 90”

Now if size of the users ./.maildir is greater than 90% (option '-w 90'), and incoming mail is coming, the maildrop sending a warning message to the user, and creating a file quotawarn in users ./.maildir. This file is a 'flag' for maildrop. Maildrop regulary checking this file for create date/time stamp, and if it is 24 hrs old, resending a warning message to the user.

Starting Courier

Now the only thing left to do is start the server and make it start when booting:

Code: Run Commands
rc-update add courier default
/etc/init.d/courier start

cd /etc/pam.d
ln -s imap esmtp

otherwise you will get repeated authentication failures.


Suggested Reading


Concerns or Compliments? Please use the Discussion section.

Retrieved from ""

Last modified: Sun, 28 Sep 2008 08:03:00 +0000 Hits: 32,803