Virtual Users And Domains With Postfix, Courier And MySQL (CentOS 5.1)

Version 1.0
Author: Falko Timme
Last edited 12/05/2007

This tutorial is Copyright (c) 2007 by Falko Timme. It is derived from a tutorial from Christoph Haas which you can find at You are free to use this tutorial under the Creative Commons license 2.5 or any later version.

This document describes how to install a Postfix mail server that is based on virtual users and domains, i.e. users and domains that are in a MySQL database. I'll also demonstrate the installation and configuration of Courier (Courier-POP3, Courier-IMAP), so that Courier can authenticate against the same MySQL database Postfix uses.

The resulting Postfix server is capable of SMTP-AUTH and TLS and quota (quota is not built into Postfix by default, I'll show how to patch your Postfix appropriately). Passwords are stored in encrypted form in the database (most documents I found were dealing with plain text passwords which is a security risk). In addition to that, this tutorial covers the installation of Amavisd, SpamAssassin and ClamAV so that emails will be scanned for spam and viruses.

The advantage of such a "virtual" setup (virtual users and domains in a MySQL database) is that it is far more performant than a setup that is based on "real" system users. With this virtual setup your mail server can handle thousands of domains and users. Besides, it is easier to administrate because you only have to deal with the MySQL database when you add new users/domains or edit existing ones. No more postmap commands to create db files, no more reloading of Postfix, etc. For the administration of the MySQL database you can use web based tools like phpMyAdmin which will also be installed in this howto. The third advantage is that users have an email address as user name (instead of a user name + an email address) which is easier to understand and keep in mind.

This tutorial is based on CentOS 5.1 (i386). You should already have set up a basic CentOS system, as described here: and Plus, you should make sure that the firewall is off (at least for now) and that SELinux is disabled (this is important!), as shown in the chapter six on

This howto is meant as a practical guide; it does not cover the theoretical backgrounds. They are treated in a lot of other documents in the web.

This document comes without warranty of any kind! I want to say that this is not the only way of setting up such a system. There are many ways of achieving this goal but this is the way I take. I do not issue any guarantee that this will work for you!


1 Edit /etc/hosts

Our hostname in this example is, and it has the IP address, so we change /etc/hosts as follows:

vi /etc/hosts

# Do not remove the following line, or various programs
# that require network functionality will fail.               localhost.localdomain localhost  server1
::1             localhost6.localdomain6 localhost6


2 Install Some Software

First we import the GPG keys for software packages:

rpm --import /etc/pki/rpm-gpg/RPM-GPG-KEY*

Then we update our existing packages on the system:

yum update

Now we install some software that we need later on:

yum groupinstall 'Development Tools'

yum groupinstall 'Development Libraries'


3 Install Apache, MySQL, phpMyAdmin

First we enable the RPMforge repository on our CentOS system as lots of the packages that we are going to install in the course of this tutorial are not available in the official CentOS 5.1 repositories:

rpm -Uhv

(If the above link doesn't work anymore, you can find the current version of rpmforge-release here:

Afterwards we can install the needed packages with one single command (including the packages we need to build Courier-IMAP):

yum install ntp httpd mysql-server php php-mysql php-mbstring php-mcrypt phpmyadmin rpm-build gcc mysql-devel openssl-devel cyrus-sasl-devel pkgconfig zlib-devel pcre-devel openldap-devel postgresql-devel expect libtool-ltdl-devel openldap-servers libtool gdbm-devel pam-devel gamin-devel


4 Install Courier-IMAP, Courier-Authlib, And Maildrop

Unfortunately there are no rpm packages for Courier-IMAP, Courier-Authlib, and Maildrop, therefore we have to install them as described in this tutorial: How To Install courier-imap, courier-authlib, And maildrop On Fedora, RedHat, CentOS

In case you have problems creating the rpm packages, you can download mine:


5 Apply Quota Patch To Postfix

We have to get the Postfix source rpm, patch it with the quota patch, build a new Postfix rpm package and install it.

cd /usr/src
rpm -ivh postfix-2.3.3-2.src.rpm

The last command will show some warnings that you can ignore:

warning: user mockbuild does not exist - using root
warning: group mockbuild does not exist - using root

cd /usr/src/redhat/SOURCES
gunzip postfix-2.3.3-vda.patch.gz
cd /usr/src/redhat/SPECS/

Now we must edit the file postfix.spec:

vi postfix.spec

Change %define MYSQL 0 to %define MYSQL 1, add Patch0: postfix-2.3.3-vda.patch to the # Patches stanza, and finally add %patch0 -p1 -b .vda to the %setup -q stanza:

%define MYSQL 1
# Patches

Patch0: postfix-2.3.3-vda.patch
Patch1: postfix-2.1.1-config.patch
Patch3: postfix-alternatives.patch
Patch6: postfix-2.1.1-obsolete.patch
Patch7: postfix-2.1.5-aliases.patch
Patch8: postfix-large-fs.patch
Patch9: postfix-2.2.5-cyrus.patch
%setup -q
# Apply obligatory patches
%patch0 -p1 -b .vda
%patch1 -p1 -b .config
%patch3 -p1 -b .alternatives
%patch6 -p1 -b .obsolete
%patch7 -p1 -b .aliases
%patch8 -p1 -b .large-fs
%patch9 -p1 -b .cyrus

Then we build our new Postfix rpm package with quota and MySQL support:

rpmbuild -ba postfix.spec

You will see lots of warnings like these that you can ignore:

msg.h:12:1: warning: "/*" within comment
msg.h:14:1: warning: "/*" within comment
msg.h:33:1: warning: "/*" within comment
msg.h:34:1: warning: "/*" within comment
msg.h:35:1: warning: "/*" within comment
msg.h:36:1: warning: "/*" within comment

Our Postfix rpm package is created in /usr/src/redhat/RPMS/i386, so we go there:

cd /usr/src/redhat/RPMS/i386

The command

ls -l

shows you the available packages:

[root@server1 i386]# ls -l
total 11280
-rw-r--r-- 1 root root 3819299 Dec  5 15:25 postfix-2.3.3-2.i386.rpm
-rw-r--r-- 1 root root 7655069 Dec  5 15:25 postfix-debuginfo-2.3.3-2.i386.rpm
-rw-r--r-- 1 root root   50346 Dec  5 15:25 postfix-pflogsumm-2.3.3-2.i386.rpm
[root@server1 i386]#

Pick the Postfix package and install it like this:

rpm -ivh postfix-2.3.3-2.i386.rpm

(In case you have problems creating the Postfix rpm package, you can download mine from here: postfix-2.3.3-2.i386.rpm.)


6 Set MySQL Passwords And Configure phpMyAdmin

Start MySQL:

chkconfig --levels 235 mysqld on
/etc/init.d/mysqld start

Then set passwords for the MySQL root account:

mysqladmin -u root password yourrootsqlpassword
mysqladmin -h -u root password yourrootsqlpassword

Now we configure phpMyAdmin. We change the Apache configuration so that phpMyAdmin allows connections not just from localhost (by commenting out the <Directory "/usr/share/phpmyadmin"> stanza):

vi /etc/httpd/conf.d/phpmyadmin.conf

#  Web application to manage MySQL

#<Directory "/usr/share/phpmyadmin">
#  Order Deny,Allow
#  Deny from all
#  Allow from

Alias /phpmyadmin /usr/share/phpmyadmin
Alias /phpMyAdmin /usr/share/phpmyadmin
Alias /mysqladmin /usr/share/phpmyadmin

Next we change the authentication in phpMyAdmin from cookie to http:

vi /usr/share/phpmyadmin/

/* Authentication type */
$cfg['Servers'][$i]['auth_type'] = 'http';

Then we create the system startup links for Apache and start it:

chkconfig --levels 235 httpd on
/etc/init.d/httpd start

Now you can direct your browser to or and log in with the user name root and your new root MySQL password.

Share this page:

19 Comment(s)

Add comment


From: at: 2008-04-20 14:14:05

I have created new RPMs for courier IMAP. They are avaliable here
version 4.3.1

From: at: 2008-05-29 18:31:14

I use this tutorial.
It is excellent.
But I need to let users to change they password so I make this simple php script.
I hope will be useful for someone.

Best regards,
Doru Barit

From: Anonymous at: 2008-10-14 18:21:53

Is it possible to use proftpd instaed of vsftpd?

From: Elfofdark at: 2009-09-08 08:02:02

I can't access http://ipd/phpmyadmin, it gives to me 404 not found. Maybe because i don't have anything in /var/www/html ?

 I did everything you said up every step with no error but i can't understand what did i miss. Please help me!

From: Daniel at: 2010-11-25 10:43:18

Look at this!

From: Anonymous at: 2008-11-14 20:09:01

How do you create user mailboxes? with maildirmake? or just sending an email to you new mailbox? I followed this guide too but i dunno how to create mailboxes in /home/vmail.

Any suggestion?

From: Arfie at: 2009-10-23 10:00:52

Hai doiu,

I have a problem with my squirrelmail.

When i want to change my password, i get error like this:

  ERROR:Connection refused (111)

And when i go to :

to get module chpasswd, this site is down.

would you mind if you give me that module to fix my problem?

Thank you very much 


From: Anonymous at: 2009-09-08 08:47:32



i have this setup running for 1 year now, lately it started marking mails as spam that are not.

I tried putting  "whitelist_from" into /etc/mail/spammassin/,

but the mails are still marked as spam.

So I have to put the whitelist somewhere else in this setup?

From: at: 2008-04-06 14:05:34

This is a great mail setup, and I recommend it highly to anyone looking for a good, robust, easy to manage solution for providing different clients (i.e. domains) with mail.  I have used Fedora Core 5 version, and now the CentOS 5 versions.  I couldnt be happier, except....

In it's current form, if one user authenticates and sends an email via this server to another user on the same box (either same domain or different domain), it is likely they will be flagged as spam under one of the dynamic IP lookup rules - actually they are likely to be flagged under a number of rules, and will most likely exceed the spam level. 

The solution to this is to add another postfix setting in

smtpd_sasl_authenticated_header = yes

This has TOTALLY solved this BIG problem for me.  Refer to form more information - about half way down the page.

Falco - I recommend you incorporate this into the actual instructions above, and any other guide you are doing with Postfix 2.3+ and SpamAssassin 3.1.4+ .  Thanks for the guides - keep them coming.

From: at: 2008-04-01 13:23:58

To save others from scratching their heads for so long like i did:

The maildrop rpm included for download in this tutorial is not compiled with mysql support! If you wish to use maildrop with the setup described here you will need to build your own maildrop rpm according to the instructions here:


From: at: 2008-04-06 14:29:55

This is a really good setup, but if you add greylisting it cuts down substantially more spam.

There is lots of doc around about greylisting, so make your own mind up about the best tool and method, but is really easy to follow and gets you going in minutes.

Highly Recommended as an addition to this howto...

From: at: 2008-07-14 21:00:41

Great article, and the best one I have found so far. 
However,I think that something is missing from the current tutorial (information about setting up maildir). I was getting some directory issues when i telneted on port 143. Then I realized that had to do a maildirmake on /home/vmail/[domain]/user to create the mailbox , then after that it worked just fine. My question now is : will i have to do that for every user? I thought there was a routine that would automatically create the directory after i add a user to the database.

Thanks again for this Article.

From: at: 2008-07-18 14:33:40

The following script in /etc/maildroprc will create the users maildir mailboxes automatically and it will also automatically filter anything marked as SPAM to the users' .Junk/ mail folder.


# commands and variables for making the mail directories

# make the user's mail directory if it doesn't exist
`test -e $MAILDIR`
if ($RETURNCODE != 0)
 `$mkdir -p $MAILDIR`
 `$rmdir $MAILDIR`
 `$maildirmake $MAILDIR`

# make the .Junk folder if it doesn't exist
`test -d $_JUNK_DEST`
if ($RETURNCODE != 0 )
 `$maildirmake $_JUNK_DEST`
 #auto subscribe. the following works for courier-imap
 `echo INBOX.Junk >> $MAILDIR/courierimapsubscribed`

if (/^X-Spam-Flag:.*YES/)
    exception {
        to $DEFAULT/.Junk/

From: tccom at: 2008-09-15 15:02:27

great tutorial Falko,

 this post is to remember all that if you want to use maildrop as local delivery system, the following line must be inserted into "transport" table of our mysql database 'mail':


 and then you can customize maildrop with /etc/maildroprc



From: Anonymous at: 2008-10-14 20:28:20

Hi all.

I'd like to know if this kind of configuration can work with roundcube webclient. If yes, is there any guide or how to marge this configuration with roundcube?

 My problem is that i cant find any link between postfix and roundcube's database. Any advice? Where can i start to work on?

Many thx

P.S.: wonderful guide :)

From: Britto at: 2008-10-20 12:54:20


Roundcube is just a webclient  and you should be able to integrate with roundcube.That is nothing to do with this guide and I could be able to do that .

Everything goes well as per this tutorial other than this version of postfix duplicates the mail for multi recipient inboxes. 








From: Anonymous at: 2008-10-27 13:02:19

Can someone give us some hits how to integrate Roundcube with this setup? Where is the link between the 2 databases?

From: Eugene Frakt at: 2009-08-27 04:09:12

You don't have to link the databases to use Roundcube.  It connects to the mailbox with standard imap, so all you have to do is input the imap settings in the Roundcube config.

From: Anonymous at: 2009-03-18 06:46:54

Hello. I installed postfix & courier as this HOWTO describes. I also installed Horde/IMP and configured it to use courier at localhost as an IMAP server. I added domains & users to the MySQL table, however, I kept getting authentication errors when logging into Horde. In /var/log/maillog, there were error messages like:

Mar 17 23:33:53 hostname imapd: chdir No such file or directory

(I've changed the hostname and domain name in the example above, but otherwise that is a cut-and-paste from my log file).

Turns out, the solution was that the directory it's looking for in /home/vhosts isn't created until after the account receives it's first email. It wasn't until after I'd sent a test message (via smtp a.k.a. port 25) to that IMAP logins were sucessful.

Hope this saves somebody some grief.