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.

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)

# emerge qmail

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.

(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'.

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

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

# ssh vapier@localhost
# maildirmake .maildir
# qmail-inject root << EOF
test root e-mail!
EOF
# qmail-inject postmaster << EOF
test postmaster e-mail!
EOF
# qmail-inject vapier << EOF
test vapier e-mail!
EOF
# 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.

# hostname --fqdn
wh0rd.org
# cat me
wh0rd.org
# cat defaultdomain
wh0rd.org
# cat plusdomain
wh0rd.org
# cat locals
wh0rd.org
# cat rcpthosts
wh0rd.org

# hostname --fqdn
mail.wh0rd.org
# cat me
mail.wh0rd.org
# cat defaultdomain
wh0rd.org
# cat plusdomain
wh0rd.org
# cat locals
mail.wh0rd.org
# cat rcpthosts
mail.wh0rd.org

3. vpopmail

# emerge vpopmail

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.

# 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 vpopmail@localhost identified by 'vpoppw';
flush privileges;
EOF
(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

At this point in time, vpopmail is ready to roll. In this guide, we will be providing virtual hosting for the domain 'wh0rd.org'. 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.

(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 wh0rd.org 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

# emerge net-mail/courier-imap

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.

# 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

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

# 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 wh0rd.org virtual domain and for users of the local machine. Furthermore, qmail will relay mail for anyone who sends via 127.0.0.1 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.

# emerge horde-imp

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.

# 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

Now we setup IMP real quick.

# 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' => 'wh0rd.org',
	'server' => 'localhost',
	'protocol' => 'imap/ssl/novalidate-cert',
	'port' => 993,
	'folders' => '',
	'namespace' => 'INBOX.',
	'maildomain' => 'wh0rd.org',
	'smtphost' => 'localhost',
	'realm' => '',
	'preferred' => ''
);

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

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

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

qmailadmin 

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.

qmHandle 

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.

ucspi-tcp 

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.

qmail-scanner 

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.

# 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/qmail-scanner-queue.pl.

SpamAssassin 

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.

# nano /etc/mail/spamassassin/local.cf
(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/qmail-scanner-queue.pl
(Make sure the $spamc_binary variable is set to '/usr/bin/spamc'.)
(If it is set to '', then see the note below.)

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.

# nano /etc/conf.d/clamd 
(Set START_CLAMD=yes)
# 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/qmail-scanner-queue.pl
(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)

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.