netqmail/vpopmail Virtual Mail Hosting System Guide
This document details how to create a mail hosting system based upon netqmail,
vpopmail, courier-imap, mysql, and horde's imp.
22010-11-14Introduction

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

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

netqmail (talking to myself)

# emerge mail-mta/netqmail

This guide is designed around netqmail-1.05-r4 or later. Will it work with
earlier versions? Maybe. Should you upgrade? Yes, if you want to be sure this
guide will work.
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 netqmail -p.

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.

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

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.

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, netqmail
utilizes the output of hostname --fqdn. If, on your machine, this
returns 'localhost', then check your /etc/conf.d/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.

This guide is designed around vpopmail-5.4.6 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.

# rc-update add mysql defaultIf 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

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

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

# emerge net-mail/courier-imap

You must emerge courier-imap after vpopmail. That way the authvchkpw module
will be built.
This guide is designed around net-mail/courier-imap-3.0.7 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.

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

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.

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.

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

Extra packagesqmailadmin

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

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
/etc/tcprules.d/ (older versions put 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 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 emerge qmail-scanner and edit the
/etc/tcprules.d/tcp.qmail-smtp file.

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.

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

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.

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.

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 netqmail and would gladly add stuff that
could possibly enhance a user's experience with the mta.