HOWTO Email Virtual Hosting with Courier and MySQL

From Gentoo Linux Wiki

[edit] Introduction

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 http://forums.gentoo.org/viewtopic-t-144837.html a thread on gentoo forums(which moved to http://wiki.kaspersandberg.com/doku.php?id=howtos:courier-mailsuite), with permission from the owner. In this HOWTO, we will be using the domain happyfish.org as our primary domain, and mail.happyfish.org as the address of our smtp, imap and pop servers. The postmaster email will be john@happyfish.org.

[edit] Synopsis

[edit] What this HOWTO will do

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

[edit] Required packages

• dev-db/mysql
• mail-mta/courier
• net-libs/courier-authlib

[edit] Environment

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

[edit] Use flags

You need two useflags to be set for this guide:

• mysql - adds mysql support to Courier
• ssl - adds ssl support to Courier

[edit] 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.

# emerge --sync
# emerge -av courier-authlib courier

[edit] 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.

[edit] Certificates

[edit] Using Selfsigned Certificates

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

* esmtpd.cnf 
* imapd.cnf 
* pop3d.cnf

Now, run these commands to regenarate new certificates:

# mkesmtpdcert
# mkimapdcert
# mkpop3dcert

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

[edit] 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 cacert.org 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:

openssl genrsa -out happyfish.org.key 1024

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

openssl req -new -key happyfish.org.key -out happyfish.org.csr

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 happyfish.org.crt

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:

 -----BEGIN CERTIFICATE-----

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

~ # cat happyfish.org.key happyfish.org.crt > happyfish.org.pem

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

~ # openssl gendh >> happyfish.org.pem

Now copy happyfish.org.pem to the other names:

* esmtpd.pem 
* imapd.pem 
* pop3d.pem

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

[edit] Enable the desired services

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

• imapd
• imapd-ssl
• pop3d
• pop3d-ssl
• esmtpd
• esmtpd-msa
• esmtpd-ssl

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

[edit] Creating the MySQL database

First, make sure MySQL is running:

~ # /etc/init.d/mysql start
* Starting mysqld...               [ ok ]

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

~ # mysql -p 

mysql> CREATE DATABASE courier;
mysql> use courier; 
mysql>
CREATE TABLE passwd (
      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:

MYSQL_SERVER
MYSQL_USERNAME
MYSQL_PASSWORD
MYSQL_SOCKET
MYSQL_DATABASE
MYSQL_CLEAR_PWFIELD
MYSQL_UID_FIELD
MYSQL_GID_FIELD 
MYSQL_MAILDIR_FIELD
MYSQL_DEFAULTDELIVERY(optional)
MYSQL_QUOTA_FIELD(optional)

NOTE:
 The MYSQL_SOCKET will have to be changed to what the mysql server uses.
 On gentoo systems it is: /var/run/mysqld/mysqld.sock

[edit] Configuring Courier to use MySQL

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

authmodulelist=authmysql
version=authdaemond.mysql

[edit] Setting up postmaster and hosted domains

We need to edit a few files now.

postmaster: john@happyfish.org

• /etc/courier/hosteddomains - This file should just have a list of all domains the courier mailserver should handle (one host per line)
• /etc/courier/smtpaccess/default - These settings talk for themselves. Just enable the ip adresses/subnets that you want to allow access to. Or you can empty the smtpaccess directory to allow access from any host, as long as they authorize with the daemon first. It's probably a good idea to create a backup for reference in case you decide you need more information. The format of the file is covered in the man page for couriertcpd.
• /etc/courier/esmtpacceptmailfor.dir/ - Every line in file(s) in this folder represents a domain name for which Courier is accepting mail without allowing relay.
• /etc/courier/defaultdomain - Should contain only one line with one of your domains that will serve as the default domain for when domain information is missing in E-mail addresses.

Now, run these commands:

makehosteddomains
makealiases
makesmtpaccess
makesmtpaccess-msa
makeacceptmailfor

[edit] Setting up maildirs and adding users

Next we need to make the directories for the maildirs:

mkdir /var/mail/happyfish.org
mkdir /var/mail/happyfish.org/john
cd /var/mail/happyfish.org/john
maildirmake .maildir 
chown mail:mail -R /var/mail/happyfish.org

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:

~ # 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:

[edit] 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)

[edit] 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:

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

[edit] Starting Courier

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

rc-update add courier default
/etc/init.d/courier start

• For SMTP AUTH, make sure you do:

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

otherwise you will get repeated authentication failures.

[edit] Resources

[edit] Suggested Reading

• The manpages for the different configuration files we have been editing.
• HOWTO for SSL certificates with courier
• Everything available on Google :)

[edit] Support

• Gentoo Forums
• The thread that this HOWTO is based on.
• Contact the author -- via Gentoo Forums (registration is required).