From 53210b068e4dbda66a095f692a710ed6f7988e80 Mon Sep 17 00:00:00 2001 From: mpaperno Date: Wed, 29 Aug 2012 23:32:01 -0400 Subject: Initial commit --- spampd.html | 445 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 445 insertions(+) create mode 100644 spampd.html (limited to 'spampd.html') diff --git a/spampd.html b/spampd.html new file mode 100644 index 0000000..3b0d1f5 --- /dev/null +++ b/spampd.html @@ -0,0 +1,445 @@ + + +SpamPD - Spam Proxy Daemon + + + + + + + + +

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.