1SPAMPD(8) Spam Proxy Daemon SPAMPD(8)
2
6 SpamPD - Spam Proxy Daemon (version 2.2)
7
9 spampd [--host=host[:port]] [--relayhost=hostname[:port]]
10 [--user|u=username] [--group|g=groupname] [--children|c=n]
11 #[--maxchildren|mc=n] [--maxrequests=n] [--childtimeout=n]
12 [--satimeout=n] [--pid|p=filename] [--nodetach] [--logsock=inet|unix]
13 [--maxsize=n] [--dose] [--tagall|a] [--log-rules-hit|rh]
14 [--set-envelope-headers|seh] [--set-envelope-from|sef]
15 [--auto-whitelist|aw] [--local-only|L] [--debug|d]
16 spampd --help
18
20 spampd is an SMTP/LMTP proxy that marks (or tags) spam using
21 SpamAssassin (http://www.SpamAssassin.org/). The proxy is designed to
22 be transparent to the sending and receiving mail servers and at no
23 point takes responsibility for the message itself. If a failure occurs
24 within spampd (or SpamAssassin) then the mail servers will disconnect
25 and the sending server is still responsible for retrying the message
26 for as long as it is configured to do so.
27 spampd uses SpamAssassin to modify (tag) relayed messages based on
29 their spam score, so all SA settings apply. This is described in the SA
30 documentation. spampd will by default only tell SA to tag a message if
31 it exceeds the spam threshold score, however you can have it rewrite
32 all messages passing through by adding the --tagall option (see SA for
33 how non-spam messages are tagged).
34 spampd logs all aspects of its operation to syslog(8), using the mail
36 syslog facility.
37 The latest version can be found at
39 <http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm>.
40
42 Perl modules:
43 Mail::SpamAssassin
45 Net::Server::PreForkSimple
47 IO::File
49 IO::Socket
51 Time::HiRes (not actually required but recommended)
53
55 spampd is meant to operate as an S/LMTP mail proxy which passes each
56 message through SpamAssassin for analysis. Note that spampd does not
57 do anything other than check for spam, so it is not suitable as an
58 anti-relay system. It is meant to work in conjunction with your
59 regular mail system. Typically one would pipe any messages they wanted
60 scanned through spampd after initial acceptance by your MX host. This
61 is especially useful for using Postfix's (http://www.postfix.org)
62 advanced content filtering mechanism, although certainly not limited to
63 that application.
64 Please re-read the second sentence in the above paragraph. You should
66 NOT enable spampd to listen on a public interface (IP address) unless
67 you know exactly what you're doing! It is very easy to set up an open
68 relay this way.
69 Here are some simple examples (square brackets in the "diagrams"
71 indicate physical machines):
72 Running between firewall/gateway and internal mail server
74 The firewall/gateway MTA would be configured to forward all of its
76 mail to the port that spampd listens on, and spampd would relay its
77 messages to port 25 of your internal server. spampd could either run
78 on its own host (and listen on any port) or it could run on either
79 mail server (and listen on any port except port 25).
80 Internet -> [ MX gateway (@inter.net.host:25) ->
82 spampd (@localhost:2025) ] ->
83 Internal mail (@private.host.ip:25)
84 Using Postfix advanced content filtering
86 Please see the FILTER_README that came with the Postfix
88 distribution. You need to have a version of Postfix which supports
89 this (ideally v.2 and up).
90 Internet -> [ Postfix (@inter.net.host:25) ->
92 spampd (@localhost:10025) ->
93 Postfix (@localhost:10026) ] -> final delivery
94 Note that these examples only show incoming mail delivery. Since it is
96 usually unnecessary to scan mail coming from your network (right?), it
97 may be desirable to set up a separate outbound route which bypasses
98 spampd.
99
101 If upgrading from a version prior to 2.2, please note that the
102 --add-sc-header option is no longer supported. Use SAs built-in header
103 manipulation features instead (as of SA v2.6).
104 Upgrading from version 1 simply involves replacing the spampd program
106 file with the latest one. Note that the dead-letters folder is no
107 longer being used and the --dead-letters option is no longer needed
108 (though no errors are thrown if it's present). Check the "Options"
109 list below for a full list of new and deprecated options. Also be sure
110 to check out the change log.
111
113 spampd can be run directly from the command prompt if desired. This is
114 useful for testing purposes, but for long term use you probably want to
115 put it somewhere like /usr/bin or /usr/local/bin and execute it at
116 system startup. For example on Red Hat-style Linux system one can use
117 a script in /etc/rc.d/init.d to start spampd (a sample script is
118 available on the spampd Web page @
119 http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm).
120 The options all have reasonable defaults, especially for a Postfix-
122 centric installation. You may want to specify the --children option if
123 you have an especially beefy or weak server box because spampd is a
124 memory-hungry program. Check the "Options" for details on this and all
125 other parameters.
126 Note that spampd replaces spamd from the SpamAssassin distribution in
128 function. You do not need to run spamd in order for spampd to work.
129 This has apparently been the source of some confusion, so now you know.
130 Postfix-specific Notes
132 Here is a typical setup for Postfix "advanced" content filtering as
134 described in the FILTER_README that came with the Postfix distribution
135 (which you really need to read):
136 /etc/postfix/master.cf:
138 smtp inet n - y - - smtpd
140 -o content_filter=smtp:localhost:10025
141 -o myhostname=mx.example.com
142 localhost:10026 inet n - n - 10 smtpd
144 -o content_filter=
145 -o myhostname=mx-int.example.com
146 The first entry is the main public-facing MTA which uses
148 localhost:10025 as the content filter for all mail. The second
149 entry receives mail from the content filter and does final delivery.
150 Both smtpd instances use the same Postfix main.cf file. spampd is the
151 process that listens on localhost:10025 and then connects to the
152 Postfix listener on localhost:10026. Note that the "myhostname"
153 options must be different between the two instances, otherwise Postfix
154 will think it's talking to itself and abort sending.
155 For the above example you can simply start spampd like this:
157 spampd --host=localhost:10025 --relayhost=localhost:10026
159 FILTER_README from the Postfix distro has more details and examples of
161 various setups, including how to skip the content filter for outbound
162 mail.
163 Another tip for Postfix when considering what timeout values to use for
165 --childtimout and --satimeout options is the following command:
166 "# postconf | grep timeout"
168 This will return a list of useful timeout settings and their values.
170 For explanations see the relevant "man" page (smtp, smtpd, lmtp). By
171 default spampd is set up for the default Postfix timeout values.
172
174 --host=ip[:port] or hostname[:port]
175 Specifies what hostname/IP and port spampd listens on. By default,
176 it listens on 127.0.0.1 (localhost) on port 10025.
177 Important! You should NOT enable spampd to listen on a public
179 interface (IP address) unless you know exactly what you're doing!
180 --port=n
182 Specifies what port spampd listens on. By default, it listens on
183 port 10025. This is an alternate to using the above --host=ip:port
184 notation.
185 --relayhost=ip[:port] or hostname[:port]
187 Specifies the hostname/IP where spampd will relay all messages.
188 Defaults to 127.0.0.1 (localhost). If the port is not provided,
189 that defaults to 25.
190 --relayport=n
192 Specifies what port spampd will relay to. Default is 25. This is
193 an alternate to using the above --relayhost=ip:port notation.
194 --user=username or --u=username
196 --group=groupname or --g=groupname
197 Specifies the user and group that the proxy will run as. Default
198 is mail/mail.
199 --children=n or --c=n
201 Number of child servers to start and maintain (where n > 0). Each
202 child will process up to --maxrequests (below) before exiting and
203 being replaced by another child. Keep this number low on systems
204 w/out a lot of memory. Default is 5 (which seems OK on a 512MB
205 lightly loaded system). Note that there is always a parent
206 process running, so if you specify 5 children you will actually
207 have 6 spampd processes running.
208 You may want to set your origination mail server to limit the
210 number of concurrent connections to spampd to match this setting
211 (for Postfix this is the "xxxx_destination_concurrency_limit"
212 setting where 'xxxx' is the transport being used, usually 'smtp',
213 and the default is 100).
214 --maxrequests=n
216 spampd works by forking child servers to handle each message. The
217 maxrequests parameter specifies how many requests will be handled
218 before the child exits. Since a child never gives back memory, a
219 large message can cause it to become quite bloated; the only way
220 to reclaim the memory is for the child to exit. The default is 20.
221 --childtimeout=n
223 This is the number of seconds to allow each child server before it
224 times out a transaction. In an S/LMTP transaction the timer is
225 reset for every command. This timeout includes time it would take
226 to send the message data, so it should not be too short. Note
227 that it's more likely the origination or destination mail servers
228 will timeout first, which is fine. This is just a "sane"
229 failsafe. Default is 360 seconds (6 minutes).
230 --satimeout=n
232 This is the number of seconds to allow for processing a message
233 with SpamAssassin (including feeding it the message, analyzing it,
234 and adding the headers/report if necessary). This should be less
235 than your origination and destination servers' timeout settings
236 for the DATA command. For Postfix the default is 300 seconds in
237 both cases (smtp_data_done_timeout and smtpd_timeout). In the
238 event of timeout while processing the message, the problem is
239 logged and the message is passed on anyway (w/out spam tagging,
240 obviously). To fail the message with a temp 450 error, see the
241 --dose (die-on-sa-errors) option, below. Default is 285 seconds.
242 --pid=filename or --p=filename
244 Specifies a filename where spampd will write its process ID so
245 that it is easy to kill it later. The directory that will contain
246 this file must be writable by the spampd user. The default is
247 /var/run/spampd.pid.
248 --logsock=unix or inet "(new in v2.20)"
250 Syslog socket to use. May be either "unix" of "inet". Default is
251 "unix" except on HP-UX and SunOS (Solaris) systems which seem to
252 prefer "inet".
253 --nodetach "(new in v2.20)"
255 If this option is given spampd won't detach from the console and
256 fork into the background. This can be useful for running under
257 control of some daemon management tools or when configured as a
258 win32 service under cygrunsrv's control.
259 --maxsize=n
261 The maximum message size to send to SpamAssassin, in KBytes. By
262 default messages over 64KB are not scanned at all, and an
263 appropriate message is logged indicating this. The size includes
264 headers and attachments (if any).
265 --dose
267 Acronym for (d)ie (o)n (s)pamAssassin (e)rrors. By default if
268 spampd encounters a problem with processing the message through
269 Spam Assassin (timeout or other error), it will still pass the
270 mail on to the destination server. If you specify this option
271 however, the mail is instead rejected with a temporary error (code
272 450, which means the origination server should keep retrying to
273 send it). See the related --satimeout option, above.
274 --tagall or --a
276 Tells spampd to have SpamAssassin add headers to all scanned mail,
277 not just spam. By default spampd will only rewrite messages which
278 exceed the spam threshold score (as defined in the SA settings).
279 Note that for this option to work as of SA-2.50, the
280 always_add_report and/or always_add_headers settings in your
281 SpamAssassin local.cf need to be set to 1/true.
282 --log-rules-hit or --rh
284 Logs the names of each SpamAssassin rule which matched the message
285 being processed. This list is returned by SA.
286 --set-envelope-headers or --seh "(new in v2.30)"
288 Turns on addition of X-Envelope-To and X-Envelope-From headers to
289 the mail being scanned before it is passed to SpamAssassin. The
290 idea is to help SA process any blacklist/whitelist to/from
291 directives on the actual sender/recipients instead of the possibly
292 bogus envelope headers. This potentially exposes the list of all
293 recipients of that mail (even BCC'ed ones). Therefore usage of
294 this option is discouraged.
295 NOTE: Even though spampd tries to prevent this leakage by removing
297 the X-Envelope-To header after scanning, SpamAssassin itself might
298 add headers itself which report one or more of the recipients
299 which had been listed in this header.
300 --set-envelope-from or --sef "(new in v2.30)"
302 Same as above option but only enables the addition of X-Envelope-
303 From header. For those that don't feel comfortable with the
304 possible information exposure of X-Envelope-To. The above option
305 overrides this one.
306 --auto-whitelist or --aw
308 This option is no longer relevant with SA version 3.0 and above,
309 which controls auto whitelist use via local.cf settings.
310 For SA version < 3.0, turns on the SpamAssassin global whitelist
312 feature. See the SA docs. Note that per-user whitelists are not
313 available.
314 --local-only or --L
316 Turn off all SA network-based tests (DNS, Razor, etc).
317 --debug or --d
319 Turns on SpamAssassin debug messages which print to the system
320 mail log (same log as spampd will log to). Also turns on more
321 verbose logging of what spampd is doing (new in v2). Also
322 increases log level of Net::Server to 4 (debug), adding yet more
323 info (but not too much) (new in v2.2).
324 --help or --h
326 Prints usage information.
327 Deprecated Options
329 The following options are no longer used but still accepted for
331 backwards compatibility with prevoius spampd versions:
332 --dead-letters
334 --heloname
336 --stop-at-threshold
338 --add-sc-header
340 --hostname
342
344 Running between firewall/gateway and internal mail server
345 spampd listens on port 10025 on the same host as the internal mail
346 server.
347 spampd --host=192.168.1.10
349 Same as above but spampd runs on port 10025 of the same host as
351 the firewall/gateway and passes messages on to the internal mail
352 server on another host.
353 spampd --relayhost=192.168.1.10
355 Using Postfix advanced content filtering example and the SA auto-
357 whitelist feature
358 spampd --port=10025 --relayhost=127.0.0.1:10026 --auto-whitelist
359
361 spampd is written and maintained by Maxim Paperno
362 <MPaperno@WorldDesign.com>. See
363 http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm for latest info.
364 spampd v2 uses two Perl modules by Bennett Todd and Copyright (C) 2001
366 Morgan Stanley Dean Witter. These are distributed under the GNU GPL
367 (see module code for more details). Both modules have been slightly
368 modified from the originals and are included in this file under new
369 names.
370 Also thanks to Bennett Todd for the example smtpproxy script which
372 helped create this version of spampd. See
373 http://bent.latency.net/smtpprox/ .
374 spampd v1 was based on code by Dave Carrigan named assassind. Trace
376 amounts of his code or documentation may still remain. Thanks to him
377 for the original inspiration and code. See
378 http://www.rudedog.org/assassind/ .
379 Also thanks to spamd (included with SpamAssassin) and amavisd-new
381 (http://www.ijs.si/software/amavisd/) for some tricks.
382 Various people have contributed patches, bug reports, and ideas, all of
384 whom I would like to thank. I have tried to include credits in code
385 comments and in the change log, as appropriate.
386 Code Contributors (in order of appearance):
388 Kurt Andersen
390 Roland Koeckel
391 Urban Petry
392 Sven Mueller
393
395 spampd is Copyright (c) 2002 by World Design Group, Inc. and Maxim
396 Paperno.
397 Portions are Copyright (C) 2001 Morgan Stanley Dean Witter as mentioned
399 above in the Credits section.
400 This program is free software; you can redistribute it and/or modify
402 it under the terms of the GNU General Public License as published by
403 the Free Software Foundation; either version 2 of the License, or
404 (at your option) any later version.
405 This program is distributed in the hope that it will be useful,
407 but WITHOUT ANY WARRANTY; without even the implied warranty of
408 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
409 GNU General Public License for more details.
410 The GNU GPL can be found at http://www.fsf.org/copyleft/gpl.html
412
414 None known. Please report any to MPaperno@WorldDesign.com.
415
417 Figure out how to use Net::Server::PreFork because it has cool
418 potential for load management. I tried but either I'm missing
419 something or PreFork is somewhat broken in how it works. If anyone has
420 experience here, please let me know.
421 Add configurable option for rejecting mail outright based on spam
423 score. It would be nice to make this program safe enough to sit in
424 front of a mail server such as Postfix and be able to reject mail
425 before it enters our systems. The only real problem is that Postfix
426 will see localhost as the connecting client, so that disables any
427 client-based checks Postfix can do and creates a possible relay hole if
428 localhost is trusted.
429
431 perl(1), Spam::Assassin(3), <http://www.spamassassin.org/>,
432 <http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm>
433
435 Hey! The above document had some coding errors, which are explained
436 below:
437 Around line 1078:
439 You can't have =items (as at line 1082) unless the first thing
440 after the =over is an =item
441 Around line 1393:
443 You can't have =items (as at line 1398) unless the first thing
444 after the =over is an =item
445perl v5.10.0 2005-10-31 SPAMPD(8)