20
20
<h2>Introduction</h2>
22
<p> Postfix version 2.3 introduces support for the Sendmail version
23
8 Milter (mail filter) protocol. This protocol is used by applications
24
that run outside the MTA to inspect SMTP events (CONNECT, DISCONNECT),
25
SMTP commands (HELO, MAIL FROM, etc.) as well as mail content (headers
26
and body). All this happens before mail is queued. </p>
22
<p> Postfix implements support for the Sendmail version 8 Milter
23
(mail filter) protocol. This protocol is used by applications that
24
run outside the MTA to inspect SMTP events (CONNECT, DISCONNECT),
25
SMTP commands (HELO, MAIL FROM, etc.) as well as mail content
26
(headers and body). All this happens before mail is queued. </p>
28
28
<p> The reason for adding Milter support to Postfix is that there
29
29
exists a large collection of applications, not only to block unwanted
39
39
Having yet another Postfix-specific version of all that software
40
40
is a poor use of human and system resources. </p>
42
<p> Postfix version 2.4 implements all the requests of Sendmail
43
version 8 Milter protocols up to version 4, including message body
44
replacement (body replacement is not available with Postfix version
46
See, however, the <a href="#workarounds">workarounds</a> and <a
42
<p> The Milter protocol has evolved over time, and different Postfix
43
versions implement different feature sets. See the <a
44
href="#workarounds">workarounds</a> and <a
47
45
href="#limitations">limitations</a> sections at the end of this
46
document for differences between Postfix and Sendmail implementations.
50
49
<p> This document provides information on the following topics: </p>
68
67
<h2><a name="plumbing">How Milter applications plug into Postfix </a> </h2>
70
69
<p> The Postfix Milter implementation uses two different lists of
71
mail filters: one list of filters that are used for SMTP mail only,
72
and one list of filters that are used for non-SMTP mail. The two
70
mail filters: one list of filters for SMTP mail only,
71
and one list of filters for non-SMTP mail. The two
73
72
lists have different capabilities, which is unfortunate. Avoiding
74
73
this would require major restructuring of Postfix. </p>
204
204
Postfix currently does not provide such a library, but Sendmail
207
<p> On some Linux and *BSD distributions, the Sendmail libmilter
208
library is installed by default. With this, applications such as
209
<a href="http://sourceforge.net/projects/dkim-milter/">dkim-milter</a>
210
and <a href="http://sourceforge.net/projects/sid-milter/">sid-milter</a>
209
<li> <p> The first option is to use a pre-compiled library. Some
210
systems install the Sendmail libmilter library by default. With
211
other systems, libmilter may be provided by a package (called
212
"sendmail-devel" on some Linux systems). </p>
214
<p> Once libmilter is installed, applications such as <a
215
href="http://sourceforge.net/projects/dkim-milter/">dkim-milter</a> and
216
<a href="http://sourceforge.net/projects/sid-milter/">sid-milter</a>
211
217
build out of the box without requiring any tinkering:</p>
222
<p> On other platforms you have two options: </p>
226
<li> <p>Install the Sendmail libmilter object library and include
227
files. On Linux systems, libmilter may be provided by the
228
sendmail-devel package. After installing libmilter, build the
229
Milter applications as described in the preceding paragraph. </p>
231
<li> <p>Don't install the Sendmail libmilter library, but build the
232
library from Sendmail source code instead: </p>
228
<li> <p> The other option is to build the libmilter library from
229
Sendmail source code: </p>
425
422
temporary error status, so that the client will try again later.
426
423
Specify "accept" if you want to receive mail as if the filter does
427
424
not exist, and "reject" to reject mail with a permanent status.
425
The "quarantine" action is like "accept" but freezes the message
426
in the "hold" queue, and is available with Postfix 2.6 or later.
432
431
/etc/postfix/main.cf:
433
# What to do in case of errors? Specify accept, reject, or tempfail.
432
# What to do in case of errors? Specify accept, reject, tempfail,
433
# or quarantine (Postfix 2.6 or later).
434
434
milter_default_action = tempfail
440
440
<p> As Postfix is not built with the Sendmail libmilter library,
441
441
you may need to configure the Milter protocol version that Postfix
442
should use. The default version is 2. Other protocol versions are
443
3 and 4 (Postfix 2.3 and later), and 6 (Postfix 2.5 an later). </p>
442
should use. The default version is 6 (before Postfix 2.6 the default
447
447
/etc/postfix/main.cf:
450
# 2.3 ≤ Postfix ≤ 2.5
448
451
milter_protocol = 2
481
485
<h3><a name="timeouts">Milter protocol timeouts</a></h3>
483
487
<p> Postfix uses different time limits at different Milter protocol
484
stages. The table shows wich timeouts are used and when
488
stages. The table shows the timeout settings and the corresponding
485
490
(EOH = end of headers; EOM = end of message). </p>
489
494
<table border="1">
491
<tr> <th> Parameter </th> <th> Time limit </th> <th> Protocol
496
<tr> <th> Postfix parameter </th> <th> Time limit </th> <th> Milter
497
protocol stage</th> </tr>
494
499
<tr> <td> milter_connect_timeout </td> <td> 30s </td> <td> CONNECT
507
<p> Beware: 30s may be too short for applications doing lots of DNS
508
lookups. However, if you increase the above timeouts too much,
509
remote SMTP clients may hang up and mail may be delivered multiple
510
times. This is an inherent problem with before-queue filtering. </p>
512
<p> Beware: 30s may be too short for Milter applications that do
513
lots of DNS lookups. However, if you increase the above timeouts
514
too much, remote SMTP clients may hang up and mail may be delivered
515
multiple times. This is an inherent problem with before-queue
512
518
<h3><a name="macros">Sendmail macro emulation</a></h3>
514
520
<p> Postfix emulates a limited number of Sendmail macros, as shown
515
in the table. Different macros are available at different SMTP
521
in the table. Some macro values depend on whether a recipient is
522
rejected (rejected recipients are available on request by the Milter
523
application). Different macros are available at different Milter
516
524
protocol stages (EOH = end-of-header, EOM = end-of-message); their
517
525
availability is not
518
526
always the same as in Sendmail. See the <a
524
532
<table border="1">
526
<tr> <th> Name </th> <th> Availability </th> <th> Description </th>
529
<tr> <td> i </td> <td> DATA, EOH, EOM </td> <td> Queue ID </td> </tr>
531
<tr> <td> j </td> <td> Always </td> <td> value of myhostname </td>
534
<tr> <th> Sendmail macro </th> <th> Milter protocol stage </th>
535
<th> Description </th> </tr>
537
<tr> <td> i </td> <td> DATA, EOH, EOM </td> <td> Queue ID, also
538
Postfix queue file name </td> </tr>
540
<tr> <td> j </td> <td> Always </td> <td> Value of myhostname </td>
534
543
<tr> <td> _ </td> <td> Always </td> <td> The validated client name
549
558
<tr> <td> {client_connections} </td> <td> CONNECT </td> <td>
550
559
Connection concurrency for this client </td> </tr>
552
<tr> <td> {client_name} </td> <td> Always </td> <td> Client hostname,
553
"unknown" when lookup or verification fails </td> </tr>
561
<tr> <td> {client_name} </td> <td> Always </td> <td> Client hostname
562
<br> When address → name lookup or name → address
563
verification fails: "unknown" </td> </tr>
555
565
<tr> <td> {client_port} </td> <td> Always (Postfix ≥2.5) </td>
556
566
<td> Client TCP port </td> </tr>
558
568
<tr> <td> {client_ptr} </td> <td> CONNECT, HELO, MAIL, DATA </td>
559
<td> Client name from reverse lookup, "unknown" when lookup fails
569
<td> Client name from address → name lookup <br> When address
570
→ name lookup fails: "unknown" </td> </tr>
562
572
<tr> <td> {cert_issuer} </td> <td> HELO, MAIL, DATA, EOH, EOM </td> <td>
563
573
TLS client certificate issuer </td> </tr>
577
587
<tr> <td> {mail_addr} </td> <td> MAIL </td> <td> Sender address
590
<tr> <td> {mail_host} </td> <td> MAIL (Postfix ≥ 2.6, only with
591
smtpd_milters) </td> <td> Sender next-hop destination </td> </tr>
593
<tr> <td> {mail_mailer} </td> <td> MAIL (Postfix ≥ 2.6, only with
594
smtpd_milters) </td> <td> Sender mail delivery transport </td> </tr>
580
596
<tr> <td> {rcpt_addr} </td> <td> RCPT </td> <td> Recipient address
583
<tr> <td> {tls_version} </td> <td> HELO, MAIL, DATA, EOH, EOM </td> <td>
584
TLS protocol version </td> </tr>
597
<br> With rejected recipient: descriptive text </td> </tr>
599
<tr> <td> {rcpt_host} </td> <td> RCPT (Postfix ≥ 2.6, only with
600
smtpd_milters) </td> <td> Recipient next-hop destination <br> With
601
rejected recipient: enhanced status code </td> </tr>
603
<tr> <td> {rcpt_mailer} </td> <td> RCPT (Postfix ≥ 2.6, only with
604
smtpd_milters) </td> <td> Recipient mail delivery transport <br>
605
With rejected recipient: "error" </td> </tr>
607
<tr> <td> {tls_version} </td> <td> HELO, MAIL, DATA, EOH, EOM </td>
608
<td> TLS protocol version </td> </tr>
586
610
<tr> <td> v </td> <td> Always </td> <td> value of milter_macro_v
593
<p> Postfix sends specific sets of macros at different SMTP protocol
617
<p> Postfix sends specific sets of macros at different Milter protocol
594
618
stages. The sets are configured with the parameters as described
595
619
in the table (EOH = end of headers; EOM = end of message). The
596
620
protocol version is a number that Postfix sends at the beginning
597
621
of the Milter protocol handshake. </p>
623
<p> As of Sendmail 8.14.0, Milter applications can specify what
624
macros they want to receive at different Milter protocol stages.
625
An application-specified list takes precedence over a Postfix-specified
601
630
<table border="1">
603
<tr> <th> Parameter name </th> <th> Protocol version </th> <th>
604
Protocol stage </th> </tr>
632
<tr> <th> Postfix parameter </th> <th> Milter protocol version </th>
633
<th> Milter protocol stage </th> </tr>
606
635
<tr> <td> milter_connect_macros </td> <td> 2 or higher </td> <td>
607
636
CONNECT </td> </tr>
634
663
<h2><a name="workarounds">Workarounds</a></h2>
636
<p> Content filters may break DKIM etc. signatures. If you
637
use an SMTP-based content filter, then you should add a line to
638
master.cf with "-o disable_mime_output_conversion=yes" (note: no
639
spaces around the "="), as described in the <a
667
<li> <p> To avoid breaking DKIM etc. signatures with an SMTP-based
668
content filter, update the before-filter SMTP client in master.cf,
669
and add a line with "-o disable_mime_output_conversion=yes" (note:
670
no spaces around the "="). For details, see the <a
640
671
href="FILTER_README.html#advanced_filter">advanced content filter</a>
643
<p> Sendmail Milter applications were originally developed for the
644
Sendmail version 8 MTA, which has a different architecture than
645
Postfix. The result is that some Milter applications make assumptions
646
that aren't true in a Postfix environment. </p>
675
/etc/postfix/master.cf:
676
# =============================================================
677
# service type private unpriv chroot wakeup maxproc command
678
# (yes) (yes) (yes) (never) (100)
679
# =============================================================
680
scan unix - - n - 10 smtp
681
-o smtp_send_xforward_command=yes
682
-o disable_mime_output_conversion=yes
683
-o smtp_generic_maps=
650
686
<li> <p> Some Milter applications use the "<tt>{if_addr}</tt>" macro
651
687
to recognize local mail; this macro does not exist in Postfix.
671
<p> This happens because those Milter applications expect that the
672
queue ID is known <i>before</i> the MTA accepts the MAIL FROM
673
(sender) command. Postfix, on the other hand, does not choose a
674
queue file name until <i>after</i> it accepts the first valid RCPT
675
TO (recipient) command (Postfix queue file names must be unique
676
across multiple directories, so the name can't be chosen before the
677
file is created; if multiple messages were to use the same queue
678
ID <i>simultaneously</i>, mail would be lost). </p>
707
<p> The problem is that Milter applications expect that the queue
708
ID is known <i>before</i> the MTA accepts the MAIL FROM (sender)
709
command. Postfix does not choose a queue ID, which is used as the
710
queue file name, until <i>after</i> it accepts the first valid RCPT
711
TO (recipient) command. </p>
682
713
<p> If you experience the ugly header problem, see if a recent
683
714
version of the Milter application fixes it. For example, current
684
715
versions of dkim-filter and dk-filter already have code that looks
685
up the Postfix queue ID at a later protocol stage. </p>
687
<p> To fix the ugly message header with sid-filter applications,
688
we change the source code, so that it does the queue ID lookup after
689
Postfix receives the end of the message. </p>
693
<li> <p> Edit the filter source file (named
694
<tt>sid-filter/sid-filter.c</tt>). </p>
696
<li> <p> Look up the <tt>smfilter</tt> table and replace
697
<tt>mlfi_eoh</tt> by <tt>NULL</tt>.
716
up the Postfix queue ID at a later protocol stage, and sid-filter
717
version 1.0.0 no longer includes the queue ID in the message header.
700
<li> <p> Look up the <tt>mlfi_eom()</tt> function and add code near
701
the top that calls <tt>mlfi_eoh()</tt> as shown by the <b>bold</b>
712
if (ret != SMFIS_CONTINUE)
721
<li> <p> This was tested with sid-milter-0.2.10 and sid-milter-0.2.14. </p>
725
<p> To fix the ugly message header with other Milter applications,
726
you will need to do something like this: </p>
720
<p> To fix the ugly message header, you will need to add code that
721
looks up the Postfix queue ID at some later point im time. The
722
example below adds the lookup after the end-of-message. </p>
758
752
<li> <p> Different mail filters use slightly different names for
759
variables. If the above code does not compile, look for the code
760
at the start of the <tt>mlfi_eoh()</tt> routine. </p>
762
<li> <p> This fixes only the ugly message header, but not the WARNING
763
message. Fortunately, many Milters log that message only once. </p>
753
variables. If the above code does not compile, look elsewhere in
754
the mail filter source file for code that looks up the "i" macro
755
value, and copy that code. </p>
757
<li> <p> This change fixes only the ugly message header, but not
758
the WARNING message. Fortunately, many Milters log that message
777
<li> <p> Postfix version 2.3 introduces support for Sendmail 8
778
milter protocol versions 2, 3 and 4; Postfix version 2.5 adds support
779
for protocol version 6, which is available with Sendmail 8.14.
780
Support for other protocol types or protocol versions may be added
783
<li> <p> For applications that are written in C, you need to use
784
the Sendmail libmilter library. A Postfix replacement may be
785
provided in the future. </p>
787
<li> <p> There are TWO sets of mail filters: filters that are used
775
<li> <p> The Milter protocol has evolved over time. Therefore,
776
different Postfix versions implement different feature sets. </p>
780
<tr> <th> Postfix </th> <th> Supported Milter requests </th>
783
<tr> <td align="center"> 2.6 </td> <td> All Milter requests of
784
Sendmail 8.14.0 (see notes below). </td> </tr>
786
<tr> <td align="center"> 2.5 </td> <td> All Milter requests of
787
Sendmail 8.14.0, except: <br> SMFIP_RCPT_REJ (report rejected
788
recipients to the mail filter), <br> SMFIR_CHGFROM (replace sender,
789
with optional ESMTP parameters), <br> SMFIR_ADDRCPT_PAR (add
790
recipient, with optional ESMTP parameters). </td> </tr>
792
<tr> <td align="center"> 2.4 </td> <td> All Milter requests of
793
Sendmail 8.13.0. </td> </tr>
795
<tr> <td align="center"> 2.3 </td> <td> All Milter requests of
796
Sendmail 8.13.0, except: <br> SMFIR_REPLBODY (replace message body).
800
<li> <p> For Milter applications that are written in C, you need
801
to use the Sendmail libmilter library. </p>
803
<li> <p> Postfix has TWO sets of mail filters: filters that are used
788
804
for SMTP mail only (specified with the smtpd_milters parameter),
789
805
and filters for non-SMTP mail (specified with the non_smtpd_milters
790
806
parameter). The non-SMTP filters are primarily for local submissions.
793
<li> <p> When mail is filtered by non-SMTP filters, the Postfix
794
cleanup(8) server has to simulate the SMTP client CONNECT and
795
DISCONNECT events, and the SMTP client EHLO, MAIL FROM, RCPT TO and
796
DATA commands. This works as expected, with only one exception:
797
non-SMTP filters must not REJECT or TEMPFAIL simulated RCPT TO
798
commands. When a non-SMTP filter REJECTs or TEMPFAILs a recipient,
809
<p> When mail is filtered by non_smtpd_milters, the Postfix cleanup(8)
810
server has to simulate SMTP client requests. This works as expected,
811
with only one exception: non_smtpd_milters must not REJECT or
812
TEMPFAIL simulated RCPT TO commands. When this rule is violated,
799
813
Postfix will report a configuration error, and mail will stay in
811
825
message header or body, and cannot make modifications to the message
812
826
or to the envelope. </p>
814
<li> <p> Postfix 2.3 does not support Milter requests to replace
815
the message body. Milter applications that request this unsupported
816
operation will log a warning like this: </p>
820
<i>application name</i>: st_optionneg[134563840]: 0x3d does not fulfill action requirements 0x1e
828
<li> <p> Postfix 2.6 ignores the optional ESMTP parameters in
829
requests to replace the sender (SMFIR_CHGFROM) or to append a
830
recipient (SMFIR_ADDRCPT_PAR). Postfix logs a warning message when
831
a Milter application supplies such ESMTP parameters: </p>
834
warning: <i>queue-id</i>: cleanup_chg_from: ignoring ESMTP arguments "<i>whatever</i>"
835
warning: <i>queue-id</i>: cleanup_add_rcpt: ignoring ESMTP arguments "<i>whatever</i>"
838
<li> <p> Postfix 2.3 does not implement requests to replace the
839
message body. Milter applications log a warning message when they
840
need this unsupported operation: </p>
843
st_optionneg[134563840]: 0x3d does not fulfill action requirements 0x1e
824
846
<p> The solution is to use Postfix version 2.4 or later. </p>
826
<li> <p> Postfix version 2.5 implements the Sendmail 8.14 features
827
except: SMFIP_RCPT_REJ (report rejected recipients to the mail
828
filter), SMFIR_CHGFROM (replace sender, with optional ESMTP command
829
parameters), and SMFIR_ADDRCPT_PAR (add recipient, with optional
830
ESMTP command parameters).
832
848
<li> <p> Most Milter configuration options are global. Future Postfix
833
849
versions may support per-Milter timeouts, per-Milter error handling,
added
removed
proto/MILTER_README.html
