Virtual mail hosting with qmail

This document details how to create a mail hosting system based upon netqmail, vpopmail, courier-imap, mysql, and horde's imp.

Introduction
Whether you're providing e-mail for just system daemons, a single server, a domain, or for many virtual domains, netqmail can easily be setup to handle your needs. This guide will help you setup netqmail 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 netqmail, courier-imap, vpopmail, and horde/imp. These core packages will also bring in daemontools, ucspi-tcp, mysql, apache, and mod_php. netqmail 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. . Additionally, if you want to use horde/imp for your webmail then you will need  before emerging mod_php.

The last step of course is to commit yourself to the netqmail system. There are many other packages with which you could build your e-mail system. Now is the time to research and decide that netqmail is for you. We have another lovely guide centered around virtual mail hosting that discusses mail server infrastructure. It's up to you to choose the best solution for yourself; it is up to us to show you how to use netqmail.

netqmail (talking to myself)
Emerging netqmail 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 netqmail as a service while ucspi-tcp is responsible for managing the incoming TCP connections to the netqmail service.

First we have a few post-install configuration steps.

The design of netqmail 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'.

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

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

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.

Same but for a 3rd level domain:

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.

If you just emerged mysql for the first time, make sure you run the ebuild  config command and follow the directions before starting the mysql server.

Change the password from 'secret' to 'vpoppw'.

The following steps may or may not be needed, but we run them just to be sure.

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":

While debugging vpopmail, you may want to consult the logs:

Now quickly verify the domain is setup properly.

If you don't see something similar to above, then permissions somewhere are incorrect.

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 netqmail and SMTP.

Courier POP/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.

Set the authmodulelist variable to only contain "authvchkpw".

Edit the [ req_dn ] section.

Edit the [ req_dn ] section.

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 'vapier@wh0rd.org' and password 'vappw'.

If you receive similar errors in the log files: imapd-ssl: LOGIN FAILED, user=vapier@wh0rd.org, ip=[::ffff:123.123.123.123] authdaemond: file not found

Set the authmodulelist variable to only contain "authmysql".

If the file doesn't exist, use authmysqlrc.dist as a template. Check the MYSQL_SERVER, MYSQL_USERNAME, MYSQL_PASSWORD, MYSQL_SOCKET, MYSQL_PORT, MYSQL_DATABASE, DEFAULT_DOMAIN variables. Make sure that you have this line "MYSQL_CRYPT_PWFIELD    crypt"

Add this line (somewhere at the end of the file) MYSQL_SELECT_CLAUSE    SELECT CONCAT(pw_name, '@', pw_domain) AS username, pw_passwd AS cryptpw, '' AS clearpw, '89' AS uid,'89' AS gid, pw_dir AS home, '.maildir' AS maildir, pw_shell AS quota, pw_gecos AS fullname, 'disablewebmail=0,disablepop3=0,disableimap=0' AS options FROM vpopmail WHERE pw_name = '$(local_part)' AND pw_domain = '$(domain)'

If you receive the error message imapd-ssl: Unexpected SSL connection shutdown.

Please try to increase the Softlimit

Change the SOFTLIMIT_OPTS line to SOFTLIMIT_OPTS="-m 32000000"

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

Uncomment the SMTP-AUTH variables and set QMAIL_SMTP_CHECKPASSWORD to /var/vpopmail/bin/vchkpw.

Edit the [ req_dn ] section.

Assuming you haven't tweaked the netqmail control files at all, netqmail will now accept mail for the wh0rd.org virtual domain and for users of the local machine. Furthermore, netqmail 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 'vapier@wh0rd.org' and my password as 'vappw'. The last detail is to make sure you tell your mail client to use SSL/TLS for SMTP communication. netqmail will not let you authenticate if the session is not encrypted.

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.

Now we setup IMP real quick.

Edit the $servers['imap'] array:

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

Uncomment APACHE2_OPTS="-D SSL -D PHP5".

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 'vapier@wh0rd.org' 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.

qmailadmin
The first package I would suggest you look into is qmailadmin. It's a web based interface for managing virtual domains. Simply  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 netqmail 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 netqmail message queue. Again, all you need to do is.

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
netqmail utilizes ucspi-tcp to handle the incoming connections for netqmail. If you wish to customize these filtering rules, then see the configuration files in (older versions put files in  ). 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. Every time a connection is made to the netqmail 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  and edit the  file.

Add QMAILQUEUE="/var/qmail/bin/qmail-scanner-queue" to the catchall allow rule.

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

SpamAssassin
One of the best Open Source spam filters out there is SpamAssassin. Just  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.

At the bare minimum, add these options:

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.

Set START_CLAMD=yes.

Setup stuff the way you want it.

Make sure the $clamscan_binary variable is set to '/usr/bin/clamscan'. If it is set to '', then see the note below.

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.

Final Notes
I have no final notes other than if you experience any troubles with the guide, use the talk page for this article. If you have some interesting bits you think would enhance this guide, by all means suggest them or make the changes. I love netqmail and would gladly add stuff that could possibly enhance a user's experience with the mta.