Problem solve Get help with specific problems with your technologies, process and projects.

Qpsmtpd: Configuration and plug-ins

Qpsmtpd is a Perl-based smtpd daemon used for spam prevention. In the second part of this series, we will find out about different plugs-ins and how to configure qpsmtpd.

Fighting spam has become harder and harder since spam has become more prolific and spammers find new ways to outsmart existing spam controls. The first part of this three-part series dealt with installing qpsmtpd, a daemon designed by Ask Bjorn Hansen to fight spam. Used by the likes of, and, qpsmtpd provides all the standard SMTP functionality and is supported by a series of extensible plug-ins, also written in Perl.

Fighting spam with qpsmtpd:
 Installing qpsmtpd

Qpsmtpd: MTA integration and testing

Now that you've successfully installed qpsmtpd on a Linux-based distribution (Red Hat, for our purposes), I am going to show you how to configure and how to place qpsmtpd and explain the roles of different plug-ins.


In part 1 of the tip, we created a directory to hold qpsmtpd's configuration at /etc/qpsmtpd (which we also sym-linked to ~smtpd/config). We moved the sample configuration files from the distribution into this directory. Now, we need to configure some files in this directory.

First, we must specify the location of the spool directory using the spool_dir file, which we created a directory for at ~smtpd/tmp. Generate the spool_dir file by echoing the full path to the temporary directory like so:

# echo "/home/smtpd/tmp" > /etc/qpsmtpd/spool_dir

We also need to create a logging file to indicate where to log messages from qpsmtpd. For example:

# echo "logging/file_connection loglevel LOGINFO /var/log/qpsmtpd/qpsmtpd.log" > /etc/qpsmtpd/logging

This tells qpsmtpd to use a logging plug-in called file_connection to record all messages of syslog level INFO and above to the file qpsmtpd.log in the /var/log/qpsmtpd directory. You can also specify higher log levels to have qpsmtpd log more detailed information. There are other logging plug-ins that you can use located in the logging subdirectory of the plug-ins directory.

Functions and configurations of plug-ins

The key configuration file for qpsmtpd is the plugins file. This file lists all the plug-ins that qpsmtpd will use when processing email. You can see an example of that file below:

count_unrecognized_commands 4


virus/clamdscan clamd_socket /tmp/clamd
spamassassin spamd_socket /tmp/spamd


Plug-ins should be listed in the order they are to be executed. The plug-ins are loaded from the plug-in directory (we installed them into /usr/share/qpsmtpd/plugins in part 1) and subdirectories. Plug-ins that are located in subdirectories can be specified by prefixing them with the relative subdirectory name. For example, you can see the clamdscan plug-in is located in the virus subdirectory, while the postfix-queue plug-in is located in the queue subdirectory.

Plug-ins can also accept configuration variables, either specified on the same line as the plug-in in the plugins file itself, or defined in configuration files that are stored in the configuration directory, in our case /etc/qpsmtpd. We will see examples of both kinds of configuration below.

It is important to note that every time you make a change to the plugins file, you need to restart qpsmtpd to ensure that the correct plug-ins and configurations are loaded.

So how do plug-ins work? Plug-ins interact with different portions of the SMTP transaction using hooks. They can be initiated (or hooked in) at one or more points of the transactions. For example, at connection time plug-ins may be initiated when the EHLO, DATA or QUIT commands are received, amongst other hook points. Here is a full list of the potential plug-in hooks.

After hooking in, the plug-in does some processing of the transaction, like checking the validity of a recipient, and exiting with one of a number of return codes. These return codes tell qpsmtpd what to do with the email. For example, if a plug-in returns the code DECLINED, then the plug-in has declined to do anything. If the plug-in returns the DENYSOFT code, then qpsmtpd sends a temporary rejection code to the sender's server (a 4xx code for example) and denies the email. You can see a full list of return codes in the README.plugins file that comes with the qpsmtpd distribution.

A list of installed plug-ins

So let's look at some of the plug-ins we've enabled in the plugins file above.

  • check_earlytalker This plug-in monitors to see that the sender waits until it receives the SMTP banner before talking to your server. This helps to defend against direct-to-MX spam that pipelines the entire SMTP transaction to your server without waiting for a response.
  • greylisting Greylisting is an anti-spam technique that temporarily rejects emails from unknown senders. Legitimate email will try to resend itself; most spammers will not attempt to resend. Senders are tracked by IP address by default (and optionally by sender and/or recipient). Legitimate senders that re-send email are added to a database and whitelisted for a user-defined period.
  • count_unrecognised_commands This plug-in counts unrecognized commands during a connection and, if a user-specified number is exceeded, then disconnects the client. You can see above that we've specified a variable, 4, which lists the unknown command threshold. This is one method of specifying configuration variables for plug-ins.
  • check_basicheaders This plug-in rejects messages that do not have a From or Date header or are completely empty. It can also optionally reject messages where the date in the Date header is earlier or later than a user-specified period in days.
  • rcpt_ok The rcpt_ok plug-in is important and needs to run after all the RCPT hook plug-ins. It allows you to specify the domains for which you intend to receive email. This is done in the style of qmail, using a rcpthosts file which should be created in the /etc/qpsmtpd directory. The contents of the file should list all the relevant domains like so:
    # List of domains
  • Virus and Anti-Spam spamassassin and clamdscan are two plug-ins that scan the content of email for spam and viruses, respectively. You can see the spamassassin plug-in is configured to connect to a spamd socket and the clamdscan plug-in is configured to connect to a clamd socket. This assumes you have configured SpamAssassin and ClamAV to run as local sockets. Other virus scanning plug-ins also exist for BitDefender, Kasperski and Sophos.

There are a large number of other plug-ins you can also enable, both available in the qpsmtpd distribution and via the qpsmtpd Wiki. These include the tls plug-in, which provides support for TLS/SSL connections, and a number of authentication plug-ins available to allow users to authenticate to your email server from a variety of sources. Examples of the latter include LDAP servers, an SMTP or IMAP server, PAM and others.

Additionally, if you can't find a plug-in that does what you want you can make use of the Plug-in API to create your own plug-ins. You can read about the Plug-in API.

Dig Deeper on Linux servers

Start the conversation

Send me notifications when other members comment.

Please create a username to comment.