Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
SPAMD(8)		  BSD System Manager's Manual		      SPAMD(8)

     spamd -- spam deferral daemon

     spamd [-45bdv] [-B	maxblack] [-c maxcon] [-G passtime:greyexp:whiteexp]
	   [-h hostname] [-l address] [-M address] [-n name] [-p port]
	   [-S secs] [-s secs] [-w window] [-Y synctarget] [-y synclisten]
	   [-m mode] [-t table_number]

     spamd is a	fake sendmail(8)-like daemon which rejects false mail.	It is
     designed to be very efficient so that it does not slow down the receiving

     spamd considers sending hosts to be of three types:

     blacklisted hosts are redirected 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 sendmail(8).

     greylisted	hosts are redirected 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 con-
     sult 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

     The options are as	follows:

     -4	     For blacklisted entries, return error code	450 to the spammer

     -5	     For blacklisted entries, return error code	550 to the spammer.

     -B	maxblack
	     The maximum number	of concurrent blacklisted connections to stut-
	     ter 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	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 de-
	     faults 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.

     -l	address
	     Specify the local address to which	spamd is to bind(2).  By de-
	     fault spamd listens on all	local addresses.

     -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 redirected SMTP connections on.	The default
	     port is found by looking for the named service "spamd" using

     -S	secs
	     Stutter at	greylisted connections for the specified amount	of
	     seconds, after which the connection is not	stuttered at.  The de-
	     fault 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, dis-
	     connections 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

     -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	If the multicast TTL is	not specified,
	     a default value of	1 is used.  This option	can be specified mul-
	     tiple times.  See also SYNCHRONISATION below.

     -y	synclisten
	     Listen on synclisten for incoming synchronisation messages.  The
	     format for	synclisten is the same as for synctarget, above.  This
	     option can	be specified only once.	 See also SYNCHRONISATION be-

     -m	mode
	     Firewall type. Can	be pf (default)	or ipfw.

     -t	table_number
	     IPFW table	number.	Use only with [-m ipfw].

     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, en-
     velope-from, and envelope-to, or tuple for	short.

     A previously unseen tuple is added	to the /var/db/spamd database, record-
     ing the time an initial connection	attempt	was seen.  After passtime min-
     utes 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 connec-
     tions to pass to the real MTA.  Any addresses not found in	<spamd-white>
     are redirected to spamd.  The following pf.conf(5)	example	is suggested:

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

     spamd removes tuple entries from the /var/db/spamd	database if delivery
     has not been retried within greyexp hours from the	initial	time a connec-
     tion 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	black-
     list-only mode, the -b flag should	be specified.  Use crontab(1) to un-
     comment 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 dedi-
     cated file:

	   daemon.err;daemon.warn;	   /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.

     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>.	Spam-
     trap addresses are	added to the /var/db/spamd database with the following
     spamdb(8) command:

	   # spamdb -T -a ''

     See spamdb(8) for further details.

     The file /usr/local/etc/spamd/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:

     The following destination addresses would not cause the sending host to
     be	trapped:

     However the following addresses would cause the sending host to be

     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 tu-
     ples when connecting to this address; only	existing entries may be	up-
     dated.  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	an-
     other 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.

     When running in default mode, the pf.conf(5) rules	described above	are
     sufficient.  However when running in blacklist-only mode, a slightly mod-
     ified pf.conf(5) ruleset is required, redirecting any addresses found in
     the <spamd> table to spamd.  Any other addresses are passed to the	real

	 table <spamd> persist
	 rdr pass inet proto tcp from <spamd> to any \
	     port smtp -> 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 black-
     lists, 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.

     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 in-
     formation,	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.

     spamd supports realtime synchronisation of	spamd databases	between	a num-
     ber of spamd daemons running on multiple machines,	using the -Y and -y
     options.  The databases are synchronised for greylisted and trapped en-
     tries; whitelisted	entries	are not	updated.

     The following example will	accept incoming	multicast and unicast synchro-
     nisation messages,	and send outgoing multicast messages through the net-
     work interface em0:

	   # /usr/local/libexec/spamd -y em0 -Y	em0

     The second	example	will increase the multicast TTL	to a value of 2, add
     the unicast targets and, and accept
     incoming unicast messages sent to only.

	   # /usr/local/libexec/spamd -y -Y em0:2	\
		   -Y	-Y

     If	the file /usr/local/etc/spamd/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=/usr/local/etc/spamd/spamd.key bs=2048 count=1

     The file spamd.key	needs to be copied to all hosts	sending	or receiving
     synchronisation messages.

     /usr/local/etc/spamd/spamd.alloweddomains	  Required suffixes for	grey-
     /usr/local/etc/spamd/spamd.conf		  Default configuration	file.
     /usr/local/etc/spamd/spamd.key		  Authentication key for syn-
						  chronisation messages.
     /var/db/spamd				  Greylisting database.

     pf.conf(5), services(5), spamd.conf(5), syslog.conf(5), pfctl(8),
     spamd-setup(8), spamdb(8),	spamlogd(8), syslogd(8)

     The spamd command first appeared in OpenBSD 3.3.

     Previous versions of spamd	required traps to be entered into the database
     including the enclosing <>	characters; current versions expect only the
     email address without the enclosing <> characters.

     Blacklisted hosts are no longer stored in the <spamd> table when operat-
     ing in default mode for performance reasons.

     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.

BSD				 April 20 2009				   BSD


Want to link to this manual page? Use this URL:

home | help