path: root/libexec/spamd/spamd.8

.\"	$OpenBSD: spamd.8,v 1.73 2007/02/27 02:10:58 beck Exp $
.\"
.\" 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
.Bk -words
.Op Fl 45bdv
.Op Fl B Ar maxblack
.Op Fl l Ar address
.Op Fl c Ar maxcon
.Op Fl G Ar passtime:greyexp:whiteexp
.Op Fl h Ar hostname
.Op Fl n Ar name
.Op Fl p Ar port
.Op Fl r Ar reply
.Op Fl S Ar secs
.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.
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl 4
For blacklisted entries, return error code 450 to the spammer (default).
.It Fl 5
For blacklisted entries, return error code 550 to the spammer.
.It 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
.Ar maxcon
\- 100.
.It Fl l Ar address
Specify the local address to which
.Nm
is to
.Xr bind 2 .
By default
.Nm
listens on all local addresses.
.It Fl c Ar maxcon
The maximum number of concurrent connections to allow.
.Ar maxcon
may not exceed 800 (the default).
.It Fl d
Debug mode.
.Nm
does not
.Xr fork 2
into the background.
.It Fl G Ar passtime:greyexp:whiteexp
Adjust the three time parameters for greylisting; see
.Sx GREYLISTING
below.
.Ar passtime
defaults to 25 (minutes),
.Ar greyexp
to 4 (hours),
and
.Ar whiteexp
to 864 (hours, approximately 36 days).
.It Fl b
Turn off Greylisting mode, and run only as a blacklister. see
.Sx GREYLISTING
below.
.It Fl h Ar hostname
The hostname that is reported in the SMTP banner.
.It Fl n Ar name
The SMTP version banner that is reported upon initial connection.
.It 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 .
.It Fl r Ar reply
For blacklisted entries, the SMTP error to return to the spammer,
e.g. 450, 451, 550.
This defaults to 450.
.It Fl S Ar secs
Stutter at greylisted connections for the specified amount
of seconds, after which the connection is not stuttered at.
Defaults to 10.
.It Fl s Ar secs
Delay each character sent to the client by the specified
amount of seconds.
Defaults to 1.
.It 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.
.It Fl w Ar window
Set the socket receive buffer to this many bytes, adjusting the window size.
.El
.Pp
.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.
.Pp
.Nm
can be enabled in
.Xr rc.conf.local 8 .
It should be used in conjunction with
.Xr spamd-setup 8 ,
which reads
.Xr spamd.conf 5 ,
processes a list of spammers' addresses, and applies appropriate
.Xr pf 4
.Em rdr
rules.
.Xr spamd-setup 8
should be run periodically via
.Xr cron 8 .
Use
.Xr crontab 1
to uncomment the entry in root's crontab.
.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.
.Bd -literal -offset 4n
table <spamd> persist
rdr pass inet proto tcp from <spamd> to any \e
    port smtp -> 127.0.0.1 port spamd
.Ed
.Pp
Any addresses in table
.Em <spamd>
are then redirected to
.Nm .
Addresses can be loaded into the
.Em table ,
like:
.Bd -literal -offset 4n
# pfctl -q -t spamd -T replace -f /usr/local/share/spammers
.Ed
.Pp
.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
.Nm
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 (;):
.Bd -literal -offset indent
tag;"rejection message";aaa.bbb.ccc.ddd/mm;aaa.bbb.ccc.ddd/mm
.Ed
.Pp
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
(though see the
.Fl S
option above)
or delayed,
and will receive the pleasantly innocuous temporary failure of:
.Bd -literal -offset 4n
451 Temporary failure, please try again later.
.Ed
.Pp
in the SMTP dialogue immediately after the recipient is specified.
.Nm
will use the db file in
.Pa /var/db/spamd
to track these non-blacklisted connections to
.Nm
by connecting IP address, HELO/EHLO, envelope-from, and envelope-to,
or "tuple" for
short.
.Pp
A previously unseen tuple is added to the
.Pa /var/db/spamd
database, recording the time an initial connection attempt was seen.
After
.Em passtime
minutes 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
.Pa /var/db/spamd .
.Pp
.Nm
regularly scans the
.Pa /var/db/spamd
database and configures all whitelist addresses as the
.Em spamd-white
.Xr pf 4
table.
The
.Em spamd-white
table
.Em must
be used to allow connections to pass to the
real MTA as in the following
.Xr pf.conf 5
example:
.Bd -literal -offset 4n
table <spamd-white> persist
no rdr inet proto tcp from <spamd-white> to any \e
    port smtp
rdr pass inet proto tcp from any to any \e
    port smtp -> 127.0.0.1 port spamd
.Ed
.Pp
Connections from addresses not listed in the
.Em spamd-white
.Xr pf 4
table are redirected to
.Nm .
If an address matches a blacklist specified in
.Pa /etc/mail/spamd.conf ,
the connection will be stuttered at by
.Nm .
All other connections will be considered for greylisting and
eventual whitelisting (by addition to the
.Em spamd-white
table so they are not redirected in the future) if they retry mail delivery.
Note that when greylisting we do not need the
.Em spamd
.Xr pf 4
table since all connections are passed to
.Nm
unless the source address is listed in the
.Em spamd-white
table.
.Pp
.Nm
removes tuple entries from the
.Pa /var/db/spamd
database if delivery has not been retried within
.Em greyexp
hours from the initial time a connection is seen.
The default is 4 hours as this is the most common setting after which
MTAs will give up attempting to retry delivery of a message.
.Pp
.Nm
removes whitelist entries from the
.Pa /var/db/spamd
database if no mail delivery activity has been seen from the
whitelisted address by
.Xr spamlogd 8
within
.Em whiteexp
hours 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.
.Pp
.Xr spamd-setup 8
should be run with the
.Fl g
flag when operating in greylisting mode.
.Pp
.Xr spamlogd 8
should be used to update the whitelist entries in
.Pa /var/db/spamd
when connections are seen to pass to the real MTA on the
.Em smtp
port.
.Pp
.Xr spamdb 8
can be used to examine and alter the contents of
.Pa /var/db/spamd .
See
.Xr spamdb 8
for further information.
.Sh GREYTRAPPING
When greylisting with
.Nm
it may be useful to define
.Em spamtrap
destination addresses to catch spammers as they send mail from greylisted
hosts.
Such
.Em spamtrap
addresses affect only greylisted connections to
.Nm
and are used to temporarily blacklist a host that is obviously sending spam.
Unused email addresses or email addresses on spammers' lists are very
useful for this.
When a host that is currently greylisted attempts to send mail to a
.Em spamtrap
address, it is blacklisted for 24 hours by adding the host to the
.Nm
blacklist
.Em spamd-greytrap .
Spamtrap addresses are added to the
.Pa /var/db/spamd
database with the following
.Xr spamdb 8
command:
.Pp
.Dl # spamdb -T -a 'spamtrap@mydomain.org'
.Pp
See
.Xr spamdb 8
for further details.
.Pp
The file
.Pa /etc/mail/spamd.alloweddomains
can be used to specify a list of domainname suffixes, one per line, one of
which must match each destination email address in the greylist.
Any destination address which does not match one of the suffixes listed in
.Pa /etc/mail/spamd.alloweddomains
will be trapped, exactly as if it were sent to a
.Em spamtrap
address above.
.Pp
For example, if
.Pa /etc/mail/spamd.alloweddomains
contains:
.Bd -literal -offset 4n
@humpingforjesus.com
obtuse.com
.Ed
.Pp
the destination addresses
.Em beardedclams@humpingforjesus.com ,
.Em beck@obtuse.com ,
and
.Em beck@snouts.obtuse.com
would not cause the sending host to be trapped.
However the addresses
.Em peter@apostles.humpingforjesus.com
or
.Em bigbutts@bofh.ucs.ualberta.ca
would cause the sending host to be trapped.
.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:
.Bd -literal -offset indent
!spamd
daemon.err;daemon.warn;daemon.info	/var/log/spamd
.Ed
.Sh FILES
.Bl -tag -width "/etc/mail/spamd.alloweddomainsXX" -compact
.It /etc/mail/spamd.conf
Default configuration file.
.It /etc/mail/spamd.alloweddomains
Optional required suffixes for greytrapping.
.It /var/db/spamd
Greylisting database.
.El
.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 first appeared in
.Ox 3.3 .
.Pp
Previous versions of
.Nm
required traps to be be entered into the database including the enclosing
\*(Lt\*(Gt characters;
current versions expect only the email address without the enclosing
\*(Lt\*(Gt characters.
.Sh BUGS
.Nm
currently uses the user
.Dq _spamd
outside a chroot jail when running in greylisting mode, and requires
the greylisting database in
.Pa /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.