Gentoo Logo

netqmail/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, 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, vpopmail, dovecot, clamav and spamassassin. These core packages will also bring in daemontools, ucspi-tcp and apache. netqmail provides the core mta functions, dovecot provides remote retrieval services, vpopmail provides virtual domain management, and spamassassin content-based spam filtering.

Important: Before emerging anything, make sure you have USE="ssl qmail-spp" enabled in make.conf. If you've already emerged any of the packages, you may have to re-emerge them.

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

2.  netqmail (talking to myself)

Code Listing 2.1: emerge netqmail

(If you want to use CRAM-MD5 authentication)
# echo mail-mta/netqmail authcram >> /etc/portage/package.use
# emerge '>=mail-mta/netqmail-1.05-r9'

Important: This guide is designed around netqmail-1.05-r9 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 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.

First we have a few post-install configuration steps.

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

(Customize to fit your personal information)
# nano /var/qmail/control/servercert.cnf
# emerge --config netqmail

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

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

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

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

Code Listing 2.4: Start netqmail delivery service

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

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

Code Listing 2.5: Test delivery service

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

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

Although it is very popular to run vpopmail with MySQL, I do not recommend it. It is a lot easier to backup mail and user data without the uglyness of MySQL. If you use the CDB backend (the default) all data you will ever need to backup is /var/vpopmail and /var/qmail. Additionally there can arise a bunch of permission problems with MySQL if you don't pay attention. Bottom line is, using vpopmail without MySQL will save you a lot of time.

Code Listing 3.1: emerge vpopmail

# echo net-mail/vpopmail -mysql maildrop >> /etc/portage/package.use
# emerge '>=net-mail/vpopmail-5.4.19'

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

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 a user account for 'jdoe' while we're here.

Code Listing 3.2: Adding a domain

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

# vadddomain postpass
(Now quickly verify the domain is setup properly)
# printf "\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 jdoepass

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 dovecot and send mail via netqmail and SMTP.

4.  Dovecot IMAP

Code Listing 4.1: emerge dovecot

# echo net-mail/dovecot vpopmail >> /etc/portage/package.use
# emerge '>=net-mail/dovecot-1.0.0'

Important: You must emerge dovecot after vpopmail. That way the vpopmail auth module will be built.

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

Code Listing 4.2: Out-of-the-box setup for dovecot

# nano /etc/dovecot/dovecot.conf
(Include imap if you want to provide non-ssl connections)
protocols = imaps

(Allow access only to vpopmail users)
first_valid_uid = 89
last_valid_uid = 89
first_valid_gid = 89
last_valid_gid = 89

(Hardlinks speed things up a bit)
maildir_copy_with_hardlinks = yes
maildir_copy_preserve_filename = yes

(Get authentication data from vpopmail databases)
auth default {
  mechanisms = plain
  passdb vpopmail {
  userdb vpopmail {
  user = vpopmail

# rc-update add dovecot default
# /etc/init.d/dovecot start

Your mail client should now be able to login to the host running dovecot and retrieve mail for the virtual host. In our case, I am now able to login with the username '' and password 'jdoepass'.

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

Code Listing 5.1: Start netqmail SMTP service

# cd /var/qmail/control/
# nano conf-smtpd
(Uncomment the QMAIL_SMTP_CHECKPASSWORD variable for vchkpw)
# ln -s /var/qmail/supervise/qmail-smtpd /service/qmail-smtpd

Assuming you haven't tweaked the netqmail control files at all, netqmail will now accept mail for the virtual domain and for users of the local machine. Furthermore, netqmail 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 our case, I set the user as '' and my password as 'jdoepass'. 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.

6.  SMTP Plugins (SPP)

qmail-spp adds plugin support to netqmails SMTP daemon (qmail-smtpd). Plugins are external programs which are executed after processing SMTP commands, but just before accepting it by netqmail - this lets you add extra checks on command arguments before accepting it - for instance you can check envelope recipient addresses against vpopmail or sender IP adresses against public real-time blacklist (RBL) servers.

Address Verification

Address verification is a feature that allows the server to block a sender (MAIL FROM) or recipient (RCPT TO) address until the address has been verified to be deliverable. The technique has obvious uses to reject junk mail with an unreplyable sender address.

The technique may also be useful to block mail for undeliverable recipients, for example during a dictionary or brute-force spam attack trying all possible combinations of usernames. This prevents undeliverable junk mail from entering the queue so the server does not have to waste resources trying to send MAILER-DAEMON messages back.

Code Listing 6.1: Sender address verficiation plugin setup

# nano /var/qmail/control/smtpplugins
(Uncomment the following in the [mail] section)

(Uncomment the following in the [rcpt] section)

qmail-smtpd will now reject every delivery attempt that has sent invalid adresses/hostnames in the MAIL FROM command and additionally checks the recipient adress against the vpopmail database.

Real Time DNS Blackhole Lists (DNSBL)

A DNSBL (aka Blocklist, aka ...) is a database of well-known spammer addresses that is queried in realtime by netqmail to proove the message is from a valid destination. Today there exist a lot of DNSBL zones for different needs or policies. Currently i have these zones in active use, as they have proven to be very reliable:

Code Listing 6.2: RBL zone setup for qmail-smtpd

# nano /var/qmail/control/smtpplugins
(Uncomment the following in the [rcpt] section)
:plugins/rblspp -r -r -r

(Restart qmail-smtpd)
# svc -du /service/qmail-smtpd

Note: The ifauthnext plugin ensures no DNSBL checks are done for authenticated users and hosts that are allowed to relay without athentication.

7.  ClamAV and SpamAssassin

Delivery Based Content Filter

Although it is very popular to run content filters like SpamAssassin directly in the queue, this approach has a major disadvantage. Providing that you do not host spammers, it is undesirable to filter outgoing messages just for the sake of wasting resources. By the definition of the delivery based approach no outgoing message is fed through the filters, only incomming messages will be.


Code Listing 7.1: emerge virus scanner

# emerge clamav

The ClamAV virus scanner should work out of the box, but you might want to tweak the location of temporary data. The default is /tmp which may be too small to extract the virus signatures if it is mounted as tmpfs.

Code Listing 7.2: set temporary directory

# nano /etc/clamd.conf
(Change the following line:)
TemporaryDirectory /var/tmp

# rc-update add clamd default
# /etc/init.d/clamd start


Code Listing 7.3: emerge virus and spam filters

# emerge spamassassin

Next we need to setup SpamAssassin. The configuration is easy since defaults are ok for most use cases.

Code Listing 7.4: /etc/spamassassin/

# nano /etc/spamassassin/
(Since most default are ok you only need:)

# this should be low enough to catch enough spam
required_score 5.0

# we don't want the original message to be modified
report_safe 0

# rblspp does this already
skip_rbl_checks 1

# yes, we have working dns
dns_available yes

# nano /etc/conf.d/spamd
(Change SPAMD_OPTS to:)
SPAMD_OPTS="-x -m 5 -i -A -u vpopmail -g vpopmail"

# rc-update add spamd default
# /etc/init.d/spamd start


Next thing is to create a global maildrop filter configuration. During delivery qmail will export the environment variable $EXT and $HOST which can be used together with vuserinfo to figure out the correct maildir directory.

Below is a sample maildrop configuration. You should read the mailfilter manual to adapt it to your needs.

Code Listing 7.5: /etc/maildroprc

# Global maildrop filter file

# get EXT@HOST parts from qmail
import EXT
import HOST

# uncomment if you want to enable logging
#logfile "/var/log/maildrop.log"

log "=== BEGIN maildrop processing for $EXT@$HOST ==="

# get home directory
VHOME=`/var/vpopmail/bin/vuserinfo -d $EXT@$HOST`
if ($VHOME eq "")
        log "VHOME ist empty, can't deliver"
        to "| /var/qmail/bin/bouncesaying 'cannot deliver to $EXT@$HOST: no such file or directory"

# create necessary folders
`test -d $VHOME/.maildir`
if ($RETURNCODE == 1)
        log "Maildir does not exist, but i will create it for you"
        `/var/qmail/bin/maildirmake $VHOME/.maildir`

`test -d $VHOME/.maildir/.Spam`
if ($RETURNCODE == 1)
        log "Spam folder does not exist, but i will create it for you"
        `/var/qmail/bin/maildirmake $VHOME/.maildir/.Spam`
        `echo Spam >> $VHOME/.maildir/subscriptions`

# check for virii first
xfilter "/usr/bin/clamdfilter"
if ($RETURNCODE == 1)
        log "=== END: VIRUS found, deleting"
        to "/dev/null"

# filter mail with spamassassin
xfilter "/usr/bin/spamc"
if (/^X-Spam-Flag: Yes.*$/)
        log "=== END: SPAM caught with spamassassin, moving to Spam folder ==="
        to "$VHOME/.maildir/.Spam/"

# include custom filter script
`test -r $VHOME/.mailfilter`
if ($RETURNCODE == 0)
        log "Including custom mailfilter from $VHOME/.mailfilter"
        exception {
                include $VHOME/.mailfilter

log "=== END: delivery to INBOX at $VHOME ==="
to "$VHOME/.maildir/"

Since clamav does not provide a filter program, put the following in /usr/bin/clamdfilter and make it executable:

Code Listing 7.6: /usr/bin/clamdfilter



echo "${MSG}" | /usr/bin/clamdscan --quiet -

if [[ $? -eq 1 ]]; then
        MSG=$(echo "${MSG}" | reformail -i "X-Virus-Status: INFECTED")
        MSG=$(echo "${MSG}" | reformail -i "X-Virus-Status: CLEAN")

echo "${MSG}"
exit 0

8.  Extra packages

ezmlm-idx - Mailing list manager

ezmlm-idx is an add-on to ezmlm, the qmail mailing list manager. It adds multi-message threaded message retrieval from the archive, digests, message and subscription moderation, and a number of remote administration function. ezmlm-idx is also supported qmailadmin (see below).

Code Listing 8.1: emerge ezmlm-idx

(Just to be sure ...)
# echo net-mail/ezmlm-idx -mysql -pgsql >> /etc/portage/package.use
# emerge ezmlm-idx

ezmlm-idx will work out-of-the-box though creating new mailing lists on the command line is not simple. I recommend to use qmailadmin (see below) to create new mailing lists.

qmailadmin - Web-based administration

The popular web-based administration package for netqmail/vpopmail is qmailadmin and can be used by any mail user for account configuration. Additionally administrators (postmaster by default) can create new mail accounts, lists and much more.

Note: This guide assumes you do not have USE="vhosts". If you do have, you are on your own.

Code Listing 8.2: emerge qmailadmin

# echo net-mail/qmailadmin maildrop >> /etc/portage/package.use
# emerge apache qmailadmin

(Now start apache)
# rc-update add apache2
# /etc/init.d/apache2 start

Open your favorite browser and point it to http://localhost/cgi-bin/qmailadmin.

qmHandle - qmail queue helper

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.

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


Page updated January 2, 2008

Summary: This document details how to create a mail hosting system based upon netqmail, vpopmail, dovecot, spamassassin, and roundcube webmail.

Mike Frysinger

Benedikt Boehm

Donate to support our development efforts.

Copyright 2001-2014 Gentoo Foundation, Inc. Questions, Comments? Contact us.