Here is some quick advice on troubleshooting qmail. Please consul the qmailrocks.org FAQ database to find answers to detailed questions.

Troubleshooting a Qmail install may seem scary at first, but in reality it's actually quite easy. Generally, in my experience, there are 2 main sources of trouble: (1) Configuration file errors and/or (2) permissions/ownership errors.

And now I impart to you the golden rule of troubleshooting: Read your logs!

1) Problems with Qmail's configuration files

The most common place that you'll screw up, when configuring Qmail, is in putting together the supervise scripts (everything in the /var/qmail/supervise directory). These scripts are the heart of Qmail and the slightest mistake can blow it. Fortunately, if you've set Qmail up according to the book, it logs all it's activities to the Qmail logs located at /var/log/qmail. Generally speaking, there are 3 types of logging that Qmail does. These 3 log types correspond to the 3 categories of supervise scripts: Qmail-smtpd, Qmail-send and Qmail-pop3d. With each of these items there is a "run" script and "log/run" script. The main "run" script runs the service itself and the other "log/run" script logs that service's activities. Here's a breakdown of where these supervise scripts are at:

/var/qmail/supervise/qmail-smtpd/run & /var/qmail/supervise/qmail-smtpd/log/run
/var/qmail/supervise/qmail-pop3d/run & /var/qmail/supervise/qmail-pop3d/log/run
/var/qmail/supervise/qmail-send/run & /var/qmail/supervise/qmail-send/log/run

All of these scripts are run by use of symbolic links in the /service directory:

ls -al /service
lrwxrwxrwx 1 root root 32 Jun 24 05:08 qmail-pop3d -> /var/qmail/supervise/qmail-pop3d
lrwxrwxrwx 1 root root 31 Jun 24 05:08 qmail-send -> /var/qmail/supervise/qmail-send
lrwxrwxrwx 1 root root 32 Jun 24 05:08 qmail-smtpd -> /var/qmail/supervise/qmail-smtpd

You can generally tell that you've got a problem in one these scripts in the following way:

A) You can check out the logs for each supervised service in the /var/log/qmail directory under the subdirectory corresponding to the service you are having trouble with. For example, if you are having trouble sending or receiving mail, you may want to check /var/log/qmail/qmail-smtpd/current. Doing a "tail -f" on the logs will often give you a real time view of what is going wrong. I love doing a "tail -f" on one of the qmail logs and then running some tests. You'll see the logs as they come in and if something is wrong in the supervise scripts it will often signal this in the log output. I'm not going to get into the individual error messages for now, but when you see them it's pretty easy to piece together what's not right.

But what if nothing is showing up in the logs?

B) If you run a "ps -aux" on your system, you will see all the current processes running. Along with all the other Qmail processes that are running, you should see one title "readproctitle service errors:". This process keeps track of the services and shoots out messages when something is wrong.

If Qmail is running correctly, the "readproctitle service errors:" line will look something like this:

root 1291 0.0 0.0 1332 252 ? S Jul06 0:00 readproctitle service errors: .......................................

The important part here is the "...................................". This means that there are no errors being detected.

However, if you've botched up the install, you may see something like this:

root 1291 0.0 0.0 1332 252 ? S Jul06 0:00 readproctitle service errors: Mutlilog cannot write blah blah blah

Notice that in this case the error monitor has spotted a problem with Qmail's logging setup and it's telling you. Imagine that.

In the case above, the logical conclusion would be: Multilog is having a problem. Therefore there is probably an error on one of my logging script within the supervise directory. You would then go and check the log scripts for each service. Make sure that the paths specified in those scripts are correct and valid, etc. etc. This is basic shell script troubleshooting at this point.

But what if my scripts are fine and I can find no errors in them?

2) Problems with permissions and ownership

If you've checked all your scripts and you can't find any problems, you may have a problem with the permissions and/or ownership settings on one of the Qmail files or directories. The most common place this will happen is on the Qmail log files, located in /var/log/qmail. The entire /var/log/qmail directory should be chowned to qmaill:root.

chown -R qmaill:root /var/log/qmail

chmod -R 750 /var/log/qmail (i threw the permissions setting in there just for fun)

If you have permissions or ownership problems elsewhere, you may want to go back and revisit the installation guide on this site and make sure that you chowned and chmoded everything that you were supposed to.