1SPAMPD(1)             User Contributed Perl Documentation            SPAMPD(1)
2
3
4

NAME

6       SpamPD - Spam Proxy Daemon
7

VERSION

9       Documentation for SpamPD version 2.61.
10

DESCRIPTION

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
20       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
27       spampd logs all aspects of its operation to syslog(8), using the mail
28       syslog facility.
29
30       The latest version can be found at
31       <https://github.com/mpaperno/spampd>.
32

SYNOPSIS

34       spampd [ options ]
35
36       Options:
37
38         --config <filename>        Load options from file(s).
39
40         --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
48         --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
57         --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
61         --[no]detach               Detach from the console daemonize (default).
62         --[no]setsid               Completely detach from stderr with setsid().
63
64         --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
70         --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
74         --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
81         --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
88       Compatibility with previous SpamPD versions:
89
90         --children or -c <n>       Same as --max-servers | -mxs (since v2.60).
91
92       Deprecated since SpamAssassin v3:
93
94         --auto-whitelist or -aw    Use the SA global auto-whitelist feature.
95

REQUIRES

97       Perl modules:
98
99       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

OPERATION

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
118       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
123       Here are some simple examples (square brackets in the "diagrams"
124       indicate physical machines):
125
126       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
133           Internet ->
134           [ MX gateway (@inter.net.host:25) -> spampd (@localhost:2025) ] ->
135           [ Internal mail (@private.host.ip:25) ]
136
137       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
142           Internet -> [ Postfix (@inter.net.host:25)  ->
143                         spampd (@localhost:10025)     ->
144                         Postfix (@localhost:10026)  ] -> final delivery
145
146       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
150   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
157       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
165       Here is what the Net::Server::PreFork documentation has to say (option
166       names changed to match spampd):
167
168       "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
175       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
180       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

INSTALLATION AND CONFIGURATION

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
194       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
203       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
212       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
218       To show default values for all options, run "spampd --show defaults".
219
220       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
225         add_header all Filter-Version SpamAssassin _VERSION_ (_SUBVERSION_, Rules: _RULESVERSION_) / SpamPD _SPAMPDVERSION_
226
227       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
231   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
236       /etc/postfix/master.cf:
237
238         smtp             inet  n  -  y  -  -   smtpd
239           -o content_filter=smtp:localhost:10025
240           -o myhostname=mx.example.com
241
242         localhost:10026  inet  n  -  n  -  10  smtpd
243           -o content_filter=
244           -o myhostname=mx-int.example.com
245
246       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
255       For the above example you can simply start spampd like this:
256
257        spampd --host=localhost:10025 --relayhost=localhost:10026
258
259       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
263       Another tip for Postfix when considering what timeout values to use for
264       --childtimout and --satimeout options is the following command:
265
266       "# postconf | grep timeout"
267
268       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
272       The following guide has some more specific setup instructions:
273       Integrating SpamAssassin into Postfix using spampd
274       <https://wiki.apache.org/spamassassin/IntegratePostfixViaSpampd>
275

UPGRADING

277       Always consult the changelog.txt file which should be included in the
278       spampd repository/distribution.
279
280       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
284       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
291       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
298       Also note that v2.60 added the ability to use a "CONFIGURATION FILE"
299       for specifying all options.
300

USAGE

302         spampd [
303           [ --config | --cfg | --config-file | --cfg-file [<filename>] ][...]
304
305           [ --host <host>[:<port>]      | --socket <path> --socket-perms <mode> ]
306           [ --relayhost <host>[:<port>] | --relaysocket <path>                  ]
307
308           [--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
317           [ --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
325       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

OPTIONS

334       Please be sure to also read the general information about specifying
335       option arguments in the above "USAGE" section.
336
337       To view default values for all options, run "spampd --show defaults".
338
339       --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
350            See "CONFIGURATION FILE" section for more details.
351
352       --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
356            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
361            Note that the port specified this way implicitly overrides the
362            "--port" option.
363
364            Important! You should NOT enable spampd to listen on a public
365            interface (IP address) unless you know exactly what you're doing!
366
367       --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
372       --socket <socketpath>
373            Specifies what UNIX socket spampd listens on. If this is
374            specified, --host and --port are ignored.
375
376       --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
381       --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
385            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
390            Note that the port specified this way implicitly overrides the
391            "--relayport" option.
392
393       --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
398       --relaysocket <socketpath>
399            Specifies what UNIX socket spampd will relay to. If this is
400            specified --relayhost and --relayport will be ignored.
401
402       --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
407       --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
416            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
422            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
428            See also "--min-servers", "--min-spare", and "--max-spare"
429            options.
430
431       --min-servers or -mns <n> "new in v2.60"
432            Minimum number of child servers to start and maintain (where n >
433            0).
434
435            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
442            See also "--max-servers", "--min-spare", and "--max-spare"
443            options.
444
445       --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
451            Note: This option is only used when running in "Scalable Mode".
452            See "--min-servers" and "--max-servers" options.
453
454       --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
458            Note: This option is only used when running in "Scalable Mode".
459            See "--min-servers" and "--max-servers" options.
460
461       --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
468       --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
477       --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
482            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
490       --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
495            The template uses printf() style formatting, but with named
496            parameter placeholders.  For example (wrapped for clarity):
497
498              %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
502            Would produce something like:
503
504              spampd: child #4(D) [req 8/30, time lst/avg/ttl 0.0222/0.0256/0.2045, ham/spm 3/5, rules v1891891]
505
506            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
515            The following variables are available:
516
517                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
535       --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
540       --logfile or -o (syslog|stderr|<filename>) "new in v2.60"
541            Logging method to use. May be one or more of:
542
543            •    "syslog": Use the system's syslogd (via Sys::Syslog). Default
544                 setting.
545
546            •    "stderr": Direct all logging to stderr (if running in
547                 background mode these may still end up in the default system
548                 log).
549
550            •    "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
555            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
559            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
563       --logsock or -ls <type> "new in v2.20"  "updated in v2.60"
564            Syslog socket to use if "--logfile" is set to syslog.
565
566            "Since v2.60:"
567
568            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
573              native, tcp, udp, inet, unix, stream, pipe, console, eventlog (Win32 only)
574
575            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
579              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
582            For more information please consult the Sys::Syslog
583            <https://metacpan.org/pod/Sys::Syslog> documentation.
584
585            To preserve backwards-compatibility, the default on HP-UX and
586            SunOS (Solaris) systems is "inet".
587
588            "Prior to v2.60:"
589
590            The default was "unix" except on HP-UX and SunOS (Solaris) systems
591            it is "inet".
592
593       --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
597       --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
601       --[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
607       --[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
613       --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
619       --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
628       --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
636       --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
640       --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
649            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
653       --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
659       --local-only or -L [0|1]
660            Turn off all SA network-based tests (DNS, Razor, etc).
661
662       --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
670            Thanks to Alexander Wirt for this fix.
671
672       --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
677       --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
684            "New in v2.60:"
685
686            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
689            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
697                -d bayes,learn,dns
698
699            You can also disable specific areas with the "no" prefix:
700
701                -d all,norules,nobayes
702
703            To show only spampd debug messages (none from SpamAssassin), use:
704
705                -d spampd
706
707            For more information about which areas (aka channels or
708            facilities) are available, please see the documentation at:
709
710            SpamAssassin Wiki::DebugChannels
711            <http://wiki.apache.org/spamassassin/DebugChannels>
712
713            Mail::SpamAssassin::Logger::add_facilities()
714            <https://spamassassin.apache.org/doc/Mail_SpamAssassin_Logger.html#METHODS>
715
716       --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
720            <thing> may be one or more of:
721
722            •   "defaults": Show default values for all options, in a format
723                suitable for a config file.
724
725            •   "config": Shows option values after processing all given
726                command-line arguments, including anything loaded from config
727                file(s).
728
729            •   "start": Shows the final configuration arguments after
730                processing any config file(s).
731
732            •   "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
736            •   "argv": Shows anything remaining on command line (@ARGV) after
737                processing all known arguments (this will be passed onto
738                Net::Server).
739
740            •   "self": Dumps the whole SpamPD object, including all settings.
741                Trés geek.
742
743            •   "all": Prints all of the above.
744
745            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
749            Note that all thing options besides "defaults" and "config"
750            require the Perl module Data::Dumper installed.
751
752       --version "new in v2.52"
753            Prints version information about SpamPD, Net::Server,
754            SpamAssassin, and Perl.
755
756       --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
765              spampd --??? | less -R
766
767            Alternatively you can request plain-text format with the optional
768            "txt" value.
769
770            "--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
778   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
788         spampd --host 10.0.0.1 -port 10025 -- --cidr_allow 10.0.0.0/24
789
790       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
794       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
798       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
801         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
804       If running in "Scalable Mode" then these settings from
805       Net::Server::PreFork can also be very relevant to performance tuning:
806
807         check_for_waiting, check_for_spawn, min_child_ttl
808
809       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
813       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
821   Deprecated Options
822       The following options are no longer used but still accepted for
823       backwards compatibility with prevoius spampd versions:
824
825       --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
836            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
840            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

CONFIGURATION FILE

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
855       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
862       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
866       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
870       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
874         # Sample configuration file for SpamPD.
875
876         # Double dashes
877         --user    spampd
878
879         # Single dash and = separator with spaces
880         -pid = /var/run/spampd/spampd.pid
881
882         # No dashes required, equals separator no spaces
883         homedir=/var/cache/spampd
884
885         # No dashes, space separator
886         host  127.0.0.1
887
888         # Disabled option (after comment character)
889         #port  10025
890
891         # 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
897         # 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

SIGNALS

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
908            "Since v2.60":
909
910            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
916            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
920            "Since v2.52": Children were restarted but SpamAssassin
921            configuration was not reloaded.
922
923            "Prior to v2.52": HUP would try to restart the server with all
924            default settings (usually failing).
925
926       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
931       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
935       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

EXAMPLES

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
944              spampd --host=192.168.1.10
945
946            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
950              spampd --relayhost=192.168.1.10
951
952       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
956       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
960              spampd --socket /var/run/spampd.socket --socket-perms 700
961
962            spampd will relay mail to "/var/run/dovecot/lmtp" instead of a TCP
963            port:
964
965              spampd --relaysocket /var/run/dovecot/lmtp
966
967            Remember that the user spampd runs as needs to have read AND write
968            permissions on the relaysocket!
969

CREDITS

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
977       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
984       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
989       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
993       Also thanks to spamd (included with SpamAssassin) and amavisd-new
994       (<http://www.ijs.si/software/amavisd/>) for some tricks.
995
996       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
1000   Code Contributors (in order of appearance):
1001        Kurt Andersen
1002        Roland Koeckel
1003        Urban Petry
1004        Sven Mueller
1005
1006       See also: <https://github.com/mpaperno/spampd/graphs/contributors/>
1007

COPYRIGHT, LICENSE, AND DISCLAIMER

1009       spampd is Copyright (c) Maxim Paperno;  All Rights Reserved.
1010
1011       Portions are Copyright (c) 2001 Morgan Stanley Dean Witter as mentioned
1012       above in the Credits section.
1013
1014           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
1019           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
1024       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

BUGS

1028       Use GitHub issue tracking: <https://github.com/mpaperno/spampd/issues>
1029

SEE ALSO

1031       spamassassin(1)
1032
1033       Mail::SpamAssassin(3)
1034       <https://spamassassin.apache.org/doc/Mail_SpamAssassin.html>
1035
1036       Net::Server(3) <https://metacpan.org/pod/Net::Server>
1037
1038       SpamAssassin Site <http://www.spamassassin.org/>
1039
1040       SpamPD Code Repository <https://github.com/mpaperno/spampd>
1041
1042       SpamPD product page
1043       <http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm>
1044
1045       Integrating SpamAssassin into Postfix using spampd
1046       <https://wiki.apache.org/spamassassin/IntegratePostfixViaSpampd>
1047
1048
1049
1050perl v5.36.0                      2023-01-21                         SPAMPD(1)
Impressum