1SPAMPD(1) User Contributed Perl Documentation SPAMPD(1)
2
6 SpamPD - Spam Proxy Daemon
7
9 Documentation for SpamPD version 2.61.
10
12 spampd is an SMTP/LMTP proxy that marks (or tags) spam using
13 SpamAssassin (<http://www.SpamAssassin.org/>). The proxy is designed to
14 be transparent to the sending and receiving mail servers and at no
15 point takes responsibility for the message itself. If a failure occurs
16 within spampd (or SpamAssassin) then the mail servers will disconnect
17 and the sending server is still responsible for retrying the message
18 for as long as it is configured to do so.
19 spampd uses SpamAssassin to modify (tag) relayed messages based on
21 their spam score, so all SA settings apply. This is described in the SA
22 documentation. spampd will by default only tell SA to tag a message if
23 it exceeds the spam threshold score, however you can have it rewrite
24 all messages passing through by adding the --tagall option (see SA for
25 how non-spam messages are tagged).
26 spampd logs all aspects of its operation to syslog(8), using the mail
28 syslog facility.
29 The latest version can be found at
31 <https://github.com/mpaperno/spampd>.
32
34 spampd [ options ]
35 Options:
37 --config <filename> Load options from file(s).
39 --host <host>[:<port>] Hostname/IP and optional port to listen on.
41 --port <n> Port to listen on (alternate syntax to above).
42 --socket <socketpath> UNIX socket to listen on.
43 --socket-perms <mode> The octal mode to set on the UNIX socket.
44 --relayhost <hst>[:<prt>] Host and optional port to relay mail to.
45 --relayport <n> Port to relay to (alternate syntax to above).
46 --relaysocket <sockpath> UNIX socket to relay to.
47 --min-servers | -mns <n> The minimum number of servers to keep running.
49 --min-spare | -mnsp <n> The minimum number of servers to have waiting.
50 --max-spare | -mxsp <n> The maximum number of servers to have waiting.
51 --max-servers | -mxs <n> The maximum number of child servers to start.
52 --maxrequests or -r <n> Maximum requests that each child can process.
53 --childtimeout <n> Time out children after this many seconds.
54 --satimeout <n> Time out SpamAssassin after this many seconds.
55 --child-name-template [s] Template for formatting child process name.
56 --pid or -p <filename> Store the daemon's process ID in this file.
58 --user or -u <user> Specifies the user that the daemon runs as.
59 --group or -g <group> Specifies the group that the daemon runs as.
60 --[no]detach Detach from the console daemonize (default).
62 --[no]setsid Completely detach from stderr with setsid().
63 --maxsize n Maximum size of mail to scan (in KB).
65 --dose (D)ie (o)n (s)pamAssassin (e)rrors.
66 --tagall Tag all messages with SA headers, not just spam.
67 --set-envelope-headers Set X-Envelope-From and X-Envelope-To headers.
68 --set-envelope-from Set X-Envelope-From header only.
69 --local-only or -L Turn off all SA network-based tests.
71 --homedir <path> Use the specified directory as SA home.
72 --saconfig <filename> Use the file for SA "user_prefs" configuration.
73 --logfile or -o <dest> Destination for logs (syslog|stderr|<filename>).
75 --logsock or -ls <sock> Allows specifying the syslog socket type.
76 --logident or -li <name> Specify syslog identity name.
77 --logfacility or -lf <nm> Specify syslog facility (log name).
78 --log-rules-hit or -rh Log the names of each matched SA test per mail.
79 --debug or -d [<areas>] Controls extra debug logging.
80 --help | -h | -? [txt] Show basic command-line usage.
82 -hh | -?? [txt] Show short option descriptions (this text).
83 -hhh | -??? [txt] Show usage summary and full option descriptions.
84 --man [html|txt] Show full docs a man page or HTML/plain text.
85 --show defaults|<thing> Print default option values or <thing> and exit.
86 --version Print version information and exit.
87 Compatibility with previous SpamPD versions:
89 --children or -c <n> Same as --max-servers | -mxs (since v2.60).
91 Deprecated since SpamAssassin v3:
93 --auto-whitelist or -aw Use the SA global auto-whitelist feature.
95
97 Perl modules:
98 Mail::SpamAssassin
100 Net::Server (>= v0.89, v2.009+ recommended) with PreForkSimple and/or
101 PreFork submodules.
102 IO::File
103 Time::HiRes
104 IO::Socket::IP (if using TCP/IP sockets)
105 IO::Socket::UNIX (if using UNIX sockets)
106
108 spampd is meant to operate as an S/LMTP mail proxy which passes each
109 message through SpamAssassin for analysis. Note that spampd does not
110 do anything other than check for spam, so it is not suitable as an
111 anti-relay system. It is meant to work in conjunction with your
112 regular mail system. Typically one would pipe any messages they wanted
113 scanned through spampd after initial acceptance by your MX host. This
114 is especially useful for using Postfix's (http://www.postfix.org)
115 advanced content filtering mechanism, although certainly not limited to
116 that application.
117 Please re-read the second sentence in the above paragraph. You should
119 NOT enable spampd to listen on a public interface (IP address) unless
120 you know exactly what you're doing! It is very easy to set up an open
121 relay this way.
122 Here are some simple examples (square brackets in the "diagrams"
124 indicate physical machines):
125 Running between firewall/gateway and internal mail server
127 The firewall/gateway MTA would be configured to forward all of its
128 mail to the port that spampd listens on, and spampd would relay its
129 messages to port 25 of your internal server. spampd could either run
130 on its own host (and listen on any port) or it could run on either
131 mail server (and listen on any port except port 25).
132 Internet ->
134 [ MX gateway (@inter.net.host:25) -> spampd (@localhost:2025) ] ->
135 [ Internal mail (@private.host.ip:25) ]
136 Using Postfix advanced content filtering
138 Please see the FILTER_README that came with the Postfix distribution.
139 You need to have a version of Postfix which supports this (ideally
140 v.2 and up).
141 Internet -> [ Postfix (@inter.net.host:25) ->
143 spampd (@localhost:10025) ->
144 Postfix (@localhost:10026) ] -> final delivery
145 Note that these examples only show incoming mail delivery. Since it is
147 often unnecessary to scan mail coming from your network, it may be
148 desirable to set up a separate outbound route which bypasses spampd.
149 Scalable Mode
151 Since v2.60 spampd can optionally run in "scalable mode" which
152 dynamically adjusts the number of child servers which can process
153 requests simultaneously. This is activated automatically if the
154 "--min-servers" option is specifically set to be lower than
155 "--max-servers".
156 Historically SpamPD inherited from the module
158 Net::Server::PreForkSimple which only allows for a static number of
159 child servers to be running at once. This new option essentially allows
160 for inheriting from Net::Server::PreFork which features dynamic
161 allocation of child servers, with some tunable parameters. (The reason
162 PreFork wasn't used to begin with is because older versions of it
163 didn't seem to work... it was an old TODO to try again later.)
164 Here is what the Net::Server::PreFork documentation has to say (option
166 names changed to match spampd):
167 "This personality binds to one or more ports and then forks
169 "--min-servers" child process. The server will make sure that at any
170 given time there are "--min-spare" servers available to receive a
171 client request, up to "--max-servers". Each of these children will
172 process up to "--maxrequests" client connections. This type is good for
173 a heavily hit site, and should scale well for most applications."
174 Some experimentation and tuning will likely be needed to get the best
176 performance vs. efficiency. Keep in mind that a SIGHUP sent to the
177 parent process will reload configuration files and restart child
178 servers gracefully (handy for tuning a busy site).
179 See the documentation for "--min-servers", "--max-servers",
181 "--min-spare", and "--max-spare" options, and also the section about
182 "Other Net::Server Options" for tuning parameters and links to further
183 documentation.
184
186 spampd can be run directly from the command prompt if desired. This is
187 useful for testing purposes, but for long term use you probably want to
188 put it somewhere like /usr/bin or /usr/local/bin and execute it at
189 system startup. For example on Red Hat-style Linux system one can use
190 a script in /etc/rc.d/init.d to start spampd (a sample script
191 <https://github.com/mpaperno/spampd/tree/master/misc> is available in
192 the spampd code repository).
193 spampd is available as a package for a significant number of Linux
195 distributions, including Debian and derivatives (Ubuntu, etc). This is
196 typically the easiest/best way to install and configure spampd since it
197 should already take into account any system specifics for setting up
198 and running as a daemon, etc. Note however that packages might not
199 offer the latest version of spampd. A good reference for available
200 packages and their versions can be found at
201 <https://repology.org/project/spampd/versions>.
202 spampd is also used in the turnkey Mail-in-a-Box
204 <https://mailinabox.email/> project, which includes Postfix as the main
205 MTA and Dovecot as the local delivery agent with LMTP protocol. Even if
206 you don't need the turnkey solution, it may be informative to peruse
207 the MIAB setup <https://github.com/mail-in-a-
208 box/mailinabox/tree/master/setup> / configuration
209 <https://github.com/mail-in-a-box/mailinabox/tree/master/conf> files
210 for reference.
211 All spampd options have reasonable defaults, especially for a Postfix-
213 centric installation. You may want to specify the "--max-servers"
214 option if you have an especially beefy or weak server box because
215 spampd is a memory-hungry program. Check the "Options" for details on
216 this and all other parameters.
217 To show default values for all options, run "spampd --show defaults".
219 Since v2.61 spampd injects a "_SPAMPDVERSION_" "template tag"
221 <https://spamassassin.apache.org/doc/Mail_SpamAssassin_Conf.html#TEMPLATE-
222 TAGS> macro at message processing time. This can be used in an
223 "add_header" SA config file directive, for example.
224 add_header all Filter-Version SpamAssassin _VERSION_ (_SUBVERSION_, Rules: _RULESVERSION_) / SpamPD _SPAMPDVERSION_
226 Note that spampd replaces spamd from the SpamAssassin distribution in
228 function. You do not need to run spamd in order for spampd to work.
229 This has apparently been the source of some confusion, so now you know.
230 Postfix-specific Notes
232 Here is a typical setup for Postfix "advanced" content filtering as
233 described in the FILTER_README that came with the Postfix distribution
234 (which you really need to read):
235 /etc/postfix/master.cf:
237 smtp inet n - y - - smtpd
239 -o content_filter=smtp:localhost:10025
240 -o myhostname=mx.example.com
241 localhost:10026 inet n - n - 10 smtpd
243 -o content_filter=
244 -o myhostname=mx-int.example.com
245 The first entry is the main public-facing MTA which uses
247 localhost:10025 as the content filter for all mail. The second entry
248 receives mail from the content filter and does final delivery. Both
249 smtpd instances use the same Postfix main.cf file. spampd is the
250 process that listens on localhost:10025 and then connects to the
251 Postfix listener on localhost:10026. Note that the "myhostname"
252 options must be different between the two instances, otherwise Postfix
253 will think it's talking to itself and abort sending.
254 For the above example you can simply start spampd like this:
256 spampd --host=localhost:10025 --relayhost=localhost:10026
258 FILTER_README from the Postfix distro has more details and examples of
260 various setups, including how to skip the content filter for outbound
261 mail.
262 Another tip for Postfix when considering what timeout values to use for
264 --childtimout and --satimeout options is the following command:
265 "# postconf | grep timeout"
267 This will return a list of useful timeout settings and their values.
269 For explanations see the relevant "man" page (smtp, smtpd, lmtp). By
270 default spampd is set up for the default Postfix timeout values.
271 The following guide has some more specific setup instructions:
273 Integrating SpamAssassin into Postfix using spampd
274 <https://wiki.apache.org/spamassassin/IntegratePostfixViaSpampd>
275
277 Always consult the changelog.txt file which should be included in the
278 spampd repository/distribution.
279 If upgrading from a version prior to 2.2, please note that the
281 --add-sc-header option is no longer supported. Use SA's built-in
282 header manipulation features instead (as of SA v2.6).
283 Upgrading from version 1 simply involves replacing the spampd program
285 file with the latest one. Note that the dead-letters folder is no
286 longer being used and the --dead-letters option is no longer needed
287 (though no errors are thrown if it's present). Check the "OPTIONS"
288 list below for a full list of new and deprecated options. Also be sure
289 to check out the change log.
290 Since v2.60 spampd has a new "Scalable Mode" feature which varies the
292 number of running child servers based on demand. This is disabled by
293 default. The option previosly known as "--children" (or "-c") is now
294 called "--max-servers" (or "-mxs"), but the old style is still
295 accepted. See descriptions of the "max-servers" and "min-servers"
296 options for details.
297 Also note that v2.60 added the ability to use a "CONFIGURATION FILE"
299 for specifying all options.
300
302 spampd [
303 [ --config | --cfg | --config-file | --cfg-file [<filename>] ][...]
304 [ --host <host>[:<port>] | --socket <path> --socket-perms <mode> ]
306 [ --relayhost <host>[:<port>] | --relaysocket <path> ]
307 [--min-servers | -mns <n>] [--saconfig <file>] [--user | -u <user> ]
309 [--min-spare | -mnsp <n>] [--satimeout <n> ] [--group | -g <group> ]
310 [--max-spare | -mxsp <n>] [--dose ] [--pid | -p <file> ]
311 [--max-servers | -mxs <n>] [--maxsize <n> ] [--[no]detach ]
312 [--maxrequests | -r <n>] [--local-only | -L ] [--[no]setsid ]
313 [--childtimeout <n>] [--tagall | -a ] [--log-rules-hit | -rh]
314 [ --child-name-template | -cnt [<template>] ] [--homedir <path> ]
315 [ [--set-envelope-headers | -seh] | [--set-envelope-from | -sef] ]
316 [ --logfile | -o (syslog|stderr|<filename>) ][...]
318 [ --logsock | -ls <socketpath> ] [ --logident | -li <name> ]
319 [ --debug | -d [<area,...>|1|0] ] [ --logfacility | -lf <name> ]
320 [ --show ( all | (defaults, config, version, argv, start, self) ) ][...]
321 ]
322 spampd --version
323 spampd [--help | -?] | -?? [txt] | -??? [txt] | [-???? | --man [html|txt]]
324 Options are case-insensitive. "=" can be used as name/value separator
326 instead of space (--name=value). "-" or "--" prefix can be used for all
327 options. Shortest unique option name can be used. All options must be
328 listed individually (no "bundling"). All boolean options can take an
329 optional argument of 1 or 0, or can be negated by adding a "no-" prefix
330 in front of the name. An option specified on the command line overrides
331 the same option loaded from config file(s).
332
334 Please be sure to also read the general information about specifying
335 option arguments in the above "USAGE" section.
336 To view default values for all options, run "spampd --show defaults".
338 --config or -cfg or --config-file or --cfg-file <filename> "new in
340 v2.60"
341 Load options from one or more configuration file(s). This option
342 can be specified multiple times. The "filename" can also be a list
343 of files separated by a ":" (colon). If multiple files specify the
344 same option, the last one loaded will take precedence. Also any
345 options specified on the actual command line will take precedence
346 (regardless of where they appear relative to the "--config"
347 option). --config can only be specified on the command line, one
348 cannot use it within another configuration file.
349 See "CONFIGURATION FILE" section for more details.
351 --host (<ip>|<hostname>)[:<port>]
353 Specifies what hostname/IP and port spampd listens on. By default,
354 it listens on 127.0.0.1 (localhost) on port 10025.
355 As of v2.60 this option can also handle IPv6 addresses in the form
357 of "--host n:n:n" or, with port, "--host [n:n:n]:port" (the square
358 brackets are optional in both forms but recommended in the latter
359 case).
360 Note that the port specified this way implicitly overrides the
362 "--port" option.
363 Important! You should NOT enable spampd to listen on a public
365 interface (IP address) unless you know exactly what you're doing!
366 --port <n>
368 Specifies what port spampd listens on. This is an alternate to
369 using the above "--host=ip:port" notation. Note that a port
370 specified in the "--host" option will override this one.
371 --socket <socketpath>
373 Specifies what UNIX socket spampd listens on. If this is
374 specified, --host and --port are ignored.
375 --socket-perms <mode>
377 The file mode for the created UNIX socket (see --socket) in octal
378 format, e.g. 700 to specify acces only for the user spampd is run
379 as.
380 --relayhost (<ip>|<hostname>)[:<port>]
382 Specifies the hostname/IP to which spampd will relay all messages.
383 Defaults to 127.0.0.1 (localhost) on port 25.
384 As of v2.60 this option can also handle IPv6 addresses in the form
386 of "--relayhost n:n:n" or, with port, "--relayhost [n:n:n]:port"
387 (the square brackets are optional in both forms but recommended in
388 the latter case).
389 Note that the port specified this way implicitly overrides the
391 "--relayport" option.
392 --relayport <n>
394 Specifies what port spampd will relay to. This is an alternate to
395 using the above --relayhost=ip:port notation. Note that a port
396 specified in the "--relayhost" option will override this one.
397 --relaysocket <socketpath>
399 Specifies what UNIX socket spampd will relay to. If this is
400 specified --relayhost and --relayport will be ignored.
401 --user or -u <username>
403 --group or -g <groupname>
404 Specifies the user and/or group that the proxy will run as.
405 Default is mail/mail.
406 --children or -c <n>
408 --max-servers or -mxs <n> "new in v2.60"
409 Number of child servers to start and maintain (where n > 0). Each
410 child will process up to "--maxrequests" (below) before exiting
411 and being replaced by another child. Keep this number low on
412 systems w/out a lot of memory. Note that there is always a parent
413 process running, so if you specify 5 children you will actually
414 have 6 spampd processes running.
415 Note: If "--min-servers" option is also set, and is less than
417 "--max-servers", then the server runs in "Scalable Mode" and the
418 meaning of this option changes. In scalable mode, the number of
419 actual running servers will fluctuate between "--min-servers" and
420 "--max-servers", based on demand.
421 You may want to set your origination mail server to limit the
423 number of concurrent connections to spampd to match this setting
424 (for Postfix this is the "xxxx_destination_concurrency_limit"
425 setting where 'xxxx' is the transport being used, usually 'smtp'
426 or 'lmtp').
427 See also "--min-servers", "--min-spare", and "--max-spare"
429 options.
430 --min-servers or -mns <n> "new in v2.60"
432 Minimum number of child servers to start and maintain (where n >
433 0).
434 Note: If this option is set, and it is less than "--max-servers"
436 option, then the server runs in "Scalable Mode". By default this
437 option is undefined, meaning spampd runs only a set number of
438 servers specified in "--max-servers". In scalable mode, the
439 number of actual running servers will fluctuate between
440 "--min-servers" and "--max-servers", based on demand.
441 See also "--max-servers", "--min-spare", and "--max-spare"
443 options.
444 --min-spare or -mnsp <n> "new in v2.60"
446 The minimum number of servers to have waiting for requests.
447 Minimum and maximum numbers should not be set to close to each
448 other or the server will fork and kill children too often. (-
449 Copied from "Net::Server::PreFork")
450 Note: This option is only used when running in "Scalable Mode".
452 See "--min-servers" and "--max-servers" options.
453 --max-spare or -mxsp <n> "new in v2.60"
455 The maximum number of servers to have waiting for requests. (-
456 Copied from "Net::Server::PreFork")
457 Note: This option is only used when running in "Scalable Mode".
459 See "--min-servers" and "--max-servers" options.
460 --maxrequests or -mr or -r <n>
462 spampd works by forking child servers to handle each message. The
463 maxrequests parameter specifies how many requests will be handled
464 before the child exits. Since a child never gives back memory, a
465 large message can cause it to become quite bloated; the only way
466 to reclaim the memory is for the child to exit.
467 --childtimeout <n>
469 This is the number of seconds to allow each child server before it
470 times out a transaction. In an S/LMTP transaction the timer is
471 reset for every command. This timeout includes time it would take
472 to send the message data, so it should not be too short. Note
473 that it's more likely the origination or destination mail servers
474 will timeout first, which is fine. This is just a "sane"
475 failsafe.
476 --satimeout <n>
478 This is the number of seconds to allow for processing a message
479 with SpamAssassin (including feeding it the message, analyzing it,
480 and adding the headers/report if necessary).
481 This should be less than your origination and destination servers'
483 timeout settings for the DATA command. (For Postfix this is set in
484 "(smtp|lmtp)_data_done_timeout" and "smtpd_timeout"). In the event
485 of timeout while processing the message, the problem is logged and
486 the message is passed on anyway (w/out spam tagging, obviously).
487 To fail the message with a temp 450 error, see the "--dose" (die-
488 on-sa-errors) option, below.
489 --child-name-template or -cnt [<template]> "new in v2.61"
491 Template for formatting child process name. Use a blank string
492 (just the argument name without a value) to leave the child
493 process name unchanged (will be same as parent command line).
494 The template uses printf() style formatting, but with named
496 parameter placeholders. For example (wrapped for clarity):
497 %base_name: child #%child_count(%child_status)
499 [req %req_count/%req_max, time lst/avg/ttl %(req_time_last).4f/%(req_time_avg).4f/%(req_time_ttl).4f,
500 ham/spm %req_ham/%req_spam, rules v%sa_rls_ver)]'
501 Would produce something like:
503 spampd: child #4(D) [req 8/30, time lst/avg/ttl 0.0222/0.0256/0.2045, ham/spm 3/5, rules v1891891]
505 Parameters are specified like: "Value of %(my_name)s is
507 %(my_float_value).4f", with names in parenthesis followed by a
508 standard printf() style formatting specifier ("s" is default), or
509 simply as "Value of %my_name is %my_value" with the default format
510 being a string (works for numerics also). Keep in mind that any
511 actual "%" characters need to be escaped as "%%". Formatting
512 warnings will be logged as "sprintf" errors (most likely a
513 parameter was misspelled).
514 The following variables are available:
516 base_name # Base script name, eg. "spampd"
518 spampd_ver # SpamPD version, eg. "2.61"
519 perl_ver # Perl version, eg. "5.28.1"
520 ns_ver # Net::Server version, eg. "2.009"
521 ns_typ # Net::Server type, "PreFork" or "PreForkSimple"
522 ns_typ_acr # Net::Server type acronym, "PF" or "PFS"
523 sa_ver # SpamAassassin version, eg. "3.4.2"
524 sa_rls_ver # SpamAassassin rules update version, eg. "1891891" or "(unknown)"
525 child_count # total number of children launched so far (current child number)
526 child_status # child status, "C" for connected, or "D" for disconnected
527 req_count # number of requests child has processed so far
528 req_max # maximum child requests before exit
529 req_time_last # [s] time to process the last message
530 req_time_ttl # [s] total processing time for this child
531 req_time_avg # [s] average processing time for this child (req_time_ttl / req_count)
532 req_ham # count of ham messages scored by child
533 req_spam # count of spam messages scored by child
534 --pid or -p <filename>
536 Specifies a filename where spampd will write its process ID so
537 that it is easy to kill it later. The directory that will contain
538 this file must be writable by the spampd user.
539 --logfile or -o (syslog|stderr|<filename>) "new in v2.60"
541 Logging method to use. May be one or more of:
542 • "syslog": Use the system's syslogd (via Sys::Syslog). Default
544 setting.
545 • "stderr": Direct all logging to stderr (if running in
547 background mode these may still end up in the default system
548 log).
549 • "filename": Use the specified file (the location must be
551 accessible to the user spampd is running as). This can also
552 be a device handle, eg: "/dev/tty0" or even "/dev/null" to
553 disable logging entirely.
554 This option may be specified multiple times. You may also specify
556 multiple destination by separating them with a ":" (colon):
557 "--logfile stderr:/var/log/spampd.log"
558 Simultaneous logging to "syslog", "stderr", and one "filename" is
560 possible. At this time only one log file can be used at a time
561 (if several are specified then the last one takes precedence).
562 --logsock or -ls <type> "new in v2.20" "updated in v2.60"
564 Syslog socket to use if "--logfile" is set to syslog.
565 "Since v2.60:"
567 The type can be any of the socket types or logging mechanisms as
569 accepted by the subroutine Sys::Syslog::setlogsock(). Depending on
570 the version of Sys::Syslog and the underlying operating system,
571 one of the following values (or their subset) can be used:
572 native, tcp, udp, inet, unix, stream, pipe, console, eventlog (Win32 only)
574 The default behavior since spampd v2.60 is to let Sys::Syslog pick
576 the default syslog socket. This is the recommended usage for
577 Sys::Syslog (since v0.15), which chooses thusly:
578 The default is to try native, tcp, udp, unix, pipe, stream, console. Under systems with the
580 Win32 API, eventlog will be added as the first mechanism to try if Win32::EventLog is available.
581 For more information please consult the Sys::Syslog
583 <https://metacpan.org/pod/Sys::Syslog> documentation.
584 To preserve backwards-compatibility, the default on HP-UX and
586 SunOS (Solaris) systems is "inet".
587 "Prior to v2.60:"
589 The default was "unix" except on HP-UX and SunOS (Solaris) systems
591 it is "inet".
592 --logident or -li <name> "new in v2.60"
594 Syslog identity name to use. This may also be used in log files
595 written directly (w/out syslog).
596 --logfacility or -lf <name> "new in v2.60"
598 Syslog facility name to use. This is typically the name of the
599 system-wide log file to be written to.
600 --[no]detach [0|1] "new in v2.20"
602 Tells spampd to detach from the console and fork into the
603 background ("daemonize"). Using "--nodetach" can be useful for
604 running under control of some daemon management tools or testing
605 from a command line.
606 --[no]setsid [0|1] "new in v2.51"
608 If "--setsid" is specified then spampd will fork after the bind
609 method to release itself from the command line and then run the
610 POSIX::setsid() command to truly daemonize. Only used if
611 "--nodetach" isn't specified.
612 --maxsize <n>
614 The maximum message size to send to SpamAssassin, in KBytes.
615 Messages over this size are not scanned at all, and an appropriate
616 message is logged indicating this. The size includes headers and
617 attachments (if any).
618 --dose [0|1]
620 Acronym for (d)ie (o)n (s)pamAssassin (e)rrors. When disabled and
621 spampd encounters a problem with processing the message through
622 SpamAssassin (timeout or other error), it will still pass the mail
623 on to the destination server. When enabled, the mail is instead
624 rejected with a temporary error (code 450, which means the
625 origination server should keep retrying to send it). See the
626 related "--satimeout" option, above.
627 --tagall or -a [0|1]
629 Tells spampd to have SpamAssassin add headers to all scanned mail,
630 not just spam. Otherwise spampd will only rewrite messages which
631 exceed the spam threshold score (as defined in the SA settings).
632 Note that for this option to work as of SA-2.50, the
633 always_add_report and/or always_add_headers settings in your
634 SpamAssassin local.cf need to be set to 1/true.
635 --log-rules-hit or -rh [0|1]
637 Logs the names of each SpamAssassin rule which matched the message
638 being processed. This list is returned by SA.
639 --set-envelope-headers or -seh [0|1] "new in v2.30"
641 Turns on addition of X-Envelope-To and X-Envelope-From headers to
642 the mail being scanned before it is passed to SpamAssassin. The
643 idea is to help SA process any blacklist/whitelist to/from
644 directives on the actual sender/recipients instead of the possibly
645 bogus envelope headers. This potentially exposes the list of all
646 recipients of that mail (even BCC'd ones). Therefore usage of
647 this option is discouraged.
648 NOTE: Even though spampd tries to prevent this leakage by removing
650 the X-Envelope-To header after scanning, SpamAssassin itself might
651 add headers that report recipient(s) listed in X-Envelope-To.
652 --set-envelope-from or -sef [0|1] "new in v2.30"
654 Same as above option but only enables the addition of X-Envelope-
655 From header. For those that don't feel comfortable with the
656 possible information exposure of X-Envelope-To. The above option
657 overrides this one.
658 --local-only or -L [0|1]
660 Turn off all SA network-based tests (DNS, Razor, etc).
661 --homedir <directory> "new in v2.40"
663 Use the specified directory as home directory for the spamassassin
664 process. Things like the auto-whitelist and other plugin
665 (razor/pyzor) files get written to here. A good place for this is
666 in the same place your "bayes_path" SA config setting points to
667 (if any). Make sure this directory is accessible to the user that
668 spampd is running as.
669 Thanks to Alexander Wirt for this fix.
671 --saconfig <filename>
673 Use the specified file for SpamAssassin configuration options in
674 addition to the default local.cf file. Any options specified here
675 will override the same option from local.cf.
676 --debug or -d [<area,...>|1|0] "(updated in v2.60)"
678 Turns on SpamAssassin debug messages which print to the system
679 mail log (same log as spampd will log to). Also turns on more
680 verbose logging of what spampd is doing (new in v2). Also
681 increases log level of Net::Server to 4 (debug), adding yet more
682 info (but not too much) (new in v2.2).
683 "New in v2.60:"
685 Setting the value to 1 (one) is the same as using no parameter
687 (eg. simply -d). The value of 0 (zero) disables debug logging.
688 The area list is passed on directly to SpamAssassin and controls
690 logging facilities. If no areas are listed (and debug logging is
691 enabled), all debugging information is printed (this equivalent to
692 passing "all" as the area). Diagnostic output can also be enabled
693 for each area individually; area is the area of the code to
694 instrument. For example, to produce diagnostic output on bayes,
695 learn, and dns, use:
696 -d bayes,learn,dns
698 You can also disable specific areas with the "no" prefix:
700 -d all,norules,nobayes
702 To show only spampd debug messages (none from SpamAssassin), use:
704 -d spampd
706 For more information about which areas (aka channels or
708 facilities) are available, please see the documentation at:
709 SpamAssassin Wiki::DebugChannels
711 <http://wiki.apache.org/spamassassin/DebugChannels>
712 Mail::SpamAssassin::Logger::add_facilities()
714 <https://spamassassin.apache.org/doc/Mail_SpamAssassin_Logger.html#METHODS>
715 --show <thing>[,<thing>[,...]] "new in v2.60"
717 Meant primarily for debugging configuration settings (or code),
718 this will print some information to the console and then exit.
719 <thing> may be one or more of:
721 • "defaults": Show default values for all options, in a format
723 suitable for a config file.
724 • "config": Shows option values after processing all given
726 command-line arguments, including anything loaded from config
727 file(s).
728 • "start": Shows the final configuration arguments after
730 processing any config file(s).
731 • "version": Same as "--version" switch but runs after parsing
733 all options and shows actual Net::Server type which would be
734 used (PreFork or PreForkSimple).
735 • "argv": Shows anything remaining on command line (@ARGV) after
737 processing all known arguments (this will be passed onto
738 Net::Server).
739 • "self": Dumps the whole SpamPD object, including all settings.
741 Trés geek.
742 • "all": Prints all of the above.
744 Multiple "thing"s may be specified by using the --show option
746 multiple times, or separating the items with a comma: "--show
747 config,start,argv".
748 Note that all thing options besides "defaults" and "config"
750 require the Perl module Data::Dumper installed.
751 --version "new in v2.52"
753 Prints version information about SpamPD, Net::Server,
754 SpamAssassin, and Perl.
755 --help or -h or -? [txt]
757 --hh or -?? [txt]
758 --hhh or -??? [txt]
759 --man or -hhhh or -???? [html|txt]
760 Prints increasingly verbose usage information. By default help is
761 displayed in "terminal" (groff) format with some text styling
762 applied. If you want to use "less" as a pager, provide it with the
763 "-R" switch, eg.:
764 spampd --??? | less -R
766 Alternatively you can request plain-text format with the optional
768 "txt" value.
769 "--man" displays the full documentation, optionally in "html" or
771 plain text "txt" formats (default is to use actual "man"
772 format/display). HTML version is saved to a temp file and an
773 attempt is made to open it in the default system browser (it is
774 better if the browser is already opened). If available, the
775 optional Perl module HTML::Display is used to (try to) open a
776 browser.
777 Other Net::Server Options
779 Net::Server supports some other options which spampd doesn't accept
780 directly. For example there are access control options, child process
781 tuning, and a few more (see below). Such options can be passed through
782 to Net::Server (and subtypes) by specifying them at the end of the
783 spampd command line (or in a configuration file) following two dashes "
784 -- " by themselves (this is a failry typicaly convention for passing
785 options onto another program). As an example, it may look something
786 like this:
787 spampd --host 10.0.0.1 -port 10025 -- --cidr_allow 10.0.0.0/24
789 The "--cidr_allow" after the " -- " is passed onto Net::Server. If the
791 " -- " were not there, you would get an error from spampd about an
792 unknown option.
793 To specify Net::Server options in a configuration file, place them
795 after two dashes ("--") on a line by themselves. See "CONFIGURATION
796 FILE" for an example.
797 This only makes sense with the few options not directly controlled
799 by/through spampd. As of Net::Server v2.009 the list is:
800 reverse_lookups, allow, deny, cidr_allow, cidr_deny, chroot, ipv, conf_file,
802 serialize, lock_file, check_for_dead, max_dequeue, check_for_dequeue
803 If running in "Scalable Mode" then these settings from
805 Net::Server::PreFork can also be very relevant to performance tuning:
806 check_for_waiting, check_for_spawn, min_child_ttl
808 Keep in mind that the Net::Server types inherit from each other:
810 "PreFork" inherits from "PreForkSimple" which inherits from
811 "Net::Server" itself. Which means all the options are also inherited.
812 See the Net::Server(3)
814 <https://https://metacpan.org/pod/Net::Server#DEFAULT-ARGUMENTS-FOR-
815 Net::Server>, Net::Server::PreForkSimple(3)
816 <https://metacpan.org/pod/Net::Server::PreForkSimple#COMMAND-LINE-
817 ARGUMENTS>, and Net::Server::PreFork(3)
818 <https://metacpan.org/pod/Net::Server::PreFork#COMMAND-LINE-ARGUMENTS>
819 documentation for details.
820 Deprecated Options
822 The following options are no longer used but still accepted for
823 backwards compatibility with prevoius spampd versions:
824 --dead-letters
826 --heloname
827 --stop-at-threshold
828 --add-sc-header
829 --hostname
830 --auto-whitelist or -aw "deprecated with SpamAssassin v3+"
831 This option is no longer relevant with SA version 3.0 and above,
832 which controls auto whitelist use via config file settings. Do not
833 use it unless you must use an older SA version. An error will be
834 generated if attempting to use this option with SA 3.0 or above.
835 For SA version < 3.0, turns on the SpamAssassin global whitelist
837 feature. See the SA docs. Note that per-user whitelists are not
838 available.
839 NOTE: DBBasedAddrList is used as the storage mechanism. If you
841 wish to use a different mechanism (such as SQLBasedAddrList), the
842 spampd code will need to be modified in 2 instances (search the
843 source for DBBasedAddrList).
844
846 Since v2.60 spampd allows for the use of a configuration file to load
847 server parameters. One or more files can be specified on the command
848 line (see "--config" option for more details on syntax). The format of
849 a configuration file is simple key/value pairs. Comments (starting with
850 # or ;) and blank lines are ignored. The option names are exactly as
851 they appear above in the "OPTIONS" section. They can be listed with or
852 w/out the "-"/"--" prefixes. Key/value separator can be one or more of
853 space, tab, or "=" (equal) sign.
854 Multiple configuration files can be loaded, with the latter ones being
856 able to override options loaded earlier. Any options specified on the
857 command line will take precedence over options from file(s).
858 Configuration file(s) are reloaded during a HUP-induced restart (see
859 "SIGNALS"), making it possible to adjust settings dynamically on a
860 running server.
861 You may also provide "passthrough" options directly to Net::Server by
863 putting them after a "--" on a line by itself (this is just like using
864 the lonesome "--" on a command line; see "Other Net::Server Options").
865 Note that one cannot use the "--config" option to load a file from
867 within another file. A config file can only be specified on the command
868 line.
869 Use the "spampd --show defaults > spampd.config" command to generate a
871 sample configuration file showing all default values. The example below
872 demonstrates various valid syntax for the file.
873 # Sample configuration file for SpamPD.
875 # Double dashes
877 --user spampd
878 # Single dash and = separator with spaces
880 -pid = /var/run/spampd/spampd.pid
881 # No dashes required, equals separator no spaces
883 homedir=/var/cache/spampd
884 # No dashes, space separator
886 host 127.0.0.1
887 # Disabled option (after comment character)
889 #port 10025
890 # Boolean values can be set/unset a number of ways:
892 tagall 1
893 local-only 0
894 set-envelope-from
895 no-log-rules-hit
896 # Passthrough arguments for Net::Server[::PreFork[Simple]] could go here.
898 # Be sure to also uncomment the "--" if using any.
899 # --
900 # cidr_allow 127.0.0.1/32
901
903 HUP "updated in v2.60"
904 Sending HUP signal to the master process will restart all the
905 children gracefully (meaning the currently running requests will
906 shut down once the request is complete).
907 "Since v2.60":
909 SpamAssassin configuration IS reloaded on HUP. Any children
911 currently in the middle of a transaction will finish with the
912 previous SA config and then exit. A new set of children, using the
913 new config, is spawned immediately upon HUP and will serve any new
914 requests.
915 In a similar manner, spampd will also reload its own settings from
917 any configuration file(s) specified on the original command line
918 with "--config" option (see "OPTIONS" and "CONFIGURATION FILE").
919 "Since v2.52": Children were restarted but SpamAssassin
921 configuration was not reloaded.
922 "Prior to v2.52": HUP would try to restart the server with all
924 default settings (usually failing).
925 TTIN, TTOU
927 Sending TTIN signal to the master process will dynamically
928 increase the number of children by one, and TTOU signal will
929 decrease it by one.
930 INT, TERM
932 Sending INT or TERM signal to the master process will kill all the
933 children immediately and shut down the daemon.
934 QUIT Sending QUIT signal to the master process will perform a graceful
936 shutdown, waiting for all children to finish processing any
937 current transactions and then shutting down the parent process.
938
940 Running between firewall/gateway and internal mail server:
941 spampd listens on port 10025 on the same host as the internal mail
942 server.
943 spampd --host=192.168.1.10
945 Same as above but spampd runs on port 10025 of the same host as
947 the firewall/gateway and passes messages on to the internal mail
948 server on another host.
949 spampd --relayhost=192.168.1.10
951 Using Postfix advanced content filtering example and disable SA network
953 checks:
954 spampd --port=10025 --relayhost=127.0.0.1:10026 --local-only
955 Using UNIX sockets instead if INET ports:
957 spampd listens on the UNIX socket "/var/run/spampd.socket" with
958 persmissions 700 instead of a TCP port:
959 spampd --socket /var/run/spampd.socket --socket-perms 700
961 spampd will relay mail to "/var/run/dovecot/lmtp" instead of a TCP
963 port:
964 spampd --relaysocket /var/run/dovecot/lmtp
966 Remember that the user spampd runs as needs to have read AND write
968 permissions on the relaysocket!
969
971 spampd is written and maintained by Maxim Paperno
972 <MPaperno@WorldDesign.com>. The open source code repository is located
973 at <https://github.com/mpaperno/spampd/>. See
974 <http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm> for historical
975 info.
976 spampd v2 uses two Perl modules (MSDW::SMTP::Client and
978 MSDW::SMTP::Server) by Bennett Todd and Copyright (C) 2001 Morgan
979 Stanley Dean Witter. These are distributed under the GNU GPL (see
980 module code for more details). Both modules have been slightly
981 modified from the originals and are included in this file under new
982 names (SpamPD::Client and SpamPD::Server, respectively).
983 Also thanks to Bennett Todd for the example smtpproxy script which
985 helped create this version of spampd. See
986 <http://bent.latency.net/smtpprox/> (seems to be down) or
987 <https://github.com/jnorell/smtpprox>.
988 spampd v1 was based on code by Dave Carrigan named assassind. Trace
990 amounts of his code or documentation may still remain. Thanks to him
991 for the original inspiration and code. <https://openshut.net/>.
992 Also thanks to spamd (included with SpamAssassin) and amavisd-new
994 (<http://www.ijs.si/software/amavisd/>) for some tricks.
995 Various people have contributed patches, bug reports, and ideas, all of
997 whom I would like to thank. I have tried to include credits in code
998 comments and in the change log, as appropriate.
999 Code Contributors (in order of appearance):
1001 Kurt Andersen
1002 Roland Koeckel
1003 Urban Petry
1004 Sven Mueller
1005 See also: <https://github.com/mpaperno/spampd/graphs/contributors/>
1007
1009 spampd is Copyright (c) Maxim Paperno; All Rights Reserved.
1010 Portions are Copyright (c) 2001 Morgan Stanley Dean Witter as mentioned
1012 above in the Credits section.
1013 This program is free software; you can redistribute it and/or modify
1015 it under the terms of the GNU General Public License as published by
1016 the Free Software Foundation; either version 2 of the License, or
1017 (at your option) any later version.
1018 This program is distributed in the hope that it will be useful,
1020 but WITHOUT ANY WARRANTY; without even the implied warranty of
1021 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
1022 GNU General Public License for more details.
1023 You should have received a copy of the GNU General Public License along
1025 with this program. If not, see <https://www.gnu.org/licenses/>.
1026
1028 Use GitHub issue tracking: <https://github.com/mpaperno/spampd/issues>
1029
1031 spamassassin(1)
1032 Mail::SpamAssassin(3)
1034 <https://spamassassin.apache.org/doc/Mail_SpamAssassin.html>
1035 Net::Server(3) <https://metacpan.org/pod/Net::Server>
1037 SpamAssassin Site <http://www.spamassassin.org/>
1039 SpamPD Code Repository <https://github.com/mpaperno/spampd>
1041 SpamPD product page
1043 <http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm>
1044 Integrating SpamAssassin into Postfix using spampd
1046 <https://wiki.apache.org/spamassassin/IntegratePostfixViaSpampd>
1047perl v5.36.0 2023-01-21 SPAMPD(1)