max simultaneous remote deliveries
defaultdomain me qmail-inject default domain name
defaulthost me qmail-inject default host name
databytes 0 qmail-smtpd max number of bytes in message (0=no limit)
doublebouncehost me qmail-send host name of double bounce sender
doublebounceto postmaster qmail-send user to receive double bounces
envnoathost me qmail-send default domain for addresses without "@"
helohost me qmail-remote host name used in SMTP HELO command
idhost me qmail-inject host name for Message-ID's
localiphost me qmail-smtpd name substituted for local IP address
locals me qmail-send domains that we deliver locally
me FQDN of system various default for many control files
morercpthosts none qmail-smtpd secondary rcpthosts database
percenthack none qmail-send domains that can use "%"-style relaying
plusdomain me qmail-inject domain substituted for trailing "+"
qmqpservers none qmail-qmqpc IP addresses of QMQP servers
queuelifetime 604800 qmail-send seconds a message can remain in queue
rcpthosts none qmail-smtpd domains that we accept mail for
smtpgreeting me qmail-smtpd SMTP greeting message
smtproutes none qmail-remote artificial SMTP routes
timeoutconnect 60 qmail-remote how long, in seconds, to wait for SMTP connection
timeoutremote 1200 qmail-remote how long, in seconds, to wait for remote server
timeoutsmtpd 1200 qmail-smtpd how long, in seconds, to wait for SMTP client
virtualdomains none qmail-send virtual domains and users

For more information about a particular control file, see the man page for the module listed under "Used by".

3.2. Relaying

3.2.1. Introduction

What is relaying? It's when an MTA accepts a message via SMTP that doesn't appear to be either for a local address or from a local sender.

In the pre-spam days, it was common for MTA's to be configured as open relays: promiscuous servers that would accept mail from anyone, for anyone.

Most MTA's now are configured to either completely disable relaying, or to only a allow certain trusted users or systems to use them as a relay.

Chris Johnson has written a very nice document on the topic for qmail users. I encourage you to visit http://www.palomine.net/qmail/relaying.html.

3.2.2. Disabling relaying

If you follow the official directions for installing qmail, relaying will be turned off by default. This is accomplished by populating the file /var/qmail/control/rcpthosts with the fully-qualified domain names listed in locals and virtualdomains (the local hosts). The name of the control file, rcpthosts, comes from the SMTP RCPT (recipient) command. In an SMTP session, RCPT is used to specify the addresses of the recipients of a message. rcpthosts, then, lists the valid hostnames that can appear in a RCPT address.

3.2.3. Allowing selective relaying

Most single-user and small workgroup servers can disable relaying completely, but if you have to support a distributed user community, you'll need a way to allow your users, and only your users, to use your system as a relay. This is accomplished by using tcpserver to set the RELAYCLIENT environment variable, which tells qmail-smtpd to override the rcpthosts file.

If you follow the installation instructions in this document, selective relaying will be enabled by default. To give a client relay access, add an entry to /etc/tcp.smtp like:


    IP address of client:allow,RELAYCLIENT=""

Then rebuild the SMTP access database by doing:


    tcprules /etc/tcp.smtp.cdb /etc/tcp.smtp.tmp < /etc/tcp.smtp

    chmod 644 /etc/tcp.smtp*

If you followed the official installation instructions, Chris Johnson has written another very nice document on how to configure qmail to allow selected hosts to relay. See http://www.palomine.net/qmail/selectiverelay.html.

3.3. Multiple host names

If your system is known by more than one name, e.g., all addresses of the form user@host1.example.com can also be written as user@example.com or user@mail.example.com, then you need to tell qmail this so it'll know which addresses it should deliver locally and which messages it should accept from remote systems.

To do this, just add all of the names to two control files:

3.4. Virtual domains

Virtual domains are similar to the multiple host names discussed in the previous section, but there are some important differences. First, if example.net hosts the virtual domain virtual.example.com, it's generally not true that messages sent to joe@example.net will end up in the same mailbox as messages sent to joe@virtual.example.com. The namespace for each virtual domain is distinct.

With qmail, virtual domains are configured in the virtualdomains file, which consists of one or more entries of the form:


    user@domain:prepend

qmail converts user@domain to prepend-user@domain and treats the result as if domain was local. The user@ part is optional. If it's omitted, the entry matches all @domain addresses.

Returning to the example scenario above, if the example.net mail administrator wanted to create a virtual domain, virtual.example.com, under the administrative control of user john, the following entry in virtualdomains would accomplish that:


    virtual.example.com:john

An incoming message to joe@virtual.example.com would be rewritten as john-joe@virtual.example.com and delivered locally. See the .qmail section, and the extension addresses subsection for more information about how john can manage his virtual domain.

As with multiple host names, all virtual domains must be listed in rcpthosts so qmail-smtpd will know to accept messages addressed to them. However, unlike multiple host names, virtual domains must not be added to locals.


Note: domain name server (DNS) mail exchanger (MX) records must be set up to direct messages for virtual domains to the appropriate mail server. This is a job for the name server administrator and is beyond the scope of this guide.

3.5. Aliases

qmail's standard aliasing mechanism is a natural outgrowth of qmail's local delivery mechanism. qmail-local attempts to deliver a message addressed to localpart@host to a local user named localpart. If no matching user is found, the message is delivered to the alias user, a pseudo-user on all qmail systems whose home directory is /var/qmail/alias.

For example, say you want to create an info@example.com alias that forwards messages to user tom. On example.com, do, as user root:


    echo tom > /var/qmail/alias/.qmail-info

The .qmail section and extension addresses subsection describe how to create .qmail files that specify which aliases exist, and what to do with messages sent to them.

Note that because of the way aliases are implemented in qmail, an alias can never override a valid user's deliveries. E.g., if rachel is a normal user, ~alias/.qmail-rachel will not be used.

The fastforward package provides an alternative aliasing mechanism that puts multiple aliases in a single file compatible with Sendmail's alias database.

The next section, qmail-users, describes another mechanism that can be used to implement aliases.

3.6. qmail-users

qmail-users is a system for assigning addresses to users. A series of configuration files resides under /var/qmail/users. The assign file is a table of assignments. There are two kinds of assignments: simple and wildcard.


Note: assign contains a series of assignments, one per line, followed by a line containing a single dot (.). If you create assign manually, don't forget the dot line.

3.6.1. Simple assignment

A simple assignment looks like:


=address:user:uid:gid:directory:dash:extension:

What this means is that messages received for address will run as user user, with the specified uid and gid, and the file directory/.qmaildashextension will specify how the messages are to be delivered.

3.6.2. Wildcard assignment

A wildcard assignment looks like:


+prefix:user:uid:gid:directory:dash:prepend:

What this means is that messages received for addresses of the form prefixrest will run as user user, with the specified uid and gid, and the file directory/.qmaildashprependrest will specify how the messages are to be delivered.

3.6.3. qmail-user programs

qmail-user has two helper programs: qmail-newu and qmail-pw2u.

qmail-newu processes the assign file and generates a constant database (CDB) file called cdb in /var/qmail/users. CDB is binary format that can be accessed quickly by qmail-lspawn, even when there are thousands of assignments.

qmail-pw2u converts the system user database, /etc/passwd, into a series of assignments suitable for assign. qmail-pw2u uses a set of files to modify the translation rules.


Note: if you use qmail-pw2u, don't forget to re-run qmail-pw2u and qmail-newu whenever you add users, remove users, or change UID's or GID's.

3.7. Spam Control

Chris Hardie has written a good qmail Anti-Spam HOWTO. It's available from http://www.summersault.com/chris/techno/qmail/qmail-antispam.html.


4. Usage

This section covers the usage of qmail by normal users. If you read or send mail on a qmail system, this is where you'll find information about how to do that with qmail.

4.1. .qmail files

Delivery of a user's mail is usually controlled by one or more ".qmail" (pronounced dot kyoo mail) files--files in the user's home directory with names beginning with .qmail. The dot-qmail man page describes .qmail file usage.

.qmail files contain a list of delivery instructions, one instruction per line. The first character of the line determines what kind of delivery is involved:

Character Delivery Type Value
# none (comment) ignored
| program command to be run by shell
/ or . mbox (if last char isn't a /) pathname of mbox (including the / or .)
/ or . maildir (if last char is a /) pathname of maildir (including the / or .)
& forward address to forward message
letter or number forward address to forward message (including the first char)

4.1.1. program delivery

When a program delivery instruction is encountered, qmail starts a shell (/bin/sh) to execute the command and feeds the command a copy of the incoming message on standard input. The qmail-command man page documents the details of this process.

Program delivery is very powerful, and can be used to implement a wide range of functionality such as message filtering, automatically responding to messages, and delivery via third-party delivery agents such as procmail.

E.g.:


    |preline /usr/ucb/vacation djb

This causes qmail to start preline, pass it /usr/ucb/vacation and djb as arguments, and provide a copy of the message on standard input.

4.1.2. mbox delivery

"Mbox" is qmail-speak for the standard UNIX mailbox format, in which multiple messages are stored in a single file and messages are headed with a "From " line. This line looks like a header field, but it isn't one: it's just something the delivery agent adds so mail readers can tell where each message begins.

E.g.:


    ./Mailbox

This causes messages to be appended to $HOME/Mailbox, with a "From " line prepended. A simple mbox mailbox with a single message looks like:


    From user1@example.net Thu May 13 18:34:50 1999

    Received: (qmail 1287205 invoked from network); 13 May 1999 18:34:49 -0000

    From: user1@example.net

    To: user2@example.com

    Subject: hey



    What's up?

The first line was added at delivery by qmail.

4.1.3. maildir delivery

"Maildir" is a mailbox format created by Dan Bernstein to address the shortcomings of the mbox format. A maildir mailbox is a directory containing three subdirectories, new, cur, and tmp. Each message in a maildir mailbox is in a separate file in one of the subdirectories, depending upon its status: new is for unread messages, cur is for messages that have been seen, and tmp is for messages in the process of being delivered. The maildir man page describes the format of a maildir in detail.

One of the benefits of the maildir format is that, even though it doesn't use locking to prevent simultaneous updates from different delivery agents, it's reliable. This means maildir mailboxes can safely reside on NFS-mounted filesystems.

E.g.:


    ./Maildir/

This causes messages to be saved in $HOME/Maildir, a maildir-format mailbox.


Note: qmail-local can deliver mail to maildir mailboxes, but it can't create them. Maildir mailboxes should be created with the maildirmake program that comes with qmail. E.g., "maildirmake ~/Maildir".

4.1.4. forward delivery

Forward deliveries causes the message to be resent to the specified address. Addresses specified in .qmail files can't contain comment fields or extra spaces.

These are wrong:


    &<user@example.com>

    & user@example.com

    &Joe User <user@example.com>

These are correct:


    &user@example.com

    user@example.com

    &user

The first two cause user@example.com to receive a copy of the message. The last sends a copy to the local user user.

4.1.5. extension addresses

qmail supports user-controlled extension addresses. In addition to the base address, username@hostname.domain, users can receive mail at username-extension@hostname.domain. For the remainder of this section, I'll leave off the "@hostname.domain" part since we're considering actions that take place on the local system.

The delivery instructions for username-extension are in ~username/.qmail-extension.

For example, dave-lwq@sparge.example.com is controlled by ~dave/.qmail-lwq on host sparge.

Extensions can have multiple fields, e.g., dave-list-qmail, controlled by ~dave/.qmail-list-qmail. In this example, dave-list-qmail is subscribed to the qmail mailing list, and ~dave/.qmail-list-qmail files the list messages in a separate mailbox.

.qmail files can be wildcarded using -default. So dave-list-qmail could also be handled by ~dave/.qmail-list-default. This would allow one catch-all .qmail file to handle all dave-list-whatever addresses. Note that dave-list wouldn't be handled by ~dave/.qmail-list-default because it doesn't match the "-" after "list".

qmail uses the closest match it finds. E.g., when a message comes in addressed to dave-list-qmail, it'll use the first one of the following that it finds:


    .qmail-list-qmail

    .qmail-list-default

    .qmail-default

If no matching .qmail file is found, the delivery fails and the message bounces back to the sender.

4.2. Sending messages

Mail users don't usually use the MTA directly to send messages. Typically, messages are composed and sent using a Mail User Agent (MUA) such as pine or mutt, which then calls the MTA to deliver the message. The process of handing a message to the MTA is called injection.

There are two ways to inject messages into most MTA's: via the Simple Mail Transfer Protocol, SMTP, or using a program provided by the MTA for that purpose.

4.2.1. SMTP

MUA's can open a TCP connection to port 25, the standard SMTP port, on the local host or a designated mail server. The MUA and the MTA then engage in a dialogue that results in either:

SMTP has no mechanism for authentication, so no username or password is required to send a message. However, many MTA's refuse to accept messages that don't appear to be either from or for a local user. If a properly formatted message is rejected, relaying restrictions are the most likely cause. See the Relaying section for more information about relay configuration.

4.2.2. /var/qmail/bin/sendmail

For many years, Sendmail was theUNIX MTA. It was so ubiquitous, that many programmers just assumed that it was the MTA. As a result, Sendmail's local injection mechanism became the standard Application Programmer's Interface (API) for local mail injection. qmail and other non-Sendmail MTA's provide a sendmail program that works the same way as the real Sendmail's sendmail for local injection.

The qmail sendmail, which is normally in /var/qmail/bin/sendmail, usually replaces the Sendmail sendmail on qmail systems. Typical locations of the sendmail program include:

On a qmail system, "ls -l path-to-sendmail" should show that sendmail is a symbolic link to /var/qmail/bin/sendmail:


  $ ls -l /usr/lib/sendmail

  lrwxrwxrwx   1 root     root           29 Feb 19 11:04 /usr/lib/sendmail -> /var/qmail/bin/sendmail

The sendmail man page provided with qmail describes how to use the program.

4.2.3. qmail-inject

In addition to emulating the sendmail API, i<qmail> has its own injection program: qmail-inject. In fact, sendmail is just a wrapper around qmail-inject.

As an API, sendmail is probably better because it's much more widely available. The qmail API provided by qmail-inject will only work on systems with qmail, but the sendmail interface is nearly universal.

For example, to send a blank message to joe@example.com:


 echo To: joe@example.com | /var/qmail/bin/qmail-inject

4.3. Environment Variables

Some qmail programs set or use environment variables. The following table lists these variables and describes their use.

Name Man page Set or used Purpose
DATABYTES qmail-smtpd used Overrides control/databytes
DEFAULT qmail-command set Portion of address matching "-default" in a .qmail file name.
DTLINE qmail-command set Delivered-To header field
EXT qmail-command set The address extension
EXT2 qmail-command set Portion of EXT following first dash
EXT3 qmail-command set Portion of EXT following second dash
EXT4 qmail-command set Portion of EXT following third dash
HOME qmail-command set The user's home directory
HOST qmail-command set The domain part of the recipient address
HOST2 qmail-command set Portion of HOST preceding last dot.
HOST3 qmail-command set Portion of HOST preceding second-to-last dot
HOST4 qmail-command set Portion of HOST preceding third-to-last dot
LOCAL qmail-command set The local part of the recipient address
LOGNAME qmail-inject used User name in From header field (4)
MAILHOST qmail-inject used Host name in From header field (2)
MAILNAME qmail-inject used Personal name in From header field (2)
MAILUSER qmail-inject used User name in From header field (2)
NAME qmail-inject used Personal name in From header field (3)
NEWSENDER qmail-command set Forwarding sender address (see "man dot-qmail")
QMAILDEFAULTDOMAIN qmail-inject used Overrides control/defaultdomain
QMAILDEFAULTHOST qmail-inject used Overrides control/defaulthost
QMAILHOST qmail-inject used Host name in From header field (1)
QMAILIDHOST qmail-inject used Overrides control/idhost
QMAILINJECT qmail-inject used Specify various options (see next table)
QMAILMFTFILE qmail-inject used File containing list of mailing list addresses for Mail-Followup-To generation
QMAILNAME qmail-inject used Personal name in From header field (1)
QMAILPLUSDOMAIN qmail-inject used Overrides control/plusdomain
QMAILSHOST qmail-inject used Host name in envelope sender address
QMAILSUSER qmail-inject used User name in envelope sender address
QMAILUSER qmail-inject used User name in From header field (1)
RECIPIENT qmail-command set Envelope recipient address
RELAYCLIENT qmail-smtpd used Ignore control/rcpthosts and append value to recipient address
RPLINE qmail-command set Return-Path header field
SENDER qmail-command set Envelope sender address
UFLINE qmail-command set UUCP-style "From " line
USER qmail-command set The current user
USER qmail-inject used User name in From header field (3)
QMAILINJECT Flags
Letter Purpose
c Use address-comment style for the From field
s Do not look at any incoming Return-Path field
f Delete any incoming From field
i Delete any incoming Message-ID field
r Use a per-recipient VERP
m Use a per-message VERP

5. Advanced Topics

5.1. procmail

procmail is a popular Message Delivery Agent (MDA). The function of an MDA is to accept a message from the MTA for a specific user or mailbox, and deliver the message according to the user's desires. procmail can be used to "filter" messages by the content of various header fields or the body of the message. For example, messages from a particular person can be directed to a mailbox for just that person.

There are a couple tricks to running procmail with qmail. First, procmail is usually built to deliver to an mbox mailbox in /var/spool/mail. You can rebuild procmail to default to $HOME or you can instruct users not to rely on procmail to default the location of the mbox. Unless you patch it for $HOME delivery, procmail will still use /var/spool/mail for temporary files.

Another problem is that qmail-command and procmail don't have a common understanding of which exit codes mean what. procmail uses the standard UNIX exit codes: zero means success, nonzero means failure, and the cause of the failure is indicated by /usr/include/sys/errno.h. qmail-command uses certain nonzero codes to indicate permanent errors and the rest are considered temporary. A small shell script wrapper can be used to translate the exit codes for qmail-command. Such a wrapper was posted to the qmail list and is available from the archives at http://www.ornl.gov/its/archives/mailing-lists/qmail/1998/04/msg00487.html.

Also, older versions of procmail (prior to 3.14) don't deliver directly to maildir-format mailboxes. Your best bet is to upgrade to the current version of procmail. Another approach is safecat, a program that writes a message on standard input to a specified maildir. Users can write procmail recipes (delivery instructions) that use safecat to file the message. You can also skip procmail altogether, and use maildrop.

Finally, procmail expects the messages it receives to be in mbox format. Normal qmail program deliveries include only the actual mail message, not including a "From " line. The preline command can be used to format the message as procmail expects.

For example, let's say user "dave" wants his mail to be processed by procmail. His system administrator has built procmail to deliver to $HOME by default, and has provided an exit code wrapper, called /usr/local/bin/qmail-procmail. His .qmail file should look like:


|/var/qmail/bin/preline /usr/local/bin/qmail-procmail dave

5.2. POP and IMAP servers

qmail includes a POP server, qmail-pop3d, but it's not configured and installed as part of the qmail installation process. You can also use one of the other POP or IMAP servers available, although most of them were written for Sendmail and will require some work to use with qmail.

5.2.1. qmail-pop3d

qmail-pop3d is the POP server included with qmail. It's a fine POP server, and many qmail sites use it. It's modular, and supports multiple authentication schemes via alternative authentication modules.


Note: qmail-pop3d supports only maildir-format mailboxes, so if you have users logging into the POP server and running MUA's locally, they all have to support maildir. If all of your users read mail via POP, the mailbox format on the server is not an issue.

5.2.1.1. Architecture of qmail-pop3d

A qmail-pop3d server consists of three modules:

Typically, qmail-popup is run via inetd or tcpserver, listening to port 110, the POP3 port. When a connection is made, it prompts for the username and password. Then it invokes checkpassword, which verifies the username/password and invokes qmail-pop3d if they match.

5.2.1.2. Installation of qmail-pop3d

  1. Completely install and test qmail. If you want all users to have POPable mailboxes, make sure defaultdelivery is set to ./Maildir/. If you installed the qmail script from the Installation section, this is configured in control/defaultdelivery. If not, it's probably in /var/qmail/rc on the qmail-start command line.
  2. Download a checkpassword program from http://www.qmail.org/top.html#checkpassword. The standard checkpassword, http://cr.yp.to/checkpwd.html, is a good choice if you don't need anything fancy.
  3. Compile and install checkpassword according to the directions. Make sure you install it as /bin/checkpassword.
  4. For a lightly-used POP server, add an entry to /etc/inetd.conf like the following, all on one line:

pop3   stream  tcp     nowait  root    /var/qmail/bin/qmail-popup qmail-popup

    hostname.domain /bin/checkpassword /var/qmail/bin/qmail-pop3d Maildir


Note: Some systems, notably Red Hat Linux, don't call the POP3 port "pop3". Check /etc/services for the name of the service on port 110. Also, check your inetd man page to ensure the entry is formatted correctly. One tricky part is that some inetd's require the first argument to the program (qmail-popup in this example) to be the name of the program. Other inetd's want only the "real" arguments.

  1. "kill -HUP PID of inetd" to tell inetd to reread /etc/inetd.conf.
  2. For a busier service, use tcpserver instead.

To use tcpserver, add the following to your qmail startup script (not inetd.conf):


    tcpserver -v -R 0 pop3 /var/qmail/bin/qmail-popup FQDN \

        /bin/checkpassword /var/qmail/bin/qmail-pop3d Maildir 2>&1 | \

        /var/qmail/bin/splogger pop3d &

where pop3 is the name of the POP3 service listed in /etc/services and FQDN is the fully qualified domain name of the POP server you're setting up, e.g., pop.example.net.

5.2.2. qpopper

If you need a POP daemon that works with mbox-format mailboxes, you can use Qualcomm's qpopper. Vince Vielhaber has a patch available from http://www.qmail.org/qpopper2.53.patch.tar.gz that makes it work with mailboxes in user home directories. qpopper is available from http://www.eudora.com/freeware/qpop.html.

5.2.3. Solid

The Solid POP3 server supports both maildir and mbox mailboxes. It's available from http://solidpop3d.pld.org.pl/.

5.2.4. imap-maildir