PPoossttffiixx bbeeffoorree--qquueeuuee MMiilltteerr ssuuppppoorrtt
-------------------------------------------------------------------------------
IInnttrroodduuccttiioonn
Postfix version 2.3 introduces support for the Sendmail version 8 Milter (mail
filter) protocol. This protocol is used by applications that run outside the
MTA to inspect SMTP events (CONNECT, DISCONNECT), SMTP commands (HELO, MAIL
FROM, etc.) as well as mail content (headers and body). All this happens before
mail is queued.
The reason for adding Milter support to Postfix is that there exists a large
collection of applications, not only to block unwanted mail, but also to verify
authenticity (examples: DomainKeys Identified Mail (DKIM), SenderID+SPF and
DomainKeys) or to digitally sign mail (examples: DomainKeys Identified Mail
(DKIM), DomainKeys). Having yet another Postfix-specific version of all that
software is a poor use of human and system resources.
Postfix version 2.4 implements all the requests of Sendmail version 8 Milter
protocols up to version 4, including message body replacement (body replacement
is not available with Postfix version 2.3). See, however, the workarounds and
limitations sections at the end of this document.
This document provides information on the following topics:
* How Milter applications plug into Postfix
* Building Milter applications
* Running Milter applications
* Configuring Postfix
* Workarounds
* Limitations
HHooww MMiilltteerr aapppplliiccaattiioonnss pplluugg iinnttoo PPoossttffiixx
The Postfix Milter implementation uses two different lists of mail filters: one
list of filters that are used for SMTP mail only, and one list of filters that
are used for non-SMTP mail. The two lists have different capabilities, which is
unfortunate. Avoiding this would require major restructuring of Postfix.
* The SMTP-only filters handle mail that arrives via the Postfix smtpd(8)
server. They are typically used to filter unwanted mail and to sign mail
from authorized SMTP clients. You specify SMTP-only Milter applications
with the smtpd_milters parameter as described in a later section. Mail that
arrives via the Postfix smtpd(8) server is not filtered by the non-SMTP
filters that are described next.
* The non-SMTP filters handle mail that arrives via the Postfix sendmail(1)
command-line or via the Postfix qmqpd(8) server. They are typically used to
digitally sign mail only. Although non-SMTP filters can be used to filter
unwanted mail, they have limitations compared to the SMTP-only filters. You
specify non-SMTP Milter applications with the non_smtpd_milters parameter
as described in a later section.
For those who are familiar with the Postfix architecture, the figure below
shows how Milter applications plug into Postfix. Names followed by a number are
Postfix commands or server programs, while unnumbered names inside shaded areas
represent Postfix queues. To avoid clutter, the path for local submission is
simplified (the OVERVIEW document has a more complete description).
SMTP-only non-SMTP
filters filters
^ |
| v
^ |
| |
Network -> smtpd(8) | |
| v
\
Network -> qmqpd(8) -> cleanup(8) -> incoming
/
pickup(8)
:
Local -> sendmail(1)
BBuuiillddiinngg MMiilltteerr aapppplliiccaattiioonnss
Milter applications have been written in C, JAVA and Perl, but this document
deals with C applications only. For these, you need an object library that
implements the Sendmail 8 Milter protocol. Postfix currently does not provide
such a library, but Sendmail does.
On some Linux and *BSD distributions, the Sendmail libmilter library is
installed by default. With this, applications such as dkim-milter and sid-
milter build out of the box without requiring any tinkering:
$ ggzzccaatt ddkkiimm--mmiilltteerr--xx..yy..zz..ttaarr..ggzz || ttaarr xxff --
$ ccdd ddkkiimm--mmiilltteerr--xx..yy..zz
$ mmaakkee
[...lots of output omitted...]
On other platforms you have two options:
* Install the Sendmail libmilter object library and include files. On Linux
systems, libmilter may be provided by the sendmail-devel package. After
installing libmilter, build the Milter applications as described in the
preceding paragraph.
* Don't install the Sendmail libmilter library, but build the library from
Sendmail source code instead:
$ ggzzccaatt sseennddmmaaiill--xx..yy..zz..ttaarr..ggzz || ttaarr xxff --
$ ccdd sseennddmmaaiill--xx..yy..zz//lliibbmmiilltteerr
$ mmaakkee
[...lots of output omitted...]
After building your own libmilter library, follow the installation
instructions in the Milter application source distribution to specify the
location of the libmilter include files and object library. Typically,
these settings are configured in a file named sid-filter/Makefile.m4 or
similar:
APPENDDEF(`confINCDIRS', `-I/some/where/sendmail-x.y.z/include')
APPENDDEF(`confLIBDIRS', `-L/some/where/sendmail-x.y.z/obj.systemtype/
libmilter')
Then build the Milter application.
RRuunnnniinngg MMiilltteerr aapppplliiccaattiioonnss
To run a Milter application, see the documentation of the filter for options. A
typical command looks like this:
# //ssoommee//wwhheerree//ddkkiimm--ffiilltteerr --uu uusseerriidd --pp iinneett::ppoorrttnnuummbbeerr@@llooccaallhhoosstt ......ootthheerr
ooppttiioonnss......
Please specify a userid value that isn't used for other applications (not
"postfix", not "www", etc.).
CCoonnffiigguurriinngg PPoossttffiixx
Like Sendmail, Postfix has a lot of configuration options that control how it
talks to Milter applications. With the initial Postfix Milter protocol
implementation, many options are global, that is, they apply to all Milter
applications. Future Postfix versions may support per-Milter timeouts, per-
Milter error handling, etc.
Information in this section:
* SMTP-Only Milter applications
* Non-SMTP Milter applications
* Milter error handling
* Milter protocol version
* Milter protocol timeouts
* Sendmail macro emulation
SSMMTTPP--OOnnllyy MMiilltteerr aapppplliiccaattiioonnss
The SMTP-only Milter applications handle mail that arrives via the Postfix
smtpd(8) server. They are typically used to filter unwanted mail, and to sign
mail from authorized SMTP clients. Mail that arrives via the Postfix smtpd(8)
server is not filtered by the non-SMTP filters that are described in the next
section.
NOTE: Do not use the header_checks(5) IGNORE action to remove Postfix's own
Received: message header. This causes problems with mail signing filters.
Instead, keep Postfix's own Received: message header and use the header_checks
(5) REPLACE action to sanitize information.
You specify SMTP-only Milter applications (there can be more than one) with the
smtpd_milters parameter. Each Milter application is identified by the name of
its listening socket; other Milter configuration options will be discussed in
later sections. Milter applications are applied in the order as specified, and
the first Milter application that rejects a command will override the responses
from other Milter applications.
/etc/postfix/main.cf:
# Milters for mail that arrives via the smtpd(8) server.
# See below for socket address syntax.
smtpd_milters = inet:localhost:portnumber ...other filters...
The general syntax for listening sockets is as follows:
uunniixx::pathname
Connect to the local UNIX-domain server that is bound to the specified
pathname. If the smtpd(8) or cleanup(8) process runs chrooted, an
absolute pathname is interpreted relative to the Postfix queue
directory.
iinneett::host::port
Connect to the specified TCP port on the specified local or remote
host. The host and port can be specified in numeric or symbolic form.
NOTE: Postfix syntax differs from Milter syntax which has the form
iinneett::port@@host.
NNoonn--SSMMTTPP MMiilltteerr aapppplliiccaattiioonnss
The non-SMTP Milter applications handle mail that arrives via the Postfix
sendmail(1) command-line or via the Postfix qmqpd(8) server. They are typically
used to digitally sign mail. Although non-SMTP filters can be used to filter
unwanted mail, there are limitations as discussed later in this section. Mail
that arrives via the Postfix smtpd(8) server is not filtered by the non-SMTP
filters.
NOTE: Do not use the header_checks(5) IGNORE action to remove Postfix's own
Received: message header. This causes problems with mail signing filters.
Instead, keep Postfix's own Received: message header and use the header_checks
(5) REPLACE action to sanitize information.
You specify non-SMTP Milter applications with the non_smtpd_milters parameter.
This parameter uses the same syntax as the smtpd_milters parameter in the
previous section. As with the SMTP-only filters, you can specify more than one
Milter application; they are applied in the order as specified, and the first
Milter application that rejects a command will override the responses from the
other applications.
/etc/postfix/main.cf:
# Milters for non-SMTP mail.
# See below for socket address syntax.
non_smtpd_milters = inet:localhost:portnumber ...other filters...
There's one small complication when using Milter applications for non-SMTP
mail: there is no SMTP session. To keep Milter applications happy, the Postfix
cleanup(8) server actually has to simulate the SMTP client CONNECT and
DISCONNECT events, and the SMTP client EHLO, MAIL FROM, RCPT TO and DATA
commands.
* When new mail arrives via the sendmail(1) command line, the Postfix cleanup
(8) server pretends that the mail arrives with ESMTP from "localhost" with
IP address "127.0.0.1". The result is very similar to what happens with
command line submissions in Sendmail version 8.12 and later, although
Sendmail uses a different mechanism to achieve this result.
* When new mail arrives via the qmqpd(8) server, the Postfix cleanup(8)
server pretends that the mail arrives with ESMTP, and uses the QMQPD client
hostname and IP address.
* When old mail is re-injected into the queue with "postsuper -r", the
Postfix cleanup(8) server uses the same client information that was used
when the mail arrived as new mail.
This generally works as expected, with only one exception: non-SMTP filters
must not REJECT or TEMPFAIL simulated RCPT TO commands. When a
non_smtpd_milters application REJECTs or TEMPFAILs a recipient, Postfix will
report a configuration error, and mail will stay in the queue.
None of this is a problem for mail filters that digitally sign mail.
MMiilltteerr eerrrroorr hhaannddlliinngg
The milter_default_action parameter specifies how Postfix handles Milter
application errors. The default action is to respond with a temporary error
status, so that the client will try again later. Specify "accept" if you want
to receive mail as if the filter does not exist, and "reject" to reject mail
with a permanent status.
/etc/postfix/main.cf:
# What to do in case of errors? Specify accept, reject, or tempfail.
milter_default_action = tempfail
MMiilltteerr pprroottooccooll vveerrssiioonn
As Postfix is not built with the Sendmail libmilter library, you may need to
configure the Milter protocol version that Postfix should use. The default
version is 2. Other protocol versions are 3 and 4 (Postfix 2.3 and later), and
6 (Postfix 2.5 an later).
/etc/postfix/main.cf:
milter_protocol = 2
If the Postfix milter_protocol setting specifies a too low version, the
libmilter library will log an error message like this:
application name: st_optionneg[xxxxx]: 0xyy does not fulfill action
requirements 0xzz
The remedy is to increase the Postfix milter_protocol version number. See,
however, the limitations section below for features that aren't supported by
Postfix.
If the Postfix milter_protocol setting specifies a too high version, the
libmilter library simply hangs up without logging a warning, and you see a
Postfix warning message like one of the following:
postfix/smtpd[21045]: warning: milter inet:host:port: can't read packet
header: Unknown error : 0
postfix/cleanup[15190]: warning: milter inet:host:port: can't read packet
header: Success
The remedy is to lower the Postfix milter_protocol version number.
MMiilltteerr pprroottooccooll ttiimmeeoouuttss
Postfix uses different time limits at different Milter protocol stages. The
table shows wich timeouts are used and when (EOH = end of headers; EOM = end of
message).
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
|PPaarraammeetteerr |TTiimmee lliimmiitt|PPrroottooccooll ssttaaggee |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|milter_connect_timeout|30s |CONNECT |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|milter_command_timeout|30s |HELO, MAIL, RCPT, DATA, UNKNOWN|
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|milter_content_timeout|300s |HEADER, EOH, BODY, EOM |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
Beware: 30s may be too short for applications doing lots of DNS lookups.
However, if you increase the above timeouts too much, remote SMTP clients may
hang up and mail may be delivered multiple times. This is an inherent problem
with before-queue filtering.
SSeennddmmaaiill mmaaccrroo eemmuullaattiioonn
Postfix emulates a limited number of Sendmail macros, as shown in the table.
Different macros are available at different SMTP protocol stages (EOH = end-of-
header, EOM = end-of-message); their availability is not always the same as in
Sendmail. See the workarounds section below for solutions.
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
|NNaammee |AAvvaaiillaabbiilliittyy |DDeessccrriippttiioonn |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|i |DATA, EOH, EOM |Queue ID |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|j |Always |value of myhostname |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|_ |Always |The validated client name |
| | |and address |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|{auth_authen} |MAIL, DATA, EOH, EOM |SASL login name |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|{auth_author} |MAIL, DATA, EOH, EOM |SASL sender |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|{auth_type} |MAIL, DATA, EOH, EOM |SASL login method |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|{client_addr} |Always |Client IP address |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|{client_connections}|CONNECT |Connection concurrency for|
| | |this client |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
| | |Client hostname, "unknown"|
|{client_name} |Always |when lookup or |
| | |verification fails |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|{client_port} |Always (Postfix >=2.5) |Client TCP port |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
| | |Client name from reverse |
|{client_ptr} |CONNECT, HELO, MAIL, DATA|lookup, "unknown" when |
| | |lookup fails |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|{cert_issuer} |HELO, MAIL, DATA, EOH, |TLS client certificate |
| |EOM |issuer |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|{cert_subject} |HELO, MAIL, DATA, EOH, |TLS client certificate |
| |EOM |subject |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|{cipher_bits} |HELO, MAIL, DATA, EOH, |TLS session key size |
| |EOM | |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|{cipher} |HELO, MAIL, DATA, EOH, |TLS cipher |
| |EOM | |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|{daemon_name} |Always |value of |
| | |milter_macro_daemon_name |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|{mail_addr} |MAIL |Sender address |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|{rcpt_addr} |RCPT |Recipient address |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|{tls_version} |HELO, MAIL, DATA, EOH, |TLS protocol version |
| |EOM | |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|v |Always |value of milter_macro_v |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
Postfix sends specific sets of macros at different SMTP protocol stages. The
sets are configured with the parameters as described in the table (EOH = end of
headers; EOM = end of message). The protocol version is a number that Postfix
sends at the beginning of the Milter protocol handshake.
_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _
|PPaarraammeetteerr nnaammee |PPrroottooccooll vveerrssiioonn|PPrroottooccooll ssttaaggee |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|milter_connect_macros |2 or higher |CONNECT |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|milter_helo_macros |2 or higher |HELO/EHLO |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|milter_mail_macros |2 or higher |MAIL FROM |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|milter_rcpt_macros |2 or higher |RCPT TO |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|milter_data_macros |4 or higher |DATA |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|milter_end_of_header_macros |6 or higher |EOH |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|milter_end_of_data_macros |2 or higher |EOM |
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
|milter_unknown_command_macros|3 or higher |unknown command|
|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _ _|_ _ _ _ _ _ _ _ _ _ _ _ _ _ _ |
WWoorrkkaarroouunnddss
Content filters may break DKIM etc. signatures. If you use an SMTP-based
content filter, then you should add a line to master.cf with "-
o disable_mime_output_conversion=yes" (note: no spaces around the "="), as
described in the advanced content filter example.
Sendmail Milter applications were originally developed for the Sendmail version
8 MTA, which has a different architecture than Postfix. The result is that some
Milter applications make assumptions that aren't true in a Postfix environment.
* Some Milter applications use the "{if_addr}" macro to recognize local mail;
this macro does not exist in Postfix. Workaround: use the "{client_addr}"
macro instead.
* Some Milter applications log a warning that looks like this:
sid-filter[36540]: WARNING: sendmail symbol 'i' not available
And they may insert an ugly message header with "unknown-msgid" like this:
X-SenderID: Sendmail Sender-ID Filter vx.y.z host.example.com <unknown-
msgid>
This happens because those Milter applications expect that the queue ID is
known before the MTA accepts the MAIL FROM (sender) command. Postfix, on
the other hand, does not choose a queue file name until after it accepts
the first valid RCPT TO (recipient) command (Postfix queue file names must
be unique across multiple directories, so the name can't be chosen before
the file is created; if multiple messages were to use the same queue ID
simultaneously, mail would be lost).
If you experience the ugly header problem, see if a recent version of the
Milter application fixes it. For example, current versions of dkim-filter and
dk-filter already have code that looks up the Postfix queue ID at a later
protocol stage.
To fix the ugly message header with sid-filter applications, we change the
source code, so that it does the queue ID lookup after Postfix receives the end
of the message.
* Edit the filter source file (named sid-filter/sid-filter.c).
* Look up the smfilter table and replace mlfi_eoh by NULL.
* Look up the mlfi_eom() function and add code near the top that calls
mlfi_eoh() as shown by the bboolldd text below:
assert(ctx != NULL);
#endif /* !DEBUG */
rreett == mmllffii__eeoohh((ccttxx));;
iiff ((rreett !!== SSMMFFIISS__CCOONNTTIINNUUEE))
rreettuurrnn rreett;;
NOTES:
* This was tested with sid-milter-0.2.10 and sid-milter-0.2.14.
To fix the ugly message header with other Milter applications, you will need to
do something like this:
* Edit the filter source file (typically named xxx-filter/xxx-filter.c or
similar).
* Look up the mlfi_eom() function and add code near the top shown as bboolldd
text below:
dfc = cc->cctx_msg;
assert(dfc != NULL);
//** DDeetteerrmmiinnee tthhee jjoobb IIDD ffoorr llooggggiinngg.. **//
iiff ((ddffcc-->>mmccttxx__jjoobbiidd ==== 00 |||| ssttrrccmmpp((ddffcc-->>mmccttxx__jjoobbiidd,, JJOOBBIIDDUUNNKKNNOOWWNN)) ==== 00)) {{
cchhaarr **jjoobbiidd == ssmmffii__ggeettssyymmvvaall((ccttxx,, ""ii""));;
iiff ((jjoobbiidd !!== 00))
ddffcc-->>mmccttxx__jjoobbiidd == jjoobbiidd;;
}}
/* get hostname; used in the X header and in new MIME boundaries */
NOTES:
* Different mail filters use slightly different names for variables. If the
above code does not compile, look for the code at the start of the mlfi_eoh
() routine.
* This fixes only the ugly message header, but not the WARNING message.
Fortunately, many Milters log that message only once.
LLiimmiittaattiioonnss
This section lists limitations of the Postfix Milter implementation. Some
limitations will be removed as the implementation is extended over time. Of
course the usual limitations of before-queue filtering will always apply. See
the CONTENT_INSPECTION_README document for a discussion.
* Postfix version 2.3 introduces support for Sendmail 8 milter protocol
versions 2, 3 and 4; Postfix version 2.5 adds support for protocol version
6, which is available with Sendmail 8.14. Support for other protocol types
or protocol versions may be added later.
* For applications that are written in C, you need to use the Sendmail
libmilter library. A Postfix replacement may be provided in the future.
* There are TWO sets of mail filters: filters that are used for SMTP mail
only (specified with the smtpd_milters parameter), and filters for non-SMTP
mail (specified with the non_smtpd_milters parameter). The non-SMTP filters
are primarily for local submissions.
* When mail is filtered by non-SMTP filters, the Postfix cleanup(8) server
has to simulate the SMTP client CONNECT and DISCONNECT events, and the SMTP
client EHLO, MAIL FROM, RCPT TO and DATA commands. This works as expected,
with only one exception: non-SMTP filters must not REJECT or TEMPFAIL
simulated RCPT TO commands. When a non-SMTP filter REJECTs or TEMPFAILs a
recipient, Postfix will report a configuration error, and mail will stay in
the queue.
* Postfix currently does not apply content filters to mail that is forwarded
or aliased internally, or to mail that is generated internally such as
bounces or Postmaster notifications. This may be a problem when you want to
apply a signing Milter to such mail.
* When you use the before-queue content filter for incoming SMTP mail (see
SMTPD_PROXY_README), Milter applications have access only to the SMTP
command information; they have no access to the message header or body, and
cannot make modifications to the message or to the envelope.
* Postfix 2.3 does not support Milter requests to replace the message body.
Milter applications that request this unsupported operation will log a
warning like this:
application name: st_optionneg[134563840]: 0x3d does not fulfill action
requirements 0x1e
The solution is to use Postfix version 2.4 or later.
* Postfix version 2.5 implements the Sendmail 8.14 features except:
SMFIP_RCPT_REJ (report rejected recipients to the mail filter),
SMFIR_CHGFROM (replace sender, with optional ESMTP command parameters), and
SMFIR_ADDRCPT_PAR (add recipient, with optional ESMTP command parameters).
* Most Milter configuration options are global. Future Postfix versions may
support per-Milter timeouts, per-Milter error handling, etc.