"SfR Fresh" - the SfR Freeware/Shareware Archive 
Member "amavisd-new-2.6.1/README_FILES/README.postfix" of archive amavisd-new-2.6.1.tar.gz:
As a special service "SfR Fresh" has tried to format the requested source page into HTML format using source code syntax highlighting with prefixed line numbers.
Alternatively you can here view or download the uninterpreted source code file.
That can be also achieved for any archive member file by clicking within an archive contents listing on the first character of the file(path) respectively on the according byte size field.
1 Integrating amavisd-new in Postfix
2
3 Patrick Ben Koetter
4
5 <[1]patrick.koetter@state-of-mind.de>
6
7 Mark Martinec
8
9 <[2]Mark.Martinec+amavis@ijs.si>
10
11 License: GNU GENERAL PUBLIC LICENSE, Version 2, June 1991
12
13 +------------------------------------------------------------------------+
14 | Revision History |
15 |------------------------------------------------------------------------|
16 | Revision 141 | 11. Mar 2008 | PK |
17 |------------------------------------------------------------------------|
18 | Updated parameters that override Postfix defaults for the amavisdfeed |
19 | and the reentry smtpd servers |
20 |------------------------------------------------------------------------|
21 | Revision 139 | 11. Mar 2008 | PK |
22 |------------------------------------------------------------------------|
23 | Added corrections sent in from Chris Pepper |
24 |------------------------------------------------------------------------|
25 | Revision 122 | 15. Jun 2007 | PK |
26 |------------------------------------------------------------------------|
27 | Added Section on Advanced Configuration |
28 |------------------------------------------------------------------------|
29 | Revision 108 | 22. Apr 2007 | PK |
30 |------------------------------------------------------------------------|
31 | Initial publication |
32 +------------------------------------------------------------------------+
33
34 Table of Contents
35
36 [3]1. Requirements
37
38 [4]1.1. Which Postfix version is required?
39
40 [5]1.2. Catching errors during integration
41
42 [6]2. Basic Postfix and amavisd-new configuration
43
44 [7]2.1. Configuring amavisd-new for Postfix
45
46 [8]2.2. Configuring the transport from Postfix to amavisd-new
47
48 [9]2.3. Configuring a dedicated SMTP-server for message
49 reinjection
50
51 [10]2.4. Testing basic configuration
52
53 [11]3. Message filtering examples
54
55 [12]3.1. Filtering E-mail globally
56
57 [13]3.2. Filtering E-mail by Postfix service
58
59 [14]3.3. Filtering E-Mails per Recipient Domain
60
61 [15]3.4. Filtering E-Mails by Sender-Domain
62
63 [16]3.5. Filtering E-mail per Content
64
65 [17]4. Advanced Postfix and amavisd-new configuration
66
67 [18]4.1. Multiple cleanup service architecture
68
69 [19]4.2. Configuring two cleanup services
70
71 [20]5. Tuning
72
73 [21]5.1. Maximum Number of Concurrent Processes
74
75 [22]5.2. Additional Tips for Tuning
76
77 Abstract
78
79 This document describes how amavisd-new can be integrated into the Postfix
80 SMTP delivery process. It lists the necessary requirements, explains how
81 Postfix and amavisd-new need to be configured to basically work together
82 and it gives filter-examples to show how amavisd-new can be called from
83 Postfix.
84
85 1. Requirements
86
87 The following requirements must be met before integration can begin:
88
89 1. amavisd-new has already been installed and successfully tested.
90
91 2. Postfix has been installed, configured for basic operations and tested
92 successfully.
93
94 [23][Tip] Tip
95 Independently of the configuration examples shown in this
96 document, it is advisable to set strict_rfc821_envelopes = yes
97 in /etc/postfix/main.cf. Postfix will reject any message from
98 envelope-senders, whose address can't be used to send a reply
99 to.
100
101 This avoids accepting e-mails from erroneous envelope-senders
102 that can't be informed of problems, which finally would result
103 in deleting the message - even if Postfix claimed successful
104 delivery in the first.
105
106 1.1. Which Postfix version is required?
107
108 Integrating amavisd-new into the Postfix delivery process requires that
109 Postfix is able to delegate messages to external content filters. The
110 minimum version that provides content filtering is Postfix
111 release-20010228.
112
113 1.2. Catching errors during integration
114
115 Chances are that configuration errors during implementation cause Postfix
116 to bounce legitimate messages. Setting the soft_bounce parameter during
117 integration and reloading the Postfix configuration afterwards prevents
118 Postfix from bouncing legitimate mail during that time:
119
120 # postconf -e "soft_bounce = yes"
121 # postfix reload
122
123 As soon as soft_bounce has been activated Postfix will treat all delivery
124 errors as temporary errors - any client that wants to send messages to
125 Postfix will keep mail in the mailqueue and it will suspend delivery until
126 the soft_bounce parameter has been removed or set to no.
127
128 Once the integration of amavisd-new into the Postfix delivery process has
129 been completed successfully soft_bounce must be removed or Postfix will
130 not generate bounce messages for legitimate mail.
131
132 2. Basic Postfix and amavisd-new configuration
133
134 There are several moments at which Postfix can hand messages over to
135 amavisd-new (before it accepts a message from a client or after) and there
136 are different filter approaches (globally, per recipient (domain), per
137 network interface, etc.) that can trigger Postfix to transport a message
138 to amavisd-new.
139
140 The transport methods - transporting a message from Postfix to amavisd-new
141 and back - however always remain the same. They will be described in this
142 section first. The section that follows will deal with different filtering
143 approaches.
144
145 [24][Tip] Integration procedure
146 The following examples have been structured to cause minimum
147 trouble on an online mail system. The order of steps ensures
148 that filtering will be enabled at the very last moment. Several
149 tests will have been conducted to verify the delivery chain
150 works before the filter is enabled. Once enabled the complete
151 system should work at once.
152
153 2.1. Configuring amavisd-new for Postfix
154
155 Configuring amavisd-new to work with Postfix answers the following two
156 questions:
157
158 1. Which port should the amavisd-new daemon listen to for incoming
159 connections from Postfix?
160
161 2. Which IP-address and port should the amavisd-new SMTP client use to
162 (re)inject filtered messages (and notifications about message status)
163 into the Postfix SMTP delivery system?
164
165 2.1.1. Configuring amavisd-new for incoming connections
166
167 The $inet_socket_port parameter in /etc/amavisd.conf sets the port number
168 where amavisd-new will listen for incoming (E)SMTP connections. The
169 following example explicitly configures amavisd-new to bind to port 10024
170 (default setting undef):
171
172 $inet_socket_port = 10024;
173
174 2.1.2. Configuring the reinjection path
175
176 Two parameters, $forward_method and $notify_method, need to be configured
177 (usually identically) to reinject messages into the Postfix mail system.
178
179 The first parameter, $forward_method, specifies where amavisd-new should
180 transport scanned messages to, while the second parameter, $notify_method,
181 specifies where notifications about scanned messages should be transported
182 to.
183
184 By default amavisd uses 127.0.0.1 on port 10025 to contact a SMTP server
185 for reinjection of filtered messages. Unless a different IP address or
186 port should be used, no modifications must be applied and this section can
187 be skipped.
188
189 In case a different IP address or port should be used, the parameters
190 $notify_method and $forward_method need to be adjusted to reflect these
191 requirements. The following example edits these parameters in
192 /etc/amavisd.conf and uses 192.0.2.1 as IP address and port 20025:
193
194 $notify_method = 'smtp:[192.0.2.1]:20025';
195 $forward_method = 'smtp:[192.0.2.1]:20025';
196
197 2.2. Configuring the transport from Postfix to amavisd-new
198
199 Both amavisd-new and Postfix are able to use either SMTP- or
200 LMTP-communication to transport a message from Postfix to amavisd-new.
201 Both variants will be described in this section.
202
203 Why configure a dedicated service?
204
205 Theoretically it's possible to transport messages from Postfix to
206 amavisd-new using the existing smtp-, lmtp, or even the relay-service in
207 /etc/postfix/master.cf.
208
209 In practice transporting messages to amavisd-new requires imposing
210 transport limits on the transporting service. Imposing such limits on a
211 globally available service would impose these limits on the complete
212 Postfix mail system - it would slow down the system significantly and
213 should be avoided.
214
215 [25][Note] Note
216 The number of Postfix clients that may connect simultaneously
217 to amavisd-new instances must be limited to the maximum number
218 of daemon child processes amavisd-new starts.
219
220 If the Postfix transport client was allowed to open more
221 connections than amavisd-new can handle, amavisd-new would
222 start to queue incoming Postfix connections. Postfix in turn
223 would interpret such behaviour as "unresponsive remote MTA" and
224 would itself begin to queue mail that should be filtered. All
225 this would possibly throttle down the complete system and all
226 further filtering attempts would suffer.
227
228 2.2.1. Configuring a dedicated lmtp-client
229
230 The following example creates a new, dedicated lmtp-transport named
231 amavisfeed in /etc/postfix/master.cf. Its configuration details are
232 explained following the listing:
233
234 # ==========================================================================
235 # service type private unpriv chroot wakeup maxproc command + args
236 # (yes) (yes) (yes) (never) (100)
237 # ==========================================================================
238
239 ...
240
241 amavisfeed unix - - n - 2 lmtp
242 -o lmtp_data_done_timeout=1200
243 -o lmtp_send_xforward_command=yes
244 -o lmtp_tls_note_starttls_offer=no
245
246 [26][Important] Important
247 A noteworthy quote from the Postfix documentation: "...do
248 not specify whitespace around the `='. In parameter
249 values, either avoid whitespace altogether, ...". Further
250 details on master.cf configuration syntax can be found in
251 master.cf or master(5).
252
253 Here's a quick rundown on the settings that differ from other services
254 defaults:
255
256 maxproc
257
258 The maximum number of concurrent Postfix amavis-service processes
259 has been limited to 2 (default: default_process_limit = 100). This
260 value reflects the default of 2 amavisd-daemon children processes
261 and is a good setting to start from. The value may be raised
262 later, when the system works stable and still can take a higher
263 load. It should not exceed the number of simultaneous amavisd
264 child processes.
265
266 lmtp_data_done_timeout
267
268 Setting lmtp_data_done_timeout to 1200 (seconds) doubles the
269 default time span a regular Postfix client waits after message
270 delivery for the server to reply DONE to claim successful
271 delivery. It must be larger than amavisd setting $child_timeout
272 (default 8*60 seconds) and should add a sufficient safety margin,
273 for example to cater for periods of automatic database maintenance
274 (e.g. bayes database on non-SQL database types) which can take a
275 long time in some cases.
276
277 If the server does not reply within the configured time span, the
278 Postfix client will quit the connection, put the message into the
279 deferred queue, log a delivery failure and retry later to
280 transport the message to amavisd-new.
281
282 [27][Note] Note
283 Raising this value serves a trick amavisd uses to avoid
284 message loss in case of power outage etc. The trick
285 consists in keeping the incoming connection as long
286 open as it takes to filter the message and take
287 appropriate action (reinjection, notification,
288 quarantine, etc.).
289
290 Only when the message (or notifications etc.) has been
291 reinjected amavisd will send DONE to the client and the
292 client will close the connection. This way Postfix will
293 always keep the message in its own mail queue, where it
294 can be reactivated after a system failure.
295
296 lmtp_send_xforward_command
297
298 Enabling lmtp_send_xforward_command configures the Postfix
299 lmtp-client to forward the original clients HELO name and IP
300 address to amavisd-new. amavisd-new in turn can use this
301 information for
302
303 * logging and notifications (macro %a)
304
305 * switching policy banks (MYNETS, @mynetworks_maps)
306
307 * pen pals functionality
308
309 * p0f fingerprinting
310
311 lmtp_tls_note_starttls_offer
312
313 Starting with version 2.6 amavisd-new can offer TLS to a smtp- or
314 lmtp-client. This option cuts down unnecessary logging by Postfix,
315 just in case logging TLS session offers has been enabled globally
316 setting lmtp_tls_note_starttls_offer in Postfix main.cf
317 configuration file.
318
319 2.2.2. Configuring a dedicated smtp-client
320
321 Configuring a dedicated smtp-client is almost identical to configuring a
322 dedicated lmtp-client. The syntax differences in detail are that the names
323 of parameters start with smtp_ instead of lmtp_ and that the command at
324 the end of the service invokes the smtp- and not lmtp-client. The same
325 reasons given for differing lmtp client options apply to the dedicated
326 smtp client configuration.
327
328 Here's an example of a dedicated smtp client given the service name
329 amavisfeed:
330
331 # ==========================================================================
332 # service type private unpriv chroot wakeup maxproc command + args
333 # (yes) (yes) (yes) (never) (100)
334 # ==========================================================================
335
336 ...
337
338 amavisfeed unix - - n - 2 smtp
339 -o smtp_data_done_timeout=1200
340 -o smtp_send_xforward_command=yes
341 -o smtp_tls_note_starttls_offer=no
342
343 2.3. Configuring a dedicated SMTP-server for message reinjection
344
345 The second service that needs to be added to the Postfix mail system is a
346 dedicated SMTP-server. It will exist only to accept filtered messages and
347 notifications from amavisd-new to transported them closer to their final
348 destination.
349
350 This dedicated smtpd server will differ in many aspects from the default
351 smtpd daemon. The most important difference is that it configures an empty
352 content_filter parameter, thus overriding any global external content
353 filtering settings in Postfix.
354
355 [28][Note] Note
356 Delegating messages to an external content filter in Postfix is
357 done using the content_filter parameter. If the dedicated
358 smtpd-daemon would not override any global content_filter
359 settings, the reinjected message would be sent of to the
360 external content filter again - the mail would end in an
361 endless loop.
362
363 The following Postfix example uses amavisd-new default settings taken from
364 the $forward_method and $notify_method parameters. These settings
365 configure amavisd-new to forward filtered messages and notifications to
366 127.0.0.1 on port 10025; the Postfix smtpd daemon will be configured to
367 bind to that IP address and listen on the specified port for incoming
368 connections:
369
370 # ==========================================================================
371 # service type private unpriv chroot wakeup maxproc command + args
372 # (yes) (yes) (yes) (never) (100)
373 # ==========================================================================
374
375 ...
376
377 127.0.0.1:10025 inet n - n - - smtpd
378 -o content_filter=
379 -o smtpd_delay_reject=no
380 -o smtpd_client_restrictions=permit_mynetworks,reject
381 -o smtpd_helo_restrictions=
382 -o smtpd_sender_restrictions=
383 -o smtpd_recipient_restrictions=permit_mynetworks,reject
384 -o smtpd_data_restrictions=reject_unauth_pipelining
385 -o smtpd_end_of_data_restrictions=
386 -o smtpd_restriction_classes=
387 -o mynetworks=127.0.0.0/8
388 -o smtpd_error_sleep_time=0
389 -o smtpd_soft_error_limit=1001
390 -o smtpd_hard_error_limit=1000
391 -o smtpd_client_connection_count_limit=0
392 -o smtpd_client_connection_rate_limit=0
393 -o receive_override_options=no_header_body_checks,no_unknown_recipient_checks,no_milters
394 -o local_header_rewrite_clients=
395 -o smtpd_milters=
396 -o local_recipient_maps=
397 -o relay_recipient_maps=
398
399 Here's a quick rundown on the settings that differ from smtpd defaults:
400
401 content_filter
402
403 The empty content_filter overrides other, globally set
404 content_filter delegations.
405
406 ..._maps
407
408 Empty ..._maps override any other globally set map lookups.
409 Procedures to enforce settings specified in such maps have already
410 taken place when Postfix accepted the message from the external
411 client. Doing them again will not produce new results but only
412 waste resources.
413
414 ..._restrictions_...
415
416 There's no need to apply any already enforced ..._restrictions_...
417 another time. It would also only waste resources.
418
419 mynetworks
420
421 To avoid abuse from remote hosts, the dedicated smtpd-daemon will
422 only allow clients from 127.0.0.0/8 to relay messages.
423
424 local_header_rewrite_clients
425
426 By default this option would "rewrite message header addresses in
427 mail from these clients and update incomplete addresses with the
428 domain name". If such action has already been taken by Postfix
429 before the message went off to amavis, it should not be done a
430 second time when it reenters the Postfix mail system. Leaving this
431 option empty disables local header rewrites and saves resources.
432
433 remaining options
434
435 All remaining options either configure the dedicated smtpd-daemon
436 to be more failure tolerant or exist to avoid unnecessary use of
437 resources.
438
439 Running the postfix reload will activate the new transports (Postfix will
440 not yet send regular mail to amavisd). Combined with the tail command
441 problems can easily be detected:
442
443 # postfix reload && tail -f /var/log/maillog
444
445 If there are no problems reported, basic configuration can be tested.
446
447 2.4. Testing basic configuration
448
449 Testing basic configuration consists of three separate tests, starting at
450 the end of the new delivery chain and working to it's beginning. Their
451 goal is to answer the following questions:
452
453 1. Will amavisd-new accept connections at the specified IP address and
454 port?
455
456 2. Will the new dedicated smtpd-daemon accept connections at the
457 specified IP address and port?
458
459 3. Will a test message, injected into amavisd-new, be filtered, sent to
460 Postfix and delivered into a mailbox?
461
462 2.4.1. Testing amavisd's host and port
463
464 A test, using the telnet command, serves to verify that amavisd listens on
465 the specified IP address and port. A successful connection looks like
466 this:
467
468 $ telnet localhost 10024
469 220 [127.0.0.1] ESMTP amavisd-new service ready
470 EHLO localhost
471 250-[127.0.0.1]
472 250-VRFY
473 250-PIPELINING
474 250-SIZE
475 250-ENHANCEDSTATUSCODES
476 250-8BITMIME
477 250-DSN
478 250 XFORWARD NAME ADDR PROTO HELO
479 QUIT
480 221 2.0.0 [127.0.0.1] amavisd-new closing transmission channel
481
482 If the test fails, the following questions may help to debug the problem:
483
484 * Is the amavisd-new daemon running?
485
486 * Does amavisd-new write an error to the log?
487
488 * Do the IP address and port number specified in the amavisd-new
489 configuration match the values used during the test?
490
491 * Does a firewall intercept connections?
492
493 2.4.2. Testing the dedicated Postfix smtpd-daemon
494
495 When Postfix was reloaded, the new, dedicated smtpd-daemon
496 (127.0.0.1:10025) should have been activated. A successful connection
497 looks like this:
498
499 $ telnet 127.0.0.1 10025
500 220 mail.example.com ESMTP Postfix (2.3.2)
501 EHLO localhost
502 250-mail.example.com
503 250-PIPELINING
504 250-SIZE 40960000
505 250-ETRN
506 250-STARTTLS
507 250-AUTH PLAIN CRAM-MD5 LOGIN DIGEST-MD5
508 250-AUTH=PLAIN CRAM-MD5 LOGIN DIGEST-MD5
509 250-ENHANCEDSTATUSCODES
510 250-8BITMIME
511 250 DSN
512 QUIT
513 221 2.0.0 Bye
514
515 If the test fails, the following questions may help to debug the problem:
516
517 * Is the Postfix master daemon running?
518
519 * Does Postfix write an error to the log?
520
521 * Do the IP address and port number specified in the new services
522 configuration match the values used during the test?
523
524 * Does a firewall intercept connections?
525
526 2.4.3. Testing the new transport chain
527
528 This test proves amavisd accepts e-mail as specified in [29]Section 2.1,
529 "Configuring amavisd-new for Postfix", filters it and finally hands it
530 over to Postfix' dedicated smtpd-daemon as specified in [30]Section 2.3,
531 "Configuring a dedicated SMTP-server for message reinjection".
532
533 The following example uses the content of test-messages/sample-nonspam.txt
534 from the amavisd test-messages to send an e-mail:
535
536 $ telnet localhost 10024
537 220 [127.0.0.1] ESMTP amavisd-new service ready
538 HELO localhost
539 250 [127.0.0.1]
540 MAIL FROM: <>
541 250 2.1.0 Sender OK
542 RCPT TO: <postmaster>
543 250 2.1.5 Recipient postmaster OK
544 DATA
545 354 End data with <CR><LF>.<CR><LF>
546 From: virus-tester
547 To: undisclosed-recipients:;
548 Subject: amavisd test - simple - no spam test pattern
549
550 This is a simple test message from the amavisd-new test-messages.
551 .
552 250 2.6.0 Ok, id=30897-02, from MTA([127.0.0.1]:10025): 250 2.0.0 Ok: queued as 079474CE44
553 QUIT
554 221 2.0.0 [127.0.0.1] amavisd-new closing transmission channel
555
556 The maillog shows the delivery path. Here's an excerpt from a successful
557 delivery process:
558
559 Nov 1 11:28:10 mail postfix/smtpd[30986]: connect from localhost[127.0.0.1] [31]1
560 Nov 1 11:28:10 mail postfix/smtpd[30986]: 079474CE44: client=localhost[127.0.0.1]
561 Nov 1 11:28:10 mail postfix/cleanup[30980]: 079474CE44: message-id=<20061101102810.079474CE44@mail.example.com>
562 Nov 1 11:28:10 mail postfix/qmgr[20432]: 079474CE44: from=<>, size=822, nrcpt=1 (queue active)
563 Nov 1 11:28:10 mail amavis[30897]: (30897-02) Passed BAD-HEADER, <> -> <postmaster>, quarantine: badh-le5gjszxowBk, mail_id: le5gjszxowBk, Hits: -1.76, queued_as: 079474CE44, 39505 ms [32]2
564 Nov 1 11:28:10 mail postfix/smtpd[30986]: disconnect from localhost[127.0.0.1]
565 Nov 1 11:28:10 mail postfix/local[30987]: 079474CE44: to=<postmaster@example.com>, relay=local, delay=0.27, delays=0.14/0.05/0/0.08, dsn=2.0.0, status=sent (delivered to mailbox: postmaster) [33]3
566 Nov 1 11:28:10 mail postfix/qmgr[20432]: 079474CE44: removed
567
568 [34]1 amavisd connects with Postfix dedicated smtpd-daemon and hands over
569 the e-mail that had been sent during the telnet session. smtpd gives
570 a queue-id of 079474CE44 that can be tracked throughout the maillog.
571 [35]2 amavisd notices it has checked and sent an e-mail to <postmaster>.
572 [36]3 Postfix' local-service logs it successfully delivered an e-mail with
573 queue-id 079474CE44 to the mailbox of postmaster.
574
575 If the test fails, the following questions may help to debug the problem:
576
577 * Does amavisd-new log errors?
578
579 * Does running amavisd-new in debug-mode report errors?
580
581 3. Message filtering examples
582
583 Postfix can use various criteria to decide whether a message should be
584 sent to amavisd-new for examination. Combinations of criteria may serve to
585 create different configurations. The following section describes the
586 following configurations:
587
588 * Filtering e-mail globally
589
590 * Filtering e-mail globally by service
591
592 * Filtering e-mail per recipient domain
593
594 * Filtering e-mail per sender domain
595
596 * Filtering e-mail by content
597
598 3.1. Filtering E-mail globally
599
600 In most cases email policies require global filtering - every inbound and
601 every outbound e-mail must be filtered by amavisd-new - before it may be
602 sent closer to its final destination.
603
604 [37][Note] Why check outgoing mail traffic?
605 Some reasons for checking mail coming from internal networks or
606 from authenticated roaming users are:
607
608 * detect an internal infected PC which is sending viruses
609
610 * detect an internal zombiized PC (or an internal open relay
611 or proxy) which is sending or relaying spam
612
613 * let the SpamAssassin Bayes autolearning feature see a
614 balanced view of all mail, including useful samples of
615 non-spam originating from inside
616
617 * make it possible for pen pals feature to function (if
618 enabled)
619
620 In Postfix global settings for its services are written to main.cf. The
621 content_filter parameter, the parameter configuring that messages are sent
622 to amavisd-new, must therefore be placed in main.cf.
623
624 The content_filter parameter requires a triplet, consisting of the
625 transport service's name (here: amavisfeed, given in [38]Section 2.2.1,
626 "Configuring a dedicated lmtp-client"), the target hosts IP address and
627 the port where amavisd-new listens for incoming connections. Following the
628 values used in this documents examples the content_filter configuration
629 results in this:
630
631 content_filter=amavisfeed:[127.0.0.1]:10024
632
633 The new external content filter will be activated once Postfix has been
634 reloaded. Sending a test-mail verifies the system works.
635
636 3.2. Filtering E-mail by Postfix service
637
638 Postfix is able to filter messages per service. Such configuration
639 requires the content_filter not to be applied globally to all services in
640 main.cf (see: [39]Section 3.1, "Filtering E-mail globally"), but
641 selectively, per service in master.cf.
642
643 The following example presumes Postfix runs on a system offering three IP
644 addresses. In this example these are: 192.0.2.1 (WAN), 127.0.0.1
645 (localhost) and 10.0.0.254 (LAN). The goal is to filter only e-mail that
646 enters from the WAN interface.
647
648 This requires to create three dedicated smtpd-daemon instances, each
649 binding to one of the given IP addresses and deactivating the global smtp
650 service calling the smtpd command.
651
652 Additionally the WAN interface (here: 192.0.2.1:25) is configured to use
653 content_filter =amavisfeed:[127.0.0.1]:10024 - it will delegate any
654 message that enters the Postfix mail system at this service to the
655 external amavisd content filter.
656
657 # ==========================================================================
658 # service type private unpriv chroot wakeup maxproc command + args
659 # (yes) (yes) (yes) (never) (100)
660 # ==========================================================================
661 # smtp inet n - n - - smtpd
662
663 ...
664
665 192.0.2.1:25 inet n - n - - smtpd
666 -o content_filter=amavisfeed:[127.0.0.1]:10024
667 -o receive_override_options=no_address_mappings
668
669 10.0.0.254:25 inet n - n - - smtpd
670
671 127.0.0.1:10025 inet n - n - - smtpd
672 -o content_filter=
673 -o smtpd_delay_reject=no
674 -o smtpd_client_restrictions=permit_mynetworks,reject
675 -o smtpd_helo_restrictions=
676 -o smtpd_sender_restrictions=
677 -o smtpd_recipient_restrictions=permit_mynetworks,reject
678 -o smtpd_data_restrictions=reject_unauth_pipelining
679 -o smtpd_end_of_data_restrictions=
680 -o smtpd_restriction_classes=
681 -o mynetworks=127.0.0.0/8
682 -o smtpd_error_sleep_time=0
683 -o smtpd_soft_error_limit=1001
684 -o smtpd_hard_error_limit=1000
685 -o smtpd_client_connection_count_limit=0
686 -o smtpd_client_connection_rate_limit=0
687 -o receive_override_options=no_header_body_checks,no_unknown_recipient_checks,no_milters
688 -o local_header_rewrite_clients=
689 -o smtpd_milters=
690 -o local_recipient_maps=
691 -o relay_recipient_maps=
692
693 3.3. Filtering E-Mails per Recipient Domain
694
695 Postfix is able to filter e-mails per recipient domain. In order to do
696 this the content_filter parameter must not be set globally (see:
697 [40]Section 3.1, "Filtering E-mail globally"). Instead the content_filter
698 parameter has to be associated with one or more recipient domains listed
699 in a lookup table (map).
700
701 [41][Caution] Caution
702 This filter method is not selective! It will send any mail
703 with a recipient domain listed in the lookup table to amavis
704 even if the mail contains another recipient that should not
705 be examined by the amavis framework.
706
707 If fully selective rules are required all mail should be
708 sent to amavis and amavis' own rule sets should be
709 configured to decide whether a message for a given recipient
710 should be examined or not.
711
712 When Postfix searches the lookup table and finds the recipients domain
713 listed as key, it will take the action associated with that domain. The
714 action will send the message to a FILTER amavisfeed:[127.0.0.1]:10024.
715
716 The following map /etc/postfix/filter_recipient_domains specifies to send
717 messages to the FILTER amavisfeed whenever a message for any recipient at
718 example.com enters the Postfix mailqueues:
719
720 example.com FILTER amavisfeed:[127.0.0.1]:10024
721
722 Once the table has been created the postmap command must be used to create
723 an indexed map Postfix can read:
724
725 # postmap /etc/postfix/filter_recipient_domains
726
727 Once the map has been indexed, the postmap command is used to test the
728 map. In the following example the postmap command queries for the domain
729 example.com and returns the associated action:
730
731 # postmap -q "example.com" /etc/postfix/filter_recipient_domains
732 FILTER amavisfeed:[127.0.0.1]:10024
733
734 The tested map must be added to main.cf, before Postfix can make use of
735 the new filter policy. Setting the check_recipient_access parameter in the
736 list of smtpd_recipient_restrictions triggers evaluation of entries in the
737 map - check_recipient_access is triggered by the envelope-recipient(s)
738 given by a SMTP-client in a SMTP-session with Postfix.
739
740 The following example puts the check_recipient_access rule before
741 permit_mynetworks - all clients envelope-recipient(s) will be filtered:
742
743 smtpd_recipient_restrictions =
744 ...
745 check_recipient_access hash:/etc/postfix/filter_recipient_domains
746 ...
747 permit_mynetworks
748 reject_unauth_destination
749 ...
750
751 Filtering E-Mails per Recipient Domain only from External Clients
752
753 This example puts the check_recipient_access rule after permit_mynetworks
754 - only messages sent from clients that are not in Postfix $mynetworks list
755 (external or untrusted clients) will be filtered:
756
757 smtpd_recipient_restrictions =
758 ...
759 permit_mynetworks
760 reject_unauth_destination
761 check_recipient_access hash:/etc/postfix/filter_recipient_domains
762 ...
763
764 3.4. Filtering E-Mails by Sender-Domain
765
766 In general it doesn't make sense to filter e-mails by sender-domain, as
767 anyone can fake a sender-domain during a SMTP-session. Filtering by
768 sender-domain will probably only make sense, if messages are not filtered
769 globally, but e-mails from ones own domain should be checked for spam or
770 viruses before they leave the network.
771
772 Most of the configuration steps are identical with the ones noted in
773 [42]Section 3.3, "Filtering E-Mails per Recipient Domain", except for the
774 parameter that triggers evaluation of the indexed map. In this scenario
775 envelope-senders should trigger map evaluation. The map, named
776 /etc/postfix/filter_sender_domains this time, contains the sender domain
777 (example.com) and associates it with the required FILTER:
778
779 example.com FILTER amavisfeed:[127.0.0.1]:10024
780
781 Once the map has been converted and tested with the postmap command (see:
782 [43]Section 3.3, "Filtering E-Mails per Recipient Domain") it must be
783 added to the list of smtpd_recipient_restrictions using the
784 check_sender_access parameter:
785
786 smtpd_recipient_restrictions =
787 ...
788 check_sender_access hash:/etc/postfix/filter_sender_domains
789 ...
790 permit_mynetworks
791 reject_unauth_destination
792 ...
793
794 [44][Important] Important
795 The map must be listed before permit_mynetworks, because
796 only then it will be applied to all clients - even the
797 ones Postfix trusts, which are very likely the ones from
798 example.com.
799
800 3.5. Filtering E-mail per Content
801
802 Postfix is able - with deliberate limitations (see: BUILTIN_FILTER_README)
803 - to search for strings in headers, the body and MIME-headers. If a string
804 matches, Postfix may call appropriate action.
805
806 The following example configures Postfix to look for the string offer in
807 Subject:-headers and delegate the message to an external content filter if
808 if finds a matching string.
809
810 A map, consisting of the search string noted as regexp-expression,
811 associates the search pattern with a FILTER action:
812
813 /^Subject:.*offer/ FILTER amavisfeed:[127.0.0.1]:10024
814
815 [45][Note] Indexing regexp- or pcre-maps?
816 regexp- or pcre-maps are and must be plaintext files. They must
817 not and cannot be converted to an indexed map using the postmap
818 command. They can be tested using the postmap command using the
819 -q command line option.
820
821 Once the map has been created, Postfix must be configured to use it. The
822 following example uses the header_checks parameter (not body_checks or
823 mime_header_checks as they apply to other message parts) to implement the
824 map into the Postfix delivery process:
825
826 header_checks = regexp:/etc/postfix/filter_header
827
828 Once Postfix has been reloaded it will send every e-mail that contains the
829 word offer in the Subject:-header off to the external amavisd content
830 filter.
831
832 4. Advanced Postfix and amavisd-new configuration
833
834 In a post-queue content filtering setup, a mail message passes through
835 smtpd and cleanup Postfix services twice, once before a content filter,
836 and the second time when an approved message is reinjected from a content
837 filter into the Postfix mail system. This is because checks and
838 transformations that have been configured in main.cf are globally active
839 and will be loaded and run by any instance of these two services. To avoid
840 wasting resources, options that control runtime behavior of these services
841 should not be applied globally in main.cf, but selectively to separate
842 instances of these services in master.cf.
843
844 Checks and transformations which are performed by a smtpd Postfix service
845 itself, e.g. access controls, recipient validation, milters etc., can be
846 controlled by adding options (-o) to appropriate smtpd services. This has
847 been shown in the basic configuration examples (see: [46]Section 2.3,
848 "Configuring a dedicated SMTP-server for message reinjection").
849
850 Checks and transformations which are performed by a cleanup Postfix
851 service are trickier because in a normal Postfix setup there is only one
852 cleanup service, unlike smtpd services of which there are many. Some of
853 the more important cleanup settings are dynamically controllable by a
854 smtpd service through the use of its receive_override_options option.
855
856 [47][Tip] Transformations and checks
857 Any transformation should preferably only be performed once,
858 either before or after content filtering. When to transform
859 depends on the desired effect, for example whether a content
860 filter should see unchanged or modified mail messages. Typical
861 transformations are:
862
863 * rewrite addresses
864
865 * add BCC recipients
866
867 * modify mail header.
868
869 Most checks should also be performed only once, preferably only
870 on the first passage, when the mail enters the Postfix mail
871 system the first time. This way messages can be rejected early -
872 if needed - and will not tie up downstream resources. Checking
873 early also avoids bounces in case of negative check results on a
874 second passage after content filtering.
875
876 4.1. Multiple cleanup service architecture
877
878 To gain more control over a cleanup service than offered by
879 receive_override_options, two (or more) cleanup services, each with its
880 own set of options, must be run. A Postfix setup with more than one
881 cleanup service is possible either with two separate Postfix instances, or
882 through a specification of services and their options in master.cf file of
883 a single Postfix instance.
884
885 The following diagram illustrates a setup with two cleanup services in a
886 single Postfix instance:
887
888 .......................................
889 : Postfix :
890 ----->smtpd \ :
891 : -pre-cleanup-\ /local---->
892 ---->pickup / -queue- :
893 : -cleanup-/ | \smtp----->
894 : bounces/ ^ v :
895 : and locally | v :
896 : forwarded smtpd amavisfeed :
897 : messages 10025 | :
898 ...........................|...........
899 ^ |
900 | v
901 ............|...............................
902 : | $inet_socket_port=10024 :
903 : | :
904 : $forward_method='smtp:[127.0.0.1]:10025' :
905 : $notify_method ='smtp:[127.0.0.1]:10025' :
906 : :
907 : amavisd-new :
908 ............................................
909
910 Procedure 1. Message flow with two cleanup services
911
912 1. Messages enter the Postfix system at the regular smtpd or pickup
913 service.
914
915 2. The pre-cleanup cleanup service performs transformations and checks on
916 these messages.
917
918 3. The qmgr service schedules the messages to be sent to the amavisd-new
919 content filter.
920
921 4. amavisd-new performs various tests on the messages.
922
923 5. Messages are re-injected into the Postfix mail system, sending them to
924 a dedicated, local smtpd service.
925
926 6. The cleanup cleanup service performs transformations and checks that
927 must be done at this stage, but omits the ones that have already been
928 carried out in step 2.
929
930 4.2. Configuring two cleanup services
931
932 Configuring Postfix smtpd services to use two separate, dedicated cleanup
933 services requires the following steps:
934
935 1. Create a second cleanup instance
936
937 2. Modify the existing cleanup service
938
939 3. Configure smtpd services to use either of the two cleanup services.
940
941 4.2.1. Creating a second cleanup instance
942
943 The following example adds a cleanup daemon named pre-cleanup. It will
944 handle messages before a content filter.
945
946 # ==========================================================================
947 # service type private unpriv chroot wakeup maxproc command + args
948 # (yes) (yes) (yes) (never) (100)
949 # ==========================================================================
950 # smtp inet n - n - - smtpd
951
952 ...
953
954 pre-cleanup unix n - n - 0 cleanup
955 -o virtual_alias_maps=
956
957 The above leaves canonicalization address rewriting enabled so that a
958 content filter will see canonicalized (external) sender mail addresses,
959 but it disables globally configured virtual alias transformations.
960
961 Such transformations will be done later by the second cleanup service, so
962 that a content filter will see original (external) recipient mail
963 addresses. Other options may also be used as needed.
964
965 4.2.2. Modifying the existing cleanup service
966
967 The already existing cleanup service - having the service name cleanup -
968 will be used to process messages that re-enter the Postfix mail system
969 (also for delivery notifications and forwarding as generated internally by
970 Postfix).
971
972 Cleanup jobs that already have been performed by the pre-cleanup service
973 should not be run again. The following example disables typical checks
974 that have been run before or are not needed for internally generated
975 notifications:
976
977 # ==========================================================================
978 # service type private unpriv chroot wakeup maxproc command + args
979 # (yes) (yes) (yes) (never) (100)
980 # ==========================================================================
981 # smtp inet n - n - - smtpd
982
983 ...
984
985 cleanup unix n - n - 0 cleanup
986 -o mime_header_checks= [48]1
987 -o nested_header_checks= [49]2
988 -o body_checks= [50]3
989 -o header_checks= [51]4
990
991 [52]1 The specified options disable header and body checks as these would
992 [53]2 already be performed by a pre-cleanup service.
993 [54]3
994 [55]4
995
996 [56][Note] always_bcc
997 This cleanup service would also be the appropriate one for
998 specifying always_bcc option - doing it globally would apply to
999 both cleanup services and would result in two copies of each
1000 message to be sent to the specified address.
1001
1002 4.2.3. Configuring smtpd services
1003
1004 Finally existing smtpd services on ports 25 and 587 (submission), and the
1005 pickup service must be configured to send messages to the new pre-cleanup
1006 service instead of a default cleanup service:
1007
1008 # ==========================================================================
1009 # service type private unpriv chroot wakeup maxproc command + args
1010 # (yes) (yes) (yes) (never) (100)
1011 # ==========================================================================
1012 # smtp inet n - n - - smtpd
1013
1014 ...
1015
1016 pickup fifo n - n 60 1 pickup
1017 -o cleanup_service_name=pre-cleanup
1018 smtp inet n - n - - smtpd
1019 -o cleanup_service_name=pre-cleanup
1020 submission inet n - n - - smtpd
1021 -o cleanup_service_name=pre-cleanup
1022
1023 5. Tuning
1024
1025 5.1. Maximum Number of Concurrent Processes
1026
1027 The most important settings to tune and optimize in Postfix and amavisd
1028 workflow are the maximum number of concurrent processes. The maximum
1029 number of concurrent processes on both sides must be chosen with care.
1030
1031 If the number is too low, hardware resources aren't used efficiently and
1032 delivery time will be unnecessarily prolonged. Experience tells that
1033 raising the number of processes a little, will not raise the overall
1034 throughput in the same proportion.
1035
1036 As the system resources are nearing saturation with each increase of the
1037 number of processes, an increase in throughput becomes marginal, and
1038 eventually even negative when the number of processes exceeds its
1039 near-optimum value. E-mail throughput will decrease, because processes
1040 need to wait for each other. At worst e-mail delivery stalls.
1041
1042 Best practice is to start with a (conservative) maximum number of 2
1043 concurrent processes. Everyday use has shown that this value may be raised
1044 to a value between 10 and 30 concurrent Postfix client and amavisd server
1045 processes. This also depends on the overall resources the system may
1046 provide, how amavisd has been integrated into the Postfix delivery process
1047 and on the anti-virus and anti-spam software being loaded and used by
1048 amavisd-new.
1049
1050 Regardless of the maximum number of concurrent processes, both sides -
1051 Postfix and amavisd - should be synchronized. To synchronize both sides
1052 edit, the $max_servers parameter for amavisd-new (see: amavisd.conf) and
1053 the number of processes in master.cf listed in the dedicated transports
1054 maxproc column for Postfix.
1055
1056 Both values should be identical for two reasons: If amavisd-new offers
1057 more processes than Postfix will ever use, amavisd-new wastes resources.
1058 On the other hand, if Postfix starts more dedicated transports than
1059 amavisd can handle simultaneously, e-mail transport will be refused and
1060 logged as error.
1061
1062 [57][Note] Controlling the maximum number of concurrent processes in
1063 main.cf
1064 Instead of controlling the maximum number of concurrent
1065 processes of Postfix' dedicated transport in master.cf it is
1066 also possible to keep the default setting - in master.cf and
1067 set the following parameter and option in main.cf:
1068
1069 amavisfeed_destination_concurrency_limit = 2
1070
1071 The name of the parameter starts with the service in master.cf
1072 (here: amavisfeed) that should be controlled and goes on with
1073 the suffix _destination_concurrency_limit. Here also 2 is set
1074 as initial (conservative) value.
1075
1076 5.2. Additional Tips for Tuning
1077
1078 Further Tuning-Tips can be found in README.performance and the slides from
1079 [58]amavisd-new, advanced configuration and management.
1080
1081 References
1082
1083 Visible links
1084 58. http://www.ijs.si/software/amavisd/amavisd-new-magdeburg-20050519.pdf