spamdyke

A drop-in connection-time spam filter for qmail

spamdyke Documentation

This file is updated with each version of spamdyke to reflect the latest features and behavior. If you need documentation for an older version, each version's README file is included in the download package for that version.

This document applies to spamdyke version 5.0.1.

• About spamdyke
• Support
• How spamdyke works: When a message is not blocked
• How spamdyke works: When a message is blocked
• Usage
• Configuration Files
• Configuration Directories
• Configuration Tests
• Log Messages
• SMTP Error Codes
• Logging All Data
• Permissions
• DNS Queries
• Filter Levels
• TLS
• SMTP AUTH
• Relaying
• Reverse DNS
• Blacklists
• DNS RBLs
• DNS RHSBLs
• Whitelists
• Rejecting Senders
• Rejecting Recipients
• DNS Whitelists
• Whitelisting Senders and Recipients
• Graylisting / Greylisting
• Earlytalkers
• Limiting Numbers of Recipients
• Rejecting Messages by Header Content
• Timeouts
• Extra Utilities

Other Documentation

The following additional documents are available:

Installation instructions: INSTALL.txt

Upgrading instructions: UPGRADING.txt

Frequently Asked Questions: FAQ.html

Change log: Changelog.txt

To-do list: TODO.txt

About spamdyke

help
more-help
version

spamdyke is a filter for monitoring and intercepting incoming SMTP connections to a qmail server. It acts as a transparent middleman, observing the conversation without interference unless it sees something it should block. Because it can silently monitor, it can also log mail traffic in several different ways.

spamdyke is ©2015 Sam Clippinger, samc (at) silence (dot) org. It is distributed under the GNU General Public License (version 2 only) from http://www.spamdyke.org/

The --help command line option will give a list of the available options. The --more-help command line option will give a more detailed list of available options and their default values. The --version command line option will give just the version and copyright statement.

Support

spamdyke support is available from the spamdyke-users mailing list: www.spamdyke.org/mailman/listinfo/spamdyke-users.

The mailing list archives are searchable thanks to mail-archive.com: www.mail-archive.com/spamdyke-users@spamdyke.org.

If all else fails, email the author directly at samc (at) silence (dot) org.

How spamdyke works: When a message is not blocked

spamdyke works by acting as a middleman between qmail and the network (in Unix terms, it's a pipe). When no spamdyke filters are triggered and a message is delivered normally, spamdyke silently passes data in both directions. As the SMTP conversation takes place, spamdyke collects a few pieces of data (e.g. the sender and recipient addresses) so they can be logged.

spamdyke does modify the incoming message in one way. The SMTP protocol requires the remote sender to end every line with a two character terminator -- a carriage return and a line feed. Unlike most other mail servers, qmail chooses to strictly enforce this requirement. If a remote sender uses only a line feed to end a line (a typical and easy mistake to make), qmail will reject the message:

451 See http://pobox.com/~djb/docs/smtplf.html.

How spamdyke works: When a message is blocked

spamdyke's filters are described in detail below. When one of them is triggered, spamdyke moves in to block the incoming message.

First, it considers the enabled filters and waits until there is no way the client can avoid a rejection. For example, if authentication could take place but has not done so, spamdyke will wait to see if the remote sender authenticates. Authenticated or whitelisted connections are never filtered.

Next, once spamdyke is certain the message should be filtered, it cuts the connection between the remote sender and qmail. In the background, spamdyke closes the connection to qmail, so qmail will exit normally, believing the remote sender disconnected.

spamdyke continues sending responses to the remote server, just as qmail would have. Once the remote sender has identified the sender and recipient, spamdyke sends an error code and refuses to accept the message. The remote server disconnects, never knowing that spamdyke hijacked the conversation. spamdyke, meanwhile, uses the sender and recipient information it gathered to construct its log messages.

Usage

spamdyke's behavior is controlled through options given on the command line or in configuration files (or both).

On the command line, long options should be prefixed with two hyphens (--). Some options have short versions, which should be prefixed with one hyphen (-).

In a configuration file, only the long versions are valid and an equals sign must separate the value from the option. See Configuration Files for details.

For example, consider the max-recipients option, which restricts the maximum number of recipients per message. On the command line, limiting the number of recipients to 5 might look like this:

spamdyke --max-recipients 5 ...

spamdyke -a 5 ...

max-recipients=5

If the option's value contains spaces, it should be surrounded by quotes on the command line. For example, consider the rejection-text-ip-blacklist option, which changes the error message spamdyke sends if the remote server's IP address is blacklisted. On the command line, changing the message might look like this:

spamdyke --rejection-text-ip-blacklist "Go away spammer" ...

rejection-text-ip-blacklist=Go away spammer

After all options are given, spamdyke expects the rest of its command line to contain the qmail command. For example:

spamdyke -a 5 /var/qmail/bin/qmail-smtpd

ERROR: Missing qmail-smtpd command

spamdyke -a 5 -- /var/qmail/bin/qmail-smtpd

The following options are only valid on the command line:

The following options are valid on the command line and in configuration files. Some options are not valid in files within configuration directories; those options are noted below. See Configuration Directories for details.

Configuration Files

config-file

The configuration file format is very simple. Each line should use the following format:

OPTION=VALUE

VALUE is the parameter for the option. Note: While multi-word values must be quoted on the command line, quotes are not allowed in configuration files. spamdyke reads the entire VALUE after the equals sign, even if it contains spaces, so no quoting is needed.

Blank lines and lines beginning with # are ignored.

For example:

smtp-auth-command=/home/vpopmail/bin/vchkpw /bin/true

rdns-blacklist-dir=/home/vpopmail/blacklist_rdns.d

graylist-dir=/home/vpopmail/graylist.d

check-dnsrbl=dul.dnsbl.sorbs.net

check-dnsrbl=zombie.dnsbl.sorbs.net

max-recipients=5

reject-empty-rdns

reject-empty-rdns=yes

reject-empty-rdns=true

reject-empty-rdns=1

spamdyke --config-file /etc/spamdyke.conf ...

spamdyke --reject-empty-rdns --config-file /etc/spamdyke.conf ...

reject-empty-rdns=false

Some options can be given multiple times and spamdyke will use all of the values it finds. For example, if the following lines are given, spamdyke will search each of the files for a match to the sender's email address:

sender-blacklist-file=/home/vpopmail/sender_blacklist.txt

sender-blacklist-file=/home/vpopmail/more_sender_blacklist.txt

sender-blacklist-file=/home/vpopmail/additional_sender_blacklist.txt

OPTION=!VALUE

sender-blacklist-file=!/home/vpopmail/sender_blacklist.txt

To clear all values from a list, three exclamation points should be given instead of a value:

OPTION=!!!

sender-blacklist-file=!!!

Note: spamdyke processes configuration directives in the order they are read. If an option is cleared and later set again, the option will retain the last value. For example, if the following five lines appear in this order:

sender-blacklist-file=/home/vpopmail/sender_blacklist.txt

sender-blacklist-file=/home/vpopmail/more_sender_blacklist.txt

sender-blacklist-file=/home/vpopmail/additional_sender_blacklist.txt

sender-blacklist-file=!!!

sender-blacklist-file=/home/vpopmail/last_blacklist.txt

NOTE: It may seem that scanning a configuration file instead of the command line would impose a performance penalty each time spamdyke is started. However, the reverse seems to be true. Some rudimentary testing has indicated the configuration files are actually faster. This is likely due to inefficiencies in GNU's getopt_long() function.

Configuration Directories

config-dir
config-dir-search

Configuration directories allow spamdyke's behavior to be altered based on the remote server's IP address, the remote server's rDNS name, the sender's email address, the recipient's email address or any combination of those things. This can be very useful when, for example, graylisting should be deactivated for a specific sender. Or when RBL filters should be disabled for a specific IP address. Or perhaps when extra filters should be enabled for only a few recipients.

Configuration directories could be used to allow domain administrators or even individual users to set their own options, such as whitelisting or blacklisting IPs or senders without affecting other domains/users on the server. Creating a web-based control panel to do this would be relatively easy.

Configuration directories are given with the config-dir option. The option's value should be the path to the directory that contains the subdirectories explained below. If config-dir is given multiple times, spamdyke will search each given directory structure and load all of the matching files before it continues processing the SMTP connection.

In essence, a configuration directory is a special directory structure that contains configuration files. spamdyke determines which files to load based on the names of the directories and the details of the SMTP connection. Not all options are valid within configuration directories, but in all other respects the files follow the same rules as global configuration files. See Usage for details of which options are valid within configuration directories. See Configuration Files for details of the configuration file format.

When spamdyke loads a file from a configuration directory, it will do so because the names of the directories and the name of the file match all or part of the information from the SMTP connection. The last piece of information should always be used as the name of the file, not the name of a directory.

To create a file using the IP address of the remote server, first create a directory structure that begins with _ip_ and uses the first three octets of the address as directory names. For example, if the IP address is 11.22.33.44, the directory structure should look like this:

.../_ip_/11/22/33

.../_ip_/11/22/33/44

To create a file using the rDNS name of the remote server, first create a directory structure that begins with _rdns_ and contains directories named using the rDNS name with its words reversed. For example, if the rDNS name is mail.internal.headquarters.example.com, the directory structure should look like this:

.../_rdns_/com/example/headquarters/internal

.../_rdns_/com/example/headquarters/internal/mail

To create a file using the sender's email address, first create a directory structure that begins with _sender_ and contains directories using the domain portion of the sender's email address with its words reversed and ending in _at_. For example, if the sender's email address is mom@home.example.com, the directory structure should look like this:

.../_sender_/com/example/home/_at_

.../_sender_/com/example/home/_at_/mom

To create a file using the recipient's email address, first create a directory structure that begins with _recipient_ and contains directories using the domain portion of the recipient's email address with its words reversed and ending in _at_. For example, if the recipient's email address is kid@school.example.com, the directory structure should look like this:

.../_recipient_/com/example/school/_at_

.../_recipient_/com/example/school/_at_/kid

.../_ip_/11/22/33/44

.../_ip_/11/22/33

.../_ip_/11/22

.../_ip_/11

.../_rdns_/com/example/headquarters/internal/mail

.../_rdns_/com/example/headquarters/internal

.../_rdns_/com/example/headquarters

.../_rdns_/com/example

.../_rdns_/com

.../_recipient_/com/example/school/_at_/kid

.../_recipient_/com/example/school

.../_recipient_/com/example

.../_recipient_/com

.../_sender_/com/example/home/_at_/mom

.../_sender_/com/example/home

.../_sender_/com/example

.../_sender_/com

Configuration directories can be nested to create more specific targets. For example, if the IP address of the remote server is 11.22.33.44 and the sender's email address is mom@home.example.com, spamdyke will read a configuration file if its path is either of the following:

.../_ip_/11/22/33/44/_sender_/com/example/home/_at_/mom

.../_sender_/com/example/home/_at_/mom/_ip_/11/22/33/44

.../_ip_/11/22/33/44/_sender_/com/example/home

.../_ip_/11/22/33/44/_sender_/com/example

.../_ip_/11/22/33/44/_sender_/com

.../_ip_/11/22/33/_sender_/com/example/home/_at_/mom

.../_ip_/11/22/_sender_/com/example/home/_at_/mom

.../_ip_/11/_sender_/com/example/home/_at_/mom

.../_sender_/com/example/home/_ip_/11/22/33

.../_sender_/com/example/_ip_/11/22

.../_sender_/com/_ip_/11

If all of that isn't confusing enough, spamdyke will only read one file from a _ip_, _rdns_, _sender_ or _recipient_ directory, even if more matches are possible. For example, if the remote IP address is 11.22.33.44, the sender's email address is mom@home.example.com and the recipient's email address is kid@school.example.com and two files exist with the following paths:

.../_ip_/11/22/33/44/_sender_/com/example/home/_at_/mom

.../_ip_/11/22/33/44/_recipient_/com/example/school/_at_/kid

config-dir-search can be given multiple times; the values will be added together to create a composite value. The possible values are:

• first: Match each _ip_, _rdns_, _sender_ or _recipient directory only once. NOTE: The first value erases the composite value created from the other possible values, essentially "resetting" the config-dir-search option.
• all-ip: Match each _ip_ directory as many times as possible.
• all-rdns: Match each _rdns_ directory as many times as possible.
• all-sender: Match each _sender_ directory as many times as possible.
• all-recipient: Match each _recipient_ directory as many times as possible.

To aid with troubleshooting, spamdyke will log the paths it searches if the log-level option is debug or higher.

Configuration Tests

config-test
config-test-smtpauth-username
config-test-smtpauth-password

spamdyke has the ability to scan its configuration and look for common configuration mistakes. It checks file paths, permissions, graylist folders, directory structures, SMTP AUTH commands, TLS certificates and more. This feature was inspired by Apache's ability to check its configuration file for syntax errors.

To use the testing feature:

1. Find and copy the entire spamdyke command line from your "supervise" script or xinetd configuration file, including the qmail command(s).
2. At a command prompt, login as root and paste the spamdyke command without running it.
3. Add the option --config-test among the spamdyke options (before the qmail command). If appropriate, add the options --config-test-smtpauth-username and --config-test-smtpauth-password.
4. Run the command and carefully read the results. More output can be obtained by increasing the logging level (no test output goes to syslog).

If spamdyke is configured to provide SMTP AUTH (using the smtp-auth-level and smtp-auth-command options), the --config-test-smtpauth-username and --config-test-smtpauth-password options should be used to provide a valid username and password for authentication. spamdyke will run the SMTP AUTH command to test its capabilities and make recommendations.

IMPORTANT! DANGER! WARNING! DO NOT EVER PUT THE --config-test OPTION IN THE SPAMDYKE COMMAND LINE THAT IS RUN FOR INCOMING CONNECTIONS! YOUR MAIL SERVER WILL IMMEDIATELY STOP RECEIVING MAIL AND REMOTE USERS WILL SEE ONLY THE DIAGNOSTIC OUTPUT! If you make this mistake and ask for help, expect to be publicly mocked. You have been warned.

Log Messages

log-level
log-target

The log-target option controls where spamdyke logs its messages. By default, log-target is set to syslog, which sends log messages to the system syslog facility. When log-target is set to stderr, messages are sent to standard error (stderr) instead. For most qmail installations, this will cause spamdyke's messages to be logged by the "multilog" program, along with qmail-smtpd's output. If log-target is given multiple times with different values, spamdyke will send its output to each given target.

When spamdyke logs to syslog, it uses the LOG_MAIL facility, which typically puts the messages in /var/log/maillog. (Note: Plesk reconfigures syslog to put the messages in /usr/local/psa/var/log/maillog.)

Regardless of how the messages are logged, errors are always be preceded by the text ERROR: and are fairly self-explanatory. Whenever possible, spamdyke will recover from an error and continue processing mail. Philosophically, it's better to continue receiving spam than to block all mail.

The log-level option controls how much logging takes place. The following values are supported:

• none: No logging at all, even if errors occur. This is not recommended.
• error: Critical errors only, including authentication failures. This is the default when log-level is not given.
• info: Everything from error plus logging of messages (sender, recipient, IP address, rDNS name and authenticated username). This is the value used when log-level is given with no value.
• verbose: Everything from info plus non-critical errors such as network errors caused by the remote host, protocol errors, config-test status messages and child process error messages. At this level, spamdyke will also print messages to show which filter blocked the connection (if applicable) and some details about the filter's settings. These messages will be prefixed with FILTER:.
• debug: Everything from verbose plus high-level debugging messages, intended to show the processing path within spamdyke. This level is handy for troubleshooting but it can be rather noisy. Extra messages generated by this level will be prefixed with DEBUG(): and will show the file and line number within the spamdyke source code where the message was produced. NOTE: If the configure script is run with the --without-debug-output option, spamdyke will accept the debug value but it will not print any more output than if verbose were used.
• excessive: Everything from debug plus lots of internal status messages. This value should only be used for development. Extra messages generated by this level will be prefixed with EXCESSIVE(): and will show the file and line number within the spamdyke source code where the message was produced. NOTE: Unless the configure script is run with the --with-excessive-output option, spamdyke will not produce any more output for excessive than if debug were used.

/usr/local/bin/spamdyke --log-level=verbose ...

/usr/local/bin/spamdyke -lverbose ...

/usr/local/bin/spamdyke --log-level ...

/usr/local/bin/spamdyke -l ...

Error messages and debugging statements are always preceeded by ERROR, DEBUG or EXCESSIVE, followed by the function name, the filename and the line number that produced it. Messages showing when a filter is triggered are preceeded by FILTER and do not include the location information. Each message log entry (produced when the value of log-level is info or higher) takes the following form:

CODE from: SENDER to: RECIPIENT origin_ip: IPADDRESS origin_rdns: RDNSNAME auth: USERNAME encryption: TYPE reason: REASON

The possible values of CODE are listed below:

SENDER is the sender email address, if known, or (unknown) otherwise. NOTE: According to RFC 821, it is legal to deliver messages with no sender address. Most bounce messages are delivered this way.

RECIPIENT is the recipient email address, if known, or (unknown) otherwise. If CODE is ALLOWED, the recipient email address will be known.

IPADDRESS is the IP address of the remote server. This value is always known.

RDNSNAME is the rDNS name of the remote server, if known, or (unknown) otherwise.

USERNAME is the username given during authentication, if authentication was successful, or (unknown) otherwise.

TYPE is the type of encryption used during the connection. The possible values are listed below:

REASON is provided to give an explanation of why a connection was blocked. See the table above for the possible values.

SMTP Error Codes

policy-url
rejection-text-auth-failure
rejection-text-auth-unknown
rejection-text-dns-blacklist
rejection-text-earlytalker
rejection-text-empty-rdns
rejection-text-graylist
rejection-text-header-blacklist
rejection-text-ip-blacklist
rejection-text-ip-in-cc-rdns
rejection-text-ip-in-rdns-keyword-blacklist
rejection-text-local-recipient
rejection-text-max-recipients
rejection-text-missing-sender-mx
rejection-text-rdns-blacklist
rejection-text-recipient-blacklist
rejection-text-recipient-invalid
rejection-text-recipient-same-as-sender
rejection-text-recipient-unavailable
rejection-text-reject-all
rejection-text-relaying-denied
rejection-text-rhs-blacklist
rejection-text-sender-authentication-mismatch
rejection-text-sender-blacklist
rejection-text-sender-not-local
rejection-text-smtp-auth-required
rejection-text-timeout
rejection-text-tls-failure
rejection-text-unresolvable-rdns
rejection-text-zero-recipients

When spamdyke blocks a connection and returns an error code to a remote server, the text it sends is different from what appears in the logs (above). It is more user-friendly, just in case a human ever reads it (some, but not all, mail servers display the rejection message in bounce messages).

The messages can be changed using the options that are listed in the third column of the table below.

The messages that correspond to the syslog codes are:

If a policy location URL is given with the policy-url option, it will be appended to the end of the message, just in case a human ever reads it. This option should always be used. When a legitimate remote user is incorrectly blocked, the URL should provide your contact information so the error can be corrected.

spamdyke will always append the syslog code to the policy URL so a web browser will jump to an anchor within the HTML document. Most of the time, the code is prefixed with a # character. For example, if the policy URL is:

http://www.example.com/policy.html

http://www.example.com/policy.html#DENIED_RDNS_MISSING

http://www.example.com/policy?code=

http://www.example.com/policy?code=DENIED_RDNS_MISSING

Logging All Data

full-log-dir

spamdyke has the ability to log all SMTP data to files. This is very helpful when debugging but (depending on the mail server traffic levels) it can generate a huge number of files.

This feature is activated with the full-log-dir option. Each connection will be logged to a different file in the folder given, with a naming convention that incorporates the current date and time, the process ID of the spamdyke process and a random number:

YYYYMMDD_HHMMSS_PID_RANDOMNUM

The data from the remote server and qmail are both logged to the file. Each transmission is preceded with a line showing its origin and destination as well as the time and date.

If the remote client establishes a TLS session with qmail and spamdyke passes the encrypted data, the logs will contain the data as hexadecimal bytes.

The logs will contain all debugging output spamdyke can produce, the same output that would be produced if log-level were set to its highest level. spamdyke will also print its current configuration into the log file every time it processes a configuration file, to show what options are active and what their values are.

Log files are created with a 0600 mode to protect them from being read by unauthorized users. Please take other precautions to protect them and don't leave them lying around.

NOTE: This feature is intended to be used for debugging delivery problems, not for monitoring email content. Among other issues, the format of the log files does not make it easy to reconstruct a whole message. If you must monitor your users' email data, please use a packet sniffer on a separate machine or SMTP proxy software designed for the task.

Permissions

run-as-user

On most Unix-based systems, only the superuser can start a daemon that listens on port 25 (the SMTP port). However, since running daemons as the superuser should be avoided whenever possible, most qmail installations use utilities to switch the daemon's owner to a normal user before qmail actually runs.

Some older qmail installations lack this ability, notably ones that use the inetd "superserver" to start qmail. To help provide security in these situations, spamdyke provides the run-as-user option to force spamdyke to switch to a different user account as soon as it starts. All of spamdyke's child processes (including qmail) will run under the new user account.

The value of run-as-user takes the following form:

USER[:GROUP]

On systems where qmail does not run as the superuser, run-as-user can be used to force spamdyke to change accounts when the config-test option is used, so that its tests of filesystem permissions will be meaningful.

DNS Queries

dns-level
dns-max-retries-primary
dns-max-retries-total
dns-query-type-a
dns-query-type-mx
dns-query-type-ptr
dns-query-type-rbl
dns-resolv-conf
dns-server-ip
dns-server-ip-primary
dns-spoof
dns-tcp
dns-timeout-secs

Because so many of spamdyke's filters rely so heavily on DNS queries, spamdyke provides a number of options to tune its DNS activities. Take care when using any of these options, as setting them incorrectly can prevent spamdyke from functioning correctly. Most of the time, there is no need to use them -- spamdyke will read its DNS information from /etc/resolv.conf and the environment, as documented in the system resolver(5) manual page. If the option dns-resolv-conf is given, spamdyke will read the given file instead of /etc/resolv.conf. NOTE: spamdyke does not read the /etc/hosts file.

spamdyke ranks nameservers into two categories: "primary" and "secondary". Primary nameservers are queried first; secondary nameservers are only queried if no response is received from a primary nameserver.

Normally, spamdyke reads its list of nameservers from /etc/resolv.conf (or another file given with dns-resolv-conf), just like any other program. It considers the first nameserver it finds in that file to be a primary nameserver. All others are considered to be secondary nameservers. This list can be overridden, however, using the dns-server-ip and dns-server-ip-primary options. spamdyke also honors the port, timeout and options directives (if any) in the /etc/resolv.conf file (or another file given with dns-resolv-conf). If the environment variable RES_OPTIONS is present, spamdyke will parse it for a timeout value.

If either dns-server-ip or dns-server-ip-primary are used, the file /etc/resolv.conf is not loaded. Both options take values in the same format:

IPADDRESS[:PORT]

dns-server-ip and dns-server-ip-primary can each be given multiple times to specify multiple servers in each category.

If dns-server-ip and dns-server-ip-primary are not given and no nameservers can be found by reading /etc/resolv.conf, the IP address 127.0.0.1 (the localhost address) is used.

By default, spamdyke will attempt to query its primary nameserver once, then all of its nameservers twice more, taking no more than 30 seconds total. The option dns-max-retries-total controls the total number of attempts spamdyke makes to contact its nameservers (the number of query packets actually sent may be much greater than this value; see below). The option dns-max-retries-primary controls how long spamdyke sends queries only to its primary nameservers. This value must be less than or equal to dns-max-retries-total.

The option dns-timeout-secs controls the total time spamdyke will spend waiting for the results of a single query. All of its retries will be carried out within this time limit. NOTE: The timeout value must be large enough for nameservers to complete their work and respond. If it is too low, spamdyke will never successfully complete a query.

The dns-level option controls how aggressively spamdyke queries its nameservers. It takes the following values:

• aggressive: Query all primary nameservers simultaneously until dns-max-retries-primary is reached, then query all nameservers simultaneously until dns-max-retries-total is reached. This is the default. For example, if there are 2 primary nameservers, 3 secondary nameservers, dns-max-retries-primary is 4 and dns-max-retries-total is 6, spamdyke will: send a simultaneous query to each of the 2 primary nameservers 4 times, for a total of 8 queries. It will then send a simultaneous query to all 5 nameservers 2 more times, for a grand total of 18 queries.
• normal: Imitate the standard system resolver's behavior by sending queries to one nameserver at a time. spamdyke will send queries to each of the primary nameservers in sequence until dns-max-retries-primary is reached, then it will add the secondary nameservers to the sequence and continue sending queries until dns-max-retries-total is reached. Depending on the number of nameservers and the values of dns-max-retries-primary and dns-max-retries-total, some nameservers may never be queried.
• none: Do not query any nameservers at all. All DNS-based features will behave as though their queries returned no results.

Depending on the type of query spamdyke is performing, multiple packets are typically sent to each nameserver. By default, when querying a DNS RBL, a "query" consists of 3 packets -- one requesting A records, one requesting TXT records and one requesting CNAME records. In the aggressive example above, the 18 queries would result in 52 data packets. This behavior can be controlled through the use of several options:

dns-query-type-a: Sets the types of queries that are performed when seeking an IP address when looking up a reverse DNS name. The following values can be given:

• a: Request and process DNS A records in response to queries.
• cname: Request and process DNS CNAME records in response to queries. This is desirable if the target name is simply an alias for another name.

dns-query-type-mx: Sets the types of queries that are performed when seeking a mail server record within the "reject-missing-sender-mx" filter. The following values can be given:

• a: Request and process DNS A records in response to queries. This is desirable if the name is a specific machine instead of a domain name.
• cname: Request and process DNS CNAME records in response to queries. This is desirable if the target name is simply an alias for another name.
• mx: Request and process DNS MX records in response to queries.

dns-query-type-ptr: Sets the types of queries that are performed when seeking a reverse DNS name. The following values can be given:

• cname: Request and process DNS CNAME records in response to queries. This is desirable if the target name is simply an alias for another name. Many ISPs delegate PTR control this way.
• ptr: Request and process DNS PTR records in response to queries.

dns-query-type-rbl: Sets the types of queries that are performed when querying a DNS RBL, RHSBL, DNS whitelist or RHSWL. The following values can be given:

• a: Request and process DNS A records in response to queries.
• cname: Request and process DNS CNAME records in response to queries.
• txt: Request and process DNS TXT records in response to queries.

Most DNS queries are performed using UDP packets, which can carry no more than 512 bytes of data. This is enough data for typical DNS data, but occasionally some records are too big to fit in 512 bytes. When that happens, the nameserver should reply with a UDP packet that indicates the data is too large. The solution is to then resend the query via TCP, which can handle data of any size. spamdyke will fall back to TCP if the dns-tcp option is set to normal. If it is none, spamdyke will not use TCP at all; it will ignore the response entirely and continue its normal query pattern.

UDP packets are stateless, which means any server on the internet can send a UDP packet to any other server at any time. In theory, if spamdyke sends a DNS query via UDP and a malicious server sends a UDP response at the right moment, spamdyke will accept it as the answer to its query. (This would be extremely difficult, as the malicious server would have to know a lot about spamdyke's internal state to create an acceptable reply, but it is possible).

To prevent this from happening, spamdyke always checks the response ID against the query IDs and dicards any responses that don't match. In addition, spamdyke can check the IP address and port number of the remote server to see if they match the IP and port to which the query packet(s) were sent. The following values of the dns-spoof option control spamdyke's behavior:

• accept-all: Accept any response from any server. This is the default.
• accept-same-ip: Accept any response as long as the IP address of the sending server is the same as the IP address the query was sent to. The port number may be different.
• accept-same-port: Accept any response as long as the port number on the sending server is the same as the port number the query was sent to. The IP address may be different. (This option may not be very useful.)
• reject: Only accept responses where the IP address and port number of the sending server match the IP address and port number the query was sent to.

Filter Levels

filter-level

spamdyke's overall filter behavior can be controlled with the filter-level option. NOTE: filter-level takes precedence over all other filters and features, including authentication and whitelisting.

The possible values are:

• allow-all: Allow all connections, effectively whitelisting everything.
• normal: Allow only the connections that pass the enabled filters. This is the default.
• require-auth: Allow only authenticated connections, even the ones that match a whitelist entry.
• reject-all: Reject all connections, even if they are whitelisted or authenticated.

The values allow-all and reject-all are most useful within configuration directories, where they can be set e.g. for specific recipients.

TLS

tls-certificate-file
tls-cipher-list
tls-dhparams-file
tls-level
tls-privatekey-file
tls-privatekey-password
tls-privatekey-password-file

TLS is another name for SSL, the same encryption protocol used by secure websites (it's called SSL when the entire connection is encrypted from the start, it's called TLS when the encryption is started later during the connection). TLS can be used during SMTP to provide secure communications between the remote client and the server.

spamdyke supports TLS in several ways. First, with no TLS options given, spamdyke will identify a TLS conversation and simply pass the data back and forth between qmail and the remote client. In this mode, spamdyke cannot read the SMTP data (obviously -- it's encrypted). This prevents some of its filters from functioning, including graylisting, sender and recipient blacklisting, limiting the number of recipients, checking the sender's domain name for an MX record and relaying.

Second, spamdyke can provide TLS itself. To do this, it must be compiled with TLS support, which requires OpenSSL libraries on the server (see the Installation instructions for details). The value of the tls-level option controls how TLS is provided:

• none: Do not provide or allow TLS, even if qmail supports it. qmail's attempt to advertise its TLS support will be hidden and the remote server's request for TLS will be denied.
• smtp: Provide TLS during the SMTP session, so it can be started if the remote server requests it. spamdyke will decrypt all of the data and pass the plaintext to qmail. qmail will not be aware TLS is happening. In this mode, qmail does not need to be patched to provide TLS. However, if the SSL library cannot be initialized for some reason (e.g. missing certificate, bad cipher list), the TLS data will be passed through to qmail in encrypted format so qmail can provide TLS (assuming qmail has been patched to support it). In this mode, spamdyke will not be able to read the data, so some of its filters will not function.
• smtp-no-passthrough: Provide TLS during the SMTP session, so it can be started if the remote server requests it. spamdyke will decrypt all of the data and pass the plaintext to qmail. qmail will not be aware TLS is happening. In this mode, qmail does not need to be patched to provide TLS. If spamdyke cannot start TLS for any reason, the encrypted data will not be passed through to qmail.
• smtps: Start an SSL session as soon as the connection is opened. This mode is called "SMTP over SSL" or "SMTPS". The remote client must support this method. Typically, SMTPS is offered on port 465, not port 25.

If tls-level is smtp, smtp-no-passthrough or smtps, the server certificate must also be provided with the tls-certificate-file parameter.

The server certificate file must be in PEM format. If the private key is not in the certificate file, it must be provided in PEM format with the tls-privatekey-file parameter. If the private key is encrypted with a password, the password must be provided with the tls-privatekey-password parameter. Because providing the private key password on the command line is very insecure, the password can also be contained in a file and loaded using the tls-privatekey-password-file parameter.

Generating self-signed certificates is very easy with OpenSSL. Countless tutorials are available on the web.

Rarely, some situations will require specifying the list of encryption algorithms (ciphers) to be used during TLS. In those cases, the tls-cipher-list option can be used to pass a list of ciphers in the format expected by the OpenSSL library. The vast majority of spamdyke installations will not need this option -- the default list of ciphers is usually fine. To see the full list of available ciphers, run the command openssl ciphers. For details on how to construct the list, see www.openssl.org/docs/apps/ciphers.html. NOTE: Be careful to check the list of ciphers very carefully -- invalid ciphers (typos) are allowed and will be silently ignored. The OpenSSL library will only produce an error if none of the ciphers in the list can be used.

Some ciphers will generate "ephemeral" keys for encrypting the connection, which provides an extra level of security (referred to as "forward security"). In order to do this, an additional "DH params" file must be provided in PEM format with the tls-dhparams-file option. The file can be generated using the openssl dhparam command. NOTE: This option is unneeded unless the tls-cipher-list option is also used to specify a cipher that requires a "DH params" file.

If there are any problems reading the certificate, the private key, decrypting the private key or initializing the ciphers, spamdyke will log the errors to syslog and fall back to passing the TLS data through to qmail, if qmail has been patched to provide TLS (or spamdyke will send the remote client an error message if qmail doesn't provide TLS). spamdyke will also log the error messages produced by OpenSSL, even though they're rarely helpful.

NOTE: spamdyke does not disable any of its filters simply because a remote client uses TLS or SSL. In SMTP, TLS/SSL is simply a method of securing the communication channel. It is not an authentication method and spammers are using TLS. spamdyke will only disable its filters for clients it finds on its whitelists or ones that use SMTP AUTH.

If in doubt about enabling TLS, do it. Encrypting email data is always a good thing.

SMTP AUTH

hostname
hostname-command
hostname-file
smtp-auth-command
smtp-auth-level

SMTP AUTH is a mechanism for remote users to authenticate before sending email (defined in RFC 2554). This is very handy when users are likely to connect from remote locations (e.g. coffee shops, hotels) and want to bypass relaying restrictions and other filters. spamdyke will disable all of its filters for authenticated connections unless the filter-level option overrides this behavior. See Filter Levels for details.

spamdyke supports SMTP AUTH according to the value of the smtp-auth-level option:

• none: Do not offer or allow SMTP AUTH. If qmail has been patched to provide SMTP AUTH, spamdyke will block its advertisement of SMTP AUTH and will prevent the remote server from authenticating.
• observe: If qmail has been patched to provide SMTP AUTH, simply observe the authentication and trust qmail's response. If qmail has not been patched to provide SMTP AUTH, do not provide SMTP AUTH. This is the default.
• ondemand: If qmail has been patched to provide SMTP AUTH, simply observe the authentication and trust qmail's response. If qmail has not been patched to provide SMTP AUTH, offer it and process the authentication without letting qmail know it took place.
• ondemand-encrypted: Offer SMTP AUTH as needed, just like ondemand, but also offer the encrypted protocol CRAM-MD5. See below for a full description.
• always: Always offer and process SMTP AUTH, even if qmail has been patched to provide SMTP AUTH. This value should only be used if qmail's authentication is malfunctioning for some reason.
• always-encrypted: Always offer and process SMTP AUTH, just like always, but also offer the encrypted protocol CRAM-MD5. See below for a full description.

When the value of smtp-auth-level is ondemand, ondemand-encrypted, always or always-encrypted, the option smtp-auth-command must also be given to provide spamdyke with the command for processing authentication. If multiple commands are available, smtp-auth-command may be given multiple times. spamdyke will run each command in order until one of them is successful.

For bare qmail installations where the users are stored in /etc/passwd the value of smtp-auth-command is usually:

/bin/checkpassword /bin/true

/home/vpopmail/bin/vchkpw /bin/true

For Plesk users, the values of smtp-auth-command are usually:

/var/qmail/bin/smtp_auth /var/qmail/bin/true

/var/qmail/bin/cmd5checkpw /var/qmail/bin/true

Some background on encrypted authentication: SMTP AUTH can be done using one of several protocols, defined by RFC 2554. Two of them are very simple: LOGIN and PLAIN. Although they work slightly differently, LOGIN and PLAIN both send the username and password to the server, which authenticates them. With these protocols, the server does not have to store the user's password in an unencrypted format. If the passwords are encrypted on the server, the authentication process can simply encrypt the password it receives and compare the two encrypted versions. If they match, the password must have been correct.

Unfortunately, this means that the password must be sent to the server in an unencrypted format so the authentication process can encrypt it for comparison. Unless an external encryption protocol is used (e.g. TLS or SMTPS), the passwords are theoretically vulnerable to eavesdropping.

For this reason, another protocol was created called CRAM-MD5. CRAM-MD5 is a "challenge/response" protocol, which allows authentication to take place without sending the password to the server in an unencrypted form. In essence, the protocol starts when the server generates some random text and sends it to the remote client (the "challenge"). The remote client encrypts the text with the user's password and sends it back to the server (the "response"). The server also encrypts the text with the user's password and compares the result to the response from the client. If they match, the remote client must have the correct password.

The challenge text is generated from several sources, including the name of the local server. The hostname, hostname-command or hostname-file option can be used to provide the local server's name for this reason. When hostname is used, the value should be the server's name. When hostname-command is used, the value should be a command that will print the server's name as its first line of output. When hostname-file is used, the value should be the path to a file that contains the server's name as its first line. By default, hostname-file is set to /var/qmail/control/me. NOTE: If the local server's name is not provided, CRAM-MD5 will still work and it will still generate random challenge text. Using the local server's name only makes it slightly more secure. It's not worth a large effort to provide it.

Unfortunately, this means that the password must be stored on the server in an unencrypted format so the authentication process can use it to encrypt the challenge text. Theoretically, this leaves the passwords vulnerable to theft by an intruder who breaks into the server.

When smtp-auth-level is ondemand-encryption or always-encryption, spamdyke will offer the CRAM-MD5 protocol to the remote client. However, if the passwords are not stored on the server in an unencrypted format or if the authentication command does not understand CRAM-MD5, CRAM-MD5 will always fail.

If you're not sure which value to use, run spamdyke with the config-test option. It will test the authentication commands and recommend a value. See Configuration Tests for details.

If in doubt about enabling SMTP AUTH, do it. Authenticating your users is always a good thing.

Relaying

ip-relay-entry
ip-relay-file
rdns-relay-entry
rdns-relay-file
relay-level

A little background: when a message is delivered for a recipient that isn't hosted on the local server, that message is said to be "relayed". Most servers do not allow relaying except from authorized sources, in order to prevent abuse by spammers or poorly-configured software. When a server allows every connection to relay messages without authentication, it is called an "open relay". Open relays are quickly blacklisted all across the internet because spammers quickly exploit them for sending massive amounts of email.

Remote servers are allowed to relay if the environment variable RELAYCLIENT is set to any value. Most qmail guides recommend an entry like this one in the /etc/tcp.smtp file:

11.22.33.44:allow,RELAYCLIENT=""

spamdyke's relay-level option controls how spamdyke controls relaying. The available options are:

• block-all: Block all attempts at relaying, even if the remote server has authenticated.
• normal: Do not check for or prevent relaying and do not interfere with qmail's relay filter. Authenticated connections and any servers identified by the options ip-relay-entry, ip-relay-file, rdns-relay-entry and rdns-relay-file are allowed to relay. This is the default.
• allow-all: Allow all connections to relay messages (create an open relay). This is not recommended.

spamdyke will allow relaying from IP addresses listed in a file and given with the option ip-relay-file. See IP Address Files for details on the format of this file. If the ip-relay-file option is given multiple times, each file will be checked for the remote IP address; relaying will be allowed if the IP address is found in any of the files.

If only a few IP addresses should be allowed to relay, the option ip-relay-entry may be used instead. The entries should follow the format as the lines in an IP address file.

Alternatively, spamdyke will allow relaying from rDNS names listed in a file and given with the option rdns-relay-file. See rDNS Files for details on the format of this file. If the rdns-relay-file option is given multiple times, each file will be checked for the rDNS name; relaying will be allowed if the rDNS name is found in any of the files.

If only a few rDNS names should be allowed to relay, the option rdns-relay-entry may be used instead. The entries should follow the format as the lines in an rDNS file.

Reverse DNS

ip-in-rdns-keyword-blacklist-entry
ip-in-rdns-keyword-blacklist-file
ip-in-rdns-keyword-whitelist-entry
ip-in-rdns-keyword-whitelist-file
reject-empty-rdns
reject-ip-in-cc-rdns
reject-unresolvable-rdns

Reverse DNS is the part of the DNS system that maps IP addresses back to names. If you don't understand reverse DNS, please please please read one of the (thousands of) online tutorials on the subject. Every mail server administrator should know about reverse DNS. It's not complicated. Please take the time to learn it.

spamdyke does a lot of work with rDNS names. The first and most basic test is to make sure the remote server has an rDNS name, any name. This filter is activated with the reject-empty-rdns option. AOL and most other major ISPs use this test. By default, this filter is not run.

The next test is to make sure the remote server's rDNS name resolves. This test only attempts to get at least one IP address from the name. It does not require the rDNS name's IP address to match the remote server's IP address. For example, if the remote server's IP address is 11.22.33.44 and its rDNS name is mail.example.com, this test will query mail.example.com. Even if it resolves to 66.77.88.99, the test will pass. Note: The name localhost is handled specially. If the rDNS name is localhost and the IP address is not 127.0.0.1, the test fails. This filter is activated with the reject-unresolvable-rdns option. By default, this filter is not run.

NOTE: reject-unresolvable-rdns does not imply reject-empty-rdns. In other words, using just the reject-unresolvable-rdns option will block connections from servers with unresolvable rDNS names but it will not block connections from servers with no rDNS names at all. Most users will want to use reject-empty-rdns if they use reject-unresolvable-rdns.

spamdyke also has several filters that look for an IP address in the rDNS name, since that typically indicates a server sending email that shouldn't be (e.g. a virus-infected Windows machine on a cable modem). If the rDNS name contains the IP address and a keyword given with the ip-in-rdns-keyword-blacklist-entry option, spamdyke will block the connection.

Simple keywords can be provided. For example, dynamic will match an rDNS name like 11.22.33.44.dynamic.example.com. NOTE: The keyword will not be matched in the domain name (i.e. the keyword example would not be found).

Domain names can be provided if they are preceded by a dot. For example, .example.com (or just .com) will match 11.22.33.44.dynamic.example.com.

Complex patterns can also be provided to match multiple keywords in sequence. When the keywords are separated by spaces, spamdyke will only find a match if all of the keywords are found. For example, cable dynamic .example.com will match 11.22.33.44.cable.modem.dynamic.customer.example.com but it will not match 11.22.33.44.cable.modem.static.customer.example.com.

All keyword searches are case-insensitive.

If more than a few keywords are provided, the ip-in-rdns-keyword-blacklist-file option is much more efficient. The keywords (or patterns) should be listed one per line. Blank lines and lines beginning with # will be ignored.

spamdyke also accepts the ip-in-keyword-whitelist-entry and ip-in-keyword-whitelist-file options that match keywords exactly the same way as the blacklist options. The whitelist options bypass all filters when a connection matches, however, instead of blocking the connection.

spamdyke offers one other option that searches for an IP address in the rDNS name: reject-ip-in-cc-rdns. In essence, this option is the same as using ip-in-rdns-keyword-blacklist-entry for every two-letter country code (e.g. .us). This option is not very useful for large servers or servers outside the United States. As ICANN begins allowing arbitrary top-level domains, two-letter domains will no longer be a reliable way of detecting non-US servers.

When matching an IP address in an rDNS name, spamdyke looks for the IP address in many forms; for example, if the IP address is 11.22.33.44, spamdyke will look for the following patterns in the rDNS name (the dots in the examples below can be any single character):

11.22.33.44

011.022.033.044

11.022.033.044

11.22.033.044

11.22.33.044

44.33.22.11

44.33.22.011

44.33.022.011

44.033.022.011

044.033.022.011

44.11.22.33

33.22.11.44

44.33.1122

3344.11.22

11.22.8492 (last two octets combined and converted to an integer)

11223344

11.22.3344

11.223344

011022033044

11022033044

1122033044

112233044

44332211

044033022011

3930621781 (entire address converted to an integer)

5080d7e3 (each octet converted to hexadecimal)

Blacklists

ip-blacklist-entry
ip-blacklist-file
rdns-blacklist-dir
rdns-blacklist-entry
rdns-blacklist-file

First, let's all agree that blacklists are evil, arbitrary, unforgiving, unfair, etc, etc, blah blah blah. OK. If you feel that way, don't use one.

But, if you decide to use one, it can block over half the spam you would otherwise receive. Blacklists are very effective against professional spammers who buy thousands of domain names and run their own mail servers (constantly moving them around, of course). It's your decision.

NOTE: Constructing and maintaining a blacklist is left as an exercise for the reader. spamdyke will use a blacklist but it won't help you build one.

spamdyke will search for the remote server's rDNS name in a file and block the connection if it is found. This is activated with the rdns-blacklist-file option. See rDNS Files for details on the format of this file. If the rdns-blacklist-file option is given multiple times, each file will be checked before the connection is allowed.

If only a few rDNS names should be blacklisted, the option rdns-blacklist-entry can be used instead. The entries should follow the same format as the lines in an rDNS file.

spamdyke will also search for the remote server's rDNS name in a directory structure and block the connection if it is found. For large lists of rDNS names (more than 100), the directory structure is much faster than a file. This is activated with the rdns-blacklist-dir option. See rDNS Directories for details on the structure of this directory. If the rdns-blacklist-dir option is given multiple times, each directory will be checked before the connection is allowed.

spamdyke will also search for the remote server's IP address in a file and block the connection if it is found. This is activated with the ip-blacklist-file option. See IP Address Files for details on the format of this file. If the ip-blacklist-file option is given multiple times, each blacklist file will be checked before the connection is allowed.

If only a few IP addresses should be blacklisted, the option ip-blacklist-entry can be used instead. The entries should follow the same format as the lines in an IP address file.

DNS RBLs

dns-blacklist-entry
dns-blacklist-file

DNS Realtime Blackhole Lists are services maintained by third parties that list IP addresses (presumably the IP addresses of spammers). The criteria for getting listed on a DNS RBL vary by organization and it's often very hard to get delisted. Sometimes, listings are politically motivated; some DNS RBL operators try to force large ISPs to cancel spammers' accounts by listing all of the ISP's IP addresses, innocent or guilty. If you choose to use a DNS RBL, please do some preliminary research to understand its policies and history of complaints.

spamdyke will reject connections from an IP address listed in a given DNS RBL. This feature is activated with the dns-blacklist-entry option. By default, spamdyke does not use a DNS RBL. If the dns-blacklist-entry option is given multiple times, each DNS RBL will be checked before the connection is allowed.

If more than a few DNS RBLs are needed, the dns-blacklist-file option is more efficient than dns-blacklist-entry. Each line in the file should contain the name of one DNS RBL.

NOTE: Checking DNS RBLs can impose a serious performance penalty. Using more than three DNS RBLs is not recommended.

DNS RHSBLs

rhs-blacklist-entry
rhs-blacklist-file

DNS Righthand-side Blacklists are services maintained by third parties that list domain names (presumably the domain names of spammers). The criteria for getting listed on a DNS RHSBL vary by organization and it's often very hard to get delisted. Sometimes, listing are politically motivated; some DNS RHSBL operators try to force large ISPs to cancel spammers' accounts by listing all of the ISP's domain names, innocent or guilty. If you choose to use a DNS RHSBL, please do some preliminary research to understand their policies and history of complaints.

spamdyke will reject connections from servers whose reverse DNS names are listed in a given DNS RHSBL. spamdyke will also reject connections from senders whose email domain names are listed in a given DNS RHSBL. These features are activated with the rhs-blacklist-entry option. By default, spamdyke does not use a DNS RHSBL. If the rhs-blacklist-entry option is given multiple times, each DNS RHSBL will be checked before the connection is allowed.

If more than a few DNS RHSBLs are needed, the rhs-blacklist-file option is more efficient than rhs-blacklist-entry. Each line in the file should contain the name of one DNS RHSBL.

NOTE: Checking DNS RHSBLs can impose a serious performance penalty. Using more than three DNS RHSBLs is not recommended.

Whitelists

ip-whitelist-entry
ip-whitelist-file
rdns-whitelist-dir
rdns-whitelist-entry
rdns-whitelist-file

spamdyke will match the remote server's rDNS name against a list given with the rdns-whitelist-entry option and skip all filters if it is found. If more than a few entries are given, the rdns-whitelist-file option is much more efficient; it can be used to put the entries in a file, one per line. See rDNS Files for details on the format of this file. If rdns-whitelist-file option is given multiple times, each whitelist file will be checked before the connection is blocked.

spamdyke will also search for the remote server's rDNS name in a directory structure and skip all filters if it is found. This is activated with the rdns-whitelist-dir option. See rDNS Directories for details on the format of this directory structure. If rdns-whitelist-dir option is given multiple times, each directory will be checked before the connection is blocked.

spamdyke will also search for the remote server's IP address in a list of entries and skip all filters if it is found. This is activated with the ip-whitelist-entry option. If more than a few entries are given, the ip-whitelist-file option is more efficient; it can be used to put the entries in a file. See IP Address Files for details on the format of this file. If the ip-whitelist-file option is given multiple times, each whitelist file will be checked before the connection is blocked.

Rejecting Senders

reject-sender
sender-blacklist-entry
sender-blacklist-file

Before using spamdyke's options to block senders, it's important to understand the difference between a "sender address" (sometimes call the "envelope sender") and the "from address". The "sender address" is the email address given to the mail server when the message arrives and it's where a bounce message will be sent. The "from address" is what the user sees in their email client on the "from" line. The two addresses can be completely different and totally unrelated. To use an analogy, the "sender address" is like the return address written on the outside of a snail mail envelope. If the envelope can't be delivered, the post office will send it back to the sender address. The "from address" is like the address on the top of the letter inside the envelope. The post office never sees the letter inside the envelope, so it they can't use it. spamdyke (and qmail) is like the post office -- it uses only the "sender" address. That's why the filters described in this section work on the "sender" address, not the "from" address. To block messages based on the "from" address, see Rejecting Messages by Header Content.

spamdyke will block all incoming messages from a specific address with the sender-blacklist-entry option. If more than a few addresses are given, the sender-blacklist-file option is more efficient. The given file must contain one email address per line. Blank lines and lines beginning with # are ignored. If the sender-blacklist-file option is given multiple times, each blacklist file will be checked before the connection is blocked.

One form of wildcard address is supported. All usernames within a domain (and its subdomains) may be blocked by a line starting with @. For example, if the file contained the following entry:

@example.com

spamdyke's reject-sender option controls several other filters for blocking senders and it can be used multiple times to enable more than one filter. The available options are:

• none: Disable the reject-sender filters. This is the default.
• no-mx: Use DNS to check if a sender's domain name can receive email. To pass this filter, the sender's domain name must have a valid mail exchanger (MX record) and the mail exchanger must have an IP address (A record). This filter tends to block a lot of mail from compromised web servers that aren't supposed to be sending email.
• not-local: Senders are only accepted if their domain name is hosted on the local server. This is determined by searching the files given using the qmail-rcpthosts-file and qmail-morercpthosts-cdb options. Those options have default values but if the files do not exist or those options are cleared, this value has no effect. See Rejecting Recipients for more details on those options.
• authentication-mismatch: Senders are only accepted if the sender address is the same as the username that was used for authentication. This filter enforces an exact match. For example, if the mail client authenticated with the username fred@example.com, the sender must be exactly fred@example.com. If the mail client authenticated with a username that wasn't an email address, this filter will only match the username portion of the sender address. For example, if the mail client authenticated with just barney, this filter will allow both barney@example.com and barney@somethingelse.net, because they both begin with barney@. NOTE: if the mail client does not authenticate, this value has no effect.
• authentication-domain-mismatch: Senders are only accepted if the sender's domain name is the same as the domain name of the email address used for authentication. For example, if the mail client authenticated with the username wilma@bedrock.com, the sender address barney@bedrock.com will be accepted but fred@flintstone.com will not. If the mail client authenticates with a username that isn't an email address, this value has no effect. NOTE: if the mail client does not authenticate, this value has no effect.

Rejecting Recipients

qmail-morercpthosts-cdb
qmail-rcpthosts-file
recipient-blacklist-entry
recipient-blacklist-file
recipient-validation-command
reject-recipient

There are lots of different reasons for wanting to block messages to specific recipient addresses. Sometimes spammers will choose to target a specific address and send it thousands of messages. Sometimes a spammer will use one of your email addresses as the sender address on thousands of spam messages and you receive bounce messages for all of their spams. (This is commonly referred to as a "joe job".) Many spammers attempt to send messages that are "from" and "to" the same address, hoping to bypass spam filters. spamdyke can stop those messages as well.

But most often, qmail administrators need a way to stop "backscatter spam". This is the name given to spam that is sent to invalid addresses. If the mail server accepts the message and later tries to send a bounce message, it results in "backscatter" because the "from" address is almost always invalid, which makes the bounce message land in some other victim's mailbox. qmail will do this, because it was created before spam was really a problem. spamdyke can validate recipient addresses as they come in and reject invalid addresses, which stops backscatter spam in its tracks.

spamdyke will block all incoming messages to a specific address with the recipient-blacklist-entry option. If more than a few addresses are given, the recipient-blacklist-file option is much more efficient. The given file must contain one email address per line. Blank lines and lines beginning with # are ignored. If the recipient-blacklist-file option is given multiple times, each blacklist file will be checked before the connection is blocked.

One form of wildcard address is supported. All usernames within a domain (and its subdomains) may be blocked by a line starting with @. For example, if the file contained the following entry:

@example.com

spamdyke's other recipient filters are activated through the reject-recipient option, which has the following options:

• none: Disable the reject-recipient filters. This is the default.
• same-as-sender: Reject any recipient address that is the same as the sender address.
• invalid: Reject any invalid recipient address. This filter rejects any address that will result in a bounce message from qmail.
• unavailable: Reject any recipient address that is currently unavailable. Under certain conditions (usually depending upon permission settings on specific files), qmail will queue messages to an address until the conditions are resolved. If the message is queued too long, it will bounce. This feature may have been useful a few decades ago (maybe), when everyone used text-based mail readers and routinely logged into shell accounts on their mail servers. These days however, it has techically become a "misfeature". If these conditions are ever triggered, they are almost certainly an accident and won't be corrected before the message bounces. It's usually best to use this value whenever invalid is also in use.

In order for spamdyke to reject invalid or unavailable recipients, it must have access to a number of qmail's control files. Two files are used by spamdyke itself: the "rcpthosts" file and the "morercpthosts" CDB file. The path to the "rcpthosts" file is usually /var/qmail/control/rcpthosts, but this default value can be changed with the qmail-rcpthosts-file. Similarly, the path to the "morercpthosts" CDB file is usually /var/qmail/control/morercpthosts.cdb, but this default value can be changed with qmail-morercpthosts-cdb (be sure to provide the path to the CDB file, not the text that was used to create it). NOTE: The only reason to change the paths to these two files is if qmail was compiled to use files in a different location. If different input files are provided to spamdyke and qmail, the recipient validation procedure will not function properly.

For the remainder of the recipient validation process, a number of other qmail configuration files must be accessed, along with the recipients' mail configuration files (often stored in their home directories). Unfortunately, there is only one user (on most systems) who can access all the needed files: root. spamdyke does not normally run as root because it is started by the tcpserver process, which is typically run with a non-root account. For this reason, the recipient validation procedure is contained in spamdyke-qrv, which is intended to be run as root (technically "setuid root"). spamdyke-qrv will validate an address and return its result to spamdyke, which allows spamdyke to function while running as a non-root user. In order to use spamdyke-qrv, the recipient-validation-command option must be given with the full path to the spamdyke-qrv binary (spamdyke will not search the PATH for spamdyke-qrv).

For full details on spamdyke-qrv and how it works, see Recipient Validation With spamdyke-qrv.

DNS Whitelists

dns-whitelist-entry
dns-whitelist-file
rhs-whitelist-entry
rhs-whitelist-file

spamdyke has the ability to consult DNS whitelists and allow connections from hosts or senders who match entries on them. DNS whitelists are essentially DNS RBLs and DNS RHSBLs that list allowed IP addresses and domain names instead of blocked ones. All of the same cautionary statements apply to DNS whitelists as to DNS blacklists. See DNS RBLs and DNS RHSBLs for details.

To use a DNS Realtime Whitelist (the opposite of a DNS RBL), the option dns-whitelist-entry should be given. To use a DNS Righthand-side Whitelist, the option rhs-whitelist-entry should be given. By default, spamdyke does not use a DNS whitelist. If either option is given multiple times, each list will be consulted before the connection is blocked.

If more than a few lists are given, the dns-whitelist-file or rhs-whitelist-file options may be used to provide the lists in files.

NOTE: Checking DNS whitelists can impose a serious performance penalty. Using more than three DNS whitelists is not recommended.

Whitelisting Senders and Recipients

recipient-whitelist-entry
recipient-whitelist-file
sender-whitelist-entry
sender-whitelist-file

Sometimes, adding IP addresses and reverse DNS names to whitelist files is not enough to satisfy some users. Either they continue to receive mail from unexpected places or they just think spamdyke is blocking their email. In those cases, a last resort can be to whitelist the sender or recipient address.

NOTE: Using these features is a bad idea! Sender addresses are very easy to forge; this is why spam is so hard to block. Recipient addresses are obviously already known to the spammers; this is why spam is delivered. Whitelisting any addresses this way will allow spam to get through.

To whitelist a sender or recipient address, the sender-whitelist-entry or recipient-whitelist-entry option should be used, respectively. The entries can use the same formats as those for sender-blacklist-entry and recipient-blacklist-entry; see Rejecting Recipients for details.

Whitelist entries can be placed in files and referenced with sender-whitelist-file or recipient-whitelist-file. This is more efficient for more than a few entries.

Graylisting / Greylisting

graylist-dir
graylist-exception-ip-entry
graylist-exception-ip-file
graylist-exception-rdns-dir
graylist-exception-rdns-entry
graylist-exception-rdns-file
graylist-level
graylist-max-secs
graylist-min-secs

Graylisting is the technique of denying mail delivery the first time a sender tries to deliver to a recipient. The next time the remote server attempts to deliver the message, it is accepted. All future messages from the sender to the recipient are also allowed.

Graylisting works because spammers don't use real mail servers, so when the initial delivery fails, they don't retry it. Even if they do, they change to a different random sender address, which is also graylisted.

spamdyke's graylisting is activated first with the graylist-level option, which will accept the following values:

• none: Do not graylist any connections. This is the default.
• always: Always graylist connections if a domain folder exists for the recipient and the remote server's IP address or rDNS name are not found on one of the exception lists.
• always-create-dir: Always graylist connections unless the remote server's IP address or rDNS name are found on one of the exception lists. If a domain folder does not exist for the recipient, create it.
• only: Do not graylist any connections unless a domain folder exists for the recipient and the remote server's IP address or rDNS name are found on one of the exception lists.
• only-create-dir: Do not graylist any connections unless the remote server's IP address or rDNS name are found on one of the exception lists. If a domain folder does not exist for the recipient, create it.

The option graylist-dir is required if graylist-level is not none. The value of graylist-dir must be the path to a directory where spamdyke has permission to create folders and write files.

A list of local domains must also be provided with qmail-rcpthosts-file. Without a list of local domains, spamdyke cannot know which domains should be graylisted. See Rejecting Recipients for details.

The "domain directories" required by graylist-level's always and only values are just folders named using the recipient's domain name. For example, if the value of graylist-dir is:

/var/tmp/graylist.d

/var/tmp/graylist.d/example.com

NOTE: Domain directories must be named in lowercase. Unfortunately, spamdyke cannot perform a case insensitive search for directory paths.

If graylist-dir is given multiple times, spamdyke will search each given directory for the recipient's domain folder. If the domain folder is not found and the value of graylist-level is always-create-dir or only-create-dir, spamdyke will create a domain folder in the last directory given.

As spamdyke creates graylist entries, it breaks apart the sender's and recipient's addresses to create folders. For example, a graylist entry for messages from sender@remote.com to recipient@local.com will be a file with the following path:

.../local.com/recipient/remote.com/sender@remote.com

If the options graylist-exception-ip-entry or graylist-exception-rdns-entry are given, spamdyke will reverse its graylist policy for remote servers whose IP addresses or rDNS names, respectively, match the given entries.

If more than a few IP address or rDNS entries are given, the options graylist-exception-ip-file and graylist-exception-rdns-file are more efficient. See IP Address Files and rDNS Files for details on the formats of these files.

If more than 100 entries are given in an rDNS file, the option graylist-exception-rdns-dir is more efficient than graylist-exception-rdns-file. See rDNS Directories for details.

spamdyke accepts two options to control the lifetimes of its graylist entries. The option graylist-min-secs controls the minimum amount of time an entry must exist before it is valid. For example, if the value 300 is given, a graylist entry is not valid until it has existed for at least 5 minutes. This prevents a spammer from attempting delivery twice in rapid succession.

The option graylist-max-secs controls the maximum amount of time an entry will remain valid after it is created. For example, if the value 604800 is given, a graylist entry will become invalid after 7 days. If the sender attempts to deliver a message after the entry has expired, they will be graylisted again. NOTE: A graylist entry's expiration date is reset each time a message passes the filter. If the maximum age is 2 weeks and the sender sends a message every day, their entry will never expire because it is continually reset.

As of 2013, graylisting is becoming more and more widespread. Spammers are adapting by sending their spam through legitimate servers, which aren't stopped by graylisting. There are still enough botnets using unintelligent spam software to make graylisting worthwhile but its effectiveness is definitely declining.

NOTE: Because spamdyke's graylist filter creates lots (and lots) of small files, it can threaten a server's filesystem by consuming all of the available inodes (especially on busy servers). Be sure to monitor the number of available inodes in case this becomes a problem.

Earlytalkers

greeting-delay-secs

Some years back, someone noticed that some spam software didn't follow the SMTP protocol. Specifically, spammers were opening connections to remote mail servers and pushing out all of the mail commands as quickly as they could, without waiting for (or checking) responses. By delaying the sending of the greeting banner, it's possible to catch these spammers and block them.

spamdyke will delay sending the opening greeting in order to wait for the sender to send data. If that happens, spamdyke will block the connection. This is activated with the greeting-delay-secs option.

It may seem strange that spamdyke will accept the greeting-delay-secs in a configuration directory, since the delay must take place long before the sender or recipient addresses are known. There is one allowed scenario however -- the command line or global configuration file may activate the earlytalker filter and the configuration directory may deactivate it. In that case, the connection will be delayed but the results of the test will be ignored. The reverse is not possible however -- the configuration directory cannot activate the filter or change its delay amount. See Configuration Directories for more information.

Unfortunately, spammers have mostly updated their software so this trick doesn't work any more. It still catches badly written botnet spam sources though.

Even if it doesn't catch the spammers any more, this is still a good test to run because it slows down the rate at which spammers can send email. Making it more expensive for them is not a bad thing.

Limiting Numbers of Recipients

max-recipients

RFC 821 says an SMTP server must allow the remote server to specify as many recipients as the SMTP server has memory to hold. This allows spammers to send a single message to (potentially) thousands of users in one connection.

spamdyke offers a way to violate the RFC by limiting the number of recipients per message. Once that number has been reached, the remaining recipients will be rejected. Legitimate mail servers use the multi-recipient feature as well, but they will retry their deliveries. Spammers generally don't.

This feature is activated by the max-recipients option. By default, spamdyke allows unlimited recipients per connection.

If you enable this feature, make sure all of your users are using SMTP AUTH or are allowed to relay or are whitelisted. Otherwise, their MUAs will show them error messages when they try to send to large address book mailing lists and they will complain. Loudly.

Rejecting Messages by Header Content

header-blacklist-entry
header-blacklist-file

Email messages are divided into two parts: the header and the body. The header is composed of data fields that are parsed by mail agents so the data can be shown to the user in a useful way. For example, the subject line and the date are part of the header. The message body contains all of the text (often HTML these days) and attachment data.

NAME: VALUE

Subject: Fantastic news!

• An asterisk (*) will match zero or more characters.
• A question mark (?) will match a single character.
• A bracketed series of characters (e.g. [abcd]) will match any one of the bracketed characters.
• ...probably more, depending on the implementation of fnmatch() on your system.

Subject:*c?a[i1]is*

Subject: cialis

Subject: Got some cialis for you

Subject: Need cXalis?

Subject: Order cia1is today

header-blacklist-entry=Subject: Cialis

header-blacklist-entry=Subject: Viagra

Timeouts

connection-timeout-secs
idle-timeout-secs

Most spam software is pretty stupid and doesn't handle error codes from SMTP servers. Instead, they send their commands and wait for specific responses. When those responses don't come, the software just sits forever and waits.

spamdyke will time out these connections in one of two ways. First, an absolute time limit can be imposed on a connection. This is activated with the connection-timeout-secs option. If this feature is enabled, it should be set to a very high value. Large (legitimate) messages can take a very long time to deliver, especially if the link is slow. A value of 0 disables this feature. By default, this feature is not activated.

Second, an idle time limit can be imposed on a connection. This is activated with the idle-timeout-secs option. If no data is received within the given number of seconds, the connection is closed. A value of 0 disables this feature. By default, this feature is not activated.

Extra Utilities

There are some additional programs included with spamdyke in the utils folder. They are:

domain2path

A utility for constructing rDNS folder paths from domain names. Useful in scripts. See rDNS Directories for details on domain2path.

domainsplit

A utility for finding the base domain name of a fully qualified domain name. For example, given foo.bar.baz.example.com, domainsplit will return example.com. Also useful in scripts.

dnsa

An example program that demonstrates finding DNS A records (IP addresses) for fully qualified domain names.

dnsany

An example program that demonstrates finding DNS records of "any" type (which doesn't actually return all types) for fully qualified domain names.

dnsany_libc

An example program that demonstrates finding DNS records of "any" type (which doesn't actually return all types) for fully qualified domain names. This version uses the system resolver library instead of sending UDP packets itself.

dnscname

An example program that demonstrates finding DNS CNAME records (alias names) for fully qualified domain names.

dnsmx

An example program that demonstrates finding DNS MX records (mail exchangers) for domain names.

dnsns

An example program that demonstrates finding DNS NS records (nameservers) for domain names.

dnsptr

An example program that demonstrates finding DNS PTR records (reverse DNS names) for fully qualified domain names or IP addresses.

dnssoa

An example program that demonstrates finding DNS SOA records (start-of-authority) for domain names.

dnstxt

An example program that demonstrates finding DNS TXT records (text information) for fully qualified domain names.

timefilter

A utility for filtering log files to display log entries from within a given date range. Only really useful in scripts.

None of these utilities depend on being installed in any specific folder. None of them depend on the presence of the others or spamdyke. spamdyke does not require them or use them.