2.3 The Pieces of Qmail

Qmail consists of five daemons that run continuously, and about ten other programs run either from those daemons or from other commands, as shown in Figure 2-1.

Figure 2-1. How the qmail daemons connect to each other

The primary daemon is qmail-send, which manages the message queue and dispatches messages for delivery. It is connected to two other daemons, qmail-lspawn and qmail-rspawn, which dispatch local and remote deliveries, respectively, using qmail-local and qmail-remote.

Once a message has been completely processed, with all deliveries having either succeeded or permanently failed, qmail-send notifies qmail-clean to remove the files for the message. The fifth daemon, tcpserver is discussed next.

2.3.1 A Message's Path Through Qmail

A message enters qmail either from another program within the system or via incoming SMTP. Regardless of where the mail originates, the originating program runs qmail-queue, which copies the message to a file in the queue directory, copies the envelope sender and recipient to a second file, and notifies qmail-send. For locally originating mail, qmail-queue is generally called from qmail-inject, or newinject, which adds missing header lines and cleans up address fields. (It's entirely legitimate for programs to call qmail-queue directly if they create messages with all needed headers. Mailing list managers such as Majordomo2 do for efficiency.) Most often, qmail-inject is run from sendmail, a small program that interprets its arguments like the legacy sendmail and calls qmail-inject. It's a useful shim to maintain compatibility with the many applications that call sendmail directly to send mail.

For mail arriving from remote systems, tcpserver runs as a daemon listening for incoming connections on the SMTP port. Each time a connection arrives, it runs qmail-smtpd, which receives a message via SMTP and calls qmail-queue to queue the message.

Regardless of where the message originates, qmail-queue writes the message to a temporary file in the queue/todo directory, putting a new Received: line at the top, and also saves the envelope sender and recipient addresses to files. Then it notifies qmail-send by writing a byte to a "trigger" socket file.

qmail-send takes the message out of queue/todo, and analyzes each recipient address to see if it's local, remote, or virtual.

For local addresses, it notifies qmail-lspawn to run qmail-local to do the local deliveries. For each local delivery, qmail-local sets up the context of the user that controls the delivery address (user id, group id, home directory, and a few environment variables) and then performs the actions listed in the address's .qmail file. Depending on the contents of the .qmail file, the local delivery may store the message into a mailbox, provide a different address to which to deliver the message, run a program to handle the message, or any combination of the three. Qmail doesn't provide any other built-in facilities for local deliveries, instead using separate programs run from .qmail files.

For each remote address, qmail-send notifies qmail-rspawn to run qmail-remote to do the remote deliveries. Every remote address is delivered through a separate SMTP session, even if there are several addresses in the same domain. (This is one of the most controversial features of qmail. See Chapter 11 for some ways you can merge multiple deliveries together and why you probably don't want to.)

For virtual addresses, qmail-send rewrites each virtual address as a modified local address, using the information from the virtualdomains files. (See Chapter 12.) Once it's translated a virtual address to the corresponding local address, the message is delivered the same as to any other local address.

For each delivery, local or remote, the spawn program writes back status reports to qmail-send. Each delivery can succeed, fail temporarily, or fail permanently. A delivery that fails temporarily is retried later until the message is "too old," by default a week, but usually configured to be less. A delivery that fails permanently, or that fails temporarily but is too old, produces a bounce report that is mailed back to the message's envelope sender.

Once all of a message's addresses have succeeded or failed, qmail-send notifies qmail-clean to remove the message's files from the queue, and qmail is done with it.