Fixing Common Problems | The qmail Handbook

< Free Open Study >

Now that you have a toolbox full of troubleshooting tools, let's look at some common problems and see how you can apply those tools to determine the cause of the problem.

Mail Not Delivered Locally or Remotely

You discover that mail is not being delivered to local users or remote addresses. You might have just installed qmail or reconfigured it, or maybe it's been up and running for some time and has suddenly stopped working. qmail is either not running at all, or is running, but failing to deliver messages. In any case, do the following:

Verify that the qmail daemons are running. See the earlier "Process Monitoring" section.
Check the qmail-send logs for error messages. See the earlier "Understanding Logs" section.

Mail Not Accepted from Remote Hosts

You discover that messages sent locally to local addresses are being delivered, but no mail is being accepted from remote hosts.

The qmail-smtpd service may not be running, may not be accessible by remote hosts, your domain's mail exchanger (MX) might not point to the correct system, your qmail may be misconfigured, your network may be unreachable, or your domain's name service (DNS) might be misconfigured or down. In any of those cases, do the following:

Verify that the qmail-smtpd service is running. See the earlier "Testing" section.
Verify that remote hosts can access the SMTP service. Conduct the SMTP service test from a remote system. If it fails, SMTP traffic may be blocked by a firewall or denied by tcpserver (check /etc/tcp.smtp), tcp.smtp.cdb may be missing—unless you're using -X (dash capital X) on the tcpserver command line—or concurrencyincoming could be set to 0 (zero).
Verify that your system is correctly configured in the DNS as the MX for your domain.
Verify that your qmail system is accepting mail for your domain. See the earlier "Testing" section. Inject a message via SMTP that your system should accept and deliver. If it rejects the message, check control/rcpthosts. If it accepts the message but doesn't deliver it, check the qmail-send logs.
Verify that your domain's name service is working right.
Verify that your network can reach other networks.

Mail Not Delivered to Local User

You discover that mail to one or more local users is not being delivered: It's either rejected immediately or remains in the queue.

The user doesn't exist or isn't a valid mail user, or delivery is failing due to problems considered temporary. In any case, do the following:

Check the qmail-send logs. Any time a delivery fails for any reason—permanent or temporary—qmail-send records the reason for the failure.
If the error message looks like this:
```
 delivery 473: failure: Sorry,_no_mailbox_here_by_that_name._(#5.1.1)/ 
```
then verify that the user exists and meets the criteria for a valid mail user required by qmail-getpw (see the "Command Reference" section of Chapter 5).
If the error message looks like this:
```
 delivery 130: deferral: /bin/sh:_qmail-porcmail:_command_not_found/ 
```
the problem is that the address is valid, but delivery attempts are failing. In this case, the user's .qmail file contains a typographical error.
If the error message looks like one of these:
```
 deferral: Uh-oh: home directory is writable. (#4.7.0) deferral: Uh-oh: .qmail file is writable. (#4.7.0) 
```
then verify that user home directory permissions and .qmail file permissions do not contain any of the permission bits excluded by the conf-patrn compile-time configuration variable. (See Chapter 2, "Installing qmail," for more information.)
If the error message looks like this:
```
 deferral: Home directory is sticky: user is editing his .qmail file. (#4.2.1) 
```
remove the sticky bit from the user's home directory using chmod -t homedir.
If /var/qmail/users/assign exists, check it to be sure that the user's mail isn't being redirected elsewhere. Also examine users/exclude and users/include.
Check /var/qmail/queue/lock/trigger. (See Appendix F, "Gotchas," for more information.)
Verify that concurrencylocal is not set to 0 (zero).

Mail Not Delivered to Remote Address

You discover that mail to local addresses is working, but mail to remote addresses isn't being delivered.

The problem could be due to user error, local configuration error, network outage, or remote configuration error. In any case, do the following:

Check the qmail-send logs. If errors are being logged, they will explain the problem and you can analyze it further (go to step 2). If no errors are being logged, then delivery is either succeeding or being handled by some other mechanism such as maildirsmtp, in which case you'll need to check the logs associated with that mechanism.
If the logs indicate a permanent error (failure), either the remote address (local part or domain) is invalid, or the remote site is refusing to accept the message. In either case, qmail-send should log enough information for you determine a course of action.
If the logs indicate a temporary error (deferral), either the remote host is unreachable, or it is reachable but temporarily unable to deliver the message.
If all messages are being deferred because remote hosts can't be reached, for example, because of temporary DNS lookup failure or inability to establish an SMTP connection, verify that the local host has network connectivity. Ping known hosts using the ping utility, or look up known remote domains using dig or some other DNS look-up utility. Use traceroute or mtr to verify that the remote server is reachable.
If you can't look up or ping any known hosts, the problem is that your network connection is down or malfunctioning.
If you can reach known hosts, but not others, the problem is with the hosts you can't reach. You could try to contact the administrators by phone, but they're probably aware of the problem.
Verify that concurrencyremote is not set to 0 (zero).

Mail Not Retrievable by Users

You discover that although mail is delivered locally and remotely, users who access their mailboxes via network mail protocols like POP3 or IMAP are unable to retrieve new mail.

The problem could be that you haven't installed a mailbox service, the service is not working properly, or the users' MUAs are misconfigured or not working properly. A typical qmail installation provides SMTP service, which remote users use to send mail, but it doesn't provide POP3 or IMAP service, which remote users need in order to receive mail. In any case, do the following:

If you haven't installed a POP3 or IMAP service, see Chapter 10, "Serving Mailboxes."
If you have installed a POP3 or IMAP service, check its logs for any error messages.
Verify that the service is active by attempting to connect to it from the server. See the earlier "Testing" section.
Verify that user authentication is working by logging in to the service with a known username/password.
Verify that user mail is being delivered to the correct location for the mailbox service.
Verify that user's MUA is properly configured with correct server, port/protocol, authentication method, username, and password.
Verify that user's MUA is working properly by testing with a known-working MUA or by using recordio to record their sessions (see the earlier "Using recordio to Log SMTP Sessions" section).

Local Users Can't Send Mail

You discover that although mail is delivered locally and remotely when injected locally, users who access their mail over the local network using MUAs such as Outlook Express or Eudora are unable to send mail.

It could be your SMTP service isn't working properly, it's not allowing local users to relay, or the users' MUAs are misconfigured or not working properly. In any case, do the following:

See the earlier "Mail Not Accepted from Remote Hosts" section to verify that your SMTP is working properly.
Verify that trusted hosts are granted relaying access. Their IP or network addresses should be listed in /etc/tcp.smtp, and /etc/tcp.smtp.cdb should be up-to-date. Run qmailctl cdb to update it. See Chapter 3, "Configuring qmail: The Basics," for more information.
Verify that user's MUA is configured with correct SMTP server.
Verify that user's MUA is working properly by testing with a known working MUA or by using recordio to record their sessions (see the earlier "Using recordio to Log SMTP Sessions" section).

< Free Open Study >