Copyright (c) 2002 Theo de Raadt. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
.Dd December 18, 2002 .Dt SPAMD 8 .Os .Sh NAME .Nm spamd .Nd spam deferral daemon .Sh SYNOPSIS .Nm spamd k -words .Op Fl 45dgv .Op Fl B Ar maxblack .Op Fl b Ar address .Op Fl c Ar maxcon .Op Fl G Ar passtime:greyexp:whiteexp .Op Fl n Ar name .Op Fl p Ar port .Op Fl r Ar reply .Op Fl s Ar secs .Op Fl w Ar window .Ek .Sh DESCRIPTION .Nm is a fake .Xr sendmail 8 Ns -like daemon which rejects false mail. If the .Xr pf 4 packet filter is configured to redirect port 25 (SMTP) to this daemon, it will attempt to waste the time and resources of the spam sender.
p The options are as follows: l -tag -width Ds t Fl 4 Return error code 450 to the spammer (default). t Fl 5 Return error code 550 to the spammer. t Fl B Ar maxblack The maximum number of concurrent blacklisted connections to allow in greylisting mode. This value may not be greater than maxcon (see below). The default is maxcon - 100 t Fl b Ar address Specify the local address to which .Nm is to .Xr bind 2 . By default .Nm listens on all local addresses. t Fl c Ar maxcon The maximum number of concurrent connections to allow. The default is 800. t Fl d Debug mode. .Nm does not .Xr fork 2 into the background. t Fl G Ar passtime:greyexp:whiteexp Adjust the three time parameters for greylisting; see .Sx GREYLISTING below. t Fl g Greylisting mode; see .Sx GREYLISTING below. t Fl n Ar name The SMTP version banner that is reported upon initial connection. t Fl p Ar port Specify a different port number from the default port that .Nm should listen for redirected SMTP connections on. The default port is found by looking for the named service .Em spamd using .Xr getservbyname 3 . t Fl r Ar reply The SMTP error to return to the spammer, i.e. 450, 451, 550. This defaults to 450. t Fl s Ar secs Delay each character sent to the client by the specified amount of seconds. Defaults to 1. t Fl v Enable verbose logging. By default .Nm logs connections, disconnections and blacklist matches to .Xr syslogd 8 at .Dv LOG_INFO level. With verbose logging enabled, message detail including subject and recipient information is logged at .Dv LOG_INFO , along with the message body and SMTP dialogue being logged at .Dv LOG_DEBUG level. t Fl w Ar window Set the socket receive buffer to this many bytes, adjusting the window size. .El
p .Nm is designed to be very efficient so that it does not slow down the receiving machine. Spam is never accepted, but always rejected with either a 450 or 550 error message. The normal way that spam has been dealt with in the past is to either accept and drop, or outright block. When configured to use 450 responses, .Nm takes neither of these actions: it rejects the mail back to the senders' queue.
p .Nm is best started from .Xr rc 8 in conjunction with the .Xr spamd-setup 8 which processes a list of spammers' addresses, and applies appropriate .Xr pfctl 8 .Em rdr rules. .Xr spamd-setup 8 is run from .Xr cron 8 . .Sh REDIRECTING SMTP CONNECTIONS With .Xr pf 4 , connections to port 25 (SMTP) can be redirected to another host or port, based on the source address of the sender. The .Em rdr rules used for this purpose are described in .Xr pf.conf 5 . The rules can be loaded into a .Em table to simplify handling. d -literal -offset 4n table <spamd> persist rdr pass inet proto tcp from <spamd> to any \e port smtp -> 127.0.0.1 port 8025 .Ed
p Any addresses in table .Em <spamd> are then redirected to .Nm running on port 8025. Addresses can be loaded into the .Em table , like: d -literal -offset 4n # pfctl -q -t spamd -T replace -f /usr/local/share/spammers .Ed
p .Xr spamd-setup 8 can also be used to load addresses into the .Em <spamd> table. .Xr spamd-setup 8 also has the added benefit of being able to remove addresses from blacklists, and will connect to .Nm over a localhost socket, giving .Nm information about each source of blacklist addresses, as well as custom rejection messages for each blacklist source that can be used to let any real person whose mail is deferred by spamd know why their address has been listed from sending mail. This is important as it allows legitimate mail senders to pressure spam sources into behaving properly so that they may be removed from the relevant blacklists. .Sh CONFIGURATION CONNECTIONS .Nm listens for configuration connections on the port identified by the named service .Em spamd-cfg (see .Xr services 5 ) . The configuration socket listens only on the INADDR_LOOPBACK address. Configuration of spamd is done by connecting to the configuration socket, and sending blacklist information, one blacklist per line. Each blacklist consists of a name, a message to reject mail with, and addresses in CIDR format, all separated by semicolons (;): d -literal -offset indent tag;"rejection message";aaa.bbb.ccc.ddd/mm;aaa.bbb.ccc.ddd/mm .Ed
p The rejection message must be inside double quotes. A \e" will produce a double quote in the output. \en will produce a newline. %A will expand to the connecting IP address in dotted quad format. %% may be used to produce a single % in the output. \e\e will produce a single \e. .Nm will reject mail by displaying all the messages from all blacklists in which a connecting address is matched. .Xr spamd-setup 8 is normally used to configure this information. .Sh GREYLISTING When run in greylisting mode, .Nm will run in the normal mode for any addresses blacklisted by .Xr spamd-setup 8 . Connections from addresses not blacklisted by .Xr spamd-setup 8 will be considered for greylisting. Such connections will not be stuttered at or delayed, and will receive the pleasantly innocuous temporary failure of: d -literal -offset 4n 450 Temporary failure, please try again later. .Ed
p in the SMTP dialogue immediately after the recipient is specified. .Nm will use the db file in
a /var/db/spamd to track these non-blacklisted connections to .Nm by connecting IP address, envelope-from, and envelope-to, or "tuple" for short.
p A previously unseen tuple is added to the
a /var/db/spamd database, recording the time an initial connection attempt was seen. After .Em passtime minutes (by default 30) if .Nm sees a retried attempt to deliver mail for the same tuple, .Nm will whitelist the connecting address by adding it as a whitelist entry to
p .Nm regularly scans the
a /var/db/spamd database and configures all whitelist addresses as the .Em spamd-white .Xr pf 4 table. The .Em spamd-white table must be used to allow connections to pass to the real MTA as in the following .Xr pf.conf 5 example: d -literal -offset 4n table <spamd> persist table <spamd-white> persist rdr pass inet proto tcp from <spamd> to any \e port smtp -> 127.0.0.1 port 8025 rdr pass inet proto tcp from !<spamd-white> to any port smtp \e -> 127.0.0.1 port 8025 .Ed
p With this configuration, .Xr spamd-setup 8 should be used to configure blacklists in .Nm and add them to the .Em spamd .Xr pf 4 table. These connections will be stuttered at by .Nm . All other connections not in the .Em spamd-white table are redirected to .Nm but will not be stuttered at. Such connections will be considered for greylisting and eventual whitelisting (by addition to the .Em spamd-white table so they are not redirected) if they retry mail delivery.
p .Nm removes tuple entries from the
a /var/db/spamd database if delivery has not been retried within .Em greyexp hours (by default 4) from the initial time a connection is seen. The default is 4 hours as this is the most common setting after which MTA's will give up attempting to retry delivery of a message.
p .Nm removes whitelist entries from the
a /var/db/spamd database if no mail delivery activity has been seen from the whitelisted address by .Xr spamlogd 8 within .Em whiteexp hours (by default 864, or 36 days) from the initial time an address is whitelisted. The default is 36 days to allow for the delivery of monthly mailing list digests without greylist delays every time. .Xr spamlogd 8 should be used to update the whitelist entries in
a /var/db/spamd when connections are seen to pass to the real MTA on the .Em smtp port. .Sh LOGGING .Nm sends log messages to .Xr syslogd 8 using .Em facility daemon and, with increasing verbosity, .Em level err, warn, info and debug. The following .Xr syslog.conf 5 section can be used to log connection details to a dedicated file: d -literal -offset indent !spamd daemon.err;daemon.warn;daemon.info /var/log/spamd .Ed .Sh FILES /etc/spamd.conf .Sh SEE ALSO .Xr pf.conf 5 , .Xr services 5 , .Xr spamd.conf 5 , .Xr syslog.conf 5 , .Xr pfctl 8 , .Xr spamd-setup 8 , .Xr spamdb 8 , .Xr spamlogd 8 , .Xr syslogd 8 .Sh HISTORY The .Nm command appeared in .Ox 3.3 . .Sh BUGS .Nm currently uses the user .Dq _spamd outside a chroot jail when running in greylisting mode, and requires the greylisting database in
a /var/db/spamd to be owned by the .Dq _spamd user. This is wrong and should change to a distinct user from the one used by the chrooted .Nm process.