Control Files List

Back

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 (described 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 getting 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