Sending Modules

---

Now we'll look at the modules comprising the sending function: qmail-send, qmail-lspawn, qmail-rspawn, qmail-local, and qmail-remote.

qmail-send

qmail-send is the heart of qmail. It processes messages in the queue and dispatches them to qmail-rspawn and qmail-lspawn. Chapter 5, "Managing qmail," covers qmail-send, but we'll examine qmail-send's functions in the order that a message in the queue would experience them: preprocessing, delivery, and cleanup.

Preprocessing

Preprocessing, like queuing, is done in stages:

1. Upon discovering todo/inode, qmail-send deletes info/split/inode, local/split/inode, and remote/split/inode, if they exist.

2. A new info/split/inode is created, containing the envelope sender address.

3. If the message has local recipients, they're added to local/split/inode.

4. If the message has remote recipients, they're added to remote/split/inode.

5. intd/inode and todo/inode are deleted.

At the moment todo/inode is deleted, the message is considered preprocessed.

Recipients are considered local if the domain is listed in control/locals or the entire recipient or domain is listed in control/virtualdomains. If the recipient is virtual, the local part of the address is rewritten as specified in virtualdomains.

Delivery

Initially, all recipients in local/split/inode and remote/split/inode are marked not done, meaning that qmail-send should attempt to deliver to them. On its own schedule, qmail-send sends delivery commands to qmail-lspawn and qmail-rspawn using channels set up by qmail-start. When it receives responses from qmail- lspawn or qmail-rspawn that indicate successful delivery or permanent error, qmail-send changes their status in local/split/inode or remote/split/inode to done, meaning that it should not attempt further deliveries. When qmail-send receives a permanent error, it also records that in bounce/split/inode.

Bounce messages are also handled on qmail-send's schedule. Bounces are handled by injecting a bounce message based on mess/split/inode and bounce/split/inode, and deleting bounce/split/inode.

When all of the recipients in local/split/inode or remote/split/inode are marked done, the respective local or remote file is removed.

Retry Schedules

qmail-send uses a simple formula to determine the times at which messages in the queue are retried. If attempts is the number of failed delivery attempts so far, and birth is the time at which a message entered the queue (determined from the creation time of the queue/info file), then:

nextretry = birth + (attempts c)²

where c is a retry factor equal to 10 for local deliveries and 20 for remote deliveries. Table A-2 shows the complete retry schedule for a remote message that's never successfully delivered, with the default queuelifetime of 604,800 seconds.

Table A-2: Remote Message Retry Schedule

DELIVERY ATTEMPT	SECONDS	DAY-HOUR:MIN:SEC
1	0	0-00:00:00
2	400	0-00:06:40
3	1,600	0-00:26:40
4	3,600	0-01:00:00
5	6,400	0-01:46:40
6	10,000	0-02:46:40
7	14,400	0-04:00:00
8	19,600	0-05:26:40
9	25,600	0-07:06:40
10	32,400	0-09:00:00
11	40,000	0-11:06:40
12	48,400	0-13:26:40
13	57,600	0-16:00:00
14	67,600	0-18:46:40
15	78,400	0-21:46:40
16	90,000	1-01:00:00
17	102,400	1-04:26:40
18	115,600	1-08:06:40
19	129,600	1-12:00:00
20	144,400	1-16:06:40
21	160,000	1-20:26:40
22	176,400	2-01:00:00
23	193,600	2-05:46:40
24	211,600	2-10:46:40
25	230,400	2-16:00:00
26	250,000	2-21:26:40
27	270,400	3-03:06:40
28	291,600	3-09:00:00
29	313,600	3-15:06:40
30	336,400	3-21:26:40
31	360,000	4-04:00:00
32	384,400	4-10:46:40
33	409,600	4-17:46:40
34	435,600	5-01:00:00
35	462,400	5-08:26:40
36	490,000	5-16:06:40
37	518,400	6-00:00:00
38	547,600	6-08:06:40
39	577,600	6-16:26:40
40	608,400	7-01:00:00

The local message retry schedule is similar, but because of the lower c , messages are retried twice as often.

Cleanup

When both local/split/inode and remote/split/inode have been removed, the message is dequeued by:

1. Processing bounce/split/inode, if it exists.

2. Deleting info/split/inode.

3. Deleting mess/split/inode.

Partially queued and partially dequeued messages left when a system crash interrupts qmail-queue or qmail-send are deleted by qmail-send using qmail-clean, another long-running daemon started by qmail-start. Messages with a mess/split/inode file and possibly an intd/inode—but no todo, info, local, remote, or bounce—are safe to delete after 36 hours because qmail-queue kills itself after 24 hours. Similarly, files in the pid directory more than 36 hours old are also deleted.

Local Sending Modules

Messages to be delivered locally are passed from qmail-send to qmail-lspawn, which invokes qmail-local to perform the delivery.

qmail-lspawn

qmail-lspawn reads delivery commands from qmail-send on file descriptor 0 (zero), invokes qmail-local to deliver the messages, and reports the results to qmail-send on descriptor 1 (one).

Before invoking qmail-local, qmail-lspawn determines which local user controls the address so qmail-local can be started with the necessary user ID and group ID. qmail-lspawn first checks the qmail-users database, users/cdb. If the address is not listed there, it runs qmail-getpw. If qmail-getpw doesn't find a matching user, it gives control of the address to the alias user.

qmail-local

qmail-local accepts a message on standard input with envelope information, delivery location, and default delivery instructions supplied as arguments. Before attempting delivery, it constructs a Delivered-To field based on the envelope and checks the message for an identical Delivered-To field. If it finds one, it bounces the message to prevent a mail loop. Chapter 4, "Using qmail," details the actual delivery process. If the delivery is successful, qmail-local returns an exit status of 0 (zero). All other codes indicate either permanent or temporary failure.

Remote Sending Modules

Messages to be delivered remotely are passed from qmail-send to qmail-rspawn, which invokes qmail-remote to perform the delivery.

qmail-rspawn

qmail-rspawn reads delivery commands from qmail-send on file descriptor 0 (zero), invokes qmail-remote to deliver the messages, and reports the results to qmail-send on descriptor 1 (one).

qmail-remote

qmail-remote accepts a message on standard input with envelope information supplied as arguments. After attempting to deliver the message remotely via SMTP, it summarizes its results via reports printed to standard output. Chapter 5, "Managing qmail," explains the format of these reports.

The remote host is specified as one of qmail-remote's arguments. It can be either a fully qualified domain name or an IP address. If it's a domain name, qmail-remote checks the Domain Name System (DNS) for a mail exchanger (MX) record for that domain. If the remote host is listed in control/smtproutes, qmail-remote uses the host specified in smtproutes.

---