An overview of Qmail, part 2: Configuring Qmail

So you've installed Qmail. Now what? Vincent Danen concludes his two-part series on Qmail with a discussion of Qmail's various configuration options. He also offers some tips that will help you get the most out of your new Qmail setup.

In “An overview of Qmail, part 1: Installing Qmail,” I explained how you could install Qmail, a Mail Transfer Agent (MTA) that provides POP3 and SMTP services for your Linux server. (It is very similar to sendmail or postfix.) I told you how to change your system so that you could use Qmail's maildir format instead of the traditional mailbox format that most MTAs use. In this Daily Drill Down, I’ll examine some configuration options, and I’ll give you some tips that will help you get the most out of your new Qmail setup.

Hard or soft error in qmail-pop3d.init
First, let’s discuss a particular problem with the POP3 server. Depending on your system and setup, users may not be able to read their e-mail via POP3 on your system. If not, Qmail will report a variety of different error messages to the e-mail client. I experienced this very frustrating and time-consuming problem after installation.

When you run the POP3 server startup script /etc/rc.d/init.d/qmail-pop3d.init, it may report a hard or soft error before the daemon starts. Usually, this error is associated with dnsfq, a program that Qmail calls in order to determine your host information. To check for errors, this program performs a reverse lookup on your IP address. Since many hosts on the Internet perform reverse lookups before connecting to another host, Qmail tries to determine whether or not doing so will cause a problem for you. If some hosts can’t perform a reverse lookup, they’ll refuse to connect to your host. If the reverse lookup doesn’t work, then you probably have an issue with your ISP or with your own DNS server (if you’re running one). On the other hand, many hosts will perform a reverse lookup based on your domain name instead of your IP address; if so, the reverse lookup probably will be successful. This problem isn’t critical, and you can solve it easily.

Take your favorite editor and edit the /etc/rc.d/init.d/qmail-pop3d.init file. In this file, you’ll find a line that is similar to the following:
HOST=$($QMAILHOME/bin/dnsfq $($QMAILHOME/bin/hostname))

Simply comment out that line and add this new line (where is the fully qualified domain name for your server):

Restart the POP3 server by issuing:
/etc/rc.d/init.d/qmail-pop3d.init restart

Now, you shouldn’t see any more hard or soft error messages at startup. If you attempt to connect to the POP3 server in order to read your e-mail, you shouldn’t have any problems.

Forwarding e-mail to another host
By default, Qmail will only accept e-mail for its own domain and for any defined virtual domains. With some configuration settings, however, you may need to forward e-mail that you receive on your system to another internal server or to a completely different host. To enable Qmail to forward e-mail to another host machine or SMTP server, you must edit two configuration files in your /var/qmail/control directory. First, you must edit the rcpthosts file, which contains a list of the domains for which Qmail will accept mail. For example, if your domain name were and you provided Web hosting services for, both domain names would point to your server because of the Web hosting. However, suppose that wanted to handle its own e-mail directly with its own SMTP server. You still need to handle the Web hosting, so still needs to point to your server. But you also need to receive mail for and forward it to another host. At the end of the /var/qmail/control/rcpthosts file, add the following line:

This line tells Qmail to accept any messages that are addressed to Now, you need to tell Qmail to forward these messages to another host machine for processing. If the file doesn’t exist already, you’ll need to create a new file called /var/qmail/control/smtproutes. Then, add the following line to this file:

This line tells Qmail to forward all e-mail messages addressed to to the host. If the host has a static IP address instead of a domain name, you could use this line (where is the IP address of the host computer to which Qmail will forward e-mail):

Of course, might have the SMTP server listening on port 1025 instead of on the standard SMTP port 25 in an attempt to discourage people from connecting to the SMTP server too easily. If so, Qmail needs to forward e-mail both to a remote host and to an alternate SMTP port. Thus, you should use something like the following line:

You can use the same method on a local machine or within a local network. For example, if you run two SMTP servers on the same computer, you can forward e-mail for a sub-domain to a secondary SMTP server. If you need to forward e-mail for the subdomain to another SMTP server that’s on the same computer but that listens to port 1025, you must place the following line in /var/qmail/control/smtproutes:

Since points to the same IP address that does, all mail for will be forwarded to the secondary SMTP server that’s listening to port 1025. (Remember, this server is on the same computer that houses Qmail, which listens to the standard SMTP port 25.) Of course, you also need to add to your /var/qmail/control/rcpthosts file. It will tell Qmail to accept e-mail that’s addressed to this domain name.

Users and alias users
Qmail uses a different method of handling users and aliases than do other SMTP servers, such as sendmail. In sendmail, all system aliases are defined in the /etc/aliases file. In Qmail, these aliases are defined in "dot-qmail" files, which are found in the /var/qmail/alias directory for system-wide aliases or in the user's home directory for user-specific aliases.

You may need to set up e-mail forwarding on your system. For example, suppose that you’ve defined the address as an e-mail address where people contact you via your Web site. Instead of creating a Webmaster username on your server and connecting via POP3 to retrieve your e-mail, you can tell Qmail to forward all mail for that user to your primary e-mail address, such as

It makes sense to perform e-mail forwarding. If you already have an existing account on the system, why log in twice to retrieve mail for both accounts? Or if you log in remotely with POP3 to retrieve mail, why connect to the same server twice for two accounts? It's redundant. Qmail allows you to keep things simple; you can log into your myemail account and retrieve e-mail for both myemail and Webmaster. Of course, you’ll need to create a new dot-qmail file. Since it’s a system alias, you must create the file in the /var/qmail/alias directory, like so:
cd /var/qmail/alias
joe .qmail-webmaster

Use your favorite text editor to create a new file: .qmail-webmaster. (I used the joe editor.) The format for these dot-qmail files is .qmail-[aliasname]. Since you want to create an alias for, you’ll need to create .qmail-webmaster. Here’s the only thing you need to place in the file:

This line tells Qmail to forward all of Webmaster’s e-mail to the myemail account. The ampersand (&) indicates that this is a forwarding operation. If you want to forward the e-mail for to an e-mail account on a different system, however, you would use the same syntax, but you would supply the full e-mail address. For example, if your primary e-mail address were, you would use the following line:

To forward e-mail to local users, you could inject the e-mail directly into a mailbox file or a maildir directory. Inside .qmail-webmaster, type this line:

This line will place all e-mail for inside the mailbox file /home/myemail/Mailbox.webmaster. (You can use any mailbox name you want.) For this example, I put all of the e-mail for this alias in a different mailbox file from the standard mailbox file for this user (which is /home/myemail/Mailbox). For this method to be effective, your e-mail client must understand and support multiple mailbox files. You can accomplish the same thing with a maildir:

This line will forward all e-mail for into the maildir /home/myemail/Maildir/. For Qmail to know the difference between maildirs and mailboxes, note the differing syntax. To define a mailbox, begin the string with a forward slash and end with a valid mailbox filename. To define a maildir, begin the string with a forward slash and end with a forward slash. You can use this method to define another maildir (like /home/myemail/Maildir-webmaster/), but your e-mail client must support multiple maildirs if you’re going to inject the e-mail into a different maildir.

Qmail also supports user-specific aliases, which provide greater flexibility to your users. For example, suppose you have a user with the e-mail address Joe is a local user with a/home/joe directory, and he collects his mail via POP3—just like any normal e-mail user. Perhaps Joe wishes to set up his own mailing list about Qmail. Instead of getting the system administrator to set up a new alias ( for his mailing list, Joe can set up something like That way, he won’t need to deal with the system administrator at all. When Qmail sees this kind of address, it will consult the dot-qmail files that are defined in /var/qmail/alias. If there’s no match, it will try to deliver to the local user joe. In order for this concept to work, Joe needs to set up a file called /home/joe/.qmail-qmail-list. This file will point to the mailing list program, or it will contain a list of users who are supposed to receive e-mail. For a very basic mailing list, Joe might include the following lines in the /home/joe/.qmail-qmail-list file:

These lines will forward all messages for to,, and For more complicated mailing lists (such as lists that provide user subscription and un-subscription), you’ll want to look at a mailing list manager, such as majordomo or ezmlm. My example merely illustrates what users can do with local aliases that they can define without intervention on the part of the system administrator. Of course, for Joe to enable this idea in the first place, he must have local access to the server that contains Qmail, or he must be able to use telnet or SSH to log into the server remotely in order to create the alias file.

Aliases that run programs
So far, I’ve explained how you can create aliases that forward e-mail to other users based on a list of addresses that are defined in your dot-qmail file. There’s one other function that dot-qmail files can perform—sending a message to a specific program. This function could involve anything from an auto-responder robot to a mailing list program.

First, you must define the alias file in the same way that you would for forwarding e-mail to another address, mailbox, or maildir. Use a pipe (|) to begin the command line of the program that you want to call. For example, e-mail to must run the program /usr/bin/myprogram. So, create the /var/qmail/alias/.qmail-auto alias file and include the following line in this file:

To run a series of programs over the incoming e-mail message, you can include as many lines as you like. Basically, Qmail runs the specified program in a shell and uses sh -c [command] to execute the command that’s listed in the dot-qmail file. When Qmail runs the shell command, it also provides a number of environment variables from the message that will be processed, including:
SENDER The envelope's sender address
RECIPIENT The envelope's recipient address (local@domain)
USER The user's username
HOME The user's home directory

There are several other useful variables. (To obtain more information, use man qmail-command 8 and view the manual pages.) Qmail also makes the message text available by using standard input for whatever command you’re running.

Virtual domains
Qmail also supports virtual domains. If your system ( wishes to accept e-mail for, just tell Qmail to accept e-mail for Add the following line to your /var/qmail/control/rcpthosts file:

This line will give every user on your system a address, along with their normal addresses. If you want to forward all e-mail for the virtual domain to one specific user, however, you’ll need to create a file called /var/qmail/control/virtualdomains. If you want all e-mail for to be forwarded to Joe, add this line to the new virtualdomains file:

You’ll still need to include in your /var/qmail/control/rcpthosts file. Otherwise, Qmail will refuse e-mail for that domain.

Restarting Qmail after configuration
You need to restart Qmail each time you change a control file. When you make changes to dot-qmail files, however, you don’t need to restart Qmail. Qmail reads that information dynamically; changes or additions to aliases are immediate. If you’re adding support for virtual domains or adding new hosts for which Qmail needs to receive mail, however, you need to restart Qmail. On a Red Hat or a Linux Mandrake system that uses the /etc/rc.d/init.d startup scripts, you can use:
/etc/rc.d/init.d/qmail.init restart

You don’t need to restart the SMTP and POP3 daemons—just Qmail itself.

If Qmail is supervised, you could use the following line:
svc -h /service/qmail

This line sends the HUP signal to the qmail-send process. To have the supervise program watch the Qmail programs, you need to install the daemontools package. Then, issue the following command line as root:
mkdir /service/qmail
ln -s /var/qmail/rc /service/qmail/run

Now, in your startup scripts, you’ll find the following line:

Change it to this line:
supervise /service/qmail

The benefit of having supervise control Qmail is that you can use the svc program to start, stop, and restart Qmail safely. You can use the svstat program to see if Qmail is even running. It can restart Qmail if Qmail ever exits, and it will ensure that Qmail is running constantly. The best thing about the supervise program is that it’s not limited just to usage with Qmail; it can be used for any service that you want to run supervised.

The number of ways in which Qmail can be configured would fill a book. In fact, John Levine and Russell Nelson are writing a book, which O'Reilly & Associates is scheduled to publish this year. (Apparently, the book has slipped from O'Reilly's production calendar because the authors are behind schedule. There’s no way to know when it will become available to the public.) Qmail also offers numerous FAQs and extension programs that will help you to get the best performance from your Qmail system.

About Vincent Danen

Vincent Danen works on the Red Hat Security Response Team and lives in Canada. He has been writing about and developing on Linux for over 10 years and is a veteran Mac user.

Editor's Picks

Free Newsletters, In your Inbox