|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".
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.
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.
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.
If your system is known by more than one name, e.g., all addresses of the form email@example.com can also be written as firstname.lastname@example.org or email@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:
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 firstname.lastname@example.org will end up in the same mailbox as messages sent to email@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:
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:
An incoming message to firstname.lastname@example.org would be rewritten as email@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.
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 firstname.lastname@example.org 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.
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.
A simple assignment looks like:
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.
A wildcard assignment looks like:
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.
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.
Chris Hardie has written a good qmail Anti-Spam HOWTO. It's available from http://www.summersault.com/chris/techno/qmail/qmail-antispam.html.
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.
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:
||||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)|
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.
|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.
"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.
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 email@example.com Thu May 13 18:34:50 1999 Received: (qmail 1287205 invoked from network); 13 May 1999 18:34:49 -0000 From: firstname.lastname@example.org To: email@example.com Subject: hey What's up?
The first line was added at delivery by qmail.
"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.
This causes messages to be saved in $HOME/Maildir, a maildir-format mailbox.
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:
&<firstname.lastname@example.org> & email@example.com &Joe User <firstname.lastname@example.org>
These are correct:
&email@example.com firstname.lastname@example.org &user
The first two cause email@example.com to receive a copy of the message. The last sends a copy to the local user user.
qmail supports user-controlled extension addresses. In addition to the base address, firstname.lastname@example.org, users can receive mail at email@example.com. 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, firstname.lastname@example.org 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.
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.
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.
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.
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 email@example.com:
echo To: firstname.lastname@example.org | /var/qmail/bin/qmail-inject
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|
|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")|
|QMAILHOST||qmail-inject||used||Host name in From header field (1)|
|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)|
|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)|
|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|
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
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.
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.
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.
pop3 stream tcp nowait root /var/qmail/bin/qmail-popup qmail-popup hostname.domain /bin/checkpassword /var/qmail/bin/qmail-pop3d Maildir
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.
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.
The Solid POP3 server supports both maildir and mbox mailboxes. It's available from http://solidpop3d.pld.org.pl/.