Gentoo Logo
Gentoo Logo Side

qmail/vpopmail Virtual Mail Hosting System Guide


1. Introduction

Whether you're providing e-mail for just system daemons, a single server, a domain, or for many virtual domains, qmail can easily be setup to handle your needs. This guide will help you setup qmail for all of these scenarios with a focus on remote access and encrypted communications the whole way through.

Specifically, the packages this guide will help you with are qmail, courier-imap, vpopmail, and horde/imp. These core packages will also bring in daemontools, ucspi-tcp, mysql, apache, and mod_php. qmail provides the core mta functions, courier-imap provides remote retrieval services, vpopmail provides virtual domain management, and horde/imp provides webmail access.

Before emerging anything, you will need the following USE variables enabled. If you've already emerged any of these packages, you may have to re-emerge them. USE="maildir ssl imap mysql". Additionally, if you want to use horde/imp for your webmail then you will need USE="nls" before emerging mod_php.

Note: This guide is written in steps. If at anytime you feel your setup is 'complete', you do not need to continue.

The last step of course is to commit yourself to the qmail system. There are of course many other packages with which you could build your e-mail system. Now is the time to research and decide that qmail is for you. We have another lovely guide centered around Postfix, or you could look into exim. It's up to you to choose the best solution for yourself, it is up to us to show you how to use qmail here.

2. qmail (talking to myself)

Code Listing 2.1: Emerge qmail

# emerge qmail

Important: This guide is designed around qmail-1.03-r13 or later. Will it work with earlier versions? Maybe. Should you upgrade? Yes, if you want to be sure this guide will work.

Warning: If you get a message like the virtual/mta package conflicts with another package then you need to make sure to unmerge the other MTA on your system. To figure out what package that is, just run emerge qmail -p.

Emerging qmail will also emerge ucspi-tcp and daemontools. You can read up on ucspi-tcp and on daemontools if you like. Basically, daemontools is responsible for managing qmail as a service while ucspi-tcp is responsible for managing the incoming TCP connections to the qmail service.

First we have a few post-install configuration steps.

Code Listing 2.2: Out-of-the-box setup for qmail

(Customize to fit your personal information)
# nano /var/qmail/control/servercert.cnf
# ebuild /var/db/pkg/mail-mta/qmail-1.03-r*/qmail-1.03-r*.ebuild config

The design of qmail has been completely around the focus of security. To this end, e-mail is never sent to the user 'root'. So now you have to select a user on your machine to receive mail that would normally be destined for 'root'. From now on in this guide, I will refer to that user as I have it in my setup, 'vapier'.

Code Listing 2.3: Setting up non-root account for mail

# cd /var/qmail/alias
# echo vapier > .qmail-root
# echo vapier > .qmail-postmaster
# echo vapier > .qmail-mailer-daemon

Now we want to get the qmail delivery service up and running.

Code Listing 2.4: Start qmail delivery service

# rc-update add svscan default
# /etc/init.d/svscan start
# cd /service
# ln -s /var/qmail/supervise/qmail-send qmail-send

We want to make sure qmail is working correctly, so here's a quick test.

Code Listing 2.5: Test delivery service

# ssh [email protected]
# maildirmake .maildir
# qmail-inject root << EOF
test root e-mail!
# qmail-inject postmaster << EOF
test postmaster e-mail!
# qmail-inject vapier << EOF
test vapier e-mail!
# mutt 
(You should now have 3 e-mails in your inbox)

And that's all! Now you have a mail system that will handle mail for your local machine and the system daemons/users who utilize it.

Warning: If you don't receive any mail or you see weird errors in the log files (check /var/log/qmail/) involving 'localhost.localhost', then that means your domain/dns information is not setup properly. By default, qmail utilizes the output of hostname --fqdn. If, on your machine, this returns 'localhost', then check your /etc/hostname, /etc/hosts, and your dns to make sure everything is correct. Once you have, edit the configuration files in /var/qmail/control/. Use the example setups that follow if you need some more help.

Code Listing 2.6: Example /var/qmail/control/ files for a 2nd level domain

# hostname --fqdn
# cat me
# cat defaultdomain
# cat plusdomain
# cat locals
# cat rcpthosts

Code Listing 2.7: Example /var/qmail/control/ files for a 3rd level domain

# hostname --fqdn
# cat me
# cat defaultdomain
# cat plusdomain
# cat locals
# cat rcpthosts

3. vpopmail

Code Listing 3.1: Emerge vpopmail

# emerge vpopmail

Important: This guide is designed around vpopmail-5.4.0_rc1 or later. Will it work with earlier versions? Maybe. Should you upgrade? Yes, if you want to be sure this guide will work.

vpopmail takes a little bit more effort to setup than the previous packages. Since vpopmail runs off of mysql, we'll have to make sure that it's up and running first. Then we can setup the vpopmail database and move on. Before you do this step, you should make sure you've already emerged and setup mysql properly. Note that the password I will use for the vpopmail database is 'vpoppw', you however should pick a different one.

Code Listing 3.2: Setting up vpopmail in mysql

# rc-update add mysql default
If you just emerged mysql for the first time, make sure you run 
the ebuild <mysql.ebuild> config command and follow the 
directions before starting the mysql server.
# /etc/init.d/mysql start
# nano /etc/vpopmail.conf 
(Change the password from 'secret' to 'vpoppw')
# mysql -p << EOF
create database vpopmail;
use mysql;
grant select, insert, update, delete, create, drop on vpopmail.* to [email protected] identified by 'vpoppw';
flush privileges;
(The following steps may or may not be needed, but we run them just to be sure)
# chown root:vpopmail /etc/vpopmail.conf
# chmod 640 /etc/vpopmail.conf
# chown root:vpopmail /var/vpopmail/bin/vchkpw
# chmod 4711 /var/vpopmail/bin/vchkpw

Warning: If you experience permission problems with mysql/vpopmail, you may want to try restarting mysql. Just run /etc/init.d/mysql restart.

At this point in time, vpopmail is ready to roll. In this guide, we will be providing virtual hosting for the domain ''. This means we need to tell vpopmail about this domain we want it to host for us. We'll also quickly add an user account for 'vapier' while we're here.

Code Listing 3.3: Adding a domain

(You only have to do this if the vadddomain step below results in "command not found")
# source /etc/profile

(While debugging vpopmail, you may want to consult the logs)
# mysql -u vpopmail -p
mysql> select * from vpopmail.vlog;

# vadddomain postpass
(Now quickly verify the domain is setup properly)
# printf "[email protected]\0postpass\0blah\0" | vchkpw `which id` 3<&0
uid=89(vpopmail) gid=89(vpopmail) groups=0(root)
(If you don't see something similar to above, then permissions somewhere are incorrect)
# vadduser [email protected] vappw

Every domain that vpopmail creates comes with a 'postmaster' account. Here we told vpopmail that the password for the postmaster account is 'postpass'. Before vpopmail can be truly useful, we'll need to be able to receive mail via courier and send mail via qmail and SMTP.

4. Courier POP/IMAP

Code Listing 4.1: Emerge courier-imap

# emerge net-mail/courier-imap

Important: You must emerge courier-imap after vpopmail. That way the authvchkpw module will be built.

Important: This guide is designed around net-mail/courier-imap-2.1.2-r1 or later. Will it work with earlier versions? Maybe. Should you upgrade? Yes, if you want to be sure this guide will work.

Now for the common post-install configuration steps. These steps are only needed if you wish to run SSL encrypted communications (which you should !). Otherwise you can skip to the last two steps in the two following code listings, removing the '-ssl' from the init script name each time.

Code Listing 4.2: Out-of-the-box setup for POP3/SSL

# cd /etc/courier-imap
# nano authdaemonrc
(Set the authmodulelist variable to only contain "authvchkpw")
# nano pop3d.cnf 
(Edit the [ req_dn ] section)
# mkpop3dcert
# rc-update add courier-pop3d-ssl default
# /etc/init.d/courier-pop3d-ssl start

Code Listing 4.3: Out-of-the-box setup for IMAP/SSL

# cd /etc/courier-imap
# nano imapd.cnf 
(Edit the [ req_dn ] section)
# mkimapdcert
# rc-update add courier-imapd-ssl default
# /etc/init.d/courier-imapd-ssl start

Your mail client should now be able to login to the host running courier and retrieve mail for the virtual host. In my case, I am now able to login with the username '[email protected]' and password 'vappw'.

5. qmail (talking to the world)

Let's get SMTP up and running while making sure we don't create another spam hole for people to abuse.

Code Listing 5.1: Start qmail SMTP service

# cd /var/qmail/control/
# nano conf-smtpd
(Uncomment the SMTP-AUTH variables and set QMAIL_SMTP_CHECKPASSWORD to /var/vpopmail/bin/vchkpw)
# nano servercert.cnf 
(Edit the [ req_dn ] section)
# mkservercert
# cd /service
# ln -s /var/qmail/supervise/qmail-smtpd qmail-smtpd
# /etc/init.d/svscan restart

Assuming you haven't tweaked the qmail control files at all, qmail will now accept mail for the virtual domain and for users of the local machine. Furthermore, qmail will relay mail for anyone who sends via and for anyone who is able to authenticate with vpopmail. When you setup your mail client to send mail, make sure you select options like 'Server requires authentication'. In my case, I set the user as '[email protected]' and my password as 'vappw'. The last detail is to make sure you tell your mail client to use SSL/TLS for SMTP communication. qmail will not let you authenticate if the session is not encrypted.

6. Horde / IMP Webmail Client

Although there are plenty of webmail clients out there (and you're free to use any of them), I prefer the IMP Webmail Client that is part of the Horde framework. The biggest reason is that Horde can simply provide Webmail access, or you can easily add other components to handle Address Books, Calendars, Tasks, etc... If this hasn't convinced you yet, then perhaps you need to read up on Horde for yourself.

On to the good stuff! We need to emerge IMP now.

Code Listing 6.1: Emerge IMP

# emerge horde-imp

Important: This guide is based around horde-2.2.4 and horde-imp-3.2.2. The CVS versions (and thus the next major release) will probably have very different configuration settings.

Horde currently isn't the easiest to setup unless you know exactly what to do. Fortunately for you, I know exactly what to do, thus you will too.

Code Listing 6.2: Out-of-the-box setup for Horde

# cd /var/www/localhost/htdocs/horde/config/
# for f in *.dist ; do mv ${f} ${f/.dist} ; done
# nano horde.php
(Under 'Horde Authentication':)
$conf['auth']['driver'] = 'imap';
$conf['auth']['params']['dsn'] = '{localhost:993/imap/ssl/novalidate-cert}';

(Under 'Horde Logging':)
$conf['log']['name'] = '/var/log/apache2/horde.log';

(Under 'Problem Reporting':)
$conf['problems']['enabled'] = true;
$conf['problems']['email'] = '[email protected]';

# nano registry.php
(Under 'Handlers':)
$this->registry['auth']['login'] = 'imp';
$this->registry['auth']['logout'] = 'imp';

(Under 'Application registry':)
Set the 'status' element of applications['imp'] from 'inactive' to 'active'

# touch /var/log/apache2/horde.log
# chown apache:apache /var/log/apache2/horde.log

Note: You'll may want to change the 'webmaster' e-mail account to something else. If you wish to use that e-mail address, then remember you'll have to add that user via vpopmail (or see below about qmailadmin).

Now we setup IMP real quick.

Code Listing 6.3: Out-of-the-box setup for IMP

# cd /var/www/localhost/htdocs/horde/imp/config/
# for f in *.dist ; do mv ${f} ${f/.dist} ; done
# nano servers.php

(Edit the $servers['imap'] array:)
$servers['imap'] = array(
	'name' => '',
	'server' => 'localhost',
	'protocol' => 'imap/ssl/novalidate-cert',
	'port' => 993,
	'folders' => '',
	'namespace' => 'INBOX.',
	'maildomain' => '',
	'smtphost' => 'localhost',
	'realm' => '',
	'preferred' => ''

Finally, we bring up apache so we can start using webmail.

Code Listing 6.4: Running apache

# nano /etc/conf.d/apache2 
(Uncomment APACHE2_OPTS="-D SSL -D PHP4")
# rc-update add apache2 default
# /etc/init.d/apache2 start

Warning: You should really look into forcing https on users of horde. This isn't a trivial issue, but you should look into it for the sake of security.

To test out the new IMP setup, launch a web browser and visit http://localhost/horde/ (or change localhost with the server you're setting this up on). You should see the Horde welcome page where you can login. Again, in my setup, I simply login with '[email protected]' and 'vappw' as my username and password.

At this point, Horde and IMP are all setup. You should, however, go back through the config directories and tweak each to your heart's content.

7. Extra packages


The first package I would suggest you look into is qmailadmin. It's a web based interface for managing virtual domains. Simply emerge net-mail/qmailadmin and then point your webbrowser to http://localhost/cgi-bin/qmailadmin in order to use it. Makes life a lot easier.


If you run into problems with qmail queues and have a hard time debugging the situation, you may want to look into qmHandle. It's a simple perl program which allows you to view and manage the qmail message queue. Again, all you need to do is emerge net-mail/qmhandle.

horde add ons 

I would highly recommend looking into the many other Horde applications. The Turba, Kronolith, and Nag applications complement IMP very well for instance. Their configuration is similar to that of IMP, so you should have no trouble setting them up. Just remember to edit registry.php in the horde config directory so the new applications show up at the bottom of the horde website.


qmail utilizes ucspi-tcp to handle the incoming connections for qmail. If you wish to customize these filtering rules, then see the configuration files in /etc/tcprules.d/ (older versions of qmail put the files in /etc). There you'll find two files for each service, the configuration file (i.e. tcp.qmail-smtp) and the compiled version of this file that ucspi-tcp uses (i.e. tcp.qmail-smtp.cdb). Whenever you update the configuration file, you'll have to rebuild the binary version of it. Just run tcprules tcp.qmail-smtp.cdb tcp.qmail-smtp.tmp < tcp.qmail-smtp. Every time a connection is made to the qmail service, the compiled rules file is re-read, so there's no need to restart the service.


If you wish to do content filtering on your mail server (spam and virus), then you'll need to use a different queuing program than the default one. One good program for doing so is qmail-scanner. Just emerge net-mail/qmail-scanner and edit the /etc/tcprules.d/tcp.qmail-smtp file.

Important: The build process of qmail-scanner is quite ugly. In order to support packages, they must already be on your system. This means you will have to emerge SpamAssassin and/or Clam AntiVirus before you emerge qmail-scanner. See the relevant following sections for more information.

Code Listing 7.1: Changing the queuer

# cd /etc/tcprules.d/
# nano tcp.qmail-smtp
(Add QMAILQUEUE="/var/qmail/bin/qmail-scanner-queue" to the catchall allow rule)
# tcprules tcp.qmail-smtp.cdb tcp.qmail-smtp.tmp < tcp.qmail-smtp

See the following sections for setting up spam and virus filtering. You may want to set a few custom options by editing /var/qmail/bin/


One of the best Open Source spam filters out there is SpamAssassin. Just emerge mail-filter/spamassassin to install. The package comes in two flavors, a command line version and a client/server version. For servers that will be handling a small amount of mail, running with the command line version is OK, but for anyone whose server will be handling appreciative loads should utilize the client/server version.

Code Listing 7.2: Out-of-the-box setup for SpamAssassin

# nano /etc/mail/spamassassin/
(At the bare minimum, add these options:)
required_hits 6
skip_rbl_checks 1

# rc-update add spamd default
# /etc/init.d/spamd start
# nano /var/qmail/bin/
(Make sure the $spamc_binary variable is set to '/usr/bin/spamc'.)
(If it is set to '', then see the note below.)

Important: If you did not have SpamAssassin on your system before you emerged qmail-scanner, you will have to re-emerge qmail-scanner now. Its build process is pretty ugly and will only add in features for packages it detects on the system at build time.

At this point, incoming mail should be sent through qmail-scanner which will run it through SpamAssassin for you.

Clam AntiVirus 

Like SpamAssassin, Clam AntiVirus comes in two flavors. I'll give you a quick run down on how to quickly setup the client/server version. First, just emerge app-antivirus/clamav.

Code Listing 7.3: Out-of-the-box setup for Clam AntiVirus

# nano /etc/conf.d/clamd 
# nano /etc/clamav.conf
(Setup stuff the way you want it)
# rc-update add clamd default
# /etc/init.d/clamd start
# nano /var/qmail/bin/
(Make sure the $clamscan_binary variable is set to '/usr/bin/clamscan'.)
(If it is set to '', then see the note below.)
# nano /var/qmail/control/conf-common
(If ClamAV reports memory problems try rasing the softlimit)

Important: If you did not have Clam AntiVirus on your system before you emerged qmail-scanner, you will have to re-emerge qmail-scanner now. Its build process is pretty ugly and will only add in features for packages it detects on the system at build time.

At this point, incoming mail should be sent through qmail-scanner which will run it through Clam AntiVirus for you.

8. Final Notes

I have no final notes other than if you experience any troubles with the guide, please contact me or file a bug with Gentoo's Bugtracking Website. If you have some interesting bits you think would enhance this guide, by all means send it my way for inclusion. I love qmail and would gladly add stuff that could possibly enhance a user's experience with the mta.

Updated Sep 10, 2004
Mike Frysinger

Summary:  This document details how to create a mail hosting system based upon qmail, vpopmail, courier-imap, mysql, and horde's imp.
The Gentoo Linux Store
Copyright 2001-2004 Gentoo Foundation, Inc. Questions, Comments, Corrections? Email [email protected].