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:
check_earlytalker greylisting count_unrecognized_commands 4 check_basicheaders rcpt_ok virus/clamdscan clamd_socket /tmp/clamd spamassassin spamd_socket /tmp/spamd queue/postfix-queue
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 testdomain.com domain.com
- 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.
This was first published in January 2007