greylistd(8)

1greylistd(8)                  Mail Administration                 greylistd(8)
2
3
4

NAME

6       greylistd - simple greylisting system for mail transport agents
7

SYNOPSIS

9       greylistd
10

DESCRIPTION

12   Greylisting
13       This  daemon  provides a simple greylisting implementation for use with
14       Exim and other mail transport agents  (MTAs).   For  a  more  elaborate
15       introduction  to  greylisting,  please refer to Evan Harris' whitepaper
16       at:      http://projects.puremagic.com/greylisting/
17
18       Greylisting is a simple but highly effective means to weed out messages
19       that  are  being  delivered via spamware/ratware tools.  The idea is to
20       establish whether a prior relationship exists between  the  sender  and
21       the  receiver of a message.  Most of the time it does, and the delivery
22       proceeds normally.
23
24       On the other hand, if no prior relationship  exists,  the  delivery  is
25       temporarily  rejected, using a 451 SMTP response.  Legitimate MTAs will
26       treat this response accordingly, and retry the delivery in a while.  In
27       contrast,  ratware  will usually fail to retry the delivery in a normal
28       fashion.
29
30       As a result, greylisting is currently more than 90% effective in block‐
31       ing incoming junk mail, while nearly all legitimate mail goes through.
32
33       Three pieces of information (herafter called a triplet) from the deliv‐
34       ery attempt are cached for future reference:
35
36         - The address of the host attempting the delivery
37         - The envelope sender address (MAIL FROM:)
38         - The envelope recipient address (RCPT TO:)
39
40       If a delivery attempt was temporarily rejected, then after  an  initial
41       timeout  (60 minutes by default), but before a retry expiration time (8
42       hours by default), new delivery attempts  with  the  same  triplet  are
43       accepted,  and  the  triplet  is added to a whitelist.  This allows for
44       delivery retries, presumably from legitimate  MTAs,  and  ensures  that
45       future mail from the same contact is not subject to greylisting.
46
47       If a whitelisted triplet has not been seen for an extended duration (by
48       default 60 days), it is expired.  This prevents unlimited growth of the
49       list.
50
51       The  downside  to  greylisting  is that legitimate mail from people who
52       have never sent you mail in the past (or, at least, within the last  60
53       days) are subject to a one-hour delay.
54
55       The  upside is that the current generation of ratware tools will not be
56       able to deliver spam or virii to you.  Even if, as a result of lots  of
57       sites incorporating the greylisting concept, ratware tools are modified
58       such that temporarily rejected deliveries are  retried,  you  stand  an
59       increased  chance  of  blocking  such mail.  That is because within the
60       mandatory 1-hour initial delay, chances are that the sending host's  IP
61       address  has  been  listed  in  one  or  more  DNS block lists (such as
62       bl.spamcop.net, cbl.abuseat.org, etc..), and can be  rejected  by  your
63       MTA  by consulting these lists directly, or via anti-spam software like
64       SpamAssassin.
65
66   greylistd
67       greylistd is meant to be installed on a server  that  accepts  incoming
68       mail.   The  MTA on this server connects to the greylistd daemon over a
69       UNIX domain socket (by default /var/run/greylistd/socket), or  alterna‐
70       tively via the command greylist(1), and submits a string (triplet) that
71       identifies a particular host/sender/recipient relationship.   greylistd
72       responds  "white",  "grey" or "black", depending on the current listing
73       status of the  provided  triplet.   Alternatively,  if  either  of  the
74       "--white",  "--grey",  or "--black" options precede the data, greylistd
75       responds "true" or "false", indicating whether the triplet is currently
76       in the corresponding state.
77

EXAMPLES

79   Exim 4
80       A  sample greylistd statement for Exim 4 is provided with this package,
81       and  can   normally   be   found   in   "/usr/share/doc/greylistd/exam‐
82       ples/exim4-acl-example.txt".
83
84
85   Others
86       What others?  :-)
87
88       A prerequisite to greylisting in general is the ability to perform cus‐
89       tom filtering throughout the various stages in  the  SMTP  transaction,
90       most   notably  after  the  RCPT  TO:  SMTP  command.   In  particular,
91       greylistd(8) can be invoked either over a UNIX domain socket or via the
92       supplied greylist(1) utility.
93
94       Although greylistd(8) is written mainly with Exim in mind, it should be
95       possible to use it with any MTA that:
96
97         -    Allows arbitrary strings to be  passed  on  via  a  UNIX  domain
98              socket  (/var/run/greylistd/socket) or supplied to external pro‐
99              grams (greylist(1)).
100
101         -    Can defer the incoming delivery, based on the response.
102
103       Some MTAs either have limited or no support for such  external  filters
104       in the SMTP transaction (e.g. Sendmail), or define a very custom inter‐
105       face for such filters (e.g. Postifx "Policy Servers").
106
107       That said, solutions exist for these other MTAs as well.  For  Postfix,
108       check  into  "postgrey",  and  for Sendmail there is "relaydelay".  For
109       other MTAs, check the links on Evan Harris' greylisting project page:
110
111           http://projects.puremagic.com/greylisting/links.html
112
113

FILES

115   /etc/greylistd/config
116       Configuration settings.  Currently, this file consists  of  three  sec‐
117       tions:
118
119       [timeout]
120           Lists  various  timeouts  used  to determine how long to keep a new
121           triplet greylisted, and when to expire previosly known triplets.
122
123       [socket]
124           Specifies path and permissions of the UNIX domain socket  on  which
125           greylistd will listen.
126
127       [data]
128           Specifies  the  paths  to the data files, containing the data items
129           and statistics, as well as an update interval specifying how  often
130           data will be written to these files.
131
132   /var/lib/greylistd/states
133       (default path, can be modified in the configuration file)
134
135       Runtime  data.   Theare are four sections: [white], [grey], [black] and
136       [statistics].  The first three sections consist of lines of the form:
137
138           hash = lastseen firstseen count
139
140       where:
141
142         - hash is a 32-bit value representing a given triplet,
143
144         - lastseen is a 32-bit  value  representing  the  timestamp  of  last
145           delivery attempt for this triplet,
146
147         - firstseen  is  a  32-bit  value representing the timestamp of first
148           known delivery attempt for this triplet,
149
150         - count is  a  32-bit  value  representing  the  number  of  delivery
151           attempts that have been made for this triplet in this time period.
152
153       The  [statistics]  section  contains  a  counter  for each of the three
154       lists, indicating how many items that has ever made its way into  these
155       lists by way of the update protocol.
156
157   /var/lib/greylistd/triplets
158       (default path, can be modified in the configuration file)
159
160       Unhashed data - i.e. the original triplets passed to greylistd.  Inter‐
161       nally, greylistd(8) hashes the provided data into a single 32-bit value
162       for  efficiency.   Prior  to  version  0.6,  the  original data was not
163       retained; as of version 0.6, data is optionally saved into this file.
164
165       Data items are saved in the form:
166           hash = data ...
167
168   /var/run/greylistd/socket
169       (default path, can be modified in the configuration file)
170
171       The UNIX domain socket providing the  main  interface  to  "greylistd".
172       The MTA can either connect to this socket directly, or use the supplied
173       "greylist" utility to do so.
174

BUGS

176       Because triplets and timestamps are hashed into simple  32-bit  values,
177       there  is  a  very  slim  chance  that deliveries that should have been
178       greylisted are allowed through.  More so for very busy sites.
179
180       Commands are actually  executed  in  the  daemon,  not  the  "greylist"
181       client.  If the user who invokes "greylist" interactively has a differ‐
182       ent time zone than the daemon process, time and date representations in
183       the output will reflect those of the daemon.
184

AUTHOR

186       This  python  script and manual page is written by Tor Slettnes, origi‐
187       nally for Debian GNU/Linux.
188

COPYRIGHT

190       Copyright © 2004-2005 Tor Slettnes.
191
192       This program is free software; you can redistribute it and/or modify it
193       under  the  terms of the GNU General Public License as published by the
194       Free Software Foundation; either version 2 of the License, or (at  your
195       option) any later version.
196
197       This  program  is  distributed  in the hope that it will be useful, but
198       WITHOUT ANY  WARRANTY;  without  even  the  implied  warranty  of  MER‐
199       CHANTABILITY  or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General
200       Public License for more details.
201
202       On a Debian GNU/Linux system, the full text of the GPL is available  in
203       /usr/share/common-licenses/GPL.  It is also available at:
204
205           http://www.gnu.org/licenses/gpl.html
206