Modifying the Source Code

---

qmail's redistribution rights prohibit distributing modified versions of the source code or binaries generated from modified versions of the source code. So most user-contributed qmail modifications are distributed in the form of source-code patches.

Patches are the output of the diff command on the original files and the modified files. Although one could manually apply the changes by reading the patch files and making the indicated changes, the patch utility does this more quickly and reliably. The patch tool is also smart enough to skip text messages at the beginning of patch files, so installation instructions are often included.

Most Unix distributions include the patch utility, but some include obsolete versions that can't apply some patches. If you need to install a newer version, visit the GNU patch Web site (http://www.gnu.org/software/patch/patch.html).

Various source code patches are available for qmail. The unofficial qmail Web site (http://www.qmail.org/) contains many patches and links to patches.

Caution 

None of the patches available for qmail have been reviewed or approved by qmail's creator. They may be perfectly safe and reliable, or they could contain serious security, reliability, or functionality bugs. Use them at your own risk, and be sure to identify the patches you've installed when reporting any problems. Most qmail installations do not need any patches. Think twice before installing source-code patches.

Installing Patches

To install a patch, download it using your Web browser or FTP client, cd to the qmail source tree, and apply it using the patch command. For example:

 # cd /usr/local/src/qmail/qmail-1.03 # patch -p0 </tmp/patchfile ...lots of output, look for "failed hunks". . . # 

Depending on how the patch file was created, you might have to leave the -p0 (letter p, number zero) option off or change it to -p1 (letter p, number one) to get the patch to apply cleanly.

Stop qmail by killing qmail-send or, if you installed the qmailctl script in Chapter 2, "Installing qmail," do this:

 # qmailctl stop Stopping qmail. . .   qmail-smtpd   qmail-send # 

Then rebuild and install the new binaries:

 # make setup check ...lots of output ending with something like: ./install ./instcheck # 

And restart qmail:

 # qmailctl start Starting qmail # 

Finally, test qmail—especially the part you patched.

Frequently Used Patches

Most installations require no patches whatsoever. You should use patches only when there's a demonstrated need. That said, let's look at some of the more frequently used patches.

DNS

Historically, DNS responses have been limited to 512 bytes. Some large sites have started returning MX responses longer than that. qmail and many other programs have a problem with queries that return very large results. Most large sites have stopped sending oversized DNS responses because of these problems. There are three ways to fix this in qmail, two of which require modifying qmail.

Use dnscache from djbdns

This solution isn't a patch, but because it fixed a problem that is often solved using patches, it's appropriate to mention it here. The creator of qmail has written a DNS server package called djbdns. Included in this package is a caching-only DNS server called dnscache. By installing dnscache and configuring /etc/resolv.conf to direct all DNS lookups on the system to the local cache, you'll get several benefits including improved lookup performance and the ability to handle large DNS responses transparently.

This solution is preferred over those requiring source-code modification because, obviously, it doesn't require modifying qmail, and it also fixes the problem for non-qmail programs. See Appendix B, "Related Packages," for more information about djbdns.

Raise the Packet Buffer Size to 65,536

The simplest source-code fix is to increase the size of the buffer used to store DNS responses. This method works with recent Berkeley Internet Name Daemon (BIND) resolver libraries, which will automatically do a Transmission Control Protocol (TCP) query within the library code if the User Datagram Protocol (UDP) reply comes back with the truncation bit set. It's also potentially wasteful of memory, depending on how your system handles paging. To make this change, just replace PACKETSZ with 65536 in the file dns.c and rebuild qmail.

Christopher K. Davis's DNS Patch

This patch (http://www.ckdhr.com/ckd/qmail-103.patch) is an adaptation of a patch by Chuck Foster that should work with any resolver library, no matter how old, and uses a "guard byte" to avoid a common library bug regarding the number of bytes placed in the buffer. It reallocates the packet buffer only once to 65,536, rather than just to the size needed, so it can be less memory-efficient than Foster's patch (though, like Foster's patch, it only reallocates if the response is larger than PACKETSZ, which defaults to 512 bytes). After reallocating the buffer, it forces a TCP query, rather than requiring the resolver library to do so (avoiding an extra round-trip between qmail and the name server).

Big-concurrency

As distributed, qmail supports up to 240 simultaneous local and remote deliveries, limited by the concurrencylocal and concurrencyremote control files. Some sites that distribute very large numbers of messages from high-performance servers can handle more than 240 simultaneous qmail-remote processes.

This patch (http://www.qmail.org/big-concurrency.patch) allows qmail to use concurrencies of up to 65,000.

Note that few installations will benefit from this patch. Testing has shown that at high concurrencies, the delivery rate may be limited by the receiving systems. Also, if your system lacks the I/O, network, and processor performance to maintain a concurrency of 240, installing this patch won't magically fix that. See the "Performance Tuning" section for tips that will enable you to maintain higher concurrencies.

Big-todo

In the queue subdirectories most likely to contain many files, qmail adds an intermediate level of "split" subdirectories to keep the number of files per directory manageable. (See "Tuning the Queue" later in this chapter and Chapter 2, "Installing qmail," for more information about the conf-split configuration setting.) This is necessary because most Unix file system implementations use linear searches to locate files in directories, so finding files in large directories can become quite slow.

The todo directory, which stores the envelopes of queued but unprocessed messages, and the intd directory, which stores envelopes under construction, are not split, though. Normally, qmail-send processes new messages quickly, and todo and intd never contain many files. On some very busy servers, though, they can grow quite large.

This patch (http://www.qmail.org/big-todo.103.patch) adds splitting to the todo and intd directories. If your todo often contains so many files that directory lookups take a long time, you might want to apply this patch.

Caution 

Installing this patch will corrupt the queue if todo and intd aren't empty. If necessary, you can install a second copy of qmail with the big-todo patch in a separate directory (using the conf-qmail compile-time configuration setting) and run both versions until the original installation's queue is empty.

QMTP

qmail includes support for QMTP (see the next section) in the form of qmail-qmtpd, a QMTP daemon, but it has no provision for sending mail using QMTP. This patch implements the Mail Exchanger Protocol Switch (MXPS, see http://cr.yp.to/proto/mxps.txt), a convention that allows a site to indicate support for incoming QMTP by using certain special values for its MX record priorities.

For example, if example.com has a single MX record with a priority of 12801, sending MXPS-aware sites can attempt to send messages to example.com via QMTP. If they're unable to send the message via QMTP, they will try sending it using SMTP.

This patch (http://www.qmail.org/qmail-1.03-qmtpc.patch) modifies qmail-remote to make it MXPS-aware and to try to send messages using QMTP to sites that advertise support for it.

Link-sync

As mentioned in Chapter 2, "Installing qmail," qmail relies on BSD Fast File System's behavior of performing link() calls synchronously, which means that the link() function doesn't return successfully until the directory and inode information implementing the link is safely written to disk. Unfortunately, not all operating systems and file systems make the same guarantee, which can result in the loss of messages from the queue in the event of a crash.

This patch (http://www.jedi.claranet.fr/qmail-link-sync.patch) adds explicit fsync() calls everywhere qmail does a link(), restoring the crash-proof nature of qmail's queue on systems that don't inherently perform link() synchronously.

Another alternative, also discussed in Chapter 2, is the syncdir library (see Appendix B, "Related Packages"), which provides wrapped versions of standard library functions, including link(), for Linux. This has the advantage of not requiring a source-code modification to qmail but is only an option for Linux installations.

---