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