Qmail Control Files
Qmail is controlled by a large set of control files stored in /var/qmail/control. Unlike some other MTAs that group everything into one huge file that
they have to parse to figure out what's what, qmail puts each different kind of information into a separate file, so that each file needs little or
no parsing. All files are lines of plain text (although a few files are compiled into CDB databases before use). Some, noted below, allow comment lines
with a # at the beginning of the line. In files where each line contains multiple fields, the fields are separated by colons.
Most of the control files are optional, and qmail uses a reasonable default in most cases if a file isn't present. The only files that are absolutely
essential are me, which contains the hostname of the local host, and rcpthosts, which lists the names of the domains for which this host accepts mail.
List of Default Qmail Control Files
Here's a list of all the control files in alphabetical order, noting which component uses each one. Many of the optional patches introduce new control
files, which are discussed during the description of the patch.
badmailfrom (qmail-smtpd)
Envelope addresses not allowed to send mail. If the envelope From address on an incoming message matches an entry in badmailfrom, the SMTP daemon will
reject every recipient address. Entries may be either email addresses, or @dom.ain to reject every address in a domain. This is a primitive form of
spam filtering. These days, it's mostly useful to block quickly a mailbomb or flood of rejection messages.
bouncefrom (qmail-send)
Default: MAILER-DAEMON. The mailbox of the return address to put in bounce messages. I've never found any reason to change it.
bouncehost (qmail-send)
Default: me. The domain of the return address to put in bounce messages. I've never found any need to change it, although it's possible that if your
mail host is mail.example.com, you might want to have the bounces come from example.com.
concurrencylocal (qmail-send)
Default: 10. The maximum number of simultaneous local deliveries. Unless you have very slow delivery programs, the default is adequate for all but very
large systems. Keep in mind that if you have slow delivery programs, it is quite possible to have all 10 or however many running as the same user, so
be sure that the per-user process limit is high enough to permit them all to run.
concurrencyremote (qmail-send)
Default: 20. The maximum number of simultaneous remote deliveries. The default is adequate for small systems, but too low for large systems or systems
that host mailing lists. You should adjust it so that qmail uses as much of your outgoing bandwidth as you want it to. In the distributed version of
qmail, you can increase this up to 120, which is enough for a moderately busy system with mailing lists sharing a T1 with other services. See Chapter
16 for advice on increasing it past 120 on large systems.
defaultdomain (qmail-inject)
Default: the literal string defaultdomain. The domain to add to unqualified host names (names with no dot) on outgoing mail. That is, if someone injects
a message with a sender or recipient address of fred@bad and this file contains example.com, the address is rewritten as fred@bad.example.com. You
invariably want to set this to the local domain. Note that only mail injected via qmail-inject has its header addresses rewritten. Addresses in mail
that arrives via SMTP or is injected directly via qmail-queue aren't modified.
defaulthost (qmail-inject)
Default: me. Similar to defaultdomain; the domain to add to addresses in outgoing mail that have no domain at all. If defaulthost doesn't contain a dot,
defaultdomain is added, too. Set this to the name of the local domain.
databytes (qmail-smtpd)
Default: 0, meaning no limit. The maximum message size to accept via SMTP. I usually set it to about 1/10 the size of the typical amount of free space
on the partition where the qmail queue resides, to keep a single bloated incoming message from causing qmail to run out of disk space. The DATABYTES
environment variable overrides the control file, so if there are certain systems from which you want to accept huge messages, you can put entries into
the SMTP rules file to permit that. For example:
# allow 50 megabyte powerpoints from the boss
209.58.173.10:allow,DATABYTES="50000000"
# allow 20 meg outgoing mail from nearby hosts
172.16.15.1-127.:allow,RELAYCLIENT="",DATABYTES="20000000"
doublebouncehost (qmail-send)
Default: me. The domain to which to send double-bounce messages. There's rarely any reason to change it.
doublebounceto (qmail-send)
Default: postmaster. The mailbox to which to send double-bounce messages, that is, they go to doublebounceto@doublebouncehost. You can also send these
messages to a special mailbox that you examine rarely, or because these days there are vast numbers of double bounces caused by spam with fake return
addresses, you can set it to nobody or some other address that just throws them away.
envnoathost (qmail-send)
Default: me. The domain to add to envelope recipient addresses with no domain. This value is used by qmail-send, while defaultdomain is used by
qmail-inject, so in practice this value is used to fix up mail received by SMTP. The default value is fine, unless you receive a lot of spam with bare
addresses, in which case you can set it to something like invalid to make incoming mail with no domain bounce.
helohost (qmail-remote)
Default: me. The domain to use in the HELO command of outgoing SMTP sessions. The default is fine.
idhost (qmail-inject)
Default: me. The domain to use when creating Message-ID: lines in outgoing mail. The default is fine. If you want to do something special with message
ID's, you can provide them yourself on mail you send, in which case qmail won't alter them.
localiphost (qmail-smtpd)
Default: me. When qmail-smtpd sees incoming mail to an address using a dotted quad rather than a domain name, like fred@[10.11.12.99], and the IP
address is one on this host, it substitutes in localiphost. The default is usually fine unless you want to change it to the local mail domain.
locals (qmail-send)
Default: me. Domains to treat as local. Any addresses in domains listed in this file are considered to be local and are routed using the local delivery
rules. All local domains are equivalent; if foo.org and bar.com both appear in locals, the addresses fred@foo.org and fred@bar.com are handled
identically.[†] This file always includes the name of the local host (the same as what's in me) and generally includes the local domain as well and any
other domains that may have been used for the same set of addresses. For example, the locals file on my mail server tom.iecc.com also includes iecc.com
(the current local domain), iecc.cambridge.ma.us (its old name), and iecc.us (a trendy vanity equivalent.)
Note that local domains are not the same as virtual domains, nor are they the same as the SMTP recipient domains listed in rcpthosts.
me (qmail-send)
Default: none; this file is required. The name of the current host. This should be the same as what the hostname command returns.
morercpthosts (qmail-smtpd and qmail-newmrh)
Default: none. More domains for which this host accepts SMTP mail. The contents of this file are compiled into morercpthosts.cdb by qmail-newmrh. The
SMTP daemon consults the cdb file after it checks rcpthosts. If a host accepts mail for more than about 50 domains, Dan suggests that you put the 50
busiest into rcpthosts and the rest into morercpthosts.
percenthack (qmail-send)
Default: none. The "percent hack" is a primitive form of source routing introduced by sendmail in the early 1980s. If you send mail to user%in.side@out.side,
the mail would be sent to out.side, where the address would be rewritten to user@in.side and sent along to in.side. In the past 20 years, most
of the connectivity problems that require source routing have been solved, and for the ones that remain there are better tools such as smtproutes (de
scribed later), so the percent hack is obsolete. If for some reason you absolutely need it (you have an ancient mission-critical program for which all
the source code has been lost that sends mail using the percent hack, perhaps) any addresses in domains listed in percenthack are scanned for percent
signs and rewritten. In the previous example, out.side would have to be listed there.
If a domain listed in percenthack is also listed in rcpthosts, your system is an open relay, because spammers can send mail anywhere through your system
by putting the actual target address in percent form inside an address in the listed domain. Yes, spammers actually do so. The solution is simple:
don't do it.
plusdomain (qmail-inject)
Default: me. If the domain part of an address in an injected message ends with a plus sign, the contents of plusdomain are appended to the end. In
environments with many subdomains of a single main domain, say east.bigcorp.com, west.bigcorp.com, and south.bigcorp.com, this lets people abbreviate
addresses to fred@south+. No longer widely used.
qmqpservers (qmail-qmqpc)
Default: none. A list of servers to which messages can be queued using QMQP. See Chapter 17.
queuelifetime (qmail-send)
Default: 604800 seconds (a week). How long to keep trying to deliver a message. More precisely, if qmail tries to send a message and the attempt fails
with a temporary error, the error is treated as permanent if the message is older than queuelifetime, in which case the message bounces.
The default time of a week is reasonable, but you might want to decrease it to three or four days if you'd rather know sooner that a message isn't get
ting through, at the risk that the destination host might have come back to life if you'd waited longer.
rcpthosts (qmail-smtpd)
Default: every domain. The list of domains for which this host accepts SMTP mail. It is extremely important that this file exist. If it doesn't, qmail
will accept mail destined for anywhere and will be an "open relay," and a magnet for spammers.
If you receive mail for more than 50 domains, see morercpthosts.
smtpgreeting (qmail-smtpd)
Default: me. When another hosts connects via SMTP to send you mail, the greeting string to send. The default is fine.
smtproutes (qmail-remote)
Default: none. Explicit routes to use to deliver outgoing mail, overriding MX data. Each line is of one of these forms:
domain:relay
domain:relay:port
Domain is the domain in the destination email address, relay is the name of the host to which to deliver the mail, and the optional port is the port
number if not the standard port 25.
The domain can use wildcards; if it starts with a dot, it matches any target domain that ends with that domain. If the domain is empty, it matches all
addresses, providing "smarthost" routing to send all mail to a single smarthost for delivery. If relay is empty, qmail uses the standard MX lookup,
letting you override a broader wildcard or smarthost route.
Most systems can get by without smtproutes, but there are three situations where it can come in handy. The first is a smarthost, mentioned previously,
if your computer is on a dialup, DSL, or cable modem, and the smarthost is your ISP's outgoing mail server. The second is to temporarily patch around
broken MX records or mail relays. The third is to route mail for private domains within your network.
timeoutconnect (qmail-remote)
Default: 60 seconds. How long to wait for a remote server to accept the initial connection to send mail. Unless you need to exchange mail with extremely
slow and overloaded remote servers, don't change it.
timeoutremote (qmail-remote)
Default: 1200 seconds. Once a remote server is connected, how long to wait for each response before giving up. The default of 20 minutes is extremely
conservative, and can lead to all of your remote sending slots being tied up while waiting for somnolent remote hosts to time out. Unless you communicate
with extraordinarily slow and overloaded remote servers, you can drop it to a minute.
timeoutsmtpd (qmail-smtpd)
Default: 1200 seconds. How long qmail-smtpd waits for each response from a remote client before timing out and giving up. As with timeoutremote, you can
decrease this to a minute unless you have some really slow remote clients.
virtualdomains (qmail-send)
Default: none. The list of virtual users and domains for which this system receives mail. If you don't handle any virtual domains, you don't need this
file.
The virtual domain scheme works by taking the mailbox in the virtual domain, prepending a string and a hyphen to create a local address, and redeliver-
ing the mail to the local address. The virtual domain file lists the prepend string to use for each virtual user and domain. (See Chapter 12.) Each line
is of one of these forms:
user@dom.ain:string (1)
dom.ain:string (2)
.domain:string (3)
domain: (4)
:string (5)
Form (1) controls mail to a specific address. Forms (2) and (3) control mail to any address in a domain or in subdomains of a domain, respectively.
Form (4), with an empty prepend, is used to create an exception to a domain that would otherwise be handled by a line of form (3) or (5) and means to
handle the domain normally, not as a virtual domain. Form (5) is a catchall and controls all domains not listed in locals or elsewhere in virtualdomains.
If a domain erroneously appears both in locals and virtualdomains, the listing in locals takes precedence. Don't do that.
Check your Current settiings
You will want to run the qmail-showctl
/var/qmail/bin/qmail-showctl