1SPAMPD(8)                      Spam Proxy Daemon                     SPAMPD(8)
2
3
4

NAME

6       SpamPD - Spam Proxy Daemon (version 2.2)
7

Synopsis

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
17       spampd --help
18

Description

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
28       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
35       spampd logs all aspects of its operation to syslog(8), using the mail
36       syslog facility.
37
38       The latest version can be found at
39       <http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm>.
40

Requires

42       Perl modules:
43
44       Mail::SpamAssassin
45       Net::Server::PreForkSimple
46       IO::File
47       IO::Socket
48       Time::HiRes (not actually required but recommended)
49

Operation

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
55       regular 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
61       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
66       Here are some simple examples (square brackets in the "diagrams"
67       indicate physical machines):
68
69       Running between firewall/gateway and internal mail server
70
71          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
77           Internet -> [ MX gateway (@inter.net.host:25) ->
78                  spampd (@localhost:2025) ] ->
79                  Internal mail (@private.host.ip:25)
80
81       Using Postfix advanced content filtering
82
83          Please see the FILTER_README that came with the Postfix
84          distribution.  You need to have a version of Postfix which supports
85          this (ideally v.2 and up).
86
87           Internet -> [ Postfix (@inter.net.host:25) ->
88                  spampd (@localhost:10025) ->
89                  Postfix (@localhost:10026) ] -> final delivery
90
91       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

Upgrading

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
101       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

Installation

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
112       system startup.  For example on Red Hat-style Linux system one can use
113       a script in /etc/rc.d/init.d to start spampd (a sample script is
114       available on the spampd Web page @
115       http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm).
116
117       The options all have reasonable defaults, especially for a Postfix-
118       centric 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
123       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
127   Postfix-specific Notes
128       Here is a typical setup for Postfix "advanced" content filtering as
129       described in the FILTER_README that came with the Postfix distribution
130       (which you really need to read):
131
132       /etc/postfix/master.cf:
133
134        smtp   inet    n       -       y       -       -       smtpd
135               -o content_filter=smtp:localhost:10025
136               -o myhostname=mx.example.com
137
138        localhost:10026        inet    n       -       n       -       10      smtpd
139               -o content_filter=
140               -o myhostname=mx-int.example.com
141
142       The first entry is the main public-facing MTA which uses
143       localhost:10025 as the content filter for all mail.     The second
144       entry receives mail from the content filter and does final delivery.
145       Both smtpd instances use the same Postfix main.cf file.  spampd is the
146       process that listens on localhost:10025 and then connects to the
147       Postfix listener on localhost:10026.  Note that the "myhostname"
148       options must be different between the two instances, otherwise Postfix
149       will think it's talking to itself and abort sending.
150
151       For the above example you can simply start spampd like this:
152
153        spampd --host=localhost:10025 --relayhost=localhost:10026
154
155       FILTER_README from the Postfix distro has more details and examples of
156       various setups, including how to skip the content filter for outbound
157       mail.
158
159       Another tip for Postfix when considering what timeout values to use for
160       --childtimout and --satimeout options is the following command:
161
162       "# postconf | grep timeout"
163
164       This will return a list of useful timeout settings and their values.
165       For explanations see the relevant "man" page (smtp, smtpd, lmtp).  By
166       default spampd is set up for the default Postfix timeout values.
167

Options

169       --host=ip[:port] or hostname[:port]
170            Specifies what hostname/IP and port spampd listens on. By default,
171            it listens on 127.0.0.1 (localhost) on port 10025.
172
173            Important! You should NOT enable spampd to listen on a public
174            interface (IP address) unless you know exactly what you're doing!
175
176       --port=n
177            Specifies what port spampd listens on. By default, it listens on
178            port 10025. This is an alternate to using the above --host=ip:port
179            notation.
180
181       --relayhost=ip[:port] or hostname[:port]
182            Specifies the hostname/IP where spampd will relay all messages.
183            Defaults to 127.0.0.1 (localhost). If the port is not provided,
184            that defaults to 25.
185
186       --relayport=n
187            Specifies what port spampd will relay to. Default is 25. This is
188            an alternate to using the above --relayhost=ip:port notation.
189
190       --user=username or --u=username
191       --group=groupname or  --g=groupname
192            Specifies the user and group that the proxy will run as. Default
193            is mail/mail.
194
195       --children=n or --c=n
196            Number of child servers to start and maintain (where n > 0). Each
197            child will process up to --maxrequests (below) before exiting and
198            being replaced by another child.  Keep this number low on systems
199            w/out a lot of memory.  Default is 5 (which seems OK on a 512MB
200            lightly loaded system).  Note that there is always a parent
201            process running, so if you specify 5 children you will actually
202            have 6 spampd processes running.
203
204            You may want to set your origination mail server to limit the
205            number of concurrent connections to spampd to match this setting
206            (for Postfix this is the "xxxx_destination_concurrency_limit"
207            setting where 'xxxx' is the transport being used, usually 'smtp',
208            and the default is 100).
209
210       --maxrequests=n
211            spampd works by forking child servers to handle each message. The
212            maxrequests parameter specifies how many requests will be handled
213            before the child exits. Since a child never gives back memory, a
214            large message can cause it to become quite bloated; the only way
215            to reclaim the memory is for the child to exit. The default is 20.
216
217       --childtimeout=n
218            This is the number of seconds to allow each child server before it
219            times out a transaction. In an S/LMTP transaction the timer is
220            reset for every command.  This timeout includes time it would take
221            to send the message data, so it should not be too short.  Note
222            that it's more likely the origination or destination mail servers
223            will timeout first, which is fine.  This is just a "sane"
224            failsafe.  Default is 360 seconds (6 minutes).
225
226       --satimeout=n
227            This is the number of seconds to allow for processing a message
228            with SpamAssassin (including feeding it the message, analyzing it,
229            and adding the headers/report if necessary).  This should be less
230            than your origination and destination servers' timeout settings
231            for the DATA command. For Postfix the default is 300 seconds in
232            both cases (smtp_data_done_timeout and smtpd_timeout). In the
233            event of timeout while processing the message, the problem is
234            logged and the message is passed on anyway (w/out spam tagging,
235            obviously).  To fail the message with a temp 450 error, see the
236            --dose (die-on-sa-errors) option, below.  Default is 285 seconds.
237
238       --pid=filename or --p=filename
239            Specifies a filename where spampd will write its process ID so
240            that it is easy to kill it later. The directory that will contain
241            this file must be writable by the spampd user. The default is
242            /var/run/spampd.pid.
243
244       --logsock=unix or inet "(new in v2.20)"
245            Syslog socket to use.  May be either "unix" of "inet".  Default is
246            "unix" except on HP-UX and SunOS (Solaris) systems which seem to
247            prefer "inet".
248
249       --nodetach "(new in v2.20)"
250            If this option is given spampd won't detach from the console and
251            fork into the background. This can be useful for running under
252            control of some daemon management tools or when configured as a
253            win32 service under cygrunsrv's control.
254
255       --maxsize=n
256            The maximum message size to send to SpamAssassin, in KBytes. By
257            default messages over 64KB are not scanned at all, and an
258            appropriate message is logged indicating this.  The size includes
259            headers and attachments (if any).
260
261       --dose
262            Acronym for (d)ie (o)n (s)pamAssassin (e)rrors.  By default if
263            spampd encounters a problem with processing the message through
264            Spam Assassin (timeout or other error), it will still pass the
265            mail on to the destination server.  If you specify this option
266            however, the mail is instead rejected with a temporary error (code
267            450, which means the origination server should keep retrying to
268            send it).  See the related --satimeout option, above.
269
270       --tagall or --a
271            Tells spampd to have SpamAssassin add headers to all scanned mail,
272            not just spam.  By default spampd will only rewrite messages which
273            exceed the spam threshold score (as defined in the SA settings).
274            Note that for this option to work as of SA-2.50, the
275            always_add_report and/or always_add_headers settings in your
276            SpamAssassin local.cf need to be set to 1/true.
277
278       --log-rules-hit or --rh
279            Logs the names of each SpamAssassin rule which matched the message
280            being processed.  This list is returned by SA.
281
282       --set-envelope-headers or --seh "(new in v2.30)"
283            Turns on addition of X-Envelope-To and X-Envelope-From headers to
284            the mail being scanned before it is passed to SpamAssassin. The
285            idea is to help SA process any blacklist/whitelist to/from
286            directives on the actual sender/recipients instead of the possibly
287            bogus envelope headers. This potentially exposes the list of all
288            recipients of that mail (even BCC'ed ones).  Therefore usage of
289            this option is discouraged.
290
291            NOTE: Even though spampd tries to prevent this leakage by removing
292            the X-Envelope-To header after scanning, SpamAssassin itself might
293            add headers itself which report one or more of the recipients
294            which had been listed in this header.
295
296       --set-envelope-from or --sef "(new in v2.30)"
297            Same as above option but only enables the addition of X-Envelope-
298            From header.  For those that don't feel comfortable with the
299            possible information exposure of X-Envelope-To.  The above option
300            overrides this one.
301
302       --auto-whitelist or --aw
303            This option is no longer relevant with SA version 3.0 and above,
304            which controls auto whitelist use via local.cf settings.
305
306            For SA version < 3.0, turns on the SpamAssassin global whitelist
307            feature.  See the SA docs. Note that per-user whitelists are not
308            available.
309
310       --local-only or --L
311            Turn off all SA network-based tests (DNS, Razor, etc).
312
313       --debug or --d
314            Turns on SpamAssassin debug messages which print to the system
315            mail log (same log as spampd will log to).  Also turns on more
316            verbose logging of what spampd is doing (new in v2).  Also
317            increases log level of Net::Server to 4 (debug), adding yet more
318            info (but not too much) (new in v2.2).
319
320       --help or --h
321            Prints usage information.
322
323   Deprecated Options
324       The following options are no longer used but still accepted for
325       backwards compatibility with prevoius spampd versions:
326
327       --dead-letters
328       --heloname
329       --stop-at-threshold
330       --add-sc-header
331       --hostname
332

Examples

334       Running between firewall/gateway and internal mail server
335            spampd listens on port 10025 on the same host as the internal mail
336            server.
337
338              spampd --host=192.168.1.10
339
340            Same as above but spampd runs on port 10025 of the same host as
341            the firewall/gateway and passes messages on to the internal mail
342            server on another host.
343
344              spampd --relayhost=192.168.1.10
345
346       Using Postfix advanced content filtering example and the SA auto-
347       whitelist feature
348              spampd --port=10025 --relayhost=127.0.0.1:10026 --auto-whitelist
349

Credits

351       spampd is written and maintained by Maxim Paperno
352       <MPaperno@WorldDesign.com>.  See
353       http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm for latest info.
354
355       spampd v2 uses two Perl modules by Bennett Todd and Copyright (C) 2001
356       Morgan Stanley Dean Witter. These are distributed under the GNU GPL
357       (see module code for more details). Both modules have been slightly
358       modified from the originals and are included in this file under new
359       names.
360
361       Also thanks to Bennett Todd for the example smtpproxy script which
362       helped create this version of spampd.  See
363       http://bent.latency.net/smtpprox/ .
364
365       spampd v1 was based on code by Dave Carrigan named assassind. Trace
366       amounts of his code or documentation may still remain. Thanks to him
367       for the original inspiration and code. See
368       http://www.rudedog.org/assassind/ .
369
370       Also thanks to spamd (included with SpamAssassin) and amavisd-new
371       (http://www.ijs.si/software/amavisd/) for some tricks.
372
373       Various people have contributed patches, bug reports, and ideas, all of
374       whom I would like to thank.  I have tried to include credits in code
375       comments and in the change log, as appropriate.
376
377   Code Contributors (in order of appearance):
378        Kurt Andersen
379        Roland Koeckel
380        Urban Petry
381        Sven Mueller
382

Copyright, License, and Disclaimer

384       spampd is Copyright (c) 2002 by World Design Group, Inc. and Maxim
385       Paperno.
386
387       Portions are Copyright (C) 2001 Morgan Stanley Dean Witter as mentioned
388       above in the Credits section.
389
390           This program is free software; you can redistribute it and/or modify
391           it under the terms of the GNU General Public License as published by
392           the Free Software Foundation; either version 2 of the License, or
393           (at your option) any later version.
394
395           This program is distributed in the hope that it will be useful,
396           but WITHOUT ANY WARRANTY; without even the implied warranty of
397           MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
398           GNU General Public License for more details.
399
400           The GNU GPL can be found at http://www.fsf.org/copyleft/gpl.html
401

Bugs

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

To Do

406       Figure out how to use Net::Server::PreFork because it has cool
407       potential for load management.  I tried but either I'm missing
408       something or PreFork is somewhat broken in how it works.  If anyone has
409       experience here, please let me know.
410
411       Add configurable option for rejecting mail outright based on spam
412       score.  It would be nice to make this program safe enough to sit in
413       front of a mail server such as Postfix and be able to reject mail
414       before it enters our systems.  The only real problem is that Postfix
415       will see localhost as the connecting client, so that disables any
416       client-based checks Postfix can do and creates a possible relay hole if
417       localhost is trusted.
418

See Also

420       perl(1), Spam::Assassin(3), <http://www.spamassassin.org/>,
421       <http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm>
422
423
424
425perl v5.30.1                      2020-01-30                         SPAMPD(8)
Impressum