Architecture

---

This section outlines the logical and physical organization of the qmail system.

Modular System Architecture

Internet MTAs perform a variety of tasks. Earlier designs such as Sendmail and Smail are monolithic. They have one large, complex program that "switches hats." In other words, the program puts on one hat to be an SMTP server, another to be an SMTP client, another to inject messages locally, yet another to manage the queue, and so on.

qmail is modular. A separate program performs each of these functions. As a result, the programs are much smaller, simpler, and less likely to contain functional or security bugs. To further enhance security, qmail's modules run with different privileges, and they don't trust each other. In other words, they don't assume the other modules always do only what they're supposed to do. Table 1-3 describes each of qmail's modules.

Table 1-3: The qmail Modules

MODULE	FUNCTION
qmail-smtpd	Accepts/rejects messages via SMTP
qmail-inject	Constructs a message and queues it using qmail-queue
qmail-queue	Places a message in the queue
qmail-rspawn/qmail-remote	Handles remote deliveries
qmail-lspawn/qmail-local	Handles local deliveries
qmail-send	Processes the queue
qmail-clean	Cleans the queue

However, there's also a down side to the modular approach. Unlike a monolithic MTA, the interactions between modules are well defined, and modules only exchange the minimum necessary information with each other. This is generally good, but sometimes it makes it hard to perform certain tasks. For example, the Sendmail -v flag causes Sendmail to print a trace of its actions to standard output for debugging purposes. Because one Sendmail program handles injection, queuing, alias processing, .forward file processing, and remote forwarding via SMTP, it is able to easily trace the entire delivery. The equivalent capability in qmail doesn't exist and would require substantial code changes and additional complexity to implement the passing of the "debug" flag from module to module and the outputting of the debugging information.

File Structure

/var/qmail is the root of the qmail file structure. You can change this when qmail is being built, but it's a good idea to leave it so other administrators know where to find things. If you really want to relocate some or all of the qmail tree, it's better to use symbolic links. See Chapter 2, "Installing qmail," for an example of how to do this. Table 1-4 lists the top-level directories.

Table 1-4: The Top-Level /var/qmail Directories

DIRECTORY	CONTENTS
alias	.qmail files for system-wide aliases
bin	Program binaries and scripts
boot	Startup scripts
control	Configuration files
doc	Documentation, except man pages
man	man pages
queue	The queue of unsent messages
users	The qmail-users database (optional)

Note 

A frequently asked question (FAQ) is "Why is qmail installed under /var?" The answer, available at the qmail site (http://cr.yp.to/qmail/faq/install.html#whyvar), explains that /var is appropriate because most of the files under /var/qmail are system-specific. Chapter 2, "Installing qmail," shows how to relocate branches of the /var/qmail tree under other parts of the file system using symbolic links.

Queue Structure

Appendix A, "How qmail Works," discusses the details of queuing more thoroughly, but even if you don't care about how qmail works internally, you should be familiar with the organization of the queue. Table 1-5 describes the layout of the queue.

Table 1-5: Queue Subdirectories

SUBDIRECTORY	CONTENTS
bounce	Permanent delivery errors
info*	Envelope sender addresses
intd	Envelopes under construction by qmail-queue
local*	Local envelope recipient addresses
lock	Lock files
mess*	Message files
pid	Used by qmail-queue to acquire an inode number
remote*	Remote envelope recipient addresses
todo	Complete envelopes

Note 

Directories marked with an asterisk (*)contain a series of split subdirectories named "0", "1", ..., up to (confsplit-1), where conf-split is a compile-time configuration setting contained in the file conf-split in the build directory. It defaults to 23. The purpose of splitting these directories is to reduce the number of files in a single directory on very busy servers.

Files under the mess subdirectory are named after their inode number. What this means is that you can't manually move them using standard Unix utilities like mv, dump/restore, and tar. There are user-contributed utilities on the Web that will rename queue files correctly after they've been moved or restored (http://www.qmail.org/).

Caution 

It is not safe to modify queue files while qmail is running. If you want to modify the queue, then stop qmail first, alter the queue carefully, and then restart qmail. Chapter 5, "Managing qmail," covers queue management.

Pictures

There is a series of files in /var/qmail/doc with names starting with PIC. These are textual "pictures" of various situations that qmail handles. They show the flow of control through the various modules and are helpful for debugging and creating complex configurations. Table 1-6 describes these files.

Table 1-6: PIC Files

FILENAME	SCENARIO
PIC.local2alias	Locally injected message delivered to a local alias
PIC.local2ext	Locally injected message delivered to an extension address
PIC.local2local	Locally injected message delivered to a local user
PIC.local2rem	Locally injected message delivered to a remote address
PIC.local2virt	Locally injected message delivered to an address on a local virtual domain
PIC.nullclient	A message injected on a null client
PIC.relaybad	A failed attempt to use the local host as a relay
PIC.relaygood	A successful attempt to use the local host as a relay
PIC.rem2local	A message received via SMTP for a local user

---