Provided by: spampd_2.53-1.2_all bug

NAME

       SpamPD - Spam Proxy Daemon (version 2.5x)

Synopsis

       spampd [--host=host[:port]] [--relayhost=hostname[:port]] [--socket] [--socket-perms]
       [--relaysocket] [--user|u=username] [--group|g=groupname] [--children|c=n]
       [--maxrequests=n] [--childtimeout=n] [--satimeout=n] [--pid|p=filename] [--nodetach]
       [--setsid] [--logsock=inet|unix] [--maxsize=n] [--dose] [--tagall|a] [--log-rules-hit|rh]
       [--set-envelope-headers|seh] [--set-envelope-from|sef] [--auto-whitelist|aw]
       [--local-only|L] [--saconfig=filename] [--debug|d]

       spampd --help

Description

       spampd is an SMTP/LMTP proxy that marks (or tags) spam using SpamAssassin
       (<http://www.SpamAssassin.org/>). 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 spampd (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.

       spampd uses SpamAssassin to modify (tag) relayed messages based on their spam score, so
       all SA settings apply. This is described in the SA documentation.  spampd 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).

       spampd logs all aspects of its operation to syslog(8), using the mail syslog facility.

       The latest version can be found at <https://github.com/mpaperno/spampd>.

Requires

       Perl modules:

       Mail::SpamAssassin
       Net::Server::PreForkSimple
       IO::File
       IO::Socket::IP
       IO::Socket::UNIX
       Time::HiRes (not actually required but recommended)

Operation

       spampd is meant to operate as an S/LMTP mail proxy which passes each message through
       SpamAssassin for analysis.  Note that spampd 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 spampd 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 spampd
       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):

       Running between firewall/gateway and internal mail server

          The firewall/gateway MTA would be configured to forward all of its mail to the port
          that spampd listens on, and spampd would relay its messages to port 25 of your internal
          server. spampd 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)

       Using Postfix advanced content filtering

          Please see the FILTER_README 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

       Note that these examples only show incoming mail delivery.  Since it is usually
       unnecessary to scan mail coming from your network (right?), it may be desirable to set up
       a separate outbound route which bypasses spampd.

Upgrading

       If upgrading from a version prior to 2.2, please note that the --add-sc-header option is
       no longer supported.  Use SAs built-in header manipulation features instead (as of SA
       v2.6).

       Upgrading from version 1 simply involves replacing the spampd program file with the latest
       one.  Note that the dead-letters 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
       "Options" list below for a full list of new and deprecated options.  Also be sure to check
       out the change log.

Installation

       spampd 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 spampd (a sample script is
       available on the spampd Web page @
       http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm).

       The options all have reasonable defaults, especially for a Postfix-centric installation.
       You may want to specify the --children option if you have an especially beefy or weak
       server box because spampd is a memory-hungry program.  Check the "Options" for details on
       this and all other parameters.

       Note that spampd replaces spamd from the SpamAssassin distribution in function. You do not
       need to run spamd in order for spampd to work.  This has apparently been the source of
       some confusion, so now you know.

   Postfix-specific Notes
       Here is a typical setup for Postfix "advanced" content filtering as described in the
       FILTER_README that came with the Postfix distribution (which you really need to read):

       /etc/postfix/master.cf:

        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 main.cf file.  spampd is the process
       that listens on localhost:10025 and then connects to the Postfix listener on
       localhost:10026.  Note that the "myhostname" 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 spampd like this:

        spampd --host=localhost:10025 --relayhost=localhost:10026

       FILTER_README 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:

       "# postconf | grep timeout"

       This will return a list of useful timeout settings and their values.  For explanations see
       the relevant "man" page (smtp, smtpd, lmtp).  By default spampd is set up for the default
       Postfix timeout values.

Options

       --host=(ip|hostname)[:port]
            Specifies what hostname/IP and port spampd listens on. By default, it listens on
            127.0.0.1 (localhost) on port 10025.

            Important! You should NOT enable spampd to listen on a public interface (IP address)
            unless you know exactly what you're doing!

       --port=n
            Specifies what port spampd listens on. By default, it listens on port 10025. This is
            an alternate to using the above --host=ip:port notation.

       --socket=socketpath
            Specifies what UNIX socket spampd listens on. If this is specified, --host and --port
            are ignored.

       --socket-perms=mode
            The file mode fo the created UNIX socket (see --socket) in octal format, e.g. 700 to
            specify acces only for the user spampd is run as.

       --relayhost=(ip|hostname)[:port]
            Specifies the hostname/IP to which spampd will relay all messages. Defaults to
            127.0.0.1 (localhost). If the port is not provided, that defaults to 25.

       --relayport=n
            Specifies what port spampd will relay to. Default is 25. This is an alternate to
            using the above --relayhost=ip:port notation.

       --relaysocket=socketpath
            Specifies what UNIX socket spampd will relay to. If this is specified --relayhost and
            --relayport will be ignored.

       --user=username or -u=username
       --group=groupname or  -g=groupname
            Specifies the user and/or group that the proxy will run as. Default is mail/mail.

       --children=n or -c=n
            Number of child servers to start and maintain (where n > 0). Each child will process
            up to --maxrequests (below) before exiting and being replaced by another child.  Keep
            this number low on systems w/out a lot of memory.  Default is 5 (which seems OK on a
            512MB lightly loaded system).  Note that there is always a parent process running, so
            if you specify 5 children you will actually have 6 spampd processes running.

            You may want to set your origination mail server to limit the number of concurrent
            connections to spampd to match this setting (for Postfix this is the
            "xxxx_destination_concurrency_limit" setting where 'xxxx' is the transport being
            used, usually 'smtp', and the default is 100).

       --maxrequests=n
            spampd works by forking child servers to handle each message. The maxrequests
            parameter specifies how many requests will be handled before the child exits. Since a
            child never gives back memory, a large message can cause it to become quite bloated;
            the only way to reclaim the memory is for the child to exit. The default is 20.

       --childtimeout=n
            This is the number of seconds to allow each child server before it times out a
            transaction. In an S/LMTP transaction the timer is reset for every command.  This
            timeout includes time it would take to send the message data, so it should not be too
            short.  Note that it's more likely the origination or destination mail servers will
            timeout first, which is fine.  This is just a "sane" failsafe.  Default is 360
            seconds (6 minutes).

       --satimeout=n
            This is the number of seconds to allow for processing a message with SpamAssassin
            (including feeding it the message, analyzing it, and adding the headers/report if
            necessary).  This should be less than your origination and destination servers'
            timeout settings for the DATA command. For Postfix the default is 300 seconds in both
            cases (smtp_data_done_timeout and smtpd_timeout). In the event of timeout while
            processing the message, the problem is logged and the message is passed on anyway
            (w/out spam tagging, obviously).  To fail the message with a temp 450 error, see the
            --dose (die-on-sa-errors) option, below.  Default is 285 seconds.

       --pid=filename or -p=filename
            Specifies a filename where spampd will write its process ID so that it is easy to
            kill it later. The directory that will contain this file must be writable by the
            spampd user. The default is /var/run/spampd.pid.

       --logsock=(unix|inet) "(new in v2.20)"
            Syslog socket to use.  May be either "unix" of "inet".  Default is "unix" except on
            HP-UX and SunOS (Solaris) systems which seem to prefer "inet".

       --nodetach "(new in v2.20)"
            If this option is given spampd won't detach from the console and fork into the
            background. This can be useful for running under control of some daemon management
            tools or when configured as a win32 service under cygrunsrv's control.

       --setsid "(new in v2.51)"
            If this option is given spampd will fork after the bind method to release itself from
            the command line and then run the POSIX::setsid() command to truly daemonize. Only
            used if --nodetach isn't specified.

       --maxsize=n
            The maximum message size to send to SpamAssassin, in KBytes. By default messages over
            64KB are not scanned at all, and an appropriate message is logged indicating this.
            The size includes headers and attachments (if any).

       --dose
            Acronym for (d)ie (o)n (s)pamAssassin (e)rrors.  By default if spampd encounters a
            problem with processing the message through Spam Assassin (timeout or other error),
            it will still pass the mail on to the destination server.  If you specify this option
            however, the mail is instead rejected with a temporary error (code 450, which means
            the origination server should keep retrying to send it).  See the related --satimeout
            option, above.

       --tagall or -a
            Tells spampd to have SpamAssassin add headers to all scanned mail, not just spam.  By
            default spampd will only rewrite messages which exceed the spam threshold score (as
            defined in the SA settings).  Note that for this option to work as of SA-2.50, the
            always_add_report and/or always_add_headers settings in your SpamAssassin local.cf
            need to be set to 1/true.

       --log-rules-hit or --rh
            Logs the names of each SpamAssassin rule which matched the message being processed.
            This list is returned by SA.

       --set-envelope-headers or --seh "(new in v2.30)"
            Turns on addition of X-Envelope-To and X-Envelope-From headers to the mail being
            scanned before it is passed to SpamAssassin. The idea is to help SA process any
            blacklist/whitelist to/from directives on the actual sender/recipients instead of the
            possibly bogus envelope headers. This potentially exposes the list of all recipients
            of that mail (even BCC'ed ones).  Therefore usage of this option is discouraged.

            NOTE: Even though spampd tries to prevent this leakage by removing the X-Envelope-To
            header after scanning, SpamAssassin itself might add headers itself which report one
            or more of the recipients which had been listed in this header.

       --set-envelope-from or --sef "(new in v2.30)"
            Same as above option but only enables the addition of X-Envelope-From header.  For
            those that don't feel comfortable with the possible information exposure of
            X-Envelope-To.  The above option overrides this one.

       --auto-whitelist or --aw "(deprecated with SpamAssassin v3+)"
            This option is no longer relevant with SA version 3.0 and above, which controls auto
            whitelist use via config file settings. This option is likely to be removed in the
            future.  Do not use it unless you must use an older SA version.

            For SA version < 3.0, turns on the SpamAssassin global whitelist feature.  See the SA
            docs. Note that per-user whitelists are not available.

            NOTE: DBBasedAddrList is used as the storage mechanism. If you wish to use a
            different mechanism (such as SQLBasedAddrList), the spampd code will need to be
            modified in 2 instances (search the source for DBBasedAddrList).

       --local-only or -L
            Turn off all SA network-based tests (DNS, Razor, etc).

       --homedir=directory
            Use the specified directory as home directory for the spamassassin process.  Things
            like the auto-whitelist and other plugin (razor/pyzor) files get written to here.
            Defaul is /var/cache/spampd.  A good place for this is in the same place your
            bayes_path SA config setting points to (if any).  Make sure this directory is
            accessible to the user that spampd is running as (default: mail).  New in v2.40.
            Thanks to Alexander Wirt for this fix.

       --saconfig=filename
            Use the specified file for SpamAssassin configuration options in addition to the
            default local.cf file.  Any options specified here will override the same option from
            local.cf.  Default is to not use any additional configuration file.

       --debug or -d
            Turns on SpamAssassin debug messages which print to the system mail log (same log as
            spampd will log to).  Also turns on more verbose logging of what spampd is doing (new
            in v2).  Also increases log level of Net::Server to 4 (debug), adding yet more info
            (but not too much) (new in v2.2).

       --version
            Prints version information about SpamPD, Net::Server, SpamAssassin, and Perl.

       --help or -h or -?
            Prints usage information.

   Deprecated Options
       The following options are no longer used but still accepted for backwards compatibility
       with prevoius spampd versions:

       --dead-letters
       --heloname
       --stop-at-threshold
       --add-sc-header
       --hostname

Signals

       HUP  Sending HUP signal to the master process will restart all the children gracefully
            (meaning the currently running requests will shut down once the request is complete).
            SpamAssassin configuration is NOT reloaded.

       TTIN, TTOU
            Sending TTIN signal to the master process will dynamically increase the number of
            children by one, and TTOU signal will decrease it by one.

       INT, TERM
            Sending INT or TERM signal to the master process will kill all the children
            immediately and shut down the daemon.

Examples

       Running between firewall/gateway and internal mail server:
            spampd listens on port 10025 on the same host as the internal mail server.

              spampd --host=192.168.1.10

            Same as above but spampd runs on port 10025 of the same host as the firewall/gateway
            and passes messages on to the internal mail server on another host.

              spampd --relayhost=192.168.1.10

       Using Postfix advanced content filtering example and disable SA network checks:
              spampd --port=10025 --relayhost=127.0.0.1:10026 --local-only

       Using UNIX sockets instead if INET ports:
            Spampd listens on the UNIX socket /var/run/spampd.socket with persmissions 700
            instead of a TCP port:

              spampd --socket /var/run/spampd.socket --socket-perms 700

            Spampd will relay mail to /var/run/dovecot/lmtp instead of a TCP port:

              spampd --relaysocket /var/run/dovecot/lmtp

            Remember that the user spampd runs as needs to have read AND write permissions on the
            relaysocket!

Credits

       spampd is written and maintained by Maxim Paperno <MPaperno@WorldDesign.com>.  See
       <http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm> for latest info.

       spampd v2 uses two Perl modules by Bennett Todd and Copyright (C) 2001 Morgan Stanley Dean
       Witter. These are distributed under the GNU GPL (see module code for more details). Both
       modules have been slightly modified from the originals and are included in this file under
       new names.

       Also thanks to Bennett Todd for the example smtpproxy script which helped create this
       version of spampd.  See http://bent.latency.net/smtpprox/ .

       spampd v1 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.
       <https://openshut.net/>.

       Also thanks to spamd (included with SpamAssassin) and amavisd-new
       (<http://www.ijs.si/software/amavisd/>) for some tricks.

       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 and in the change log, as
       appropriate.

   Code Contributors (in order of appearance):
        Kurt Andersen
        Roland Koeckel
        Urban Petry
        Sven Mueller

       See also: <https://github.com/mpaperno/spampd/graphs/contributors/>

Copyright, License, and Disclaimer

       spampd is Copyright (c) 2002-2006, 2009, 2010, 2013, 2018 by World Design Group, Inc. and
       Maxim Paperno.

       Portions are Copyright (c) 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.

       You should have received a copy of the GNU General Public License along with this program.
       If not, see <https://www.gnu.org/licenses/>.

Bugs

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

To Do

       Figure out how to use Net::Server::PreFork because it has cool potential for load
       management.  I tried but either I'm missing something or PreFork is somewhat broken in how
       it works.  If anyone has experience here, please let me know.

       Add configurable option for rejecting mail outright based on spam score.  It would be nice
       to make this program safe enough to sit in front of a mail server such as Postfix and be
       able to reject mail before it enters our systems.  The only real problem is that Postfix
       will see localhost as the connecting client, so that disables any client-based checks
       Postfix can do and creates a possible relay hole if localhost is trusted.

See Also

       perl(1), Mail::SpamAssassin(3pm), <http://www.spamassassin.org/>,
       <http://www.WorldDesign.com/index.cfm/rd/mta/spampd.htm>, spamassassin(1p)