3.3 Configuring and Making the Software

The vast majority of the qmail configuration occurs at runtime. There are, however, a few configuration options that can only be changed at compile time. These options are, as you might expect, not often changed. If you're reading this book front to back, skip this section and come back to it later, because most of the compile-time options won't make any sense to you.

These configuration options are each in a separate file in the qmail source directory, the first line or lines of which are the value. Lines beyond those have an explanation of the meaning of the value.

3.3.1 conf-break

Qmail permits users to have subaddresses, which qmail calls extensions. For example, [e-mail] has an extension of "qmail-book" if the break character is a dash. By default it is a dash character, but some sysadmins may wish to use a plus or equals character for compatibility with other software. (Sendmail uses a plus sign.^[2])

^[2] One potential cause of confusion is the difference between the break character and the character that separates the parts of extensions. conf-break specifies the break between the username and the extension. Extensions are also split into parts; however, they are always split at a dash character. So, if you set your break character to a plus, then nelson+list-qmail will be matched by ~nelson/.qmail-list-default if there's no better match. See Chapter 7 on local delivery for more information.

3.3.2 conf-cc

The compiler is not set in the makefile, as is typical for a Unix program. The makefile actually uses a generic compile script. This script is created by the makefile. It combines conf-cc with some more information. If your C compiler needs special optimization flags, this is the place to put them.

3.3.3 conf-groups

The first two lines of this file list the names of the groups that qmail uses. They are used in the building process to get the group id (gid) for the install process. The first is the name of the group that several qmail users use to share information through group permissions. The second is the name of the group used by the other qmail users who don't need to use group permissions. Don't change this unless your system already has groups called qmail or nofile that conflict with qmail's use of them.

3.3.4 conf-ld

The first line of this file is the command used to link .o files into an executable. The most common change is to replace the --s flag it contains with --g to preserve symbols for debugging. If your linker supports static shared libraries, which start up faster than the more usual dynamic shared libraries, this is where you put the flags or command to use them.

3.3.5 conf-patrn

Qmail refuses to deliver mail to insecure accounts. If a user allows anyone to modify files in his home directory, anyone can modify his .qmail files. And that means that anyone can execute any command as the user. So, giving away write permission gives away everything.

An insecure account is identified by excess write permissions on the user's home directory and on the user's .qmail files. The excess write permissions are given as an octal number in the first line of this file. The default (002) is that other-write permission cannot be given. A stricter value would be 022, which disallows group-write in addition.^[3]

^[3] The Red Hat Linux useradd program creates a separate group for each user. In this context, group-write permissions are not a security hole, so using a conf-patrn of 022 rather than 002 just causes extra work without improving security.

3.3.6 conf-qmail

Qmail installs all its files (configuration, manpages, binaries, and mail queue) under a single directory, /var/qmail. This is advantageous because qmail is not a special program (for example, it needs to be located at /usr/lib/sendmail, or to own the queue at /var/spool/mqueue).

This directory (by default, /var/qmail) must be a local directory, not mounted via a network filesystem. Don't change it unless you have a very good reason to do so. The most likely reason to do this is to create two copies of qmail to run in parallel, as described in Chapter 17.

3.3.7 conf-spawn

This is one of the few static limits in qmail. It's imposed by the underlying operating system. A program can wait only for so many children at one time, and this number is the limit. It's set to 120 for portability reasons. You would need to increase it only if you need a concurrencylocal or concurrencyremote higher than 120, and if your operating system also allows it. (This number has to be less than half the number of file descriptors that a select( ) system call can wait for. On many Unix-like systems, it's possible to increase this limit at compile time. See Chapter 16.)

3.3.8 conf-split

The qmail queue is split into a number of hashed subdirectories, with one message in each of the subdirectories. The default of 23 is chosen so that the typical queue doesn't make the subdirectories too large. If your queue isn't typical (because, say, you run a big ISP or send mail to many customers) and has more than 10,000 messages in it, you might want to increase this number to a larger prime value. See Chapter 16.

3.3.9 conf-users

The first eight lines of this file list the names of the users that qmail uses. They are used in the building process to get the user ID (uid) for the install process. The first one (usually alias) is the user qmail uses when no other user matches. The second (qmaild) is used for the SMTP daemon. The third (qmaill) is used to log information. The fourth (root) is used to own binaries and documentation. The fifth (qmailp) is used to map a username into a uid/gid/homedir combination. The sixth (qmailq) is used to own files in the queue. The seventh (qmailr) is used to make remote connections as an SMTP client. The eighth (qmails) is used to schedule messages for delivery from the queue and generate bounce messages. Don't change this file.

What About RPMs?

Most versions of Linux provide Red Hat Package Manager (RPM) files that automatically install a package, doing whatever compilation and preprocessing is needed. Even if a qmail RPM is available, I recommend building qmail from the qmail or netqmail source code. For one thing, it's critical that qmail be built using the user and group IDs defined on your system. Building it yourself ensures this. All of the qmail RPMs contain some patches, but unlike netqmail, they rarely document which ones. You'll probably want to install some other patches and add-ons that are available to extend qmail, all of which involve recompiling from source anyway. And finally, unlike most other packages, building qmail is so quick and straightforward that using an RPM doesn't save much time.

3.3.10 Build Using make

To build qmail, simply run make. There's no separate configuration program as in some other packages. A number of portability problems are solved by Dan's inclusion of his own library functions. His library is the same from host to host and so are the calls to the library.

Because qmail uses less of the C library, qmail is less vulnerable to security holes in the C library. Unfortunately, some functions cannot be rewritten, because they require internal knowledge about the OS. For example, to read a directory, some versions of Unix require read( ) to be called and others require an internal interface routine to be called; there's no alternative to readdir( ).

3.3.11 If the Build Fails

There are only three reasons why the build might fail. First, because you didn't create the qmail users listed previously; seond, because a necessary external program such as make, cc, or nroff isn't present; or third, your platform isn't close enough to Unix to support qmail.

If your build fails with complaints about errno, you've tripped over a compatibility problem between qmail and recent versions of the C library. See Building with Recent GLIBC and Fixing the errno Problem later in this chapter for the simple fix.

3.3.12 Building the Other Packages

You must build at least the ucspi package, which includes tcpserver, to get qmail going. Fortunately, Dan's other packages are even easier to set up than qmail, because none of them depend on user IDs. For each package, just unzip and unpack the downloaded tar file into a work directory and type make. Normally all of the files in each package are installed under /usr/local, with programs in /usr/local/bin. If that's not where you want them before you make the package, edit the file conf-home and put the installation directory on the first line of the file.

Starting with daemontools 0.75, Dan has developed an extremely automatic and somewhat incompatible system to install his programs, described at http://cr.yp.to/daemontools/install.html. All of the packages are built in the directory /package, which you have to create, most likely as a symlink to a directory on a disk with more space than your root partition. (I link it to /usr/package.) Packages are built in /package, with commands symlinked into the new directory /command. For backward compatibility it also links them into /usr/local/bin. Documentation, if any, goes into /doc. See http://cr.yp.to/unix.html for more details.

To install daemontools, FTP the package (or copy it if you've already FTP'ed it somewhere else) into /package and unpack it, at which point the files will be in /package/admin/daemontools-0.76 (or whatever the current package name and version are). Then chdir to admin/daemontools-0.76 and, as super-user, run the script package/install, which builds and installs the whole thing, building the commands in commands and symlinking them into /command and /usr/local/bin.

Finally, it creates /service and arranges to start svscan at boot time. It adds lines to /etc/inittab if it exists, otherwise to /etc/rc.local to run svscanboot at boot time to startup svscan. If you have /etc/inittab, the build process pokes the init process to start svscan for you; if not, it suggests that you reboot. Rather than rebooting, run the command it just added to rc.local:

csh -cf '/command/svscanboot &'

If your system has a daemon command to run programs unattached to any terminal, use it:

daemon /command/svscanboot

3.3.13 Installing Qmail

First become the super-user. Change to the directory where you built qmail, and type make setup. This makes all of the directories and installs all of the qmail files into /var/qmail. Now type make check, which checks to make sure that all of the required files and directories are present. Assuming it reports success, qmail is installed and ready to go.

3.3.14 Installing Other Programs

To install the other programs, notably the ucspi package, change to the directory where you built each package and type make setup to install the files into /usr/local (or if you changed conf-home, into the home directory you selected). For daemontools and other packages using the new /package scheme, the build process already installed them.