Postfix-specific Notes

Options

Deprecated Options

Examples
Credits
Copyright, License, and Disclaimer
Bugs
To Do
See Also

NAME

SpamPD - Spam Proxy Daemon (version 2.10)

Synopsis

spampd --help

Description

spampd is an SMTP/LMTP proxy that marks (or tags) spam using SpamAssassin (http://www.SpamAssassin.org/). The proxy is designed to be transparent to the sending and receiving mail servers and at no point takes responsibility for the message itself. If a failure occurs within spampd (or SpamAssassin) then the mail servers will disconnect and the sending server is still responsible for retrying the message for as long as it is configured to do so.

spampd uses SpamAssassin to modify (tag) relayed messages based on their spam score, so all SA settings apply. This is described in the SA documentation. spampd will by default only tell SA to tag a message if it exceeds the spam threshold score, however you can have it rewrite all messages passing through by adding the --tagall option (see SA for how non-spam messages are tagged).

spampd logs all aspects of its operation to syslog(8), using the mail syslog facility.

The latest version can be found at http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm.

Requires

Perl modules:

Mail::SpamAssassin
Net::Server::PreForkSimple
IO::File
IO::Socket
Time::HiRes (not actually required but recommended)

Operation

spampd is meant to operate as an S/LMTP mail proxy which passes each message through SpamAssassin for analysis. Note that spampd does not do anything other than check for spam, so it is not suitable as an anti-relay system. It is meant to work in conjunction with your regular mail system. Typically one would pipe any messages they wanted scanned through spampd after initial acceptance by your MX host. This is especially useful for using Postfix's (http://www.postfix.org) advanced content filtering mechanism, although certainly not limited to that application.

Please re-read the second sentence in the above paragraph. You should NOT enable spampd to listen on a public interface (IP address) unless you know exactly what you're doing! It is very easy to set up an open relay this way.

Here are some simple examples (square brackets in the ``diagrams'' indicate physical machines):

Running between firewall/gateway and internal mail server

The firewall/gateway MTA would be configured to forward all of its mail to the port that spampd listens on, and spampd would relay its messages to port 25 of your internal server. spampd could either run on its own host (and listen on any port) or it could run on either mail server (and listen on any port except port 25).

 Internet -> [ MX gateway (@inter.net.host:25) -> 
        spampd (@localhost:2025) ] ->
        Internal mail (@private.host.ip:25)

Using Postfix advanced content filtering

Please see the FILTER_README that came with the Postfix distribution. You need to have a version of Postfix which supports this (ideally v.2 and up).

 Internet -> [ Postfix (@inter.net.host:25) -> 
        spampd (@localhost:10025) -> 
        Postfix (@localhost:10026) ] -> final delivery

Note that these examples only show incoming mail delivery. Since it is usually unnecessary to scan mail coming from your network (right?), it may be desirable to set up a separate outbound route which bypasses spampd.

Upgrading

Upgrading from version 1 simply involves replacing the spampd program file with the latest one. Note that the dead-letters folder is no longer being used and the --dead-letters option is no longer needed (though no errors are thrown if it's present). Check the Options list below for a full list of new and deprecated options. Also be sure to check out the change log.

Installation

spampd can be run directly from the command prompt if desired. This is useful for testing purposes, but for long term use you probably want to put it somewhere like /usr/bin or /usr/local/bin and execute it at system startup. For example on Red Hat-style Linux system one can use a script in /etc/rc.d/init.d to start spampd (a sample script is available on the spampd Web page @ http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm).

The options all have reasonable defaults, especially for a Postfix-centric installation. You may want to specify the --children option if you have an especially beefy or weak server box because spampd is a memory-hungry program. Check the Options for details on this and all other parameters.

Note that spampd replaces spamd from the SpamAssassin distribution in function. You do not need to run spamd in order for spampd to work. This has apparently been the source of some confusion, so now you know.

Postfix-specific Notes

Here is a typical setup for Postfix ``advanced'' content filtering as described in the FILTER_README that came with the Postfix distribution (which you really need to read):

/etc/postfix/master.cf:


 smtp   inet    n       -       y       -       -       smtpd
        -o content_filter=smtp:localhost:10025
        -o myhostname=mx.example.com

 localhost:10026        inet    n       -       n       -       10      smtpd
        -o content_filter=
        -o myhostname=mx-int.example.com

The first entry is the main public-facing MTA which uses localhost:10025 as the content filter for all mail. The second entry receives mail from the content filter and does final delivery. Both smtpd instances use the same Postfix main.cf file. spampd is the process that listens on localhost:10025 and then connects to the Postfix listener on localhost:10026. Note that the myhostname options must be different between the two instances, otherwise Postfix will think it's talking to itself and abort sending.

For the above example you can simply start spampd like this:

 spampd --host=localhost:10025 --relayhost=localhost:10026

FILTER_README from the Postfix distro has more details and examples of various setups, including how to skip the content filter for outbound mail.

Another tip for Postfix when considering what timeout values to use for --childtimout and --satimeout options is the following command:

# postconf | grep timeout

This will return a list of useful timeout settings and their values. For explanations see the relevant man page (smtp, smtpd, lmtp). By default spampd is set up for the default Postfix timeout values.

Options

--host=ip[:port] or hostname[:port] (changed in v2)

Specifies what hostname/IP and port spampd listens on. By default, it listens on 127.0.0.1 (localhost) on port 10025.

Important! You should NOT enable spampd to listen on a public interface (IP address) unless you know exactly what you're doing!

--port=n

Specifies what port spampd listens on. By default, it listens on port 10025. This is an alternate to using the above --host=ip:port notation.

--relayhost=ip[:port] or hostname[:port]

Specifies the hostname/IP where spampd will relay all messages. Defaults to 127.0.0.1 (localhost). If the port is not provided, that defaults to 25.

--relayport=n (new in v2)

Specifies what port spampd will relay to. Default is 25. This is an alternate to using the above --relayhost=ip:port notation.

--user=username or --u=username

--group=groupname or --g=groupname

Specifies the user and group that the proxy will run as. Default is mail/mail.

--children=n or --c=n (new in v2)

Number of child servers to start and maintain (where n > 0). Each child will process up to --maxrequests (below) before exiting and being replaced by another child. Keep this number low on systems w/out a lot of memory. Default is 5 (which seems OK on a 512MB lightly loaded system). Note that there is always a parent process running, so if you specify 5 children you will actually have 6 spampd processes running.

You may want to set your origination mail server to limit the number of concurrent connections to spampd to match this setting (for Postfix this is the xxxx_destination_concurrency_limit setting where 'xxxx' is the transport being used, usually 'smtp', and the default is 100).

--maxrequests=n

spampd works by forking child servers to handle each message. The maxrequests parameter specifies how many requests will be handled before the child exits. Since a child never gives back memory, a large message can cause it to become quite bloated; the only way to reclaim the memory is for the child to exit. The default is 20.

--childtimeout=n (new in v2)

This is the number of seconds to allow each child server before it times out a transaction. In an S/LMTP transaction the timer is reset for every command. This timeout includes time it would take to send the message data, so it should not be too short. Note that it's more likely the origination or destination mail servers will timeout first, which is fine. This is just a ``sane'' failsafe. Default is 360 seconds (6 minutes).

--satimeout=n (new in v2)

This is the number of seconds to allow for processing a message with SpamAssassin (including feeding it the message, analyzing it, and adding the headers/report if necessary). This should be less than your origination and destination servers' timeout settings for the DATA command. For Postfix the default is 300 seconds in both cases (smtp_data_done_timeout and smtpd_timeout). In the event of timeout while processing the message, the problem is logged and the message is passed on anyway (w/out spam tagging, obviously). To fail the message with a temp 450 error, see the --dose (die-on-sa-errors) option, below. Default is 285 seconds.

--pid=filename or --p=filename

Specifies a filename where spampd will write its process ID so that it is easy to kill it later. The directory that will contain this file must be writable by the spampd user. The default is /var/run/spampd.pid.

--maxsize=n

The maximum message size to send to SpamAssassin, in KBytes. By default messages over 64KB are not scanned at all, and an appropriate message is logged indicating this. The size includes headers and attachments (if any).

--dose (new in v2)

Acronym for (d)ie (o)n (s)pamAssassin (e)rrors. By default if spampd encounters a problem with processing the message through Spam Assassin (timeout or other error), it will still pass the mail on to the destination server. If you specify this option however, the mail is instead rejected with a temporary error (code 450, which means the origination server should keep retrying to send it). See the related --satimeout option, above.

--tagall or --a

Tells spampd to have SpamAssassin add headers to all scanned mail, not just spam. By default spampd will only rewrite messages which exceed the spam threshold score (as defined in the SA settings). Note that for this option to work as of SA-2.50, the always_add_report and/or always_add_headers settings in your SpamAssassin local.cf need to be set to 1/true.

--log-rules-hit or --rh (new in v2)

Logs the names of each SpamAssassin rule which matched the message being processed. This list is returned by SA.

--add-sc-header or --ash (new in v2.1)

Add a 'X-Spam-Checked-By: {hostname}' header to each scanned message. By default no such header is added. This can be useful in tracking which server in a pool did the scanning. See below for how to specify a hostname.

--hostname=hostname (new in v2.1)

Hostname to use in the X-Spam-Checked-By header. By default the value of the environmental variable $HOSTNAME is used, or if that is undefined/blank then 'localhost' is used as the hostname. Only relevant if the --add-sc-header option is specified.

--auto-whitelist or --aw

Turns on the SpamAssassin global whitelist feature. See the SA docs. Note that per-user whitelists are not available.

--local-only or --L (new in v2)

Turn off all SA network-based tests (DNS, Razor, etc).

--debug or --d (changed in v2)

Turns on SpamAssassin debug messages which print to STDERR (usually the console). Also turns on more verbose logging of what spampd is doing (new in v2).

--help or --h

Prints usage information.

Deprecated Options

The following options are no longer used but still accepted for backwards compatibility with spampd v1:

--dead-letters
--heloname
--stop-at-threshold

Examples

Running between firewall/gateway and internal mail server

spampd listens on port 10025 on the same host as the internal mail server.

  spampd --host=192.168.1.10

Same as above but spampd runs on port 10025 of the same host as the firewall/gateway and passes messages on to the internal mail server on another host.

  spampd --relayhost=192.168.1.10

Using Postfix advanced content filtering example and the SA auto-whitelist feature

  spampd --port=10025 --relayhost=127.0.0.1:10026 --auto-whitelist

Credits

spampd is written and maintained by Maxim Paperno <MPaperno@WorldDesign.com>. See http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm for latest info.

spampd v2 uses two Perl modules by Bennett Todd and Copyright (C) 2001 Morgan Stanley Dean Witter. These are distributed under the GNU GPL (see module code for more details). Both modules have been slightly modified from the originals and are included in this file under new names.

Also thanks to Bennet Todd for the example smtpproxy script which helped create this version of spampd. See http://bent.latency.net/smtpprox/ .

spampd v1 was based on code by Dave Carrigan named assassind. Trace amounts of his code or documentation may still remain. Thanks to him for the original inspiration and code. See http://www.rudedog.org/assassind/ .

Also thanks to spamd (included with SpamAssassin) and amavisd-new (http://www.ijs.si/software/amavisd/) for some tricks.

Copyright, License, and Disclaimer

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    The GNU GPL can be found at http://www.fsf.org/copyleft/gpl.html

Bugs

None known. Please report any to MPaperno@WorldDesign.com.

To Do

Figure out how to use Net::Server::PreFork because it has cool potential for load management. I tried but either I'm missing something or PreFork is somewhat broken in how it works. If anyone has experience here, please let me know.

Add configurable option for rejecting mail outright based on spam score. It would be nice to make this program safe enough to sit in front of a mail server such as Postfix and be able to reject mail before it enters our systems. The only real problem is that Postfix will see localhost as the connecting client, so that disables any client-based checks Postfix can do and creates a possible relay hole if localhost is trusted.

Per-user preferences: The jury is still out on this one. I'm thinking more and more that most per-user prefs should be specified on the final mailbox server. Why? Because SMTP isn't designed with per-user preferences in mind. On a relay server, the same message body can go to multiple recipients who may have wildly different preferences when it comes to handilng junk mail. The exception here might be the use of LMTP protocol, which bears further investigation.