NAME
spamd
—
spam deferral daemon
SYNOPSIS
spamd |
[-45bdv ]
[-B maxblack]
[-C file]
[-c maxcon]
[-G passtime:greyexp:whiteexp]
[-h hostname]
[-K file]
[-l address]
[-M address]
[-n name]
[-p port]
[-S secs]
[-s secs]
[-w window]
[-Y synctarget]
[-y synclisten] |
DESCRIPTION
spamd
is a fake mail daemon which rejects
false mail. It is designed to be very efficient so that it does not slow
down the receiving machine.
spamd
considers sending hosts to be of
three types:
blacklisted
hosts are diverted to spamd
and
tarpitted
i.e. they are communicated with very slowly to consume the sender's
resources. Mail is rejected with either a 450 or 550 error message. A
blacklisted host will not be allowed to talk to a real mail server.
whitelisted
hosts do not talk to spamd
. Their connections are
instead sent to a real mail server, such as
smtpd(8).
greylisted
hosts are diverted to spamd
, but
spamd
has not yet decided if they are likely
spammers. They are given a temporary failure message by
spamd
when they try to deliver mail.
When spamd
is run in default mode, it will
greylist connections from new hosts. Depending on its configuration, it may
choose to blacklist the host or, if the checks described below are met,
eventually whitelist it. When spamd
is run in
blacklist-only mode, using the -b
flag, it will
consult a pre-defined set of blacklist addresses to decide whether to tarpit
the host or not.
When a sending host talks to
spamd
, the reply will be
stuttered. That
is, the response will be sent back a character at a time, slowly. For
blacklisted hosts, the entire dialogue is stuttered. For greylisted hosts,
the default is to stutter for the first 10 seconds of dialogue only.
The options are as follows:
-4
- For blacklisted entries, return error code 450 to the spammer (default).
-5
- For blacklisted entries, return error code 550 to the spammer.
-B
maxblack- The maximum number of concurrent blacklisted connections to stutter at. This value may not be greater than maxcon (see below). The default is maxcon - 100. When this value is exceeded, new blacklisted connections will not be stuttered at.
-b
- Run in blacklist-only mode.
-C
file- Load the certificate for TLS from the given file.
-c
maxcon- The maximum number of concurrent connections to allow. maxcon may not exceed kern.maxfiles - 200, and defaults to 800.
-d
- Debug mode.
spamd
does not fork(2) into the background. -G
passtime:greyexp:whiteexp- Adjust the three time parameters for greylisting. passtime defaults to 25 (minutes), greyexp to 4 (hours), and whiteexp to 864 (hours, approximately 36 days).
-h
hostname- The hostname that is reported in the SMTP banner.
-K
file- Load the private key for TLS from the given file.
-l
address- Specify the local address to which
spamd
is to bind(2). By defaultspamd
listens on the localhost address 127.0.0.1. -M
address- Specify a local IP address which is listed as a low priority MX record, used to identify and trap hosts that connect to MX hosts out of order. See GREYTRAPPING below for details.
-n
name- The SMTP version banner that is reported upon initial connection.
-p
port- Specify a different port number from the default port that
spamd
should listen for diverted SMTP connections on. The default port is found by looking for the named service “spamd” using getservbyname(3). -S
secs- Stutter at greylisted connections for the specified amount of seconds, after which the connection is not stuttered at. The default is 10; maximum is 90.
-s
secs- Delay each character sent to the client by the specified amount of seconds. The default is 1; maximum is 10.
-v
- Enable verbose logging. By default
spamd
logs connections, disconnections and blacklist matches to syslogd(8) atLOG_INFO
level. With verbose logging enabled, message detail including subject and recipient information is logged atLOG_INFO
, along with the message body and SMTP dialogue being logged atLOG_DEBUG
level. -w
window- Set the socket receive buffer to this many bytes, adjusting the window size.
-Y
synctarget- Add target synctarget to receive synchronisation messages. synctarget can be either an IPv4 address for unicast messages or a network interface and optional TTL value for multicast messages to the group 224.0.1.240. If the multicast TTL is not specified, a default value of 1 is used. This option can be specified multiple times. See also SYNCHRONISATION below.
-y
synclisten- Listen on synclisten network interface for incoming synchronisation messages. This option can be specified only once. See also SYNCHRONISATION below.
When run in default mode, connections receive the pleasantly innocuous temporary failure of:
451 Temporary failure, please try again later.
This happens in the SMTP dialogue immediately after the
DATA command is received from the client. spamd
will
use the db file in /var/db/spamd to track these
connections to spamd
by connecting IP address,
HELO/EHLO, envelope-from, and envelope-to, or
tuple for
short.
A previously unseen tuple is added to the
/var/db/spamd database, recording the time an
initial connection attempt was seen. After
passtime minutes
if spamd
sees a retried attempt to deliver mail for
the same tuple, spamd
will whitelist the connecting
address by adding it as a whitelist entry to
/var/db/spamd.
spamd
regularly scans the
/var/db/spamd database and configures all whitelist
addresses as the pf(4) <spamd-white> table, allowing connections to pass
to the real MTA. Any addresses not found in <spamd-white> are diverted
to spamd
.
An example
pf.conf(5) fragment is given below. In the example, the file
/etc/mail/nospamd contains addresses of hosts who
should be passed directly to the SMTP agent (thus bypassing
spamd
).
table <spamd-white> persist table <nospamd> persist file "/etc/mail/nospamd" pass in on egress proto tcp from any to any port smtp \ divert-to 127.0.0.1 port spamd pass in on egress proto tcp from <nospamd> to any port smtp pass in log on egress proto tcp from <spamd-white> to any port smtp pass out log on egress proto tcp to any port smtp
spamd
removes tuple entries
from the /var/db/spamd database if delivery has not
been retried within
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.
spamd
removes whitelist
entries from the /var/db/spamd database if no mail
delivery activity has been seen from the whitelisted address by
spamlogd(8) within
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.
spamd-setup(8) should be run periodically by
cron(8). When run in blacklist-only mode, the
-b
flag should be specified. Use
crontab(1) to uncomment the entry in root's crontab.
spamlogd(8) should be used to update the whitelist entries in /var/db/spamd when connections are seen to pass to the real MTA on the smtp port.
spamdb(8) can be used to examine and alter the contents of /var/db/spamd. See spamdb(8) for further information.
spamd
sends log messages to
syslogd(8) using
facility daemon
and, with increasing verbosity,
level
err, warn, info, and debug. The following
syslog.conf(5) section can be used to log connection details
to a dedicated file:
!spamd daemon.info /var/log/spamd
A typical entry shows the time of the connection and the IP
address of the connecting host. When a host connects, the total number of
active connections and the number of connections from blacklisted hosts is
shown (connected (xx/xx)). When a host disconnects, the amount of time spent
talking to spamd
is shown.
GREYTRAPPING
When running spamd
in default mode, it may
be useful to define
spamtrap
destination addresses to catch spammers as they send mail from greylisted
hosts. Such spamtrap addresses affect only greylisted connections to
spamd
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 spamtrap address, it is blacklisted
for 24 hours by adding the host to the spamd
blacklist <spamd-greytrap>. Spamtrap addresses are added to the
/var/db/spamd database with the following
spamdb(8) command:
# spamdb -T -a
'spamtrap@mydomain.org'
See spamdb(8) for further details.
The file /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 spamd.alloweddomains will be trapped, exactly as if it were sent to a spamtrap address. Comment lines beginning with ‘#’ and empty lines are ignored.
For example, if spamd.alloweddomains contains:
@humpingforjesus.com obtuse.com
The following destination addresses would not cause the sending host to be trapped:
beardedclams@humpingforjesus.com beck@obtuse.com beck@snouts.obtuse.com
However the following addresses would cause the sending host to be trapped:
peter@apostles.humpingforjesus.com bigbutts@bofh.ucs.ualberta.ca
A low priority MX IP address may be specified with the
-M
option. When spamd
has
such an address specified, no host may enter new greylist tuples when
connecting to this address; only existing entries may be updated. Any host
attempting to make new deliveries to the low priority MX for which a tuple
has not previously been seen will be trapped.
Note that it is important to ensure that a host running
spamd
with the low priority MX address active must
see all the greylist changes for a higher priority MX host for the same
domains. This is best done by the host itself receiving the connections to
the higher priority MX on another IP address (which may be an IP alias).
This will ensure that hosts are not trapped erroneously if the higher
priority MX is unavailable. For example, on a host which is an existing MX
record for a domain of value 10, a second IP address with MX of value 99 (a
higher number, and therefore lower priority) would ensure that any RFC
conformant client would attempt delivery to the IP address with the MX value
of 10 first, and should not attempt to deliver to the address with MX value
99.
BLACKLIST-ONLY MODE
When running in default mode, the
pf.conf(5) rules described above are sufficient. However when running
in blacklist-only mode, a slightly modified
pf.conf(5) ruleset is required, diverting any addresses found in the
<spamd> table to spamd
. Any other addresses
are passed to the real MTA.
table <spamd> persist pass in on egress inet proto tcp from <spamd> to any port smtp \ divert-to 127.0.0.1 port spamd
Addresses can be loaded into the table, like:
# pfctl -q -t spamd -T replace -f /usr/local/share/spammers
spamd-setup(8) can also be used to load addresses into the
<spamd> table. It has the added benefit of being able to remove
addresses from blacklists, and will connect to spamd
over a localhost socket, giving spamd
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.
CONFIGURATION CONNECTIONS
spamd
listens for configuration
connections on the port identified by the named service
“spamd-cfg” (see
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 (;):
tag;"rejection message";aaa.bbb.ccc.ddd/mm;aaa.bbb.ccc.ddd/mm
The rejection message must be inside double quotes. A \" will
produce a double quote in the output. \n 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. \\ will produce a single \.
spamd
will reject mail by displaying all the
messages from all blacklists in which a connecting address is matched.
spamd-setup(8) is normally used to configure this
information.
SYNCHRONISATION
spamd
supports realtime synchronisation of
spamd databases between a number of spamd daemons running on multiple
machines, using the -Y
and
-y
options. The databases are synchronised for
greylisted and trapped entries; whitelisted entries and entries made
manually using
spamdb(8) are not updated.
The following example will accept incoming multicast and unicast synchronisation messages, and send outgoing multicast messages through the network interface em0:
# /usr/libexec/spamd -y em0 -Y em0
The second example will increase the multicast TTL to a value of 2, add the unicast targets foo.somewhere.org and bar.somewhere.org, and accept incoming unicast messages received on bge0 only.
# /usr/libexec/spamd -y bge0 -Y em0:2 \ -Y foo.somewhere.org -Y bar.somewhere.org
If the file /etc/mail/spamd.key exists,
spamd
will calculate the message-digest fingerprint
(checksum) for the file and use it as a shared key to authenticate the
synchronisation messages. The file itself can contain any data. For example,
to create a secure random key:
# dd if=/dev/random of=/etc/mail/spamd.key bs=2048 count=1
The file needs to be copied to all hosts sending or receiving synchronisation messages.
FILES
- /etc/mail/spamd.alloweddomains
- Required suffixes for greytrapping.
- /etc/mail/spamd.conf
- Default configuration file.
- /etc/mail/spamd.key
- Authentication key for synchronisation messages.
- /var/db/spamd
- Greylisting database.
SEE ALSO
pf.conf(5), services(5), spamd.conf(5), syslog.conf(5), pfctl(8), spamd-setup(8), spamdb(8), spamlogd(8), syslogd(8)
HISTORY
The spamd
command first appeared in
OpenBSD 3.3.
BUGS
spamd
currently uses the user
“_spamd” outside a chroot jail when running in default mode,
and requires the greylisting database in
/var/db/spamd to be owned by the
“_spamd” user. This is wrong and should change to a distinct
user from the one used by the chrooted spamd
process.