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