Receiving Modules

---

First we'll look at the modules comprising the receiving function: sendmail, qmail-inject, qmail-smtpd, qmail-qmtpd, qmail-qmqpd, and qmail-queue.

Local Receiving Modules

Messages injected locally usually come in through qmail-inject or the sendmail wrapper. It's also possible to inject messages using qmail-queue directly, but this is uncommon.

sendmail

The sendmail command is primarily a wrapper around qmail-inject. It accepts many of the Sendmail version's options and arguments, translates them to their qmail-inject equivalents, ignores irrelevant options, and runs qmail-inject.

qmail-inject

qmail-inject's job is ensuring that messages have RFC 2822-compliant headers before passing them on to qmail-queue. Chapter 4, "Using qmail," details how environment variables can adjust the appearance of messages passed through qmail-inject. The qmail-header man page details qmail-inject's header manipulation.

Address Qualification

For e-mail addresses listed in From, To, Cc, and other fields, qmail-inject ensures that they're in the format localpart@qualifieddomain.

• If an address consists only of a localpart, it appends @defaulthost.

• If an address consists only of localpart@hostname, it appends .defaultdomain.

• If an address looks like localpart@hostname+ , it replaces the + with .plusdomain.

Recipients

If no recipients are specified on the command line, qmail-inject looks for recipients in the To, Cc, Bcc, Apparently-To, Resent-To, Resent-Cc, and Resent-Bcc fields. All Bcc and Resent-Bcc fields are stripped from the header.

Because RFC 2822 requires that all messages have a To or CC field, qmail-inject adds one, if necessary, containing this:

 Cc: recipient list not shown: ; 

which is an empty address group.

Required Fields

qmail-inject adds the following fields if they're not provided:

• From-the name of the user who invoked qmail-inject.

• Date-the current time in Greenwich Mean Time (GMT).

• Message-Id-not strictly required by RFC 2822, but handy for tracking messages. The value is <timestamp.pid.qmail@qualifiedhostname>, by default, where qualifiedhostname is constructed from defaulthost and defaultdomain.

Other Features

qmail-inject also does the following:

• Resent-header fields-Resent fields are handled similarly to original fields: Resent-Cc is added if Resent-To and Resent-Cc are missing, and Resent-From and Resent-Date are added if necessary.

• Addresses listed in header fields must be separated by commas, so if qmail-inject sees addresses separated by spaces, it inserts commas. For example, this field:

   To: carol david 

  will be rewritten as this:

   To: carol, david 

• Return-Path and Content-Length fields are stripped.

Remote Receiving Modules

Messages received remotely usually come in through qmail-smtpd, qmail-qmtpd, or qmail-qmpd, depending upon the protocol used.

qmail-smtpd

qmail-smtpd conducts an SMTP session on standard input and standard output, accepts one or more messages, and passes them on to qmail-queue. qmail-smtpd does not handle accepting network connections itself: It must be run by a network server such as tcpserver from the ucspi-tcp package (see Appendix B, "Related Packages"), inetd, or xinetd.

qmail-smtpd expects the environment variables listed in Table A-1 to be set.

Table A-1: TCP Environment Variables

VARIABLE	CONTENTS
PROTO	Always TCP
TCPLOCALHOST	Lowercased domain name of the local host, if available, or unset
TCPLOCALIP	Internet Protocol (IP) address of the local host in dotted-decimal form (x.x.x.x)
TCPLOCALPORT	Local port number of the SMTP session, in decimal
TCPREMOTEHOST	Lowercased domain name of the remote host, if available, or unset
TCPREMOTEINFO	A value, often a username, supplied by the remote host, obtained using the IDENT protocol (RFC 1413), if available, or unset
TCPREMOTEIP	IP address of the remote host in dotted-decimal form
TCPREMOTEPORT	Remote port number of the SMTP session, in decimal

qmail-smtpd begins by displaying a banner message like this:

 220 dolphin.example.com ESMTP 

The 220 is a status code that indicates "no problems." See Appendix C, "An Internet Mail Primer," for more information about Simple Mail Transfer Protocol (SMTP) and its status codes. dolphin.example.com is the local host name, and ESMTP advertises that qmail-smtpd implements some SMTP extensions.

After displaying the banner message, qmail-smtpd reads SMTP commands from the client via standard input and outputs its response to standard output. SMTP requires commands to be issued in a certain order and syntax, and qmail-smtpd enforces these restrictions. It also enforces other restrictions based on environment variables such as RELAYCLIENT and DATABYTES and control files such as badmailfrom, databytes, and rcpthosts. (See Chapter 5, "Managing qmail," for more information about these variables and control files.)

One of the most important checks qmail-smtpd performs is the validation of recipients. Recipients are specified in SMTP RCPT commands, which look like this:

 RCPT TO:<localpart@domain> 

If the RELAYCLIENT environment variable is set-meaning that the client is allowed to relay-the value of the variable is appended to domain, and the modified recipient is added to the list. RELAYCLIENT is usually set to the empty string, so the recipient address is not modified. However, if RELAYCLIENT is inadvertently set to something such as a single space character, this results in making all injections from relay-approved clients fail because of invalid domain names.

Note 

There are legitimate uses of a non-empty RELAYCLIENT. The online qmail FAQ gives an example that uses RELAYCLIENT and control/virtualdomains to implement envelope rewriting (http://cr.yp.to/qmail/faq/servers.html#network-rewriting).

If RELAYCLIENT is not set, qmail-smtpd looks in control/rcpthosts and control/morercpthosts.cdb for domain. If the domain isn't listed, the recipient is rejected with this message:

 553 sorry, that domain isn't in my list of allowed rcpthosts (#5.7.1) 

Accepted messages are passed to qmail-queue to be placed in the queue. If successful, qmail-smtpd reports success, accepting responsibility for delivering the message or returning a bounce message to the sender if it's not deliverable.

Note that qmail-smtpd converts SMTP carriage return/linefeed (CR-LF) new-lines into Unix LF newlines, and returns a temporary error when it detects a bare LF-one not preceded by a CR.

qmail-smtpd adds a Received field to each message. This field looks like this:

 Received: from unknown (HELO dolphin.example.com) (127.0.0.1)   by 0 with SMTP; 8 Aug 2001 16:02:00 -0000 

where:

• unknown means that TCPREMOTEHOST was not set.

• dolphin.example.com was the parameter supplied by the client with the HELO command.

• 127.0.0.1 was the value of TCPREMOTEIP.

• 0 was the value of TCPLOCALHOST (in this case, set using the -l option to tcpserver).

• SMTP is the protocol.

• 8 Aug 2001 16:02:00 -0000 is the time and date at which qmail-smtpd received the message.

qmail-qmtpd

qmail-qmtpd does pretty much the same thing that qmail-smtpd does. The difference is that it uses the Quick Mail Transfer Protocol (QMTP) instead of SMTP, which changes the commands and responses. qmail-qmtpd requires the same TCP environment variables listed in Table A-1 and honors the RELAYCLIENT and DATABYTES environment variables and rcpthosts, morercpthosts.cdb, and databytes control files.

qmail-qmqpd

qmail-qmqpd works much like qmail-qmtpd except it does not do any relay control: All recipients are accepted unconditionally. Again, it requires the TCP environment variables listed in Table A-1.

qmail-queue

qmail-queue's job is to accept messages and place them into the queue. It reads a single message from file descriptor zero and an envelope from file descriptor one. Chapter 4, "Using qmail," explains the format of the envelope and qmail-queue's exit status codes.

qmail-queue expects the envelope recipient addresses to be fully specified, including a local part (username, alias, extension address), an @, and a fully qualified domain name.

qmail-queue adds a Received field to the message that looks like this:

 Received: (qmail 16707 invoked from network); 8 Aug 2001 16:02:00 -0000 

where:

• 1607 is qmail-queue's process ID.

• invoked from network means qmail-queue was invoked by user qmaild.

• 8 Aug 2001 16:02:00 -0000 is the time and date at which qmail-queue processed the message.

The invoked from phrase may also indicate that qmail-queue was invoked by the user alias via qmail-local (invoked by alias) or user qmails via qmail-send (invoked for bounce).

How Messages Are Placed in the Queue

To guarantee reliability, placing messages in the queue is done in four stages:

1. A file is created in /var/qmail/queue/pid named after qmail-queue's process ID. The file system assigns the file an inode number guaranteed to be unique on that file system. This is qmail's queue ID for the message.

2. The pid/pid file is renamed to mess/split/inode, and the message is written to the file.

   Note 

   split is the remainder left from dividing inode by the compile-time configuration setting conf-split. For example, if inode is 95 and conf-split is the default, 23, then split is 3 (95 divided by 23 is 4 with a remainder of 3.) Computer scientists call this operation modulo.

3. The file intd/inode is created and the envelope is written to it.

4. intd/inode is linked to todo/inode.

At the moment todo/inode is created, the message has been queued. qmail-send eventually (within 25 minutes) notices the new message, but to speed things up, qmail-queue writes a single byte to lock/trigger, a named pipe that qmail-send watches. When trigger contains readable data, qmail-send is awakened, empties trigger, and scans the todo directory.

qmail-queue kills itself if it hasn't successfully completed queuing the message after 24 hours.

---