SPAMD(8)

NAME
spamd - spam deferral daemon

SYNOPSIS
spamd [-45dgv] [-B maxblack] [-b address] [-c maxcon] [-G passtime:greyexp:whiteexp] [-n name] [-p port] [-r reply] [-S secs] [-s secs] [-w window]

DESCRIPTION
spamd is a fake sendmail(8)-like daemon which rejects false mail. If the 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.

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 allow in greylisting mode. This value may not be greater than maxcon (see below). The default is maxcon - 100.

-b address
    Specify the local address to which spamd is to bind(2). By default spamd listens on all local addresses.

-c maxcon
    The maximum number of concurrent connections to allow. The default is 800.

-d  Debug mode. spamd does not fork(2) into the background.

-G passtime:greyexp:whiteexp
    Adjust the three time parameters for greylisting; see GREYLISTING below. passtime defaults to 25 (minutes), greyexp to 4 (hours), and whiteexp to 864 (hours, approximately 36 days).

-g  Greylisting mode; see GREYLISTING below.

-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 redirected SMTP connections on. The default port is found by looking for the named service spamd using getservbyname(3). If that port (and spamd-cfg) is not defined, an error will result, and one should simply add them.

-r reply
    The SMTP error to return to the spammer, i.e. 450, 451, 550. This defaults to 450.

-S secs
    Stutter at greylisted connections for the specified amount of seconds, after which the connection is not stuttered at. Defaults to 10.

-s secs
    Delay each character sent to the client by the specified amount of seconds. Defaults to 1.

-v  Enable verbose logging. By default spamd logs connections, disconnections and blacklist matches to syslogd(8) at LOG_INFO level. With verbose logging enabled, message detail including subject and recipient information is logged at LOG_INFO, along with the message body and SMTP dialogue being logged at LOG_DEBUG level.

-w window
    Set the socket receive buffer to this many bytes, adjusting the window size.

spamd 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, spamd takes neither of these actions: it rejects the mail back to the senders' queue.

spamd can be enabled in rc.conf.local(8). It should be used in conjunction with spamd-setup(8), which reads spamd.conf(5), processes a list of spammers' addresses, and applies appropriate pf(4) rdr rules. spamd-setup(8) should be run periodically via cron(8). Use crontab(1) to uncomment the entry in root's crontab.

REDIRECTING SMTP CONNECTIONS
With pf(4), connections to port 25 (SMTP) can be redirected to another host or port, based on the source address of the sender. The rdr rules used for this purpose are described in pf.conf(5). The rules can be loaded into a table to simplify handling.

    table <spamd> persist
    rdr pass inet proto tcp from <spamd> to any \
        port smtp -> 127.0.0.1 port spamd

Any addresses in table <spamd> are then redirected to 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. spamd-setup(8) also 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.

GREYLISTING
When run in greylisting mode, spamd will run in the normal mode for any addresses blacklisted by spamd-setup(8). Connections from addresses not blacklisted by spamd-setup(8) will be considered for greylisting. Such connections will not be stuttered at (though see the -S option above) or delayed, and will receive the pleasantly innocuous temporary failure of:

    451 Temporary failure, please try again later.

in the SMTP dialogue immediately after the recipient is specified. spamd will use the db file in /var/db/spamd to track these non-blacklisted connections to spamd by connecting IP address, 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 spamd-white pf(4) table. The spamd-white table must be used to allow connections to pass to the real MTA as in the following pf.conf(5) example:

    table <spamd> persist
    table <spamd-white> persist
    rdr pass inet proto tcp from <spamd> to any \
        port smtp -> 127.0.0.1 port spamd
    rdr pass inet proto tcp from !<spamd-white> to any \
        port smtp -> 127.0.0.1 port spamd

With this configuration, spamd-setup(8) should be used to configure blacklists in spamd and add them to the spamd pf(4) table. These connections will be stuttered at by spamd. All other connections not in the spamd-white table are redirected to spamd but will not be stuttered at. Such connections will be considered for greylisting and eventual whitelisting (by addition to the spamd-white table so they are not redirected) if they retry mail delivery.

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.

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/spamdb. See spamdb(8) for further information.

GREYTRAPPING
When greylisting with spamd 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>"

It should be entered exactly, as the address will be used in the SMTP dialogue. See spamdb(8) for further details.

LOGGING
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.err;daemon.warn;daemon.info	/var/log/spamd

FILES
/etc/spamd.conf
    Default configuration file.
/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 appeared in OpenBSD 3.3.

BUGS
spamd currently uses the user “_spamd” outside a chroot jail when running in greylisting 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.