This guide provides an overview of Qmail, the mail transfer agent (MTA) often used by control panels like Plesk and InterWorx, as well as some core servers. Understanding Qmail’s characteristics and how to manage it is essential for email troubleshooting and server maintenance.

What is Qmail?

Qmail is a modular mail server software. Its design philosophy emphasizes simplicity in its basic installation. However, it’s important to note some key characteristics:

Modular Design: Qmail’s modularity means its core installation is very lean.
No Recent Updates: Qmail has not received official updates in several years and is unlikely to be updated further.
Reliance on Third-Party Addons: To achieve full functionality and for advanced troubleshooting, Qmail heavily relies on third-party patches and modules.
Alternative MTAs: While Qmail might be the default MTA for certain control panel installations (like Plesk), it’s often not the preferred choice for new setups. Postfix, a more actively developed and full-featured MTA, is generally considered a superior alternative.

Qmail vs. Postfix

It’s crucial to remember that both Qmail and Postfix often use the same log file format and share many troubleshooting techniques. Tools like qmhandle (discussed later) can work with both MTAs, but you should always confirm which MTA is active on your server. You can do this by running:

/usr/local/psa/admin/sbin/mailmng --features | grep SMTP_Server

Qmail control options

Qmail’s primary configuration settings are managed through control files located in /var/qmail/control/. These files allow you to adjust various aspects of Qmail’s behavior. A comprehensive list of these options can be found in the official Qmail manual.

Example: Adjusting Queue Lifetime

You can set how long emails remain in the queue before being deleted by modifying the queuelifetime file. The value is in seconds.

To delete mail in the queue after 3 days (259200 seconds):

echo "259200" > /var/qmail/control/queuelifetime

To delete mail in the queue after 2 days (172800 seconds):

echo "172800" > /var/qmail/control/queuelifetime

After making changes to control files, you generally need to restart Qmail for them to take effect:

/etc/init.d/qmail restart

Essential Qmail commands

Here are some fundamental Qmail commands for managing mail flow:

qmail-qstat: Shows statistics and the number of messages currently in the mail queue.
qmail-queue: Used to queue a mail message for delivery.
qmail-clean: Cleans up the queue directory.
qmail-getpw: Provides the directory path for a specific email address.
qmail-qread: Lists outgoing messages and their recipients in the queue.
qmail-send: Delivers mail messages from the queue.
qmail-start: Initiates mail delivery services.

Working with the mail queue

To review the total number of messages in the Qmail queue:

/var/qmail/bin/qmail-qstat

Alternatively, on Plesk systems, you can use:

/usr/local/psa/admin/bin/mailqueuemng -s

To list all messages in the queue (similar to exim -bp in WHM):

/var/qmail/bin/qmail-qread

Remember that Qmail is a very basic program. For anything beyond simple queue totals, you’ll often need a more robust tool like qmHandle.

qmHandle: advanced queue management

qmHandle is a third-party script that provides a more detailed view and management capabilities for the Qmail queue, as Qmail’s default tools are limited. It is specifically designed for Qmail and Plesk environments.

Installing qmHandle:

mkdir /scripts
wget -O /scripts/qmhandle http://files.liquidweb.com/qmhandle
chmod 700 /scripts/qmhandle

Note

qmHandle is a third-party script. While trusted, it falls outside Liquid Web’s scope of support.

qmHandle usage examples:

View help:

/scripts/qmhandle -h

View queue statistics:

/scripts/qmhandle -s

Force delivery of all mail in the queue: (Only if Qmail is running!)

/scripts/qmhandle -a

List messages in the queue (detailed):

/scripts/qmhandle -l

This command lists message ID, reply-to, from, to, subject, date, and message size.

Troubleshooting qmhandle -f 'regex': If you’re having trouble finding messages with qmhandle -f 'regex', try using qmhandle -h 'regex' instead.

Spam investigations

Due to differences in log file structures (compared to Exim), standard spam-detection tools may not work optimally with Qmail on Plesk servers. However, you can perform manual investigations:

Qmail Log File Location:

/usr/local/psa/var/log/maillog

See how many emails are in the queue:

/var/qmail/bin/qmail-qstat

OR

/usr/local/psa/admin/bin/mailqueuemng -s

List all emails in the queue:

/var/qmail/bin/qmail-qread

View message content by ID:

From the output of qmail-qread, you’ll see message IDs. To view the content of a specific message (e.g., if the ID is 12345), you can find its file in the queue:

find /var/qmail/queue/mess/ -iname 12345

Identify Sender by UID:

If a log entry shows a message invoked by a UID (e.g., uid 2527), you can find the corresponding user by checking /etc/passwd:

cat /etc/passwd | grep 2527

If the sender is apache, the mail was sent from a PHP script. You can list currently running PHP scripts under virtual hosts to identify potential spam sources:

lsof +r 1 -p `ps axww | grep httpd | grep -v grep | awk ' { if(!str) { str=$1 } else { str=str","$1}}END{print str}'` | grep vhosts | grep php

Detailed PHP mail script tracking

To get more precise information on which PHP scripts are sending mail, you can temporarily use a sendmail-wrapper script. Do NOT leave this active longer than necessary, as it can quickly fill up disk space. This method is not recommended for Postfix.

Create /var/qmail/bin/sendmail-wrapper:

touch /var/qmail/bin/sendmail-wrapper

Add content to sendmail-wrapper:

#!/bin/sh
(echo X-Additional-Header: $PWD ;cat) | tee -a /var/tmp/mail.send|/var/qmail/bin/sendmail-qmail "$@"

Prepare log file and link wrapper:

touch /var/tmp/mail.send
chmod a+rw /var/tmp/mail.send
chmod a+x /var/qmail/bin/sendmail-wrapper
mv /var/qmail/bin/sendmail /var/qmail/bin/sendmail-qmail
ln -s /var/qmail/bin/sendmail-wrapper /var/qmail/bin/sendmail

Wait and Revert:

Allow the wrapper to run for an hour or so to capture data. Then, revert the changes:

rm -f /var/qmail/bin/sendmail
mv /var/qmail/bin/sendmail-qmail /var/qmail/bin/sendmail

Examine the log:

The /var/tmp/mail.send file will contain X-Additional-Header: lines pointing to the directories from which PHP scripts sent mail.

grep X-Additional /var/tmp/mail.send | grep `cat /etc/psa/psa.conf | grep HTTPD_VHOSTS_D | sed -e 's/HTTPD_VHOSTS_D//' `

If there’s no output, no mail was sent from Plesk virtual hosts using the PHP mail() function during the capture window.

Tracking bouncebacks (with SpamAssassin)

If SpamAssassin is configured and enabled, you can get a count of identified spam messages and the recipients:

cat /usr/local/psa/var/log/maillog | grep -i "identified spam"| awk '{print $11}' | cut -d: -f1 | sort | uniq -c | sort -rn | head

Example Output:

 174 user1@example.com
   163 user2@test.net
    98 user3@sample.org
    94 user4@demo.com
    86 user5@mail.info
    83 user6@webmail.org
    73 user7@domain.net
    47 user8@email.co
    43 user9@mymail.com
    35 user10@mailservice.net

Using UID to find spam

You can also track spam by analyzing message UIDs in the logs to identify sending users/domains:

zgrep "info msg" /usr/local/psa/var/log/maillog /usr/local/psa/var/log/maillog.processed.[1-3].gz | awk '{print $13" "$17}' | sort | uniq -c | sort -rn | while read number email uid; do user=$(awk -F: -v u=$uid '{if ($3 == u) print $1}' /etc/passwd); echo $number $email $user; done | tr -d '<>' | sed 's/[[:blank:]][[:blank:]]/ <> /g'

Example Output:

   359 sender1@example.com <> accountuser1
   243 admin@localhost    <> serveradmin
   220 <>               <> qmails
     6 client@website.net <> clientuser

Column 1: Number of emails sent.
Column 2: Sender email address (<> indicates bouncebacks).
Column 3: Username of the account. If the email address and username don’t match or look suspicious, it can point to a spam source, especially for PHP-originated spam.

To see only the domain username that sent the email:

zgrep "info msg" /usr/local/psa/var/log/maillog /usr/local/psa/var/log/maillog.processed.[1-3].gz | awk '{print $17}' | while read uid; do user=$(awk -F: -v u=$uid '{if ($3 == u) print $1}' /etc/passwd); echo $user; done | sort | uniq -c | sort -rn

Example Output:

   359 accountuser1
   243 serveradmin
   220 qmails
     6 clientuser

Common Qmail Users: Keep in mind that Qmail uses several dedicated users for its operations:

qmaild: Runs the Qmail daemon.
qmailq: Used by qmail-clean to clean up the queue directory.
qmailr: Used by qmail-rspawn to schedule remote deliveries.
qmails: Used by qmail-send to deliver mail messages from the queue.

Troubleshooting Qmail

Root’s email not forwarding

If emails to root@hostname are not forwarding correctly and you see “Maildir not existing” errors in the log, you might need to add the server’s hostname to Qmail’s local domains.

Fix: Edit /var/qmail/control/locals and add your server’s hostname on a new line.

Changing the IP from which mail is sent

You can force Qmail to send mail from a specific IP address for a domain.

Verify domain in rcpthosts:

cat /var/qmail/control/rcpthosts

Ensure the domain is listed here.

Edit smtproutes:
The smtproutes file might not exist by default in Plesk. Create it if necessary. Add a line for your domain and the desired outbound IP. Each domain should only be referenced once. The IP must already be configured on the server.

vim /var/qmail/control/smtproutes

Add:

domain.com:new.ip.add.ress

An example entry for domain.com:new.ip.add.ress would be:

example.com:192.0.2.10

Save and quit.

Restart Qmail:

/etc/init.d/qmail restart

Test by sending an email and checking the full header for the new source IP.

Reviewing individual emails

To review individual email files for a specific user account:

/var/qmail/mailnames/<domain.com>/<username>/Maildir/cur

Each email is stored as a separate file here. You can cat these files to view their content, including full headers, which can be very useful for debugging.

Logfile anatomy

Reviewing Qmail logs can be challenging due to their non-linear organization. However, they contain a wealth of information for troubleshooting email problems. The primary log file is /usr/local/psa/var/log/maillog.

Basic Log Entry Structure:

$month $day $time $origin $mta/$process[$PID] : $id_code

Example Log Snippet (Note: This example shows Postfix logs, but Qmail logs share a similar structure for message tracking):

01 - Aug 29 03:53:31 host postfix/anvil[19376]: statistics: max connection rate 1/60s for (smtp:10.30.9.59) at Aug 29 03:50:11
...
06 - Aug 29 03:54:13 host postfix/pickup[14723]: EFF30C6009A: uid=0 from=<root>
07 - Aug 29 03:54:13 host postfix/cleanup[24808]: EFF30C6009A: message-id=<20120829075413.EFF30C6009A@host.servername.com>
08 - Aug 29 03:54:14 host postfix/qmgr[62781]: EFF30C6009A: from=<root@host.servername.com>, size=564, nrcpt=1 (queue active)
...
15 - Aug 29 03:54:14 host postfix/smtp[24811]: 0E89FC60099: to=<joel@domainname.com>, orig_to=<root>, relay=ASPMX.L.GOOGLE.com[209.85.225.27]:25, delay=0.93, delays=0.04/0.01/0.16/0.73, dsn=2.0.0, status=sent (250 2.0.0 OK 1346226854 dl9si8646004igb.29)

Key Points for Log Analysis:

PID: Process IDs can be reused and interrupted. Simply grepping by PID might not give a complete picture.
ID Code: The message ID code is crucial for tracking. Be aware that it can change if a message is forwarded or auto-responded.
Context: Be prepared to examine many lines of logs to understand the full context of a message’s journey, especially on busy servers or with complex mail rules.

System forwards

System-wide email forwards are managed through files in /var/qmail/alias.

ls -lA /var/qmail/alias

Example Output:

-rw-r--r--  1 root  qmail   21 Sep  9  2011 .qmail-anonymous
-rw-r--r--  1 root  qmail   21 Sep  9  2011 .qmail-drweb
-rw-r--r--  1 root  qmail   21 Sep  9  2011 .qmail-drweb-daemon
-rw-r--r--  1 root  qmail   21 Sep  9  2011 .qmail-kluser
-rw-r--r--  1 root  qmail   24 Dec  8 06:33 .qmail-mailer-daemon
-rw-r--r--  1 root  qmail   21 Sep  9  2011 .qmail-mailman
-rw-r--r--  1 root  qmail   24 Dec  8 06:34 .qmail-postmaster
-rw-r--r--  1 root  qmail   21 Sep  9  2011 .qmail-root

Warning

Modify these files at your own risk and always create backups before making any changes.

Conclusion

Managing Qmail effectively requires understanding its modular nature, its reliance on third-party tools like qmHandle, and its unique logging structure. By utilizing the commands and troubleshooting techniques outlined in this guide, you can efficiently diagnose and resolve common email-related issues on your server. For complex problems or specific configurations, remember that Liquid Web’s Heroic Support® team is always available to provide expert assistance.

Was this article helpful?

Thank you for your input.

Thank you for your feedback.