From e8540c2214ab542936d072b207591d7825ea753b Mon Sep 17 00:00:00 2001 From: Max Paperno Date: Mon, 9 Dec 2024 08:18:13 -0500 Subject: [PATCH] Bump to version 2.62; Update changelog; Update readme with extended info from original web page. --- changelog.txt | 10 +- readme.md | 95 +- spampd.pl | 5 +- spampd.pod | 2342 ++++++++++++++++++++++++------------------------- 4 files changed, 1270 insertions(+), 1182 deletions(-) diff --git a/changelog.txt b/changelog.txt index 232d3c5..762df73 100644 --- a/changelog.txt +++ b/changelog.txt @@ -8,6 +8,14 @@ SpamPD Change Log ! : important change, change of default behavior, etc. ----------------------------------------------------------- +2.62 (9-Dec-24) + +* Fixed that SpamPD shares the same socket to `redist` between children. + Report: https://github.com/mpaperno/spampd/issues/44 Fix: https://github.com/mpaperno/spampd/pull/45 (thanks @catap !) +* Fix option names in configuration parameter validation methods (https://github.com/mpaperno/spampd/commit/29752f8) +~ Do not set up logging if only showing debug info (https://github.com/mpaperno/spampd/commit/641e6571). + +--- 2.61 (6-Aug-21) Bug fixes, new features, and some optimization. Thanks to Simon Matter for reporting, suggestions, and testing! @@ -23,7 +31,7 @@ Bug fixes, new features, and some optimization. Thanks to Simon Matter for repor Template format documented in POD. (https://github.com/mpaperno/spampd/issues/32) + Add _SPAMPDVERSION_ as a "template tag" (macro), eg. for use in SA add_header directives. - +--- 2.60 (26-Jul-21) This version brings quite a few changes, though the base functionality and compatibility is unchanged diff --git a/readme.md b/readme.md index d6d262b..5927f59 100644 --- a/readme.md +++ b/readme.md @@ -3,20 +3,99 @@ Originally released in May of 2002, _SpamPD_ is a program used within an e-mail delivery system to scan messages for possible Unsolicited Commercial E-mail (UCE, aka spam) content. It uses an excellent program called SpamAssassin (SA) to do the actual message scanning. SpamPD acts as a transparent SMTP/LMTP proxy between two mail servers, and during the transaction it passes the mail through SA. If SA decides the mail could be spam, then SpamPD will ask SA to -add some headers and a report to the message indicating it's spam and why. SpamPD is written in Perl and should theoretically run on any -platform supported by Perl and SpamAssassin. +add some headers and a report to the message indicating it's spam and why. -Check the [Releases](https://github.com/mpaperno/spampd/releases) area for latest versions, and see the old -[Downloads](https://github.com/mpaperno/spampd/downloads) section for older releases (and the "previous-versions" folder for some even more ancient ones). -Recently the Debian package version was added to this repo as a branch, and those tags will also show up in the Releases page. +SpamPD is written in Perl and should theoretically run on any platform supported by Perl and SpamAssassin. + +Here's an un-solicited comment someone sent regarding *SpamPD* performance: + +> Just to let you know: We have the SA/spampd combo up an running in a high volume environment. With 3 KAT-B Server (4x 2,5 GHz Xeon MP +with Hyperthreading, 3 GB RAM) we handle 15.000 to 20.000 Mails/h (Hour!) with room to spare. We had some performance issues with the +Bayes databases but now everything runs smoothly. + +Check the [Releases](https://github.com/mpaperno/spampd/releases) area for latest versions, +and see the "previous-versions" folder for some more ancient ones.
+(Note that the Debian package version was added to this repo as a branch, and those tags will also show up in the Releases page.) Please read the [POD file](https://github.com/mpaperno/spampd/blob/master/spampd.pod) for full documentation of the many available options. -See the [changelog](https://github.com/mpaperno/spampd/blob/master/changelog.txt) for version history. +See the [changelog](https://github.com/mpaperno/spampd/blob/master/changelog.txt) for full version history. -More historic background information is available here. +## Package status + +**HELP!** Debian package maintainer needed. Please see [GitHub Issue 46](https://github.com/mpaperno/spampd/issues/46). Linux packages data courtesy of Repology: - Packaging status + Packaging status + +

Usage

+

SpamPD was initially designed as a content filter mechanism for use with the Postfix MTA. +However, it has no inherent dependencies on Postfix or any other MTA. +Some more specific setup information is provided in the included documentation.

+ +

Version 2 Architecture

+

Version 2 of SpamPD is a major rewrite of the underlying methods. SpamPD + no longer acts as a relay server but more as a "transparent" proxy +server. That is, it never actually takes responsibility for the mail at +any point. Instead, the origination and destination mail servers speak +directly to each other. If a failure occurs within SpamPD + (or SpamAssassin) during a transaction, then the mail servers will +disconnect and the sending server is still responsible for retrying the +message for as long as it is configured to do so. Responsibility for +mail delivery always lies with the 2 mail servers, which would be "real" + MTAs and not a 500 line Perl script :-) This removes a major problem +with version 1 of SpamPD, and makes this a recommended upgrade.

+

While this is a much safer technique than previously employed, it does remove a possible feature which some users of SpamPD + have implemented (sorry guys). That is redirecting spam to a spamtrap +address instead of letting the message through to the original +recipient. This is due to the fact that the recipient information is +passed on to the destination server before the message data is scanned +for spam. On the other hand it presents the possibility of rejecting +spam at the S/LMTP level without having to generate bounce notices and +such.

+ +

SpamPD now fully supports the LMTP + protocol (due to the nature of it's new transparency). Logging has been + improved and is now more compatible with spamd. + New parameters added: --children, --local-only, --childtimeout, +--satimeout, --dose, --log-rules-hit, --add-sc-header, and --hostname. +Three parameters are now deprecated: --dead-letters, --heloname, and +--stop-at-threshold.

+

More details and further changes are documented in the change log.

+ +

More Information

+ +

If you aren't familiar with SpamAssassin, + then you should definitely start there (or end up there) first. There +is a very helpful users discussion list for SA (see their site). For Postfix setup, be sure to read the FILTER_README document that is included with the distribution. SpamPD is meant to be used as an "advanced content filtering" method (some examples are included with the SpamPD + documentation). Postfix also has a helpful users discussion list. Make +sure you do your homework before you ask other people to help you!

+ +

Be sure to check out the SpamPD documentation, the change log, as well as comments in the ac

+ +

Credits

+

SpamPD is written and maintained by Maxim Paperno (https://github.com/mpaperno).

+

SpamPD contains code written by +Bennecode Todd (Copyright (C) 2001 Morgan Stanley Dean Witter) and is used + in accordance with the GNU General Public License. The code is in the +form of two Perl modules which have been included in the program. Also +his smtpproxy example program served as inspiration for this version of SpamPD.

+

SpamPD version 1 was based on code by Dave Carrigan named assassind. Trace amounts of his code or documentation may still remain. Thanks to him for the original inspiration and code.

+

Various people have contributed patches, bug reports, and ideas, all +of whom I would like to thank. I have tried to include credits in code +comments, documentation, and in the change log, as appropriate.

+ +

Copyright, License, & Disclaimer

+

Copyright Maxim Paperno; All rights reserved.

+

Portions are Copyright © 2001 Morgan Stanley Dean Witter as mentioned above in the CREDITS section.

+

This program is free software; you can redistribute it and/or modify +it under the terms of the GNU General Public License as published by the + Free Software Foundation; either version 2 of the License, or (at your +option) any later version.

+

This program is distributed in the hope that it will be useful, but +WITHOUT ANY WARRANTY; without even the implied warranty of +MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General + Public License for more details.

+

The GNU GPL can be found at https://www.gnu.org/licenses/

diff --git a/spampd.pl b/spampd.pl index ab38654..f49cc8d 100755 --- a/spampd.pl +++ b/spampd.pl @@ -3,6 +3,7 @@ ###################### # SpamPD - Spam Proxy Daemon # +# v2.62 - 09-Dec-24 # v2.61 - 06-Aug-21 # v2.60 - 26-Jul-21 # v2.53 - 25-Feb-19 @@ -393,7 +394,7 @@ BEGIN use Time::HiRes qw(time); use Mail::SpamAssassin (); -our $VERSION = '2.611'; +our $VERSION = '2.62'; # ISA will change to a Net::Server "flavor" at runtime based on options. our @ISA = qw(Net::Server); @@ -1675,7 +1676,7 @@ =head1 NAME =head1 VERSION -Documentation for SpamPD version 2.61. +Documentation for SpamPD version 2.62. =head1 DESCRIPTION diff --git a/spampd.pod b/spampd.pod index 02969bb..2644fda 100644 --- a/spampd.pod +++ b/spampd.pod @@ -1,1171 +1,1171 @@ -=encoding UTF-8 - -=head1 NAME - -SpamPD - Spam Proxy Daemon - -=head1 VERSION - -Documentation for SpamPD version 2.61. - - -=head1 DESCRIPTION - -I is an SMTP/LMTP proxy that marks (or tags) spam using -SpamAssassin (L). The proxy is designed -to be transparent to the sending and receiving mail servers and at no point -takes responsibility for the message itself. If a failure occurs within -I (or SpamAssassin) then the mail servers will disconnect and the -sending server is still responsible for retrying the message for as long -as it is configured to do so. - -I uses SpamAssassin to modify (tag) relayed messages based on -their spam score, so all SA settings apply. This is described in the SA -documentation. I will by default only tell SA to tag a -message if it exceeds the spam threshold score, however you can have -it rewrite all messages passing through by adding the --tagall option -(see SA for how non-spam messages are tagged). - -I logs all aspects of its operation to syslog(8), using the -mail syslog facility. - -The latest version can be found at L. - - -=head1 SYNOPSIS - -B I<[ options ]> - -Options: - - --config Load options from file(s). - - --host [:] Hostname/IP and optional port to listen on. - --port Port to listen on (alternate syntax to above). - --socket UNIX socket to listen on. - --socket-perms The octal mode to set on the UNIX socket. - --relayhost [:] Host and optional port to relay mail to. - --relayport Port to relay to (alternate syntax to above). - --relaysocket UNIX socket to relay to. - - --min-servers | -mns The minimum number of servers to keep running. - --min-spare | -mnsp The minimum number of servers to have waiting. - --max-spare | -mxsp The maximum number of servers to have waiting. - --max-servers | -mxs The maximum number of child servers to start. - --maxrequests or -r Maximum requests that each child can process. - --childtimeout Time out children after this many seconds. - --satimeout Time out SpamAssassin after this many seconds. - --child-name-template [s] Template for formatting child process name. - - --pid or -p Store the daemon's process ID in this file. - --user or -u Specifies the user that the daemon runs as. - --group or -g Specifies the group that the daemon runs as. - - --[no]detach Detach from the console daemonize (default). - --[no]setsid Completely detach from stderr with setsid(). - - --maxsize n Maximum size of mail to scan (in KB). - --dose (D)ie (o)n (s)pamAssassin (e)rrors. - --tagall Tag all messages with SA headers, not just spam. - --set-envelope-headers Set X-Envelope-From and X-Envelope-To headers. - --set-envelope-from Set X-Envelope-From header only. - - --local-only or -L Turn off all SA network-based tests. - --homedir Use the specified directory as SA home. - --saconfig Use the file for SA "user_prefs" configuration. - - --logfile or -o Destination for logs (syslog|stderr|). - --logsock or -ls Allows specifying the syslog socket type. - --logident or -li Specify syslog identity name. - --logfacility or -lf Specify syslog facility (log name). - --log-rules-hit or -rh Log the names of each matched SA test per mail. - --debug or -d [] Controls extra debug logging. - - --help | -h | -? [txt] Show basic command-line usage. - -hh | -?? [txt] Show short option descriptions (this text). - -hhh | -??? [txt] Show usage summary and full option descriptions. - --man [html|txt] Show full docs a man page or HTML/plain text. - --show defaults| Print default option values or and exit. - --version Print version information and exit. - -Compatibility with previous SpamPD versions: - - --children or -c Same as --max-servers | -mxs (since v2.60). - -Deprecated since SpamAssassin v3: - - --auto-whitelist or -aw Use the SA global auto-whitelist feature. - - -=head1 REQUIRES - -Perl modules: - -=over 5 - -=item B - -=item B (>= v0.89, v2.009+ recommended) with B and/or B submodules. - -=item B - -=item B - -=item B (if using TCP/IP sockets) - -=item B (if using UNIX sockets) - -=back - -=head1 OPERATION - -I is meant to operate as an S/LMTP mail proxy which passes -each message through SpamAssassin for analysis. Note that I -does not do anything other than check for spam, so it is not suitable as -an anti-relay system. It is meant to work in conjunction with your -regular mail system. Typically one would pipe any messages they wanted -scanned through I after initial acceptance by your MX host. -This is especially useful for using Postfix's (http://www.postfix.org) -advanced content filtering mechanism, although certainly not limited to -that application. - -Please re-read the second sentence in the above paragraph. You should NOT -enable I to listen on a public interface (IP address) unless you -know exactly what you're doing! It is very easy to set up an open relay this -way. - -Here are some simple examples (square brackets in the "diagrams" indicate -physical machines): - -=over 2 - -=item B - -The firewall/gateway MTA would be configured to forward all of its mail -to the port that I listens on, and I would relay its -messages to port 25 of your internal server. I could either -run on its own host (and listen on any port) or it could run on either -mail server (and listen on any port except port 25). - - Internet -> - [ MX gateway (@inter.net.host:25) -> spampd (@localhost:2025) ] -> - [ Internal mail (@private.host.ip:25) ] - -=item B - -Please see the F that came with the Postfix distribution. You -need to have a version of Postfix which supports this (ideally v.2 and up). - - Internet -> [ Postfix (@inter.net.host:25) -> - spampd (@localhost:10025) -> - Postfix (@localhost:10026) ] -> final delivery - -=back - -Note that these examples only show incoming mail delivery. Since it is -often unnecessary to scan mail coming from your network, it may be desirable -to set up a separate outbound route which bypasses I. - -=head2 Scalable Mode - -Since v2.60 I can optionally run in "scalable mode" which dynamically adjusts the number -of child servers which can process requests simultaneously. This is activated automatically if the -C<--min-servers> option is specifically set to be lower than C<--max-servers>. - -Historically I inherited from the module I which only allows for -a static number of child servers to be running at once. This new option essentially allows for inheriting from -I which features dynamic allocation of child servers, with some tunable parameters. -(The reason I wasn't used to begin with is because older versions of it didn't seem to work... -it was an old TODO to try again later.) - -Here is what the I documentation has to say (option names changed to match I): - -I<"This personality binds to one or more ports and then forks C<--min-servers> child process. The server -will make sure that at any given time there are C<--min-spare> servers available to receive a client -request, up to C<--max-servers>. Each of these children will process up to C<--maxrequests> client -connections. This type is good for a heavily hit site, and should scale well for most applications."> - -Some experimentation and tuning will likely be needed to get the best performance vs. efficiency. Keep in mind -that a SIGHUP sent to the parent process will reload configuration files and restart child servers gracefully -(handy for tuning a busy site). - -See the documentation for C<--min-servers>, C<--max-servers>, C<--min-spare>, and C<--max-spare> options, -and also the section about L for tuning parameters and links to further documentation. - - -=head1 INSTALLATION AND CONFIGURATION - -I can be run directly from the command prompt if desired. This is -useful for testing purposes, but for long term use you probably want to put -it somewhere like /usr/bin or /usr/local/bin and execute it at system startup. -For example on Red Hat-style Linux system one can use a script in -/etc/rc.d/init.d to start I (a L -is available in the I code repository). - -I is available as a B for a significant number of Linux distributions, -including Debian and derivatives (Ubuntu, etc). This is typically the easiest/best way -to install and configure I since it should already take into account any system -specifics for setting up and running as a daemon, etc. Note however that packages -might not offer the latest version of I. A good reference for available -packages and their versions can be found at L. - -I is also used in the turnkey L -project, which includes Postfix as the main MTA and Dovecot as the local delivery agent -with LMTP protocol. Even if you don't need the turnkey solution, it may be informative -to peruse the MIAB L / -L files for reference. - -All I options have reasonable defaults, especially for a Postfix-centric -installation. You may want to specify the C<--max-servers> option if you have an -especially beefy or weak server box because I is a memory-hungry -program. Check the L<"Options"> for details on this and all other parameters. - -To show default values for all options, run C. - -B I injects a C<_SPAMPDVERSION_> -L<"template tag"|https://spamassassin.apache.org/doc/Mail_SpamAssassin_Conf.html#TEMPLATE-TAGS> -macro at message processing time. This can be used in an C SA config file directive, for example. - - add_header all Filter-Version SpamAssassin _VERSION_ (_SUBVERSION_, Rules: _RULESVERSION_) / SpamPD _SPAMPDVERSION_ - -Note that B< I replaces I > from the I distribution -in function. You do not need to run I in order for I to work. -This has apparently been the source of some confusion, so now you know. - -=head2 Postfix-specific Notes - -Here is a typical setup for Postfix "advanced" content filtering as described -in the F that came with the Postfix distribution (which you -really need to read): - -F: - - smtp inet n - y - - smtpd - -o content_filter=smtp:localhost:10025 - -o myhostname=mx.example.com - - localhost:10026 inet n - n - 10 smtpd - -o content_filter= - -o myhostname=mx-int.example.com - -The first entry is the main public-facing MTA which uses localhost:10025 -as the content filter for all mail. The second entry receives mail from -the content filter and does final delivery. Both smtpd instances use -the same Postfix F file. I is the process that listens on -localhost:10025 and then connects to the Postfix listener on localhost:10026. -Note that the C options must be different between the two instances, -otherwise Postfix will think it's talking to itself and abort sending. - -For the above example you can simply start I like this: - - spampd --host=localhost:10025 --relayhost=localhost:10026 - -F from the Postfix distro has more details and examples of -various setups, including how to skip the content filter for outbound mail. - -Another tip for Postfix when considering what timeout values to use for ---childtimout and --satimeout options is the following command: - -C<# postconf | grep timeout> - -This will return a list of useful timeout settings and their values. For -explanations see the relevant C page (smtp, smtpd, lmtp). By default -I is set up for the default Postfix timeout values. - -The following guide has some more specific setup instructions: -B> - - -=head1 UPGRADING - -Always consult the F file which should be included in the I repository/distribution. - -If upgrading from a version B, please note that the --add-sc-header -option is no longer supported. Use SA's built-in header manipulation features -instead (as of SA v2.6). - -Upgrading from B simply involves replacing the F program file -with the latest one. Note that the I folder is no longer being -used and the --dead-letters option is no longer needed (though no errors are -thrown if it's present). Check the L list below for a full list of new -and deprecated options. Also be sure to check out the change log. - -B I has a new L feature which varies the number of running -child servers based on demand. This is disabled by default. The option previosly known as -C<--children> (or C<-c>) is now called C<--max-servers> (or C<-mxs>), but the old style is still accepted. -See descriptions of the C and C options for details. - -Also note that v2.60 added the ability to use a L for specifying all options. - - -=head1 USAGE - - spampd [ - [ --config | --cfg | --config-file | --cfg-file [] ][...] - - [ --host [:] | --socket --socket-perms ] - [ --relayhost [:] | --relaysocket ] - - [--min-servers | -mns ] [--saconfig ] [--user | -u ] - [--min-spare | -mnsp ] [--satimeout ] [--group | -g ] - [--max-spare | -mxsp ] [--dose ] [--pid | -p ] - [--max-servers | -mxs ] [--maxsize ] [--[no]detach ] - [--maxrequests | -r ] [--local-only | -L ] [--[no]setsid ] - [--childtimeout ] [--tagall | -a ] [--log-rules-hit | -rh] - [ --child-name-template | -cnt [