This document gives instructions on how to install, configure, and run qmail on
a system running Gentoo Linux. I originally wrote this after I could not find
any qmail documentation specific to Gentoo, despite Gentoo offering packages
(or "ebuilds", to use Gentoo's terminology) for qmail and related software.
You are probably not reading this if you are not familiar with Gentoo Linux,
but just in case, Gentoo is a relatively new distribution that aims at striking
a compromise between the convenience and compatibility of a linux installation
based on ready-made software packages, and the power and configurability of a
linux installation built from source. For more details, visit Gentoo's website
(http://www.gentoo.org). Gentoo's promise of being able to tailor software
exactly to a system's specifications, while at the same time having a package
manager easily keep track of it all, is what attracted me to this distribution,
to say nothing of the recommendations I received from friends and coworkers.
You are probably also not reading this if you have not heard of qmail, but to
be thorough, Daniel J. Bernstein's qmail is an email server software package,
providing the same general functionality of packages like Sendmail or ssmtp.
qmail is undebatably the most secure email server software available for
Unix-compatible operating systems, and I would argue that it is the most secure
email server software period. qmail also provides plenty of configurability,
enough to suit the needs of almost any email-related task. The fact that qmail
has not had an official release since 1997, and yet continues to grow in
popularity without a single security alert, is testimony of its quality. qmail
is not for the faint of heart, however. Even with a versatile package manager
like Gentoo's Portage, qmail requires some manual intervention, not to mention
firm knowledge of what you are doing, to run optimally.
Things to Know before Starting
These instructions were written using Gentoo Linux 1.4, installed following
the distributors' instructions, and the qmail ebuild provided by Gentoo
through its package manager, Portage. As of this writing, the recommended
Gentoo ebuild for qmail is 1.03-r13. There may be instructions here that are
specific to these versions; in particular, earlier versions of the qmail
ebuild are significantly different from 1.03-r13, and I do not recommend
trying to use this guide with them. Also, Gentoo and Portage are highly
customizable, and experienced Gentoo users who have heavily tweaked their
systems may find these instructions completely off base.
The qmail ebuild is modeled on the process prescribed by "Life with qmail"
(LWQ, http://www.lifewithqmail.org), written by Dave Sill. LWQ is *required*
reading; the instructions given here mostly highlight the differences between
LWQ and the qmail ebuild, as well as the manual steps needed to complete
qmail's installation and configuration.
Gentoo's qmail ebuild includes several patches to the original source code.
These patches fix minor, non-critical bugs, and also provide additional
features not present in the author's distribution of qmail 1.03, such as the
ability to encrypt SMTP sessions with SSL, and the ability to authenticate
sessions with passwords unique to each user on your system.
(NOTE: The current version of LWQ makes use of a package called netqmail.
netqmail 1.05 is a patched version of qmail 1.03. Bugs and incompatibilities
fixed by netqmail 1.05 are also fixed by Gentoo's 1.03-r13 ebuild for qmail,
and therefore LWQ is still an essential source of information, even for Gentoo
IMPORTANT: qmail, as well as any software package written in the C
programming language, relies on a package called glibc to provide the basic
C function libraries. As of this writing, Gentoo's recommended glibc ebuild
is version 2.3.2-r9. Because of an old coding method that is no longer
supported by the authors of glibc, all qmail ebuilds older than 1.03-r10 (as
well as the unpatched source code for qmail 1.03) ARE NOT COMPATIBLE with any
ebuilds based on glibc 2.3.2! To ensure smooth installation, make sure you
are using the latest unmasked ebuilds of qmail and all software packages
qmail depends on (including daemontools, ucspi-tcp, checkpassword,
cmd5checkpw, dot-forward, and queue-fix; more information about these packages
is provided below.)
Part One - Configuring Gentoo to Allow qmail's Installation
Before you can install qmail, you may need to configure Gentoo to allow you
to do so. This requires knowing a few things about Gentoo and Portage.
One of Portage's features is the ability to keep track of "virtual" packages.
Virtual packages are not specific software packages, but are definitions
that can be matched by any Gentoo ebuild claiming to do so. When you install
(or "merge") an ebuild that matches the definition of a virtual package,
Portage considers that virtual package present on your system.
Gentoo keeps a list of default ebuilds it will use to satisfy virtual package
needs. An ebuild from this list is merged whenever the associated virtual
package is requested and a matching ebuild is not already present. Many of
these ebuilds are added to the system during Gentoo's initial set-up.
Much of Gentoo's behavior is governed by a set of configuration files
collectively known as a "profile." Included in a profile is the default list
for satisfying virtual package requirements. Regardless of what profile you
use, you can look at the associated files in /etc/make.profile. Editing
these files is not a good idea, unless you are planning on building your own
profiles for distribution.
Besides the default list supplied by a profile, Gentoo also keeps a list of
virtual packages actually present on your system, and the ebuilds that
represent those virtual packages. Gentoo keeps this list in the file
/var/cache/edb/virtuals. Whenever you merge an ebuild that satisfies the
requirements for a virtual package, that virtual package's entry is created
or updated in /var/cache/edb/virtuals.
Gentoo ebuilds can be designed to block their own installation if they would
conflict with other software already present on the system. These blocks can
be based on virtual packages as well as specific ebuilds.
Gentoo controls the presence of an email server (or, more accurately, a "mail
transfer agent") with the virtual package "virtual/mta". Gentoo's qmail ebuild
is a virtual/mta package, but of course it is not the only one. If you
followed all instructions for installing Gentoo, ssmtp will be present on your
system, and will be listed in /var/cache/edb/virtuals. Because most systems
really only need one mail transfer agent, the ebuilds for ssmtp, qmail, and
other MTAs will block installation if a virtual/mta package is already present.
So, if ssmtp or some other virtual/mta package is already installed on your
system, you will need to allow qmail to be installed on your system. There are
two good ways of doing this:
1. Uninstall the virtual/mta package currently on your system. Any
configuration you may have performed to run the current MTA on your
system, such as having it start automatically during system boot, will
need to be undone prior to removal.
2. Edit the qmail ebuild script to remove the virtual/mta block. For
version 1.03-r13, the ebuild script is usually kept at
/usr/portage/net-mail/qmail-1.03-r13.ebuild. The edit involves finding
the two lines that look like this:
and replacing them with this one line:
#2 is the recommended choice, as other components of your system may complain
about the sudden lack of a virtual/mta package. It is safe to keep your
current MTA while installing and configuring qmail, as long as you do not try
to run both MTAs at the same time.
Once you have removed any currently installed virtual/mta packages, or have
modified the qmail ebuild script, you will be ready to install qmail.
IMPORTANT: Before you can emerge qmail and related ebuilds, you must also
have the right system users and groups on your system. You will need users
named "alias", "qmaild", "qmaill", "qmailq", "qmailr", and "qmails", and groups
named "nofiles" and "qmail". Also, the alias user's home directory must be set
to /var/qmail/alias. Normally this is all taken care of during Gentoo's
installation, specifically, when the baselayout package is emerged. If you
have since edited your users and groups files, removing entries you believed
were unnecessary, make sure you have the right users and groups before
Part Two - Installing and Configuring qmail and Related Software
Thanks to Portage and the "emerge" command, all of the software required for
running qmail is installed with a single command. However, keep in mind that
the authors of Gentoo recommend you always run emerge with the "pretend" flag
prior to installing any new packages, so that you know for certain what is
about to be installed on your system.
# emerge -p qmail
These are the packages that I would merge...
(NOTE: The 1.03-r13 qmail ebuild uses one USE flag, "ssl". You must set this
USE flag, either in /etc/make.conf or in your shell's USE environment
variable, if you want to install qmail with encrypted SMTP support. More
information about encrypted SMTP is in appendix B.5)
Depending on what you already have available, you will see a number of
ebuilds that Portage would merge along with qmail. Most likely you will see
"ucspi-tcp", "daemontools", "dot-forward", "checkpassword", "cmd5checkpw", and
"queue-fix" in this list. Except for "cmd5checkpw" and "queue-fix", these are
additional tools written by Bernstein, designed to provide a stable, easily
configurable environment for qmail. "ucspi-tcp" and "daemontools" in
particular are required packages for a qmail installation that conforms to LWQ,
and Gentoo's default configuration appropriately defines qmail as dependent on
(NOTE: "cmd5checkpw" is used to offer authenticated SMTP; see appendix B.3 for
more information. "queue-fix" is used to initially create the qmail queue,
that is, the folders qmail uses to temporarily store email that is being
processed; it can also be used to repair or recreate the queue when needed.)
Once you are satisfied in knowing what is going to be added to your system,
run emerge again without the "pretend" flag.
# emerge qmail
When this command finishes, the system will be almost ready. Portage not only
installs qmail and all related software, but also performs a number of
necessary system configurations, and installs several scripts documented in LWQ.
Gentoo's qmail ebuild includes an option that allows for some additional
automatic configuration. In fact, this extra configuration will be enough for
qmail to run securely and effectively on many systems. However, while I
recommend taking advantage of this option to prevent any security checkpoints
from being accidentally overlooked, this feature should not be considered a
substitute for following the rest of this guide, especially if qmail is to be
used in a production environment. To perform the additional automatic
configuration, run this command:
# ebuild /var/db/pkg/net-mail/qmail-1.03-r13/qmail-1.03-r13.ebuild config
If run, the above command will look up the machine's fully qualified domain
name, and set up qmail to treat as local any email bound for this name
specifically. For example, if the fully qualified domain name is
machine.example.com, qmail will process for local delivery any email bound for
addresses ending in "@machine.example.com" (but not "@example.com"). qmail
will also be set up to allow SMTP (mail transport) connections from anywhere.
For local connections, all email will be accepted, and any email not
destined for local delivery will be directed (or "relayed") to the appropriate
destination. For all other connections, only email destined for local delivery
will be accepted. These configurations may not be exactly what you want, so
continue reading to learn how to configure qmail to suit your needs.
(NOTE: Running the above ebuild command will also generate a self-signed SSL
certificate for use with encrypted SMTP. See appendix B.5 for more
information. If you plan on making use of encrypted SMTP, first edit
/var/qmail/control/servercert.cnf, particularly the values in the "req_dn"
section, before running the above ebuild command. This will ensure your new
SSL certificate contains the correct information for your system. Remember
that qmail needs to be emerged with the "ssl" USE flag for encrypted SMTP to
From this point, follow LWQ starting with section 2.7. Refer to the
instructions below for Gentoo-specific notes related to each section.
2.7. daemontools has already been installed by Portage by this point,
however, the daemontools ebuild does not change /etc/inittab. Instead,
the ebuild provides an rc script for svscan in /etc/init.d. To ensure
that svscan will start during system boot, use Gentoo's rc-update command
to link the svscan rc script within the appropriate runlevel directory
or directories. If you plan on running qmail from the default runlevel,
enter this command:
rc-update add svscan default
Note that starting svscan from an rc script does not protect it from
unexpected termination. If you would like to take advantage of init's
ability to recreate processes that have died, do *not* use Gentoo's rc
script for svscan. Instead, edit /etc/inittab, adding this line:
Note that the ebuild uses a different directory for daemontools'
executables than the author's original package.
2.8.1. The qmail ebuild supplies a /var/qmail/rc script and a
/var/qmail/control/defaultdelivery control file similar to the ones
given in LWQ. In the Gentoo ebuild versions, comments are allowed in
/var/qmail/control/defaultdelivery; any line starting with "#" will be
The ebuild configures qmail to use maildirs, however, note that the name of
each user's maildir directory is slightly different than that given in LWQ
(".maildir/" instead of "Maildir/").
22.214.171.124. The qmail ebuild does not provide the /var/qmail/bin/qmailctl
script. Instead, a script named qmail-control is created and placed in
/var/qmail/bin. qmail-control allows for qmail's services to be stopped
and started, and for the locals and virtualdomains control files (see
below) to be reread. qmailctl offers the same functionality and more,
providing an easy, convenient alternative to remembering several different
commands. So, while creating /var/qmail/bin/qmailctl as documented in this
section of LWQ is not necessary, it is highly recommended.
The comments for Red Hat Linux's chkconfig tool are not needed. PATH
does not have to include /usr/local/bin or /usr/local/sbin; these
directories are empty on a typical Gentoo system.
126.96.36.199. Gentoo's qmail ebuild creates all the necessary supervise
scripts that are documented in this section of LWQ.
/var/qmail/supervise/qmail-smtpd/log/run, as created by the qmail ebuild,
are slightly different than those given by LWQ. The difference enables the
multilog program to rotate the log files of qmail-send and qmail-smtpd when
they reach approximately 2.5MB in size, instead of the default 100kB.
(NOTE: See http://cr.yp.to/daemontools/multilog.html for more information
about how multilog maintains log files.)
/var/qmail/supervise/qmail-smtpd/run as provided by the ebuild is very
different from the one presented in LWQ. Generally speaking, version
1.03-r13 of the qmail ebuild was designed so that qmail's functionality
could be changed entirely with configuration files, removing the need for
manipulating any qmail-related scripts or programs. In particular,
the Gentoo version of /var/qmail/supervise/qmail-smtpd/run relies on the
Gentoo-specific control files /var/qmail/control/conf-common and
/var/qmail/control/conf-smtpd for configuring qmail's SMTP service.
Editing these files is not essential for basic qmail and SMTP
functionality, and is also not recommended for those installing qmail for
the first time. Once you are comfortable with how qmail operates, and
would like to take advantage of features like authenticated SMTP or spam
blacklisting, you can edit these configuration files to suit your needs.
See appendix B for more information about editing the
/var/qmail/control/conf-common and /var/qmail/control/conf-smtpd
Creating the concurrencyincoming control file is optional. You can use
this file for setting the maximum number of concurrent connections allowed,
or instead edit the appropriate section of /var/qmail/control/conf-common.
If neither action is taken, qmail will limit the number of possible
concurrent incoming SMTP connections to 40.
All log files under /var/log already exist by this point, as does the
/service directory. You will need to create the symbolic links within the
/service directory. Note that qmail will *not* start automatically after
these links are created, *unless* svscan is running (see the notes above for
LWQ section 2.7).
188.8.131.52. This section is not necessary if you used the optional "emerge"
command for extra automatic configuration, described above. Otherwise,
perform the steps in this section as given. Note that this section
expects you to have created the /var/qmail/bin/qmailctl script given in LWQ
2.8.3. If you haven't done so already, now is a good time to remove any
other virtual/mta packages from your system. For example, you can run these
commands to remove ssmtp:
emerge -C mailbase
emerge -C ssmtp
Note that you should first undo any configuration you may have performed to
run another email server on your system, such as having it start
automatically during system boot.
If qmail services began running while another virtual/mta package was still
being utilized, stop qmail as documented in this step. You can use the
qmail-control script to do so if you decided not to create qmailctl.
The "sendmail" symbolic links will already exist by this point.
2.8.4. The qmail ebuild creates all of the .qmail files under
/var/qmail/alias mentioned in this section. The .qmail files are empty,
which means any email bound for the affected addresses will be directed to
user alias's maildir. If this is not the behavior you want, follow LWQ's
instructions for editing these files.
2.8.5. Again, svscan should be running before you try to start (or
restart) qmail using qmailctl (or qmail-control). See the notes for LWQ
section 2.7 above.
2.9. Perform these steps as given to test your new installation.
Now follow the instructions given in LWQ section 3 to fully configure qmail to
your liking. If you performed the optional configuration discussed above, a
number of control files documented in LWQ section 3.1 will already exist by
Each of these files will contain a single line, the fully qualified domain
name of the machine.
Gentoo's installation of qmail allows for several extra control files in
addition to those documented in LWQ section 3.1 They are described below:
Control Default Used by Description
badmailto (none) qmail-smtpd blacklisted To addresses
badrcptto (none) qmail-smtpd blacklisted To addresses
conf-common as given various configuration common to all
of qmail's network services
conf-pop3d as given qmail-pop3d configuration specific to
qmail's POP3 service
conf-qmqpd as given qmail-qmqpd configuration specific to
qmail's QMQP service
conf-qmtpd as given qmail-qmtpd configuration specific to
qmail's QMTP service
conf-smtpd as given qmail-smtpd configuration specific to
qmail's SMTP service
morebadrcptto (none) qmail-smtpd more blacklisted To addresses
Also, regular expressions can be used in badmailfrom and badmailto.
(NOTE: Yes, badmailto and badrcptto provide essentially the same
functionality. That's what happens when a lot of different patches are used to
make a program as functional and configurable as possible.)
(NOTE: QMTP, the Quick Mail Transfer Protocol, is an alternative to SMTP,
designed by qmail's author. QMTP is not compatible with SMTP, nor is it widely
used across the Internet. If you wish to read more about QMTP, have a look at
LWQ section 5.11, and also Daniel Bernstien's documentation for QMTP
(http://cr.yp.to/proto/qmtp.txt). More information about QMTP will be in a
future revision of this guide.)
(NOTE: QMQP, the Quick Mail Queueing Protocol, was designed by qmail's author
to allow multiple servers running qmail to pool their messages into a single
queue on a centralized server. The outlying servers run a special configuration
of qmail called "mini-qmail" and use QMQP to send their messages to the central
server. Bernstien has documentation for mini-qmail
(http://cr.yp.to/qmail/mini.html) and QMQP (http://cr.yp.to/proto/qmqp.html).
More information about these features will be in a future revision of this
(NOTE: The optional configuration discussed above will also create files
"clientcert.pem", "rsa512.pem", and "servercert.pem" in /var/qmail/control.
These files are your self-signed SSL certificate and are necessary for
encrypted SMTP; more information about them is provided in appendix B.5. They
can be safely ignored if you do not plan on using encrypted SMTP, or if you
did not emerge qmail with the "ssl" USE flag enabled.)
Part Three - After qmail Is Up and Running
Some tips for smooth operation and extended functionality.
* By default, Portage's "config file protection" extends to qmail's
configuration directory, /var/qmail/control. This feature prevents qmail's
configuration from being blindly overwritten by any future upgrades or
removals. Run "emerge -h config" for more information.
* Assuming you kept the default delivery instructions provided by Gentoo
(/var/qmail/control/defaultdelivery), each user on your system will need
a maildir named ".maildir" in his or her home directory. See LWQ section
4.1.3 for more information.
* Refer any users on your system to LWQ section 4 for information on how to
exert control over their incoming email.
* LWQ section 5.2.1 provides information on how to install and configure
the POP3 server that comes with qmail. If you decide to use this POP3
server (qmail-pop3d), read through the steps given in LWQ section 184.108.40.206.
If the standard checkpassword program meets your needs, then steps 1
through 6 will already have been performed by the Gentoo qmail ebuild by
this point. The supervise scripts set up by the ebuild for POP3
service are different from those given in LWQ, and the differences are
similar to those described above for qmail-smtpd.
/var/qmail/supervise/qmail-pop3d/run is designed to read configuration from
/var/qmail/control/conf-common and /var/qmail/control/conf-pop3d.
Modifying these configuration files is not necessary for standard POP3
functionality, and not recommended for those running POP3 service for the
first time. Once you are familiar with how qmail's POP3 service operates,
you can change these files to take advantage of features like alternative
password checking programs, and POP-before-SMTP authentication. Appendix B
provides more information about how to edit the configuration files, if you
decide to do so.
When you are ready to offer POP3 service, run the following command to allow
svscan to automatically start and supervise the qmail-pop3d process:
ln -s /var/qmail/supervise/qmail-pop3d /service
(NOTE: Gentoo used to provide a separate ebuild called qmail-pop3d that
would install the necessary scripts for running qmail's POP3 server. The
current qmail ebuild provides the same functionality, therefore the
qmail-pop3d ebuild is no longer necessary.)
If you created the /var/qmail/bin/qmailctl script discussed in LWQ section
220.127.116.11, follow steps 7 through 12 to add features related to qmail-pop3d.
If you decided to keep the /var/qmail/bin/qmail-control script instead, it
is already capable of starting and stopping qmail-pop3d.
If svscan is currently running, POP3 service should now be available.
* Portage merges the dot-forward ebuild along with qmail. dot-forward
allows people to create delivery instructions using Sendmail's format.
Custom delivery instructions for Sendmail are usually kept in files named
".forward", hence this package's name. See LWQ appendix B.1 for more
Conclusion - Any Questions?
Your qmail server should now be ready for action. However, you may still
have some questions or concerns.
If you are using Gentoo without many customizations, and you have a concern
about qmail's installation as performed by Portage, contact the maintainers
of Gentoo, as they wish to be notified of any problems with their ebuilds.
Their policy is to investigate the problem, and then notify the original
software authors themselves if they determine the cause lies there. Visit
Gentoo's bug page (http://bugs.gentoo.org) for more information.
If you have successfully installed qmail, but now you have a question about
its performance and/or your configuration, the qmail mailing list is the
place to ask experienced qmail users for information. However, please keep
in mind these are people giving of their free time, and they are very tired
of reading the same questions over and over. I cannot emphasize this enough:
READ THE DOCUMENTATION and, if appropriate, CHECK YOUR LOGS before asking a
question on the list. LWQ, the qmail man pages, the web pages maintained by
qmail's author at http://cr.yp.to, and especially the qmail mailing list
archives (http://www.ornl.gov/cts/archives/mailing-lists/qmail/) are all
excellent sources of information, and many list veterans consider all of
these to be required reading. Should you decide a question to the list is
necessary, list veteran Charles Cazabon has written "12 Steps to qmail List
detailing what every list veteran would like to see happen when somebody has
a question about qmail.
If you have a question or comment about this guide in particular, feel free
to email me at firstname.lastname@example.org.
Appendix A - The qmail Program Chain
This section briefly describes how the various qmail programs are set up, and
how they interact with one another to provide qmail's services. Understanding
these interactions is essential if you plan on modifying your qmail
installation to take advantage of additional features, such as those described
in appendix B. This section does not go into much detail, and is also somewhat
specific to the way qmail is installed and configured on Gentoo systems. For a
better and more general understanding of why and how these programs interact
the way they do, you are encouraged to read the referenced documentation.
The svscan init script (/etc/init.d/svscan) is used to start all of qmail's
services. First, an svscan (http://cr.yp.to/daemontools/svscan.html) process
is created. For every symbolic link created within the /service directory,
svscan then creates and monitors two supervise
(http://cr.yp.to/daemontools/supervise.html) processes. The second supervise
process creates and monitors a multilog
(http://cr.yp.to/daemontools/multilog.html) process, which will feed the output
of the first supervise process into a log file. The first supervise process's
activity depends on the service.
For qmail-send, supervise executes and monitors the /var/qmail/rc script. By
default, this script in turn executes qmail-start, which in turn creates all
the processes in charge of processing qmail's message queue. These processes
include qmail-send, qmail-clean, qmail-lspawn, and qmail-rspawn. Man pages are
available for these four programs, and for qmail-start.
For qmail-smtpd, supervise creates and monitors a softlimit
(http://cr.yp.to/daemontools/softlimit.html) process, designed to limit the
use of system resources and prevent runaway processes. softlimit in turn
creates a tcpserver (http://cr.yp.to/ucspi-tcp/tcpserver.html) process,
configured to listen for SMTP connections. For every SMTP connection
received, tcpserver creates a qmail-smtpd process to handle that connection.
A man page is available for qmail-smtpd.
For qmail-pop3d, supervise creates and monitors a softlimit process, which in
turn creates a tcpserver process configured to listen for POP3 connections.
For every POP3 connection received, tcpserver creates a qmail-popup process to
handle that connection. qmail-popup displays to the connecting client a POP3
greeting, then prompts for a login name and password. qmail-popup then
executes a password checking program to verify the login name and password.
If the login name and password are valid, the password checking program will
then create a qmail-pop3d process to further handle that connection;
otherwise, the password checking program will exit, causing the connection to
be dropped. Man pages are available for qmail-popup and qmail-pop3d.
(NOTE: If you followed the instructions for adding svscanboot to /etc/inittab,
svscanboot (http://cr.yp.to/daemontools/svscanboot.html) will be executed
during system boot, which in turn will create the svscan process.)
Appendix B.1 - qmail Network Service Configuration
This section explains the environment variables that can be defined in
/var/qmail/control/conf-common, /var/qmail/control/conf-smtpd, and
/var/qmail/control/conf-pop3d. The values of these variables are in turn used
by /var/qmail/supervise/qmail-smtpd/run and
This section assumes an understanding of how the various programs interact to
provide qmail's services; see appendix A for an overview.
The configuration files provide default definitions for most of these
variables. The defaults will be enough for many qmail users' needs.
Appendices B.2 through B.5 provide examples of how the configuration files can
be changed to enable certain features in qmail. I *strongly* recommend leaving
these files alone until you are confident about what you are doing.
/var/qmail/control/conf-common provides definitions that affect all of qmail's
network services. /var/qmail/control/conf-smtpd and
/var/qmail/control/conf-pop3d provide definitions that will affect only SMTP
and POP3 services, respectively. Except where noted, these environment
variables can be defined in conf-common or in a specific network service's
configuration file. A definition in a specific network service's configuration
file will override any definition of that variable in conf-common, unless the
previous definition is incorporated into the new definition.
The maximum number of concurrent connections that tcpserver will allow.
If unset, tcpserver will use its internal default of 40. Normally, this
value is read from /var/qmail/control/concurrencyincoming.
The GID of the system group that will run the tcpserver processes in charge
of providing qmail-related network services.
The directory for qmail's control files. This will almost always be
/var/qmail/control. This variable is also defined in an /etc/env.d
configuration file, so defining it again is really not necessary.
Specific to POP3. This variable defines the program that will be executed
to verify a POP3 login's name and password. It is assumed that this
program provides the standard checkpassword interface, described at
http://cr.yp.to/checkpwd/interface.html, and further assumed that this
program can execute qmail-pop3d when a login name and password have been
Specific to POP3. This variable defines the name of the machine that
qmail's POP3 service will identify as its host. By default, this is read
Specific to POP3. Normally, the password checking program defined by
QMAIL_POP3_CHECKPASSWORD will execute qmail-pop3d when a login name and
password have been successfully verified. If this variable is defined, the
password checking program will instead execute the program or string of
programs given by this variable. It is assumed that qmail-pop3d and its
command-line arguments can be passed as the final command-line arguments of
this program chain.
Specific to POP3. After accepting a POP3 connection, tcpserver will
normally execute qmail-popup to provide the initial POP3 greeting and
password prompt to the connecting client. If this variable is defined,
tcpserver will instead execute the program or string of programs given by
this variable. It is assumed that qmail-popup and its command-line
arguments can be passed as the final command-line arguments of this program
Specific to SMTP. This variable provides command-line arguments to execute
Specific to SMTP. After accepting an SMTP connection, tcpserver will
normally execute qmail-smtpd to provide SMTP service to the connecting
client. If this variable is defined, tcpserver will instead execute the
program or string of programs given by this variable. It is assumed that
that qmail-smtpd and its command-line arguments can be passed as the final
command-line arguments to this program chain.
Normally, softlimit will execute tcpserver. If this variable is defined,
softlimit will instead execute the program or string of programs given by
this variable. It is assumed that tcpserver and its command-line arguments
can be passed as the final command-line arguments to this program chain.
The UID of the system user that will run the tcpserver processes in charge
of providing qmail-related network services.
Command-line arguments to execute softlimit with. See
http://cr.yp.to/daemontools/softlimit.html for more information about the
The IP address tcpserver will listen for connections on.
Command-line arguments to execute tcpserver with, in addition to
-x, -c, -u and -g. See http://cr.yp.to/ucspi-tcp/tcpserver.html for more
information about the options available.
The specific port of the IP address defined by TCPSERVER_HOST that
tcpserver will listen for connections on. This can be defined in the
configuration file specific to each network service, however, conf-common
as installed by the qmail ebuild will set the value of this variable equal
to that of the SERVICE environment variable. SERVICE is defined by each
network service's supervise script, "smtp" for SMTP, "pop3" for POP3, and
so on. For this to work, these services need to be defined with port
numbers in /etc/services.
Normally, qmail pipes all messages through a program called "qmail-queue."
qmail-queue's task is to place each message into qmail's message queue,
where later it will be picked up by qmail-send for further processing and
delivery. This environment variable, which by default is not set, allows
another program to take the place of qmail-queue, providing the opportunity
for additional processing on each message before it is placed in the queue.
See http://www.qmail.org/qqrbl for one example of a replacement qmail-queue
program. Note: You better know what you are doing if you wish to take
advantage of this feature. If you do not replace qmail-queue with a
program that provides at least the same functionality, you will break your
Appendix B.2 - Authenticated SMTP
Gentoo's installation of qmail allows SMTP sessions to be authenticated with
the ESMTP AUTH command. This permits you to restrict relaying priveleges to
people who have correct user names and passwords, instead of people who connect
from certain IP addresses (the two methods can also be used together). The
ESMTP AUTH command was designed to support different methods of password
verification, and this implementation provides the three most popular methods:
PLAIN, LOGIN, and CRAM-MD5. This makes qmail's authentication feature
compatible with most email clients currently available.
To enable authenticated SMTP, the QMAIL_SMTP_POST environment variable in
the conf-smtpd control file needs to be defined with three arguments. The man
page for qmail-smtpd explains what these arguments should be: a hostname, a
password checking program, and an additional subprogram. The hostname should
be the fully qualified domain name of your email server; it is used to generate
CRAM-MD5 "challenges." The password checking program must conform to the
checkpassword standard defined at http://cr.yp.to/checkpwd/interface.html, with
one additional requirement: If the password checking program is to support
CRAM-MD5, the program must be able to handle both unencrypted passwords and
MD5-encrypted challenges and responses. The subprogram is executed by the
password checking program if password verification was successful; usually set
to /bin/true, the subprogram must return "true" when exiting.
(NOTE: checkpassword and other compatible programs are also used by qmail to
authenticate POP3 sessions, as explained earlier in this guide. When
authenticating POP3 sessions, the subprogram argument is necessary because,
after verifying a user's name and password, the password checking program is
expected to execute qmail-pop3d. In the case of authenticated SMTP, the
subprogram really doesn't serve any purpose, which is why /bin/true is
The default conf-smtpd control file has configuration that, when uncommented,
will enable authenticated SMTP, using cmd5checkpw as the password
checking program. cmd5checkpw keeps a list of allowed user names and
passwords in /etc/poppasswd; see the cmd5checkpw man page for more details.
If cmd5checkpw suits your needs, uncomment the four environment variable
definitions in the "SMTP-AUTH" section of conf-smtpd. Be sure to set up
/etc/poppasswd as instructed by the cmd5checkpw man page for authentication to
Other password checking programs can be used. For example, checkpassword uses
/etc/passwd and/or /etc/shadow, enabling system users to use authenticated
SMTP. To use checkpassword, edit conf-smtpd, uncommenting the four environment
variable definitions mentioned in the above paragraph. Then, change the line
defining QMAIL_SMTP_CHECKPASSWORD to look like this:
Remember to restart qmail afterward.
One advantage of using checkpassword over cmd5checkpw is that passwords do not
have to be stored in an unencrypted format on the server. This is
counterbalanced by the disadvantage of checkpassword not supporting CRAM-MD5;
consequently, LOGIN or PLAIN must be used, which means passwords have to be
sent unencrypted across the network.
(NOTE: You may need to change the permissions of checkpassword for it to work
properly in this case. The program must be setuid root, otherwise
authentication will fail. Run "chmod 6755 /bin/checkpassword" to give
checkpassword the proper permissions. Keep in mind that setting programs to be
setuid root is generally a bad idea, and you may wish to look into other
password checking programs instead.)
(NOTE: If you plan on providing POP3 and/or IMAP service, you may want to use
the same authentication data across all email services. If you plan on
providing POP3 service using qmail's POP3 server, you can use the same
password checking program for both POP3 and authenticated SMTP. Have a look
at the conf-pop3d control file, and make sure the QMAIL_POP3_CHECKPASSWORD
environment variable is set to your liking.)
For more information about authenticated SMTP and how it works, Erwin Hoffman
has written a tutorial, available at http://www.fehcom.de/qmail/smtpauth.html.
Appendix B.3 - Outbound Authenticated SMTP
qmail can also be instructed to use authenticated SMTP when relaying email to
other servers. This is useful when you plan on routing all your email through
another email server, such as the one provided by your Internet service
provider, and that server requires authentication.
If you have qmail configured to deliver all email to another server, then you
should have a single line in the smtproutes control file that looks similar to
To enable outbound authenticated SMTP, modify that line to include a username
and password, both of which should be encoded in base64:
:mail.your-isp.com <base64 user name> <base64 password>
This feature was patched into qmail. The patch's original author, Jay
Soffian, has documentation at
includes some Perl commands to help with base64 encodings. There are also
web-based base64 encoders available.
For the security-conscious, keep in mind that base64 encoding is not the same
as encrypting, and anybody who can see your smtproutes control file can learn
your passwords. Also, this feature uses LOGIN for authentication, which means
the remote server must support LOGIN, and which also means your passwords will
be sent unencrypted across the network.
Appendix B.4 - POP-before-SMTP
An alternative to authenticated SMTP is POP-before-SMTP. When a
POP-before-SMTP system is in place, any user that first checks his or her
incoming email with POP3 is then permitted, for a period of time, to relay
outgoing email through the server. POP-before-SMTP implementations accomplish
this by remembering POP3 clients' IP addresses, and looking for each SMTP
client's IP address in that list, granting relay permission if the address is
listed. The list is periodically cleaned of old IP addresses, ensuring relay
permission is not granted for longer than necessary. While not as secure as
authenticated SMTP, POP-before-SMTP is a good solution that supports all email
clients, including those that cannot use authenticated SMTP.
POP-before-SMTP requires additional software, specifically, a program that will
actually maintain the list of IP addresses permitted to relay. Portage offers
relay-ctrl, written by Bruce Guenter, for this purpose. Emerge this package
with the following commands:
# emerge -p relay-ctrl
These are the packages that I would merge...
# emerge relay-ctrl
After emerge finishes, edit the conf-smtpd and conf-pop3d control files. The
default installation already includes the necessary configuration in each of
these files, commented out. In conf-smtpd, uncomment the first two environment
variable definitions in the section that begins with, "If you are interested in
providing POP or IMAP before SMTP..." In conf-pop3d, uncomment the two
environment variable defitions in the section for POP3 before SMTP. After
saving the changes, remember to restart qmail. POP-before-SMTP should now
(NOTE: This appendix assumes you are providing POP3 service, and that you are
using qmail-pop3d to do so. With relay-ctrl, it is possible to use a
different POP3 server and still provide POP-before-SMTP. It is even possible
to provide "IMAP-before-SMTP" instead, using Courier IMAP. These examples are
beyond the scope of this guide, however, there is documentation for relay-ctrl
at http://untroubled.org/relay-ctrl/ and for Courier IMAP at
http://www.inter7.com/courierimap.html, as well as notes about enabling
IMAP-before-SMTP in the default installation of conf-smtpd.)
Appendix B.5 - Encrypted SMTP
Ordinarily, SMTP communications are "in the clear," with no encryption. This
means anybody who can eavesdrop on your network activity can monitor your
email traffic, snooping messages, sender and recipient addresses, and perhaps
even SMTP authentication user names and passwords. Consequently, an extention
to the SMTP protocol was drafted, providing email servers with the ability to
encrypt SMTP sessions by using the ESMTP STARTTLS command. Gentoo's qmail
ebuild allows encryption to be used on both incoming and outgoing SMTP
To enable encrypted SMTP, first make sure that you emerged qmail with the
"ssl" USE flag enabled. Next, you must have an SSL server certificate in
place. If you ran the ebuild command for extra automatic configuration,
described in Part Two above, then a self-signed certificate is already in
place. If you did not run the ebuild command, you can generate a
self-signed certificate by first editing /var/qmail/control/servercert.cnf,
filling in information specific to your server, and then running
/var/qmail/bin/mkservercert. When the certificate generation process
finishes (using either command), three new files will appear in
/var/qmail/control: servercert.pem, the server's new self-signed certificate,
used for incoming SMTP connections; clientcert.pem, which can be a separate
certificate used for outgoing SMTP connections, but which by default is the
same as servercert.pem; and rsa512.pem, the private code-key used to decrypt
incoming SMTP traffic. Restart qmail after creating your certificate.
At this point, any client that supports the ESMTP STARTTLS command will be
able to request an encrypted SMTP session; also, the server will automatically
request an encrypted SMTP session when connecting to any remote host that
boasts ESMTP STARTTLS support. The server is ready to go. Further
configuration is possible, providing, among other features, the ability to
refuse outgoing email to remote hosts that do not support encryption, and the
ability to accept email from ecrypting clients that otherwise would have been
rejected. For more information, visit the web page for Frederik Vermeulen's
original patch for qmail (http://inoa.net/qmail-tls/).
Note that self-signed certificates may be rejected by some servers as insecure
or untrustworthy. You may want to have a certificate signed by a mutually
trusted Certificate Authority instead.
(NOTE: The process of getting an SSL certificate issued by a Certificate
Authority is really beyond the scope of this guide, however, I plan to have
more information in a future revision.)
Also, be aware that encrypting your server's SMTP traffic does not guarantee
that your email is safe from prying eyes. Email messages are sometimes
relayed through multiple servers, one or more of which may not support
encryption. Also, email that has made it to its final destination is usually
stored unencrypted, making it possible for other users or administrators on
that server to read it. For more complete email security, you may want to
consider using an email client that supports encrypting each email message
before it is sent. Of course, this will require that the recipient be able to
decrypt the message. Further information would be beyond the scope of this
guide, but you can visit the web pages of email clients that support message
encryption, such as Mutt (http://www.mutt.org/), and the web pages of
general-use encryption software, such as GnuPG (http://www.gnupg.org/).
Appendix C - Patches
Warning: Lots of technical jargon ahead. This section describes the patches
that are applied to the qmail 1.03 source code by the qmail 1.03-r13 ebuild. I
should mention that many qmail veterans consider some of these patches to be
unnecessary for general use, suggesting that one should use as pristine a copy
of qmail as possible, applying only those patches that are known to be needed.
If you are handy at writing and modifying ebuild scripts, you may want to
consider editing qmail's ebuild script to remove patches that do not apply to
you. Of course, qmail has been found to run just fine with these patches, and
they do provide features many find useful, and fix bugs many find annoying or
inconvenient. Buyer beware, however: The author of qmail makes no guarantees
about its security beyond his original code. Buyer beware again: Removing
patches may result in unexpected behavior if the configuration files and scripts
are not modified appropriately.
* qregex-starttls-2way-auth (http://www.arda.homeunix.net/store/qmail/)
This patch combines several patches into one, providing several extentions
to qmail's functionality.
This patch provides the extra configuration file
/var/qmail/control/badmailto, and enables the use of regular expressions to
be used in /var/qmail/control/badmailto and /var/qmail/control/badmailfrom.
For more information, visit the original patch's web page
This patch also provides the ESMTP AUTH command, enabling qmail to require
authorization before accepting messages for processing. For more
information, visit the original patch's web page
(http://members.elysium.pl/brush/qmail-smtpd-auth/). See appendix B.2 for
details on how to make use of this feature.
This patch also gives qmail the ability to use the ESMTP AUTH command when
connecting to other SMTP servers. See appendix B.3 for more details on
outbound authenticated SMTP.
Finally, this patch enables TLS/SSL support for encrypted SMTP sessions.
See appendix B.5 for details on how to make use of this feature.
Patch written by Andrew St. Jean, based on the work of "unixpimps.org,"
Krzysztof Dabrowski, "Mrs. Brisby," Frederik Vermeulen, and Neal Groothuis.
According to the qmail 1.03-r13 ebuild, this patch "fixes a problem when
utilizing morercpthosts" together with ESMTP AUTH.
* qmailqueue (http://www.qmail.org/qmailqueue-patch)
This patch provides qmail with the ability to replace qmail-queue with
other programs. See appendix B.1 for more details. Patch written by Bruce
* big-todo (http://qmail.null.dk/big-todo.103.patch)
qmail was designed to be able to handle large numbers of email messages
without a significant slow-down. One way it accomplishes this is by
splitting its queue into several different directories. Many of these
directories are in turn split into subdirectories, ensuring that no single
folder becomes unnecessarily large.
When a message is first accepted by qmail for processing, it is placed in
the "todo" directory. Normally, this directory is not split into
subdirectories like certain queue directories are. This means that if a
large number of messages enters the system before qmail has a chance to
process them all, the todo directory could become quite large, introducing a
lag into the system. This patch enables the todo directory to be split into
subdirectories, helping to prevent a sudden influx of email from being a
problem. Patch written by Russel Nelson, with some modification by Bruce
* qmail-1.03-qmtpc (http://www.qmail.org/qmail-1.03-qmtpc.patch)
This patch allows qmail to send email to other servers using QMTP instead
of SMTP. More information about QMTP will be in a future revision of this
guide. Patch written by Russel Nelson.
* qmail-103 (http://www.ckdhr.com/ckd/qmail-103.patch)
Unpatched qmail will have trouble sending email to domains whose DNS
servers send oversized answers to DNS queries. This patch resolves this
issue. Patch written by Christopher K. Davis.
Unpatched qmail, when handling .qmail files whose first lines are nothing but
tabs, has the potential to access an array out of range, an error more
commonly known as a memory or buffer overflow. This bug is generally
considered to be minor, because qmail by this point is running as the owner
of the .qmail file and will never run as root, and also because qmail's
documentation states that a .qmail file should not start with an empty line.
Nonetheless, this is a bug, and this patch fixes it.
* qmail-link-sync (http://www.jedi.claranet.fr/qmail-link-sync.patch)
qmail assumes that certain file commands are synchronous, that is, the
commands will not report a successful finish until the file has actually
been written to disk (as opposed to residing in a cache to be written
later). While this assumption is true for some Unix-compatible operating
systems and the file systems they use, it is not true for many flavors of
linux and its file systems. The consequence is that a disruption of service,
such as a power outage, could result in email being lost. This patch
works around this issue by forcing file synchronization to take place after
these commands. Patch written by Frank Denis.
Unpatched qmail has an inherent maximum concurrency limit of 255. In other
words, the highest number of concurrent local deliveries and concurrent
remote deliveries that can take place is 255 each. This patch allows those
limits to be as high as 65,000, though the qmail 1.03-r13 ebuild sets a new
maximum limit of 500 for each. Patch written by Johannes Erdfelt.
0.0.0.0 is considered to be a self-referencing IP address, similar to
127.0.0.1 (though the semantics of each are not quite the same).
Unpatched qmail does not treat 0.0.0.0 as a local IP address; this patch
resolves that issue. Patch written by Scott Gifford.
This patch fixes the code compatibility issue that prevents qmail 1.03 from
compiling or running properly against versions of glibc 2.3.2 and newer.
* sendmail-flagf (http://david.acz.org/software/sendmail-flagf.patch)
qmail's sendmail wrapper does not support the "-f" option that the real
sendmail does. This patch provides that feature. Patch written by David
* qmail-maildir++ (http://www.shupp.org/patches/qmail-maildir++.patch)
Sam Varshavshik, the author of Courier and Courier IMAP, authored an
extention to the maildir format called maildir++. Among other things,
maildir++ provides for multiple email subdirectories, and quota support.
This patch enables qmail to make use of maildir++, allowing greater
compatibility between qmail and packages supporting maildir++, such as
Courier IMAP and vpopmail. Patch written by Bill Shupp.
This patch fixes a typo in the above patch.
Whenever qmail needs to generate a timestamp, such as when adding a "Date:"
header to an email message, it uses Greenwich Mean Time (GMT) timestamps.
Most email clients know how to convert GMT into the local time zone, but
some do not. This patch enables qmail to generate timestamps in the local
Normally, qmail will include a copy of the entire original message for
the original sender when generating a bounce message. This patch allows
for a new control file, "bouncemaxbytes", that states the maximum size a
bounce message can be. Any bounce message that would go over this limit
will be truncated.
This patch provides support for the ESMTP SIZE command, allowing qmail to
reject messages deemed too large before they are sent, instead of after.
Some email servers allow their users to relay messages to non-local
addresses by creating a new email address that appears to be local. To
illustrate, an email server local to example.com could be instructed to
deliver a message to email@example.com by sending it a message
addressed to firstname.lastname@example.org. qmail by default does
NOT support this trick, as it can be easily abused by spammers who are
aware of it. However, according to some programs that test the integrity of
email servers, qmail APPEARS to support this trick, because it does not
reject up front any email messages addressed to local domains; instead, it
later bounces any messages that are not destined for valid addresses, such as
those with "%" or other extraneous characters. Because these broken testing
programs do not check to see if their messages were actually delivered, many
qmail servers have unfortunately been incorrectly blacklisted. This patch
works around this issue by enabling qmail to reject up front any recipient
addresses that use "%" and other such characters.
This patch provides for two new control files, "badrcptto" and
"morebadrcptto". They work similarly to badmailfrom, rejecting up front
any messages bound for addresses that appear in either of these files.
Patch originally written by Ward Vandewege, later modified.
* qmail-popupnofd2close (http://www.dataloss.nl/software/patches/)
This patch allows checkpassword and similar programs to log error messages
to stderr. Patch written by peter(at)dataloss.nl.
* qmail-1.03-reread-concurrency.2 (http://js.hu/package/qmail/)
This patch enables qmail to reread control files concurrencylocal and
concurrencyremote when the qmail-send process receives a HUP signal.
Normally qmail has to be restarted for these files to be reread. Patch
written by Julian Severn-nek.
* 08-capa.diff (http://www.mcmilk.de/qmail/dl/djb-qmail/patches/)
This patch provides the POP3 CAPA command, allowing POP3 clients to get a
list of all POP3 commands provided by qmail-pop3d. Patch written by Tino
Appendix D - Additional Software
This is a collection of additional software packages, many of which are
available through Portage, that are useful for managing qmail and extending
* Courier IMAP (http://www.inter7.com/vpopmail) (ebuild available)
An IMAP server that supports the maildir format, and therefore integrates
very well with qmail.
* qlogtools (http://untroubled.org/qlogtools) (ebuild available)
A set of programs designed to analyze qmail's logs for monitoring and
* qmail-scanner (http://qmail-scanner.sourceforge.net/) (ebuild available)
A multi-purpose email scanner specifically designed to work with qmail,
useful for combatting viruses, spam, and even unwanted file attachments.
qmail-scanner can be configured with its own set of rules, and can also work
with other popular email tools such as SpamAssassin
(http://spamassassin.org, ebuild available), F-Prot (http://www.f-prot.com,
ebuild available), and many commercial virus scanners available for linux.
* qmailanalog (http://cr.yp.to/qmailanalog.html) (ebuild available)
Another set of tools for analyzing qmail's logs, written by the author of
* vpopmail (http://www.inter7.com/vpopmail) (ebuild available)
A collection of programs designed to make the creation and management of
virtual users and multiple email domains relatively fast and painless.
Thanks to Dave Sill for excellent qmail documentation in the form of "Life
with qmail" and 'The qmail Handbook'.
Thanks to Charles Cazabon for invaluable help through the qmail mailing list.
Thanks to Daniel J. Bernstein for qmail itself.
Thanks to the authors and contributors of Gentoo for creating an excellent
Guide Revision History
3/20/03 - First release.
3/21/03 - Corrected the statement about Gentoo's scripts not providing a
limit on the number of simultaneous incoming SMTP connections. There is
always a limit, even if it is not explicitly set. Thanks to Dave Sill for
pointing out this typo.
4/17/03 - Added a note about the incompatibility between qmail 1.03 and glibc
2.3.2, and also fixed some grammatical and formatting mistakes. glibc 2.3.1
must be used to compile qmail and related packages.
5/13/03 - Added comments about the qmail ebuild's option for extra automatic
configuration, and cleaned up some wording here and there.
5/15/03 - Added comments about the qmail-sumo and qmail-pop3d ebuilds. Thanks
to Tridib Biswas for pointing these out to me.
7/20/03 - Updated the guide to reflect recent releases of qmail and related
ebuilds for Gentoo.
11/30/03 - Rewrote several sections in part one to more accurately explain
Portage's system of virtual packages and package blocking; added appendices,
which will be further fleshed out in the next update; cleaned up some wording
here and there. This update is incomplete, pending a new version of the guide
to be based on qmail ebuild 1.03-r13.
12/29/03 - Updated the guide to reflect qmail ebuild 1.03-r13. Reorganized
the appendices. This update is also incomplete, as many sections in the
appendices still need to be written.
12/30/03 - Corrected a statement concerning the Gentoo ebuild's initial
configuration of qmail. By default, qmail will accept SMTP connections from
anywhere, not just from local IP addresses.
2/8/04 - Removed information about the qmail-sumo ebuild, which is no longer
in Portage. Updated information about "Life with qmail," which is now based
on netqmail 1.05. Updated information about glibc; the latest stable ebuild
is now 2.3.2-r9. Added a note about making sure the correct system users and
groups are in place before emerging qmail. Added information about the
qmail-control script installed by the qmail ebuild. Reorganized the appendices
again, and wrote sections concerning authenticated SMTP, outbound authenticated
SMTP, POP-before-SMTP, and additional qmail-related software. The section on
encrypted SMTP still needs to be written. Cleaned up wording and formatting
in various places.
2/20/04 - Wrote the section on encrypted SMTP. Cleaned up wording in various
2/22/04 - Fixed a typo in the section for encrypted SMTP. "servercert.pem"
was mentioned where "servercert.cnf" should have been named.