Control Files Reference

 < Free Open Study > 



You configure qmail mostly by setting variables in control files in the /var/qmail/control directory. Each file in this directory contains the value or values for a single control setting. All of the control files are optional except one: me, which must contain the fully qualified domain name of the host system. The me setting is not used directly by any of the programs in the qmail suite; it's used as the default for other controls that specify a host name.

The qmail-control man page is a handy reference listing the control files, their default values, and the specific program that uses them. To find out what a control file controls, you must check the man page for the specified program.

Understanding the Format

The following sections document each of the control files.

Each section contains the following information:

  • Used by shows which qmail program uses the control file. If you want to consult the man page that documents the control file, this field identifies the appropriate page.

  • Default shows the value that will be used for the control if the control file doesn't exist. If the default is me, then the value used is the value contained in the me control file.

  • Comments indicates whether the control file can contain comment lines—lines beginning with a pound sign (#) that are ignored by the program that uses the file.

  • Purpose describes the function of the control setting.

  • Caveats provides some usage tips and cautions and documents any actions that must be taken for a change to the control file to take effect.

  • Example provides an example of the usage of the control file.

Caution 

Unless comments are allowed, the settings in a control file must start on the first line of the file. Control files must not contain extraneous spaces, tabs, or blank lines.

badmailfrom

Used by: qmail-smtpd

Default: None

Comments: Yes

Purpose: A list of addresses from which the SMTP server will reject mail. Each entry must be listed on a separate line. Hosts may be wildcarded by leaving the local part of the address empty.

Caveats: As the name badmailfrom implies, entries are matched against the argument of the SMTP MAIL FROM command, not the "From:" header field in the message. If you think badmailfrom isn't working, chances are good that the "From:" field doesn't match the envelope sender.

Example: To reject mail with an envelope return path of spammer@example.com and all addresses at freemoney.example.net, place the following in the badmailfrom file:

 # Reject mail from known spammers spammer@example.com @freemoney.example.net 

bouncefrom

Used by: qmail-send

Default: MAILER-DAEMON

Comments: No

Purpose: The username in the From header field of bounce messages. The complete From field of a bounce message is generated from bouncefrom@bouncehost.

Caveats: qmail-send must be restarted to change bouncefrom.

Example: To have bounce messages appear to come from the postmaster, place the following in the bouncefrom file:

 postmaster 

bouncehost

Used by: qmail-send

Default: me

Comments: No

Purpose: The host name in the From header field of bounce messages. The complete From field of a bounce message is generated from bouncefrom@bouncehost.

Caveats: qmail-send must be restarted to change bouncehost.

Example: To have bounce messages appear to come from example.com, place the following in the bouncehost file:

 example.com 

concurrencyincoming

Used by: tcpserver

Default: None

Comments: No

Purpose: Limits the number of concurrent incoming SMTP sessions—the number of qmail-smtpd processes that tcpserver will allow.

Caveats: concurrencyincoming is not a standard qmail control file. It's implemented in the qmail-smtpd/run script suggested in the online "Life with qmail" guide and in the installation instructions in Chapter 2, "Installing qmail," of this book. Changing concurrencyincoming requires restarting the qmail-smtpd tcpserver process, which is usually accomplished by doing this:

 svc -t /service/qmail-smtpd 

Example: To limit incoming SMTP connections to 100, place the following in the concurrencyincoming file:

 100 

concurrencylocal

Used by: qmail-send

Default: 10

Comments: No

Purpose: The maximum number of simultaneous local deliveries.

Caveats: Set too low, concurrencylocal will unnecessarily delay incoming mail. Set too high, a flood of incoming messages will cause qmail-lspawn to spawn more qmail-local processes than the system can handle. qmail-send must be restarted to change concurrencylocal. The maximum allowable concurrencylocal value is limited by the compile-time setting in conf-spawn (see Chapter 2, "Installing qmail," for more information on compile-time configuration settings).

Example: To limit concurrent local deliveries to 30, place the following in the concurrencylocal file:

 30 

Tip 

The default value of 10 is fine for small systems, but a busy mail system with many mailboxes will require a higher limit. If your qmail-send logs indicate that you're frequently hitting the limit, you should consider raising it.

concurrencyremote

Used by: qmail-send

Default: 20

Comments: No

Purpose: The maximum number of simultaneous remote deliveries.

Caveats: Set too low, concurrencyremote will unnecessarily delay outgoing mail. Set too high, a flood of outgoing messages will cause qmail-rspawn to spawn more qmail-remote processes than the system can handle. qmail-send must be restarted to change concurrencyremote. The maximum allowable concurrencyremote value is limited by the compile-time setting in conf-spawn (see Chapter 2, "Installing qmail," for more information on compile-time configuration settings).

Example: To limit concurrent remote deliveries to 100, place the following in the concurrencyremote file:

 100 

Tip 

The default value of 20 is fine for small systems, but a busy mail system will require a higher limit. If your qmail-send logs indicate that you're frequently hitting the limit, you should consider raising it.

databytes

Used by: qmail-smtpd

Default: 0

Comments: No

Purpose: Limits the size, in bytes, of messages received via SMTP. A setting of 0 (zero) means message size is unlimited.

Caveats: Can be overridden by the DATABYTES environment variable. Applies to bytes as stored on disk, so line breaks count as one byte (newline) instead of two (carriage return, linefeed). The qmail-smtpd Received line, the qmail-queue Received line, and the envelope (sender, recipient) aren't counted.

Example: To restrict SMTP-injected local messages and messages from remote hosts to 2 million bytes, place the following in the databytes file:

 2000000 

Tip 

tcpserver can be used to set the DATABYTES environment variable higher for a set of hosts trusted to send larger messages—or to set lower limits for problem hosts. See the "Allowing Selective Relaying" section later in this chapter for an example of using tcpserver to selectively set an environment variable.

defaultdelivery

Used by: /var/qmail/rc

Default: None

Comments: No

Purpose: Specifies delivery instructions for deliveries that don't use a .qmail file. The defaultdelivery argument to qmail-start is the contents of a default .qmail file.

Caveats: defaultdelivery is not a standard qmail control file. It's implemented in the /var/qmail/rc script suggested in the online "Life with qmail" guide and in the installation instructions in Chapter 2, "Installing qmail," of this book. Changing defaultdelivery requires restarting qmail-send, which is usually accomplished by doing:

 svc -t /service/qmail-send 

Note 

defaultdelivery only specifies the delivery instructions that are used when none are specified in a .qmail file, so defaultdelivery can't be used to impose system-wide delivery instructions. However, if users don't have the ability to create .qmail files, they won't be able to override defaultdelivery.

Example: Use the following defaultdelivery file to have default deliveries go through the dot-forward package (for Sendmail .forward compatibility) and to deliver to mailboxes in /var/spool/mail/username using procmail:

 |dot-forward .forward |preline procmail 

defaultdomain

Used by: qmail-inject

Default: me

Comments: No

Purpose : The domain name supplied to messages whose From field doesn't contain one.

Caveats: Can be overridden by the QMAILDEFAULTDOMAIN environment variable (see Chapter 4, "Using qmail," for more information about qmail-inject environment variables). See also plusdomain and defaulthost.

Example: To set the default domain to virtual.example.com, place the following in the defaultdomain file:

 virtual.example.com 

So if a message is injected with a From field of andy@v-roys, qmail-inject will change it to:

 From: andy@v-roys.virtual.example.com 

defaulthost

Used by: qmail-inject

Default: me

Comments: No

Purpose: The host name supplied to messages whose From field doesn't contain one.

Caveats: Can be overridden by the QMAILDEFAULTHOST environment variable (see Chapter 4, "Using qmail," for more information on environment variables). See also plusdomain and defaultdomain.

Example: To set the default host to judybats, place the following in the defaulthost file:

 judybats 

So if a message is injected with a From field of andy, and defaultdomain is set to example.com, qmail-inject will change it to:

 From: andy@judybats.example.com 

doublebouncehost

Used by: qmail-send

Default: me

Comments: No

Purpose: The host name to which messages about undeliverable bounce messages (double bounces) are sent. The complete recipient address of double bounce messages is generated from doublebounceto@doublebouncehost. Permanently undeliverable double bounces are discarded.

Caveats: qmail-send must be restarted to change doublebouncehost.

Example: To have double bounce messages sent to mail.example.com, place the following in the doublebouncehost file:

 mail.example.com 

doublebounceto

Used by: qmail-send

Default: postmaster

Comments: No

Purpose: The user to which messages about undeliverable bounce messages (double bounces) are sent. The complete recipient address of double bounce messages is generated from doublebounceto@doublebouncehost. Permanently undeliverable double bounces are discarded.

Caveats: qmail-send must be restarted to change doublebounceto.

Example: To have double bounce messages sent to doublebounce-handler on the local host, leave doublebouncehost unset and set doublebounceto to:

 doublebounce-handler 

envnoathost

Used by: qmail-send

Default: me

Comments: No

Purpose: The default host name for envelope recipient addresses that don't contain an at sign (@).

Caveats: None

Example: To have qmail-send append @mail.example.net to envelope recipient addresses that don't contain an at sign, place the following in the envnoathost file:

 mail.example.net 

helohost

Used by: qmail-remote

Default: me

Comments: No

Purpose: Specifies the host name used by the SMTP client in the HELO command.

Caveats: None

Example: To have qmail-remote identify the system as example.net during the initiation of SMTP sessions with remote hosts, place the following in the helohost file:

 example.net 

idhost

Used by: qmail-inject

Default: me

Comments: No

Purpose: Specifies the host name used in Message-ID header fields generated by qmail-inject.

Caveats: Can be overridden by the QMAILIDHOST environment variable. Must be a fully qualified domain name and must be different on each system.

Example: To prevent the host name from appearing in Message-ID fields, using the domain name fakename.example.com instead, place the following in the idhost file:

 fakename.example.com 

localiphost

Used by: qmail-smtpd

Default: me

Comments: No

Purpose: Specifies the host name that qmail-smtpd will substitute for hosts specified as Internet Protocol (IP) addresses. If a message arrives addressed to user@[192.168.1.1], and 192.168.1.1 is an IP address of the local system, qmail-smtpd will rewrite the address as user@localiphost.

Caveats: None

Example: To have local IP addresses rewritten as extropy.example.com, place the following in the localiphost file:

 extropy.example.com 

locals

Used by: qmail-send

Default: me

Comments: Yes

Purpose: List of domain names, one per line, whose messages are to be delivered on the local system.

Caveats: Virtual domains are not considered local (see also virtualdomains). The domains listed in locals should also be listed in rcpthosts if you want remote systems to be able to send to them. qmail-send must be sent a HUP signal or restarted to change locals.

Example: To identify localhost, myhost.example.com, and www.example.com as aliases for the system, place the following in the locals file:

 localhost myhost.example.com www.example.com 

me

Used by: Various

Default: None

Comments: No

Purpose: Specifies the fully qualified domain name of the system to be used as a default by various qmail modules for control files that require a host name. me is usually set by config or config-fast during installation.

Caveats: Must be a fully qualified domain name. qmail-send must be restarted to change me.

Example: If you rename your system from extract.example.com to allgrain.example.com, place the following in the me file:

 allgrain.example.com 

morercpthosts

Used by: qmail-smtpd

Default: None

Comments: No

Purpose: An optional database of rcpthosts entries.

Caveats: You must run qmail-newmrh after modifying morercpthosts to build a new morercpthosts.cdb.

Example: To add virtual.example.net to morercpthosts, execute the following commands:

 # echo virtual.example.net > /var/qmail/control/morercpthosts # qmail-newmrh # 

Tip 

If you have many more than 50 entries in rcpthosts, leave the 50 most used entries there and put the rest in morercpthosts.

percenthack

Used by: qmail-send

Default: None

Comments: Yes

Purpose: A list of domains to which Sendmail-style "percent hack" routed addresses can be used. For instance, if example.com is listed in percenthack, an address like user%domain@example.com will be changed to user@domain.

Caveats: If any domain is listed in both rcpthosts and percenthack, your system becomes an open relay. For this reason, percenthack should not be used on systems that accept mail from untrusted hosts. Percent hack routed addresses are deprecated, and selective relaying, as described later in this chapter, is a better and safer way to accomplish the same goal.

Example: To allow mail addressed to gateway.example.net to use routed addresses, place the following in the percenthack file:

 gateway.example.net 

plusdomain

Used by: qmail-inject

Default: me

Comments: No

Purpose: A domain name that is added to host names ending with a plus sign (+).

Caveats: Can be overridden by the QMAILPLUSDOMAIN environment variable.

Example: If you'd like addresses like user@host.sub+ on locally injected mail to be rewritten to user@host.sub.example.com, place the following in the plusdomain file:

 example.com 

qmqpservers

Used by: qmail-qmqpc

Default: None

Comments: Yes

Purpose: A list of the IP addresses of QMQP servers. The servers will be tried in order until qmail-qmqpc is able to connect to a server or exhausts the entire list.

Caveats: None

Example: To specify that qmail-qmqpc should first contact the QMQP server at 192.168.1.3, followed by 192.168.1.5, place the following in the qmqpservers file:

 192.168.1.3 192.168.1.5 

queuelifetime

Used by: qmail-send

Default: 604800 seconds (1 week)

Comments: No

Purpose: The maximum length of time that a temporarily undeliverable message will remain in the queue. When a message's lifetime expires, one last attempt is made to deliver the message before the message is bounced as permanently undeliverable.

Caveats: If it's set too short, some messages will bounce that could have been successfully delivered with a longer lifetime. If it's set too long, undeliverable messages won't be bounced in a timely manner.

Example: To set the queue lifetime to four days, 60 x 60 x 24 x 4 = 345,600 seconds, place the following in the queuelifetime file:

 345600 

Tip 

Shorter lifetimes (one to two days) are useful on personal systems because they provide more timely indication of delivery problems. Longer lifetimes (four to seven days) are usually used on mail servers and hubs to ensure a high rate of delivery and resilience to temporary network and host outages.

rcpthosts

Used by: qmail-smtpd

Default: None

Comments: Yes

Purpose: The list of domains for which the local server will accept mail via SMTP. The name of this control file comes from the SMTP RCPT TO command, which identifies the recipient(s) of the message.

Usage: rcpthosts supports wildcard matching of domains. An entry of the form .domain matches all domain names ending with .domain.

Caveats: Without a rcpthosts file, your system will be an open relay—accepting mail from remote systems intended for users on other remote systems. Generally, rcpthosts should contain all hosts listed in locals and virtualdomains. If the RELAYCLIENT environment variable is set, qmail-smtpd skips checking rcpthosts and appends the value of RELAYCLIENT to each recipient address.

Warning 

If you remove the rcpthosts file, your system will immediately become an open relay that can be used by junk mailers to distribute large numbers of unwanted messages to their victims.You probably don't want to appear to be cooperating in this abuse, which can result in your server being blacklisted by other hosts. If you're ever tempted to remove this file, you should enable selective relaying as described later in this chapter.

Example: The example.com mail server has localhost, example.com, and mail.example.com in locals and virtual.example.com in virtualdomains. The rcpthosts file should contain

 localhost example.com mail.example.com virtual.example.com 

smtpgreeting

Used by: qmail-smtpd

Default: me

Comments: No

Purpose: Sets the SMTP greeting banner.

Caveats: The local host name should be the first thing in the greeting. Only the first line will be used.

Example: On the host mail.example.com, to add a warning about abuse, place the following in the smtpgreeting file:

 mail.example.com -=NO UNSOLICITED BULK E-MAIL=- 

This will look like

 # telnet 0 25 Trying 0.0.0.0. . . Connected to 0. Escape character is '^]'. 220 mail.example.com -=NO UNSOLICITED BULK E-MAIL=- ESMTP quit 221 mail.example.com -=NO UNSOLICITED BULK E-MAIL=- Connection closed by foreign host. # 

Note 

The telnet command above uses 0 (zero) as short-hand for the local host. The results are the same as using localhost, 0.0.0.0, 127.0.0.1, the host name, or the domain name of the local host.

smtproutes

Used by: qmail-remote

Default: None

Comments: Yes

Purpose: Specifies "artificial" SMTP routes—hardwired routes that override Domain Name System (DNS) Mail eXchanger (MX) records.

Usage: The general format of each entry is: domain:relay[:port]. If the host part of a recipient address matches domain, the message will be delivered to relay as if relay were the sole MX listed for domain. If port is specified, the connection is made to that port number.

Domains may be wildcarded. For example

 .example.net:mail.example.net 

will match any domain ending in .example.net. And

 :mail.example.net 

will match all domains.

The relay field can be left blank to indicate that MX records should be consulted in the usual manner. So the following pair of entries:

 .example.net: :mail.example.net 

says that mail to domains ending with .example.net should be delivered through their MX records, and all other mail should be delivered through mail.example.net.

Caveats: Be careful to avoid creating routing loops using smtproutes.

Example: To forward all mail for the local domain example.com from the local host, perhaps outside a firewall, to a local hub inside the firewall, place the following in the smtproutes file:

 .example.com:mailhub.example.com example.com:mailhub.example.com 

The second line is necessary because the wildcard in the first line doesn't match example.com.

timeoutconnect

Used by: qmail-remote

Default: 60 seconds

Comments: No

Purpose: Sets the number of seconds that qmail-remote will wait for a connection to be established with a remote SMTP server.

Caveats: Most operating systems impose a 75-second upper limit on initial connection timeout.

Example: To lower the limit to 30 seconds, place the following in the timeoutconnect file:

 30 

timeoutremote

Used by: qmail-remote

Default: 1200 seconds (20 minutes)

Comments: No

Purpose: Sets the number of seconds that qmail-remote will wait for each response from a command sent to remote SMTP server.

Caveats: If it's set too short, deliveries to some remote systems will time out. If subsequent retries also time out, messages will be bounced as permanently undeliverable. If it's set too long, qmail-remote processes that could be used to deliver to responsive systems will be occupied trying to deliver to unresponsive systems, effectively lowering concurrencyremote.

Example: To lower the limit to 5 minutes, place the following in the timeoutremote file:

 300 

timeoutsmtpd

Used by: qmail-smtpd

Default: 1200 seconds (20 minutes)

Comments: No

Purpose: Sets the number of seconds that qmail-smtpd will wait for each communication from an SMTP client.

Caveats: If it's set too short, the system will prematurely terminate connections with slow systems trying to send mail into your system. These terminated deliveries will have to be retried later and may eventually be deemed permanently undeliverable by the sending system. If it's set too long, qmail-smtpd processes will be tied up with slow clients, effectively lowering the SMTP concurrency.

Example: To lower the limit to five minutes, place the following in the timeoutsmtpd file:

 300 

virtualdomains

Used by: qmail-send

Default: None

Comments: Yes

Purpose: Defines virtual domains and virtual users. Virtual domains are domains with private name spaces; for example, info@virtual.domain.com is a separate mailbox from info@domain.com, in the local domain. Virtual users are single-address virtual domains.

Usage: Virtual domain entries are of the format domain:prepend. A message to user@domain will be converted to prepend-user and delivered locally. For example, with the following virtualdomains entry:

 virtual.example.com:josh-virtual 

A message received for info@virtual.example.com will be delivered locally to josh-virtual-info. The local user josh is the manager of the virtual.example.com domain. By creating .qmail files in his home directory, he can control the disposition of mail to any address at virtual.domain.com. To have mail for info@virtual.domain.com redirected to local user zack, he'd create .qmail-virtual-info containing

 &zack 

Virtual user entries are in the format: user@domain:prepend. A message to user@domain will be converted to prepend-user and delivered locally. For example, with the following entry:

 help@virtual.example.com:josh-virtual 

A message received for help@virtual.example.com will be delivered locally to josh-virtual-help. Again, josh is the manager of this virtual user, which he will control using the file .qmail-virtual-help in his home directory.

Virtual users work exactly like virtual domains except only the addresses specified in virtualdomains are accepted and managed locally. With a virtual.example.com virtual domain, all mail for anything@virtual.example.com must be handled locally. With a something@virtual.example.com virtual user, only mail for something@virtual.example.com will be handled locally. Mail for somethingelse@virtual.example.com will be delivered remotely to the mail exchanger for virtual.example.com.

Virtual domain entries can contain wildcards. A domain like .example.net matches any domain name ending in .example.net. An empty domain matches all domain names.

Virtual domain and user entries can contain exceptions. An empty prepend tells qmail-send not to treat matching addresses as virtual.

Caveats: Domains listed in locals are always treated as local domains. Virtual domains must not be listed in locals.

Examples: On the local system, example.net, create a virtual domain, virtual.example.net, managed by the local user josh. Also create a virtual user, bfie@isp.example.com, which delivers to local user bob. Place the following in the virtualdomains file:

 virtual.example.net:josh-virtual # Use a virtual user entry to intercept a local user's mail before it's forwarded # to his ISP. bfie@isp.example.com:bob 

To use a wildcard virtual domain to catch all remote mail, place the following within the virtualdomains file:

 # Redirect remote mail to alias-catchall, e.g., for serialmail forwarding. # (will be handled by /var/qmail/alias/.qmail-catchall-default) :alias-catchall 

To manage all domains under example.com except example.com and mail.example.com, place the following within the virtualdomains file:

 # Exclude mail.example.com mail.example.com: # Catch *.example.com (but not "example.com") .example.com:josh-example 



 < Free Open Study > 



The Qmail Handbook
The qmail Handbook
ISBN: 1893115402
EAN: 2147483647
Year: 2001
Pages: 186
Authors: Dave Sill

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net