1
PPoossttffiixx SSMMTTPP AAcccceessss PPoolliiccyy DDeelleeggaattiioonn
3
-------------------------------------------------------------------------------
5
PPuurrppoossee ooff PPoossttffiixx SSMMTTPP aacccceessss ppoolliiccyy ddeelleeggaattiioonn
7
The Postfix SMTP server has a number of built-in mechanisms to block or accept
8
mail at specific SMTP protocol stages. As of version 2.1, Postfix can delegate
9
policy decisions to an external server that runs outside Postfix.
11
With this policy delegation mechanism, a simple greylist policy can be
12
implemented with only a dozen lines of Perl, as is shown at the end of this
13
document. Another example of policy delegation is the SPF policy server by Meng
14
Wong at http://spf.pobox.com/. Examples of both policies can be found in the
15
Postfix source code, in the directory examples/smtpd-policy.
17
Policy delegation is now the preferred method for adding policies to Postfix.
18
It's much easier to develop a new feature in few lines of Perl, than trying to
19
do the same in C code. The difference in performance will be unnoticeable
20
except in the most demanding environments.
22
This document covers the following topics:
24
* Policy protocol description
25
* Policy client/server configuration
26
* Example: greylist policy server
27
* Greylisting mail from frequently forged domains
28
* Greylisting all your mail
29
* Routine greylist maintenance
30
* Example Perl greylist server
32
PPrroottooccooll ddeessccrriippttiioonn
34
The Postfix policy delegation protocol is really simple. The client request is
35
a sequence of name=value attributes separated by newline, and is terminated by
36
an empty line. The server reply is one name=value attribute and it, too, is
37
terminated by an empty line.
39
Here is an example of all the attributes that the Postfix SMTP server sends in
40
a delegated SMTPD access policy request:
42
request=smtpd_access_policy
45
helo_name=some.domain.tld
49
client_address=1.2.3.4
50
client_name=another.domain.tld
60
* The "request" attribute is required. In this example the request type is
61
"smtpd_access_policy".
63
* The order of the attributes does not matter. The policy server should
64
ignore any attributes that it does not care about.
66
* When the same attribute name is sent more than once, the server may keep
67
the first value or the last attribute value.
69
* When an attribute value is unavailable, the client either does not send the
70
attribute, or sends the attribute with an empty value ("name=").
72
* An attribute name must not contain "=", null or newline, and an attribute
73
value must not contain null or newline.
75
* The "instance" attribute value can be used to correlate different requests
76
regarding the same message delivery.
78
The following is specific to SMTPD delegated policy requests:
80
* Protocol names are ESMTP or SMTP.
82
* Protocol states are CONNECT, EHLO, HELO, MAIL, RCPT, DATA, VRFY or ETRN;
83
these are the SMTP protocol states where the Postfix SMTP server makes an
84
OK/REJECT/HOLD/etc. decision.
86
* The SASL attributes are sent only when SASL support is built into Postfix.
88
The policy server replies with any action that is allowed in a Postfix SMTPD
89
access(5) table. Example:
91
action=defer_if_permit Service temporarily unavailable
94
This causes the Postfix SMTP server to reject the request with a 450 temporary
95
error code and with text "Service temporarily unavailable", if the Postfix SMTP
96
server finds no reason to reject the request permanently.
98
In case of trouble the policy server must not send a reply. Instead the server
99
must log a warning and disconnect. Postfix will retry the request at some later
102
PPoolliiccyy cclliieenntt//sseerrvveerr ccoonnffiigguurraattiioonn
104
The Postfix delegated policy client can connect to a TCP socket or to a UNIX-
105
domain socket. Examples:
108
unix:/some/where/policy
111
The first example specifies that the policy server listens on a TCP socket at
112
127.0.0.1 port 9998. The second example specifies an absolute pathname of a
113
UNIX-domain socket. The third example specifies a pathname relative to the
114
Postfix queue directory; use this for policy servers that are spawned by the
115
Postfix master daemon.
117
To create a policy service that listens on a UNIX-domain socket called
118
"policy", and that runs under control of the Postfix spawn(8) daemon, you would
119
use something like this:
121
1 /etc/postfix/master.cf:
122
2 policy unix - n n - - spawn
123
3 user=nobody argv=/some/where/policy-server
125
5 /etc/postfix/main.cf:
126
6 smtpd_recipient_restrictions =
128
8 reject_unauth_destination
129
9 check_policy_service unix:private/policy
131
11 policy_time_limit = 3600
135
* Lines 2, 11: the Postfix spawn(8) daemon by default kills its child process
136
after 1000 seconds. This is too short for a policy daemon that may run for
137
as long as an SMTP client is connected to an SMTP server process. The
138
default time limit is overruled in main.cf with an explicit
139
"policy_time_limit" setting. The name of the parameter is the name of the
140
master.cf entry ("policy") concatenated with the "_time_limit" suffix.
142
* Lines 8, 9: always specify "check_policy_service" AFTER
143
"reject_unauth_destination" or else your system could become an open relay.
145
* Solaris UNIX-domain sockets do not work reliably. Use TCP sockets instead:
147
1 /etc/postfix/master.cf:
148
2 127.0.0.1:9998 inet n n n - - spawn
149
3 user=nobody argv=/some/where/policy-server
151
5 /etc/postfix/main.cf:
152
6 smtpd_recipient_restrictions =
154
8 reject_unauth_destination
155
9 check_policy_service inet:127.0.0.1:9998
157
11 127.0.0.1:9998_time_limit = 3600
159
Other configuration parameters that control the client side of the policy
162
* smtpd_policy_service_max_idle (default: 300s): The amount of time before
163
the Postfix SMTP server closes an unused policy client connection.
165
* smtpd_policy_service_max_ttl (default: 1000s): The amount of time before
166
the Postfix SMTP server closes an active policy client connection.
168
* smtpd_policy_service_timeout (default: 100s): The time limit to connect to,
169
send to or receive from a policy server.
171
EExxaammppllee:: ggrreeyylliisstt ppoolliiccyy sseerrvveerr
173
Greylisting is a defense against junk email that is described at http://
174
www.greylisting.org/. The idea was discussed on the postfix-users mailing list
175
one year before it was popularized.
177
The file examples/smtpd-policy/greylist.pl in the Postfix source tree
178
implements a simplified greylist policy server. This server stores a time stamp
179
for every (client, sender, recipient) triple. By default, mail is not accepted
180
until a time stamp is more than 60 seconds old. This stops junk mail with
181
randomly selected sender addresses, and mail that is sent through randomly
182
selected open proxies. It also stops junk mail from spammers that change their
183
IP address frequently.
185
Copy examples/smtpd-policy/greylist.pl to /usr/libexec/postfix or whatever
186
location is appropriate for your system.
188
In the greylist.pl Perl script you need to specify the location of the greylist
189
database file, and how long mail will be delayed before it is accepted. The
190
default settings are:
192
$database_name="/var/mta/greylist.db";
195
The /var/mta directory (or whatever you choose) should be writable by "nobody",
196
or by whatever username you configure below in master.cf for the policy
202
# chown nobody /var/mta
204
Note: DO NOT create the greylist database in a world-writable directory such as
205
/tmp or /var/tmp, and DO NOT create the greylist database in a file system that
206
may run out of space. Postfix can survive "out of space" conditions with the
207
mail queue and with the mailbox store, but it cannot survive a corrupted
208
greylist database. If the file becomes corrupted you may not be able to receive
209
mail at all until you delete the file by hand.
211
The greylist.pl Perl script can be run under control by the Postfix master
212
daemon. For example, to run the script as user "nobody", using a UNIX-domain
213
socket that is accessible by Postfix processes only:
215
1 /etc/postfix/master.cf:
216
2 policy unix - n n - - spawn
217
3 user=nobody argv=/usr/bin/perl /usr/libexec/postfix/greylist.pl
219
5 /etc/postfix/main.cf:
220
6 policy_time_limit = 3600
224
* Line 3: Specify "greylist.pl -v" for verbose logging of each request and
227
* Lines 2, 6: the Postfix spawn(8) daemon by default kills its child process
228
after 1000 seconds. This is too short for a policy daemon that may run for
229
as long as an SMTP client is connected to an SMTP server process. The
230
default time limit is overruled in main.cf with an explicit
231
"policy_time_limit" setting. The name of the parameter is the name of the
232
master.cf entry ("policy") concatenated with the "_time_limit" suffix.
234
On Solaris you must use inet: style sockets instead of unix: style, as detailed
235
in the "Policy client/server configuration" section above.
237
1 /etc/postfix/master.cf:
238
2 127.0.0.1:9998 inet n n n - - spawn
239
3 user=nobody argv=/usr/bin/perl /usr/libexec/postfix/greylist.pl
241
5 /etc/postfix/main.cf:
242
6 127.0.0.1:9998_time_limit = 3600
244
To invoke this service you would specify "check_policy_service inet:127.0.0.1:
247
GGrreeyylliissttiinngg mmaaiill ffrroomm ffrreeqquueennttllyy ffoorrggeedd ddoommaaiinnss
249
It is relatively safe to turn on greylisting for specific domains that often
250
appear in forged email. A list of frequently forged MAIL FROM domains can be
251
found at http://www.monkeys.com/anti-spam/filtering/sender-domain-validate.in.
253
1 /etc/postfix/main.cf:
254
2 smtpd_recipient_restrictions =
255
3 reject_unlisted_recipient
257
5 reject_unauth_destination
258
6 check_sender_access hash:/etc/postfix/sender_access
260
8 restriction_classes = greylist
261
9 greylist = check_policy_service unix:private/policy
263
11 /etc/postfix/sender_access:
265
13 hotmail.com greylist
266
14 bigfoot.com greylist
271
* Line 9: On Solaris you must use inet: style sockets instead of unix: style,
272
as detailed in the "Example: greylist policy server" section above.
274
* Line 6: Be sure to specify "check_sender_access" AFTER
275
"reject_unauth_destination" or else your system could become an open mail
278
* Line 3: With Postfix 2.0 snapshot releases, "reject_unlisted_recipient" is
279
called "check_recipient_maps". Postfix 2.1 understands both forms.
281
* Line 3: The greylist database gets polluted quickly with bogus addresses.
282
It helps if you protect greylist lookups with other restrictions that
283
reject unknown senders and/or recipients.
285
GGrreeyylliissttiinngg aallll yyoouurr mmaaiill
287
If you turn on greylisting for all mail you will almost certainly want to make
288
exceptions for mailing lists that use one-time sender addresses, because such
289
mailing lists can pollute your greylist database relatively quickly.
291
1 /etc/postfix/main.cf:
292
2 smtpd_recipient_restrictions =
293
3 reject_unlisted_recipient
295
5 reject_unauth_destination
296
6 check_sender_access hash:/etc/postfix/sender_access
297
7 check_policy_service unix:private/policy
300
10 /etc/postfix/sender_access:
301
11 securityfocus.com OK
306
* Line 7: On Solaris you must use inet: style sockets instead of unix: style,
307
as detailed in the "Example: greylist policy server" section above.
309
* Lines 6-7: Be sure to specify check_sender_access and check_policy_service
310
AFTER reject_unauth_destination or else your system could become an open
313
* Line 3: The greylist database gets polluted quickly with bogus addresses.
314
It helps if you precede greylist lookups with restrictions that reject
315
unknown senders and/or recipients.
317
RRoouuttiinnee ggrreeyylliisstt mmaaiinntteennaannccee
319
The greylist database grows over time, because the greylist server never
320
removes database entries. If left unattended, the greylist database will
321
eventually run your file system out of space.
323
When the status file size exceeds some threshold you can simply rename or
324
remove the file without adverse effects; Postfix automatically creates a new
325
file. In the worst case, new mail will be delayed by an hour or so. To lessen
326
the impact, rename or remove the file in the middle of the night at the
327
beginning of a weekend.
329
EExxaammppllee PPeerrll ggrreeyylliisstt sseerrvveerr
331
This is the Perl subroutine that implements the example greylist policy. It is
332
part of a general purpose sample policy server that is distributed with the
333
Postfix source as examples/smtpd-policy/greylist.pl.
336
# greylist status database and greylist time interval. DO NOT create the
337
# greylist status database in a world-writable directory such as /tmp
338
# or /var/tmp. DO NOT create the greylist database in a file system
339
# that can run out of space.
341
$database_name="/var/mta/greylist.db";
345
# Demo SMTPD access policy routine. The result is an action just like
346
# it would be specified on the right-hand side of a Postfix access
347
# table. Request attributes are available via the %attr hash.
349
sub smtpd_access_policy {
350
my($key, $time_stamp, $now);
352
# Open the database on the fly.
353
open_database() unless $database_obj;
355
# Lookup the time stamp for this client/sender/recipient.
357
lc $attr{"client_address"}."/".$attr{"sender"}."/".$attr{"recipient"};
358
$time_stamp = read_database($key);
361
# If new request, add this client/sender/recipient to the database.
362
if ($time_stamp == 0) {
364
update_database($key, $time_stamp);
367
# The result can be any action that is allowed in a Postfix access(5) map.
369
# To label the mail, return ``PREPEND headername: headertext''
371
# In case of success, return ``DUNNO'' instead of ``OK'', so that the
372
# check_policy_service restriction can be followed by other restrictions.
374
# In case of failure, return ``DEFER_IF_PERMIT optional text...'',
375
# so that mail can still be blocked by other access restrictions.
377
syslog $syslog_priority, "request age %d", $now - $time_stamp if $verbose;
378
if ($now - $time_stamp > $greylist_delay) {
381
return "defer_if_permit Service temporarily unavailable";
added
removed
README_FILES/SMTPD_POLICY_README
