Make your own free website on

                   Mail Server Administrators’ Guide on qmail-1.03

Document version: 1.2

Author: Abdul Naseer (


1.  qmail basics
1.1.  Why qmail? Comparison with other MTAs
1.2.  Features of qmail
1.3.  Big qmail pictures
2.  qmail installation
2.1 qmail license
2.2 How to get the latest software?
2.3 Installation of qmail software.
3.  Configuration of qmail
3.1.  How to configure qmail?
3.2.  Spam control in qmail.
3.3.  Start qmail
4. Architecture of qmail
4.1 Modular system Architecture
4.2 File structure
4.3 Queue structure
4.4 Pictures
5. Infrequently Asked Questions!
6. Problems?
7. Further reading

1. qmail  Basics

qmail is an MTA (mail transfer Agent) for Unix flavors.  It uses SMTP and supports ESMTP also. qmail is a secure, reliable, efficient, simple message light weight transfer agent. It is meant as a replacement for the entire sendmail-binmail system on typical Internet-connected UNIX hosts.

Qmail software is written by D. J. Bernstein.

1.1. Why qmail?  - Comparison of qmail with other MTAs

I am just giving the comparison of qmail with sendmail which is being widely used as MTA for the past few decades.

Qmail is a light weight product, and unlike many other MTAs you don’t have to run qmail as root. This is one of the best security features of qmail.

Qmail is a much smaller than sendmail, and it lacks many of the features that most mail servers have today. It has no native support for RBL, which sendmail does have. Also, unlike sendmail, Qmail can't reject E-mail addressed to  a   mailbox that doesn't exist. Qmail will accept the E-mail message, and then it will generate a "no such user" bounce internally. But these are the standard features of qmail, a large number of add-ons or patches are available,and by applying these add-ons or patches you can make the qmail more powerful than any other MTA.

Qmail’s security features are widely discussed and documented. Sendmail has been hacked, revised, and patched for years. Security vulnerabilities of sendmail is an established fact and well documented also.

One of the nice features of Qmail is that it supports an alternate mail storage format, that's directory-based, instead of one huge file containing all your messages. If you do a lot of POP3 serving, you can save a lot of CPU cycles and disk activity with Qmail. Unfortunately, Pine does not natively support this storage format. But, again, there are patches for that out there.

Qmail has a problem if you are sending mails to multiple users of the same domain, qmail will connect multiple times unlike sendmail. This may lead to the wastage of bandwidth.

1.2.  Features of qmail

Secure: Security is  an absolute requirement in today’s world. Mail delivery is utmost critical for users; it should be up 24 hours a day 7 days a week , so it must be completely secure. The person who has written qmail was sick of the security holes in sendmail and other MTAs.

Reliable: qmail's straight-paper-path philosophy guarantees that a message, once accepted into the system, will never be lost. Qmail also supports maildir, a new, super-reliable user mailbox format. Maildirs, unlike mbox files and mh folders, won't be corrupted if the system crashes during delivery. Even better, not only can a user safely read his mail over NFS, but any number of NFS clients can deliver mail to him at the same time.

Efficient: On a Pentium under BSD/OS, qmail can easily sustain 200000 local messages per day---that's separate messages injected and delivered to mailboxes in a real test! Although remote deliveries are inherently limited by the slowness of DNS and SMTP, qmail overlaps 20 simultaneous deliveries by default, so it zooms quickly through mailing lists

Simple: qmail is vastly smaller than any other Internet MTA. Some reasons why: (1) Other MTAs have separate forwarding, aliasing, and mailing list mechanisms. qmail has one simple forwarding mechanism that lets users handle their own mailing lists. (2) Other MTAs offer a spectrum of delivery modes, from fast+unsafe to slow+queued. qmail-send is instantly triggered by new items in the queue, so the qmail system has just one delivery mode: fast+queued. (3) Other MTAs include, in effect, a specialized version of inetd that
watches the load average. qmail's design inherently limits the machine load, so qmail-smtpd can safely run from your system's inetd.

Replacement for sendmail: qmail supports host and user masquerading, full host hiding, virtual domains, null clients, list-owner rewriting, relay control, double-bounce recording, arbitrary RFC 822 address lists, cross-host mailing list loop detection, per-recipient
checkpointing, downed host backoffs, independent message retry schedules, etc. In short, it's up to speed on modern MTA features. qmail also includes a drop-in ``sendmail'' wrapper so that it will be used transparently by your current UAs.

Main featues of qmail:

? automatic adaptation to your UNIX variant---no configuration needed
? AIX, BSD/OS, FreeBSD, HP/UX, Irix, Linux, OSF/1, SunOS, Solaris, and more
? automatic per-host configuration (config, config-fast)
? quick installation---no big list of decisions to make

? clear separation between addresses, files, and programs
? minimization of setuid code (qmail-queue)
? minimization of root code (qmail-start, qmail-lspawn)
? five-way trust partitioning---security in depth
? optional logging of one-way hashes, entire contents, etc. (QUEUE_EXTRA)

Message construction (qmail-inject):
? RFC 822, RFC 1123
? full support for address groups
? automatic conversion of old-style address lists to RFC 822 format
? sendmail hook for compatibility with current user agents
? header line length limited only by memory
? host masquerading (control/defaulthost)
? user masquerading ($MAILUSER, $MAILHOST)
? automatic Mail-Followup-To creation ($QMAILMFTFILE)

SMTP service (qmail-smtpd):
? RFC 821, RFC 1123, RFC 1651, RFC 1652, RFC 1854
? 8-bit clean
? 931/1413/ident/TAP callback (tcp-env)
? relay control---stop unauthorized relaying by outsiders (control/rcpthosts)
? no interference between relay control and forwarding
? tcpd hook---reject SMTP connections from known abusers
? automatic recognition of local IP addresses
? per-buffer timeouts
? hop counting

Queue management (qmail-send):
? instant handling of messages added to queue
? parallelism limit (control/concurrencyremote, control/concurrencylocal)
? split queue directory---no slowdown when queue gets big
? quadratic retry schedule---old messages tried less often
? independent message retry schedules
? automatic safe queueing---no loss of mail if system crashes
? automatic per-recipient checkpointing
? automatic queue cleanups (qmail-clean)
? queue viewing (qmail-qread)
? detailed delivery statistics (qmailanalog, available separately)

Bounces (qmail-send):
? QSBMF bounce messages---both machine-readable and human-readable
? HCMSSC support---language-independent RFC 1893 error codes
? double bounces sent to postmaster

Routing by domain (qmail-send):
? any number of names for local host (control/locals)
? any number of virtual domains (control/virtualdomains)
? domain wildcards (control/virtualdomains)
? configurable percent hack support (control/percenthack)
? UUCP hook

SMTP delivery (qmail-remote):
? RFC 821, RFC 974, RFC 1123
? 8-bit clean
? automatic downed host backoffs
? artificial routing---smarthost, localnet, mailertable (control/smtproutes)
? per-buffer timeouts
? passive SMTP queue---perfect for SLIP/PPP (serialmail, available separately)

Forwarding and mailing lists (qmail-local):
? address wildcards (.qmail-default, .qmail-foo-default, etc.)
? sendmail .forward compatibility (dot-forward, available separately)
? fast forwarding databases (fastforward, available separately)
? sendmail /etc/aliases compatibility (fastforward/newaliases)
? mailing list owners---automatically divert bounces and vacation messages
? VERPs---automatic recipient identification for mailing list bounces
? Delivered-To---automatic loop prevention, even across hosts
? automatic mailing list management (ezmlm, available separately)

Local delivery (qmail-local):
? user-controlled address hierarchy---fred controls fred-anything
? mbox delivery
? reliable NFS delivery (maildir)
? user-controlled program delivery: procmail etc. (qmail-command)
? optional new-mail notification (qbiff)
? optional NRUDT return receipts (qreceipt)
? conditional filtering (condredirect, bouncesaying)

POP3 service (qmail-popup, qmail-pop3d):
? RFC 1939
? UIDL support
? TOP support
? APOP hook
? modular password checking (checkpassword, available separately)

 2. qmail installation

This document is for the qmail-1.0.3 version

2.1. qmail license

qmail is distributed under GNU GPL license.
Visit this web site for details about GNU GPL :

You are free to distribute the original version of qmail, but if you want to distribute modified versions of qmail (including ports, no matter how minor the changes are) you'll have to get the approval of the author, ?D.J.Bernstein.

Exception: You are permitted to distribute a precompiled var-qmail package if (1) installing the package produces exactly the same /var/qmail hierarchy as a user would obtain by downloading, compiling, and installing qmail-1.03.tar.gz, fastforward-0.51.tar.gz, and dot-forward-0.71.tar.gz; (2) the package behaves correctly, i.e., the same way as normal qmail+fastforward+dot-forward installations on all other systems; and (3) the package's creator warrants that he has made a good-faith attempt to ensure that the package behaves correctly. It is not acceptable to have qmail working differently on different machines; any variation is a bug. If there's something about a system (compiler, libraries, kernel, hardware, whatever) that changes qmail's behavior, then that platform is not supported, and you are not permitted to distribute binaries.

2.2. How to get the latest software?

You need to download the following packages to start off.

Qmail  (
oversize DNS packet patch for qmail (
ucspi-tcp (
daemontools (
rblsmtpd (
fastforward (
dot-forward (

2.3. qmail installation

You can start the qmail installation if you have all the software packages mentioned under 2.2 ready with you.

Change to root


2.3.1. qmail –1.03 installation

root:/usr/local/src# gzip -d qmail-1.03.tar.gz
root:/usr/local/src# tar xvf qmail-1.03.tar

Then you need to change to the qmail-1.03 folder.

root:/usr/local/src# cd qmail-1.03

You can read the INSTALL files at this point
root:/usr/local/src/qmail-1.03# more INSTALL
root:/usr/local/src/qmail-1.03# more INSTALL.alias
root:/usr/local/src/qmail-1.03# more INSTALL.mbox

After you return, apply the oversize DNS packet patch. This patch is necessary because some providers (such as AOL) have decided to ignore the RFC's, and return UDP DNS responses that are greater than 512 bytes. qmail's DNS resolver library is strictly RFC
compliant, and does not accept non-RFC-compliant replies. This patch enables qmail to correctly process illegal DNS replies.

To apply the patch, do the following (in the qmail source dir)

root:/usr/local/src/qmail-1.03# patch -p1 < /path/to/qmail-103.patch

Create a qmail directory now

# mkdir /var/qmail

The following groups and users have to be created for qmail
(Note : Debian Linux users can skip this part, since the users are already created for you by the package)
# groupadd nofiles
# useradd -g nofiles -d /var/qmail/alias -s /bin/false alias
# useradd -g nofiles -d /var/qmail -s /bin/false qmaild
# useradd -g nofiles -d /var/qmail -s /bin/false qmaill
# useradd -g nofiles -d /var/qmail -s /bin/false qmailp
# groupadd qmail
# useradd -g qmail -d /var/qmail -s /bin/false qmailq
# useradd -g qmail -d /var/qmail -s /bin/false qmailr
# useradd -g qmail -d /var/qmail -s /bin/false qmails

Important: you are going to be in trouble if you are not creating these users / groups since qmail will simply fail to work.

Start a script, this will cretae a log for you.

root:/usr/local/src/qmail-1.03#script /var/qmail/qmail_installscript

Now you can compile the package:
root:/usr/local/src/qmail-1.03# make setup check

2.3.2. rblsmtpd installation

root:/usr/local/src# gzip –d  rblsmtpd-0.70.tar.gz
root:/usr/local/src# tar xvf  rblsmtpd-0.70.tar
root:/usr/local/src# cd rblsmtpd-0.70
root:/usr/local/src/rblsmtpd-0.70# make setup check

 Note: If you are using gcc as your c compiler, you may have to edit compile and load files and replace cc with gcc at any of these installation stages. Please keep this in mind.

Install ucspi-tcp, and daemontools are also to be installed as explaned above. This will produce binaries in /usr/local/bin.  Edit .profile file and add /usr/local/bin in the path.

You can stop scripting by typing exit, and the log can be used for reference.


You have now the following packages installed on your system:
? Qmail
? Rblsmtpd
? Ucspi
? Daemontools

A brief description of packages other than qmail is given below, those who are not interested can skip this portion and go to configuration part.


rblsmtpd is a generic tool to block mail from RBL-listed sites. It works with any SMTP server that can run under tcpserver; in particular, any version of qmail or sendmail. Turning it on is easy: simply insert rblsmtpd in front of the real SMTP server in your tcpserver invocation.

rblsmtpd supports anti-RBL lists for sites that want to skip RBL lookups for preauthorized hosts. It also optionally pays attention to temporary RBL lookup errors.

The MAPS RBL (Mail Abuse Prevention System - Raltime Blackhole List) is a system for creating intentional network outages ("blackholes") for the purpose of limiting the transport of known-to-be-unwanted mass e-mail.See for more information about the RBL.

The features of rblsmtpd have been incorporated into ucspi-tcp 0.86; there will be no more rblsmtpd releases.


tcpserver and tcpclient are easy-to-use command-line tools for building TCP client-server applications.

tcpserver waits for incoming connections and, for each connection, runs a program of your choice. Your program receives environment variables showing the local and remote host names, IP addresses, and port numbers.

tcpserver offers a concurrency limit to protect you from running out of processes and memory. When you are handling 40 (by default) simultaneous connections, tcpserver smoothly defers acceptance of new connections.

tcpserver also provides TCP access control features, similar to tcp-wrappers/tcpd's hosts.allow but much faster. Its access control rules are compiled into a hashed format with cdb, so it can easily deal with thousands of different hosts.

This package includes a recordio tool that monitors all the input and output of a server.

tcpclient makes a TCP connection and runs a program of your choice. It sets up the same environment variables as tcpserver.

This package includes several sample clients built on top of tcpclient: who@, date@, finger@, http@, tcpcat, and mconnect.

tcpserver and tcpclient conform to UCSPI, the UNIX Client-Server Program Interface, using the TCP protocol. UCSPI tools are available for several different networks.

It is recommended to run your qmail as well as vpopmail under tcpserver, eventhough it is possible to run the same under inetd.


Daemontools is written by the author of qmail D. J. Bernstein.

Here is the description about various components of daemontools:

supervise monitors a service. It starts the service and restarts the service if it dies. The companion svc program stops, pauses, or restarts the service on sysadmin request. The svstat program prints a one-line status report.

cyclog writes a log to disk. It automatically synchronizes the log every 100KB (by default) to guarantee data integrity after a crash. It automatically rotates the log to keep it below 1MB (by default). If the disk fills up, cyclog pauses and then tries again, without losing any data.

accustamp puts a precise timestamp on each line of input. The timestamp is a numeric TAI timestamp with microsecond precision. The companion tailocal program converts TAI timestamps to local time.

usually watches a log for lines that do not match specified patterns, copying those lines to stderr. The companion errorsto program redirects stderr to a file.

setuser runs a program under a user's uid and gid. Unlike su, setuser does not gain privileges; it does not check passwords, and it cannot be run except by root.
 3. Configuration of qmail

3.1. How to configure qmail?

After qmail compiles, we will want to configure it.

There are three ways to do this:

A) The easiest way to do this is:

     root:/usr/local/src/qmail-1.03# ./config

The config script tries to do a reverse DNS lookup on all local IP addresses. If this doesn't work, then you've got some dirty work to do. Read INSTALL.ctl. As long as all of your local IP's are in your DNS, then you shouldn't have any problems. Otherwise you can do the following:

B) root:/usr/local/src/qmail-1.03# ./config-fast your_fully_qualified_host_name

This will create the necessary files in order to run qmail.

C) Third way is bit difficult, editing the control files manually (/var/qmail/control), but the names of these files are self explanatory. Just have a look!!

There are two important files, these are

me -- (It contains your local host name. Including domain)
rcpthosts -- (All of the hosts that qmail will receive mail for. All of your local domains must be in this file.)

You can run qmail in many ways, but the way I am going to explain is one of the safest.

Create the following files:

1. #mkdir –p /var/qmail/start
# vi /var/qmail/start/qmail-deliver
# Using stdout for logging
# Using control/defaultdelivery from qmail-local to deliver messages by default
exec env - PATH="/var/qmail/bin:$PATH" qmail-start "`cat /var/qmail/control/defaultdelivery`" splogger mail 2 > /dev/console 2>&1 &

2. chmod +x /var/qmail/start/qmail-deliver
3. #vi /var/qmail/control/defaultdelivery

(This is the default delivery method, in our example it is Maildir, your default delivery method could be different)

4. # vi /var/qmail/start/qmail-smtp
# Using cyclog for logging
# This script will start qmail smtp daemon
exec env - PATH="/var/qmail/bin:$PATH" tcpserver -x /etc/tcp.smtp.cdb -u <your_qmaild_user_id> -g <your_qmail_group_id> 0 smtp /var/qmail/bin/qmail-smtpd & setuser qmaill cyclog -s5000000 -n5 /var/log/qmail/qmail-smtpd &
Note: From the word exec, entire thing should be in single line

5. chmod +x /var/qmail/start/qmail-smtp

3.2. Spam Control

It is very important that our mail server should not be spam friendly, otherwise we need to take the server off the internet.

Create a file /etc/tcp.smtp

#vi /etc/tcp.smtp,RELAYCLIENT=""
 Note: Here we are allowing the local host as well as all hosts in the 202.144 network to use our mail server as the smtp relay server. You will have to replace 202.144 with your network.

#tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp
#chmod 644 /etc/tcp.smtp*

3.3 Start qmail

# cd /var/qmail/start
#./ qmail-smtp
#./ qmail-deliver

Qmail smtp server should be running now.

How to check?

If you do a

#ps –ef |grep qmail (for SYS V) or
#ps –aux |grep qmail (for BSD)

You should get some thing like this:

qmails   815     1  0 14:30:35 pts/0    0:00 qmail-send
qmaild   812     1  0 14:30:29 pts/0    0:00 tcpserver -x /etc/tcp.smtp.cdb -u 44421 -g 44420 0 smtp /var/qmail/bin/qmail-sm
root   818   815  0 14:30:35 pts/0    0:00 qmail-lspawn ./Maildir
qmaill   817   815  0 14:30:35 pts/0    0:00 splogger mail 2
qmailr   819   815  0 14:30:35 pts/0    0:00 qmail-rspawn
qmailq   820   815  0 14:30:35 pts/0    0:00 qmail-clean
qmailr   821   819  0 14:30:35 pts/0    0:00 qmail-remote

And if you do a telnet to local host to port 25, the smtp server will respond

#telnet localhost 25
Connected to localhost.
Escape character is '^]'.

If you are getting this reply, everything should be OK, just enter quit and press ENTER key.

 4. Architecture of qmail

4.1. Modular system architecture

Internet MTA's perform a variety of tasks. Earlier designs like Sendmail and smail are monolithic. In other words, they have one large, complex program that "switches hats": it puts on one hat to be an SMTP server, another to be an SMTP client, another to inject
messages locally, another to manage the queue, etc.

qmail is modular. Each of these functions is performed by a separate program. As a result, the programs are much smaller, simpler, and less likely to contain functional or security bugs. To further enhance security, qmail's modules run with different privileges, and they don't "trust" each other: they don't assume the other modules alwaysdo only what they're supposed to do.

The core modules are:

Modules                              Function
.................................. ..................................
qmail-smtpd    accepts/rejects messages via SMTP
qmail-inject                         injects messages locally
qmail-rspawn/qmail-remote           handles remote deliveries
qmail-lspawn/qmail-local            handles local deliveries
qmail-send                           processes the queue
qmail-clean                          cleans the queue

There's also a down side to the modular approach. Unlike a monolithic  MTA, the interactions between modules are well-defined, and modules only exchange the minimum necessary information with each other. This is generally A Good Thing, but sometimes it makes it hard to do things. For example, the sendmail "-v" flag causes Sendmail to print a
trace of its actions to standard output for debugging purposes. Since the one sendmail binary handles injection, queueing, alias processing, .forward file processing, and remote forwarding via SMTP, it is able to easily trace the entire delivery until the message is delivered.
The equivalent capability in qmail doesn't exist, and would require substantial code changes and additional complexity to implement the passing of the "debug" flag from module to module.

4.2. File structure

/var/qmail is the root of the qmail file structure. This can be changed when qmail is being built, but it's a good idea to leave it unchanged so other administrators know where to find things. If you really want to relocate some or all of the qmail tree, it's better to
do that using symbolic links. See the Create directories subsection of the Installation section for details.

The top-level subdirectories are:

Directory                          Contents
.................................. ..................................
alias                              .qmail files for system-wide
bin                                 program binaries and scripts
boot                                startup scripts
control                             configuration files
doc                                 documentation (except man pages)
man                                 man pages
queue                               the queue of unsent messages
users                               the qmail-users database files

4.3. Queue structure

The file INTERNALS in the build directory discusses the details of queueing more thoroughly. This is a broader overview of structure of the queue.

Subdirectory                        Contents
.................................. ..................................
bounce                              permanent delivery errors
info*                               envelope sender addresses
intd                                envelopes under construction by
local*                              local envelope recipient addresses
lock                                lock files
mess*                               message files
pid                                 used by qmail-queue to acquire an
                                   i-node number
remote*                             remote envelope sender addresses
todo                                complete envelopes

Note: directories marked with an "*" contain a series of split subdirectories named "0", "1", ..., up to (conf-split-1), where conf-split is a compile-time configuration setting contained in the file conf-split in the build directory. It defaults to 23. The purpose of splitting these directories is to reduce the number of files in a single directory on very busy servers.

Files under the mess subdirectory are named after their i-node number. What this means is that you can't manually move them using standard UNIX utilities like mv, dump/restore, and tar. There are a couple user-contributed utilities on that will rename queue files correctly.

Note: It is not safe to modify queue files while qmail is running. If you want to modify the queue, stop qmail first, play with the queue carefully, then restart qmail.

4.4. Pictures

There is a series of files in /var/qmail/doc with names starting with PIC. These are textual "pictures" of various situations that qmail handles. They show the flow of control through the various modules, and are very helpful for debugging and creating complex

Filename                            Scenario
.................................. ..................................
PIC.local2alias                     locally-injected message delivered
                                   to a local alias
PIC.local2ext                       locally-injected message delivered
                                   to an extension address
PIC.local2local                     locally-injected message delivered
                                   to a local user
PIC.local2rem                       locally-injected message delivered
                                   to a remote address
PIC.local2virt                      locally-injected message delivered
                                   to an address on a local virtual
PIC.nullclient                      a message injected on a null
PIC.relaybad                        a failed attempt to use the local
                                   host as a relay
PIC.relaygood                       a successful attempt to use the
                                   local host as a relay
PIC.rem2local                       a message received via SMTP for a
                                   local user

These files are also available on-line from:


If you want real pictures of qmail, check out Andre Opperman's "big qmail picture" at, which is reproduced in this guide.

5. Infrequently Asked Questions

From “Life with qmail”

These are questions that don't qualify as frequently asked, but which
are important and not easy to answer.

5.1. How frequently does qmail try to send deferred messages?

Each message has its own retry schedule. The longer a message remains undeliverable, the less frequently qmail tries to send it. The retry schedule is not configurable. The following table shows the retry schedule for a message that's undeliverable to a remote recipient until it bounces. Local messages use a similar, but more frequent, schedule.

   Delivery Attempt                    Seconds             D-HH:MM:SS
...................... ....................... ......................
          1                                  0             0-00:00:00
          2                                400             0-00:06:40
          3                               1600             0-00:26:40
          4                               3600             0-01:00:00
          5                               6400             0-01:46:40
          6                              10000             0-02:46:40
          7                              14400             0-04:00:00
          8                              19600             0-05:26:40
          9                              25600             0-07:06:40
          10                             32400             0-09:00:00
          11                             40000             0-11:06:40
          12                             48400             0-13:26:40
          13                             57600             0-16:00:00
          14                             67600             0-18:46:40
          15                             78400             0-21:46:40
          16                             90000             1-01:00:00
          17                            102400             1-04:26:40
          18                            115600             1-08:06:40
          19                            129600             1-12:00:00
          20                            144400             1-16:06:40
          21                            160000             1-20:26:40
          22                            176400             2-01:00:00
          23                            193600             2-05:46:40
          24                            211600             2-10:46:40
          25                            230400             2-16:00:00
          26                            250000             2-21:26:40
          27                            270400             3-03:06:40
          28                            291600             3-09:00:00
          29                            313600             3-15:06:40
          30                            336400             3-21:26:40
          31                            360000             4-04:00:00
          32                            384400             4-10:46:40
          33                            409600             4-17:46:40
          34                            435600             5-01:00:00
          35                            462400             5-08:26:40
          36                            490000             5-16:06:40
          37                            518400             6-00:00:00
          38                            547600             6-08:06:40
          39                            577600             6-16:26:40
          40                            608400             7-01:00:00

5.2. Why can't I send mail to a large site with lots of MX's?

If you're getting:

deferral: CNAME_lookup_failed_temporarily._(#4.4.3)/

The problem might be that qmail can't handle large name server query responses. The fix is to install a patch. See Patches under Advanced Topics.

There's also a question as to why some people don't have trouble reaching such systems. Basically, depending on the timing and ordering of queries made to your local nameserver, the size of the response to an ANY query for "" may be larger than the 512 byte limit of a UDP packet, or it may not.

"May not" is likely to happen if the A and MX records time out, but the NS records don't. Since the .COM servers set a 2 day TTL on those, but AOL sets a 1 hour TTL on their records, this will often happen on less busy nameservers. Busier nameservers are more likely to have those records in their cache at any given time, frustrating an unpatched qmail's attempts to check for CNAMEs.

A better test is to send mail to; if it clears your queue and winds up bouncing from, your MTA can send mail to hosts with MX lists that exceed 512 bytes. (By using a single RRset, with a single TTL, that exceeds 512 bytes, the problem can be seen without depending on the timing and ordering of other

5.3. What is QUEUE_EXTRA?

QUEUE_EXTRA is a compile-time configuration variable that specifies an additional recipient that will be added to every delivery. This is used primarily for logging. E.g., the FAQ describes how to use QUEUE_EXTRA to keep copies of all incoming and outgoing messages.

To use QUEUE_EXTRA, edit extra.h specifying the additional recipient in the format "Trecipient\0", and the length of the QUEUE_EXTRA string in QUEUE_EXTRALEN (the "\0" counts as one character). For example:

    #define QUEUE_EXTRA "Tlog\0"
    #define QUEUE_EXTRALEN 5

Shut down qmail if it's running. If you installed the qmail script from the Installation section, that can be done by:

    /usr/local/sbin/qmail stop

If you don't have the qmail script, you should use your startup/shutdown script or send qmail-send a TERM signal.

Then rebuild qmail using:

    make setup check

Populate ~alias/.qmail-log with whatever logging you want. E.g., to
log Message-ID's:

    | awk '/^$/ { exit } /^[mM][eE][sS][sS][aA][gG][eE]-/ { print }'

Finally, restart qmail.

6. Problems?

These frequently cause problem for qmail newbies.

6.1. qmail doesn't deliver mail to superusers.

To prevent the possibility of qmail-local running commands as a privileged user, qmail ignores all users whose UID is 0. This is documented in the qmail-getpw man page.

That doesn't mean qmail won't deliver to root, it just means that such a delivery will have to be handled by a non-privileged user. Typically, one creates an alias for root by populating ~alias/.qmail-root.

6.2. qmail doesn't deliver mail to users who don't own their home directory.

Another security feature, and just good general practice. This is documented in the qmail-getpw man page.

6.3. qmail doesn't deliver mail to users whose usernames contain uppercase letters.

qmail converts the entire "local part"--everything left of the "@" in an address, to lowercase. The man page doesn't come out and say that, but the code does. The fact that it ignores users with uppercase
characters is documented in the qmail-getpw man page.

6.4. qmail replaces dots (.) in extension addresses with colons (:).

Another security feature. The purpose is prevent extension addresses from backing up the file tree using "..". By replacing them with colons, qmail ensures that all .qmail files for a user are under their home directory. Documented in the qmail-local man page.

6.5. qmail converts uppercase characters in extension addresses to lowercase.

This is another result of the fact that qmail lowercases the entire local part of addresses. Documented in the qmail-local man page.

6.6. qmail doesn't use /etc/hosts.

qmail never uses /etc/hosts to determine the IP address associated with a host name. If you use names in control files, qmail must have access to a name server.

It is possible to run qmail on systems without access to a name server, though. Hosts in control files can be specified by IP address by enclosing them in square brackets ([]), e.g.:


Actually, the square brackets aren't always necessary--but it's a good idea to use them anyway.

6.7. qmail doesn't log SMTP activity.

For a number of reasons, qmail doesn't log SMTP connections, rejections, invalid commands, or valid commands. tcpserver can be used to log connections, and recordio can be used to log the entire SMTP dialogue. recordio is part of the ucspi-tcp package. The procedure is
documented in the FAQ at

6.8. qmail doesn't generate deferral notices.

If Sendmail is unable to deliver a message within a few hours, typically four, it sends a deferral notice to the originator. These notices look like bounce messages, but don't indicate that the delivery has failed permanently, yet.

qmail doesn't send such warnings. An undeliverable message will only be returned to the originator after it spends queuelifetime in the queue.

6.9. qmail is slow if /var/qmail/queue/lock/trigger is gone/has the wrong permissions/is a regular file.

qmail-queue and qmail-send communicate via a named pipe called /var/qmail/queue/lock/trigger. If this pipe gets messed up, qmail-send doesn't notice new messages for a half hour or so.

The best way to ensure that it's set up right is to run "make check" from the source directory. If that's not possible, make sure it looks like:

# ls -l /var/qmail/queue/lock/trigger
prw--w--w-   1 qmails   qmail           0 Jul  5 21:25 /var/qmail/queue/lock/trigger

Pay particular attention to the "p" at the beginning of the line (says it's a named pipe), the mode (especially world writable), and the owner/group.

 7. Further reading

Check these web sites out

Qmail home page:
Qmail FAQ:
Un-official FAQ:
Life with qmail:

Prepared by Abdul Naseer and distributed under OpenContent License (OPL)