initial shot at making greylisting seem normal...

1 files changed, 131 insertions, 148 deletions

diff --git a/libexec/spamd/spamd.8 b/libexec/spamd/spamd.8
index 39fb5903b6c..a8723a4ddb7 100644
--- a/libexec/spamd/spamd.8
+++ b/libexec/spamd/spamd.8
@@ -1,4 +1,4 @@
-.\"	$OpenBSD: spamd.8,v 1.74 2007/02/27 14:52:31 jmc Exp $
+.\"	$OpenBSD: spamd.8,v 1.75 2007/02/27 15:38:27 jmc Exp $
 .\"
 .\" Copyright (c) 2002 Theo de Raadt.  All rights reserved.
 .\"
@@ -49,10 +49,36 @@
 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.
+.\"It 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.
+It is designed to be very efficient so that it does not slow down the
+receiving machine.
+.Pp
+In its default mode of operation,
+.Nm
+will initially
+.Em greylist
+a connection,
+giving the connecting machine a temporary failure message
+and requesting it try again later.
+Any such machine retrying after a predefined amount of time
+will be put in a
+.Em whitelist ,
+allowing it to bypass such checks in the future.
+.Pp
+.Nm
+can also run in
+.Em blacklist
+mode,
+either in addition to or instead of greylisting mode.
+In this mode,
+spam is never accepted,
+but always rejected with either a 450 or 550 error message.
+See
+.Sx BLACKLISTING
+below for more information.
 .Pp
 The options are as follows:
 .Bl -tag -width Ds
@@ -68,9 +94,9 @@ The default is
 .Ar maxcon
 \- 100.
 .It Fl b
-Turn off Greylisting mode, and run only as a blacklister.
+Turn off greylisting mode, and run only as a blacklister.
 See
-.Sx GREYLISTING
+.Sx BLACKLISTING
 below.
 .It Fl c Ar maxcon
 The maximum number of concurrent connections to allow.
@@ -83,9 +109,8 @@ 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.
+Adjust the three time parameters for greylisting;
+see below.
 .Ar passtime
 defaults to 25 (minutes),
 .Ar greyexp
@@ -144,139 +169,22 @@ level.
 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:
+connections 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.
+This happens 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
+to track these connections to
 .Nm
-by connecting IP address, HELO/EHLO, envelope-from, and envelope-to,
-or "tuple" for
-short.
+by connecting IP address, HELO/EHLO, envelope-from, and envelope-to, or
+.Em tuple
+for short.
 .Pp
 A previously unseen tuple is added to the
 .Pa /var/db/spamd
@@ -319,22 +227,10 @@ Connections from addresses not listed in the
 .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
+Connections are 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
@@ -361,7 +257,10 @@ monthly mailing list digests without greylist delays every time.
 .Xr spamd-setup 8
 should be run with the
 .Fl g
-flag when operating in greylisting mode.
+flag.
+Use
+.Xr crontab 1
+to uncomment the entry in root's crontab.
 .Pp
 .Xr spamlogd 8
 should be used to update the whitelist entries in
@@ -437,6 +336,90 @@ However the addresses
 or
 .Em bigbutts@bofh.ucs.ualberta.ca
 would cause the sending host to be trapped.
+.Sh BLACKLISTING
+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
+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 LOGGING
 .Nm
 sends log messages to